Customizing 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	`google`
GitHub	`github`
Microsoft	`microsoft`
Apple	`apple`
Facebook	`facebook`
GitLab	`gitlab`
Discord	`discord`
Linkedin	`linkedin`
Slack	`slack`

Custom OAuth Providers

Descope allows you to create custom Social Login (OAuth) providers within the Authentication Methods page. This gives you the ability to utilize any OAuth provider to authenticate your users to your application, with Desocpe being your OAuth Service Provider (SP).

For examples of configuring custom OAuth providers, you can review our Knowledge base articles for configuring Spotify and Ethereum Wallet as custom OAuth providers.

Grant Type

You can configure your custom OAuth Providers, to use either the Authorization Code flow or Implicit Flow (with Form Post).

This configuration can be found under your Custom Provider configuration page:

If you're using Implicit Flow with Form Post, you won't need a client secret, as this is not needed with this specific grant type.

Issuer

An issuer identifier is a case-sensitive URL that uses the HTTPS scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components. This may or may not be required depending on the custom OAuth Provider you're using.

Note: For default providers, we will automatically check the Issuer URLs and this is not needed.

If the issuer does not match the OAuth Provider, you will receive an Invalid issuer or issuer alias error.

As a side note, the default iss claim in Descope JWTs is your Descope Project ID (the OIDC Client ID).

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.

This configuration can be found under Prompt:

1. 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.

2. 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.

3. 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) then you can visit our guide here

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/callbackWhen 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.

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.

Setting up an OAuth Provider Account

OAuth Provider	link to instructions
Google	Custom Social Login With Google
Apple	Custom Social Login With Apple

Was this article helpful?Yes No