Customize OAuth Social Login | Descope Documentation

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.

The following list covers the supported OOTB providers for Social Login authentication (OAuth)

Provider	API `<provider>` parameter
Google	`google`
GitHub	`github`
Microsoft	`microsoft`
Apple	`apple`
Facebook	`facebook`
GitLab	`gitlab`
Discord	`discord`
Linkedin	`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.
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[(/session-validation).

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=login value 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=consent value 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
Google	"openid", "email", "profile"
GitHub	"user:email", "read:user"
Microsoft	"openid", "email", "profile"
Apple	"openid", "name", "email"
Facebook	"openid", "email", "public_profile"
GitLab	"openid", "email", "profile"
Discord	"identify", "email"
LinkedIn	"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.

Was this helpful?

On this page