Custom Providers

When using Social Login (OAuth) as authentication method, you may need to use a provider that we don't provide out of the box.

For this, Descope allows you to create your own custom OAuth provider for your Descope Project.

For some common applications, we have dedicated guides below for you to follow. Otherwise, continue reading to learn how to create a custom OAuth provider.

Ethereum Wallet

Custom Social Login with Ethereum Wallet

LINE

Custom Social Login with LINE

Login.gov

Custom Social Login with Login.gov

Spotify

Custom Social Login with Spotify

TikTok

Custom Social Login with TikTok

Configuring a Custom Provider

In addition to the above providers, you can set up Social Login with any OAuth provider by configuring a custom provider in the Descope Console.

Under Authentication Methods → Social Login, select + Add custom provider in the top right corner. You can then set the name, logo, and description for your custom provider.

Trigger Method

Control how this provider can be invoked using the Trigger method setting:

• Enable All: Allows authentication via flows, APIs, and SDKs
• Block API/SDK: Restricts to flows and management calls only, blocking direct API/SDK access

This setting allows you to override the global OAuth trigger method for this specific provider.

Configure Account Settings

Configure the following account settings:

• Client ID: The public identifier for your OAuth application, obtained directly from your OAuth provider (e.g., Google, Microsoft, GitHub). This value is required to authenticate your application during the OAuth flow.

• Client Secret: The confidential key for your OAuth application, provided by your provider. You can also use Private Key JWT as an alternative credential method.

• Scopes: Defines which user permissions your application requests. These scopes are configured within your OAuth provider and determine what user data can be accessed. Examples include:

  • openid, email, profile (for OpenID Connect flows)
  • Provider-specific scopes like user:email, read:user, identify, public_profile, etc.

  If additional scopes are added, ensure Manage tokens from provider is enabled to allow Descope to store and manage access and refresh tokens.

• Grant Type: Choose between:

  • Authorization Code (recommended): Uses the standard authorization code exchange for better security.
  • Implicit: Uses form_post with an id_token response type (required for certain flows like Google One Tap).

Private Key JWT

You can also use Private Key JWT instead of a client secret per RFC 7521.

With this method, Descope creates a signed JWT using your project's private key during token exchange. The OAuth provider validates this JWT instead of a client secret.

Provide your project's JWK endpoint to the OAuth provider: https://api.descope.com/__ProjectID__/.well-known/jwks.json

Replace api.descope.com with your custom domain if applicable.

Example Token Request

When exchanging the authorization code for tokens, Descope sends a request like this to the OAuth provider's token endpoint with a signed JWT as the client_assertion:

POST /token HTTP/1.1
Host: provider.example.com
Content-Type: application/x-www-form-urlencoded
 
grant_type=authorization_code
&code=AUTHORIZATION_CODE
&redirect_uri=https://api.descope.com/v1/oauth/callback
&client_id=YOUR_CLIENT_ID
&client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer
&client_assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...

Configure Connection Settings

Within the connection settings section of your provider, you will configure the following items:

• Discovery URL: If your provider supports OpenID Connect Discovery, you can enter the .well-known/openid-configuration URL here. Descope will automatically populate the following fields below.

• Issuer (optional): Typically matches the iss claim returned from your provider's OpenID configuration.

• Authorization Endpoint: The provider's URL where users are redirected to authenticate. Usually auto-filled if a Discovery URL is provided.

• Token Endpoint: The endpoint used to exchange authorization codes for access and ID tokens. Usually auto-filled from the Discovery URL.

• User Info Endpoint: The endpoint that returns user claims (like email, name, or subject ID). Usually auto-filled from the Discovery URL.

• JWKs Endpoint (optional): Used to fetch public keys for validating JWTs. If not provided, Descope will rely on the User Info endpoint for user data, rather than validating the id_token with a public key from a JWKS endpoint.

Configure the Prompt

The prompt parameter defines how and when users are prompted during authentication. It can improve user experience or enhance security by controlling reauthentication and consent behavior.

You can find this under Prompt in the Descope console:

1. The login prompt

The login prompt forces the user to re-enter their credentials, guaranteeing the current user is explicitly authenticated.

This is ideal for sensitive operations or re-verification scenarios where you need to ensure the user is actively present.

2. The consent prompt

The consent prompt always asks the user to reapprove requested permissions, ensuring transparency and renewed consent from users.

This is particularly useful when handling sensitive data or when the scopes/permissions your application requests have changed.

3. The select_account prompt

The select_account prompt lets the user choose from multiple available accounts, enhancing usability for users managing multiple identities.

This is ideal for multi-account environments where users might have both personal and work accounts.

Configure User Attribute Mapping

Map attributes returned from your OAuth provider to Descope's user profile. At minimum, you must map at least one attribute to the Descope Login ID (typically sub by default).

You can map to built-in Descope fields such as email, name, or phone, as well as custom attributes you've defined for your project.

Use the Update user information upon successful login toggle to control whether user attributes are refreshed on every login. When disabled, attribute mapping only applies during initial user creation, preserving any subsequent changes made to the user's profile.

Configure Advanced Settings

Additional optional settings enhance customization and security:

• Manage Tokens from Provider: Enable this to let Descope securely store and manage provider-issued access and refresh tokens. These tokens can be used later via Descope APIs or SDKs to perform actions on behalf of the user.

• Callback Domain: The domain that handles the OAuth callback. Defaults to your Descope project domain, but can be overridden. The callback URL will be: https://api.descope.com/v1/oauth/callback Or, if using a custom domain: https://auth.mycompany.com/v1/oauth/callback

• Redirect URL: The URL users are redirected to after successful authentication when using SDKs or APIs. Typically, setting this isn't needed when using Flows. This can be overridden dynamically within SDK/API calls.

• Email Address Handling: Decide if the email address returned from the provider should be treated as a login ID. You can promote the email to a login ID only if verified, promote regardless of verification status, or keep the email as a user attribute without allowing it to be a login ID. When emails are promoted to login IDs, users will be able to sign in with just their email address without using OAuth.

• Merge User Accounts Based on Email: When enabled, Descope automatically merges accounts sharing the same verified email address. See User Merging for more.