Social Login (OAuth)
Customize your social login (OAuth) authentication flow from the Descope console (Settings > Authentication Methods > Social Login).
What is an Authentication Account?
The authentication account registers your company with an OAuth provider, where you provide details such as your application/website, company name, and company logo. Registering these details provides some specific OAuth security benefits and gives your end users an OAuth sign-up/sign-in experience branded with your details.
You do not have to create your authentication account to get started!
Descope comes preconfigured with a Descope authentication account for each OAuth provider. Behind the scenes, Descope takes care of all the Oauth registration details for you. So leave the details to Descope, and start building your OAuth flow immediately. When convenient for you, create your authentication account for each OAuth provider you want, then go to the Descope console and enter your personal IdP authentication account information.
Social Login (OAuth) Providers
The following list covers the supported OOTB providers for Social Login authentication (OAuth)
| Provider | API <provider> parameter |
|---|---|
google | |
| GitHub | github |
| Microsoft | microsoft |
| Apple | apple |
facebook | |
| GitLab | gitlab |
| Discord | discord |
linkedin | |
| Slack | slack |
Settings Summary
All Settings
Variables are displayed below and in the console as {{variable_name}}.
| Setting | Variable | Details |
|---|---|---|
| Authentication Account | This toggle switches between utilizing Descope's authentication account or your authentication account | |
| Redirect URL | {{redirectUrl}} | default URL for the route you implement to initiate OAuth logins |
| Client ID | ID from OAuth provider when creating your authentication account | |
| Client Secret | secret from OAuth provider when creating your authentication account | |
| Scopes | When adding new scopes, you will need to allow Descope to manage the access and refresh tokens. Make sure that the switch below is turned on. | |
| Allowed Grant Types | Authorization Code grant type uses the default configured response method, while implicit is set to use the Form Post response method with "id_token" response type only. Note that Implicit is required for some auth methods like Google One Tap. | |
| Prompt | The prompt parameter significantly affect the user experience by specifying whether and how the user is prompted for authentication and consent. | |
| User Attribute Mapping | This allows you to map attributes from the OAuth provider to user attributes within Descope. | |
| Manage Tokens from Provider | Allow Descope to store and manage users' provider tokens (access and refresh tokens) that can be used later on to perform actions that require access to the provider's resources. | |
| Callback Domain | Domain which to use for callbacks. This will default to the configured domain within project settings. | |
| Callback URL for social app registration | To use a custom domain in your OAuth verification screen, configure a custom domain in the Project page. | |
| Redirect URL | If redirect URL is specified in the SDK/API call, it will override this value. | |
| Merge user accounts based on returned email address from provider | This toggle switch enables or disables merging accounts based on email address. See User Merging for more details. | |
| Enable method in API and SDK | This toggle switch enables or disables the authentication method from being available for use within API and SDK |
Additional Details
This section describes additional details about the configuration options available.
Redirect URL
The redirect URL is the location to send the user upon successful OAuth authentication. The redirect URL will be overridden when specified in the SDK or API call.
Client ID and Client Secret
You do not supply the Client ID or Client Secret when you use the built-in Descope authentication account.
You will gather the Client ID and Client Secret from your provider when utilizing your authentication account and update them within the Descope UI.
Within your custom OAuth application, you also need to specify the callback URL: https://api.descope.com/v1/oauth/callback
When using a custom domain, you also need to specify the callback URL: https://app.auth.company.com/v1/oauth/callback
OAuth with Custom Domains
If you are using your own connector, it is recommended to specify the custom domain within your OAuth implementation. Setting the custom domain will result in users viewing your OAuth verification screen to see your domain rather than the Descope domain. More documentation on custom domain and how to setup it up is here available here.
Prompt
The prompt parameter significantly affect the user experience by specifying whether and how the user is prompted for authentication and consent.
Tailoring the prompt behavior can lead to a smoother and more intuitive user experience. Also, in certain contexts, forcing a user to re-authenticate or re-consent can enhance security.
The 'login' prompt:
- Usage: The
prompt=loginvalue forces the user to enter their credentials regardless of their current authentication state. - Use Case: This is particularly useful in scenarios where heightened security is required, such as sensitive transactions or changes in user settings.
- Experience: It ensures that the user is indeed the one making the request, even if they are already logged in.
The 'consent' prompt
- Usage: The
prompt=consentvalue ensures that the user is explicitly asked to grant permissions, even if they have previously given consent. - Use Case: This is essential for applications that handle sensitive data or need explicit user permissions for certain actions.
- Experience: It provides transparency and control to the user, ensuring they are aware of and agree to what permissions the application is requesting.
The 'select_account' prompt
- Usage: Allows the user to select an account in multi-account scenarios.
- Use Case: Useful in environments where users have multiple accounts (personal, work, etc.).
- Experience: Enhances user convenience by enabling them to switch between different accounts seamlessly.
You can also change these prompts in the flow itself, rather than the custom provider configuration, if you want to use the same provider with different prompt values depending on your Flow configuration.
If you're looking for how to perform silent authentication (i.e. use the prompt=none parameter).
Creating Your Own Authentication Account
When you have a personal OAuth provider authentication account you want to use, go to the console and enter the Client ID and Client Secret.
When creating the account, you must request the scopes listed below.
OAuth Scopes
Required OAuth Scopes
An OAuth scope specifies the exact information you are requesting from the OAuth provider about your end user. The full list of scopes being requested is presented by the OAuth provider during sign-up for explicit appoval by the end user.
The following table lists the minimum scopes required for sign-up/sign-in.
| OAuth Provider | required scopes |
|---|---|
| "openid", "email", "profile" | |
| GitHub | "user:email", "read:user" |
| Microsoft | "openid", "email", "profile" |
| Apple | "openid", "name", "email" |
| "openid", "email", "public_profile" | |
| GitLab | "openid", "email", "profile" |
| Discord | "identify", "email" |
| "openid", "profile", "email" | |
| Slack | "openid", "profile", "email" |
Optional OAuth Scopes
Descope allows you to customize the scopes that are requested from the provider when you have configured your
authentication account for the provider within the OAuth Authentication Methods
for the applicable provider. This feature also pairs with the option to Manage tokens from provider for later use
within your application when you would like to use the provider token to take action on the user's behalf or load
further data for the user. For details about how to configure and utilize these scopes, please review the
Customizing OAuth Scopes and Provider Tokens Guide.
Manage Provider Tokens
If you would like Descope to securely store the provider tokens, toggle the Manage tokens from provider switch.
This allows Descope to store and manage users' provider tokens (access and refresh tokens) that can be used
later on to perform actions that require access to the provider's resources. For more details on example usage,
see the Customizing OAuth Scopes and Provider Tokens Guide.