Custom Providers

When integrating Social Login (OAuth) in your application, you may want to use a provider that we don't provide by default in the console. We have a few dedicated guides on how to configure custom OAuth providers with the applications/services listed below.

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.

Configure Account Settings

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

• Client ID: This is the Client ID of the application, provided by your OAuth provider
• Client Secret: This is the Client Secret of the application, provided by your OAuth provider
• Scopes: These are the configured scopes granted to the user, defined by your OAuth provider
• Grant Type: Choose between:
  • Authorization Code: Uses the default configured response method
  • Implicit: Uses Form Post response method with id_token response type only

Configure Connection Settings

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

• Authorization Endpoint: The endpoint to request authorization from the user, provided by the OAuth provider
• Token Endpoint: The endpoint to exchange the authorization code for an access token, provided by the OAuth provider
• User Info Endpoint: The endpoint to get user details for attribute mapping, provided by the OAuth provider
• JWKs Endpoint (Optional): This endpoint is used to verify the ID token parameter, if such is received from the provider. If not provided - the ID token parameter will be ignored, and information will be fetched only from the User Info Endpoint.

Configure the Prompt

The prompt parameter specifies 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.

Configure User Attribute Mapping

Configure user attribute mapping to match OAuth provider user attributes to attributes within Descope. You can configure the mapping to be to built-in Descope user attributes, or configure custom attributes.

Configure Advanced Settings

There are a few advanced options that can be optionally configured within the custom OAuth provider's settings.

• Manage tokens from provider: If you want Descope to store the provider's access token to be able to be requested via a Management API/SDK call later.

• Callback Domain: The domain that will handle the OAuth callback. Will default to your custom domain if you have it configured.

• Redirect URL: The location to send the user upon successful OAuth authentication. If you're using our SDKs/APIs you can override the Redirect URL by including it in your SDK/API call.

• Email address handling: Controls how email addresses from the OAuth provider are used as login IDs. You can choose to:

  • Only use verified emails
  • Use all emails regardless of verification status
  • Not use emails as login IDs

  If enabled, the email will be added to the user's login IDs. If a user already exists with that email, the accounts will be merged.