Spotify OAuth Provider

Descope allows you to create custom Social Login (OAuth) providers within the Authentication Methods page. This allows you to add any Social OAuth authentication within your application. This guide specifically covers the step by step configuration of a custom Spotify OAuth provider.

Creating the Spotify Application

Before creating the custom OAuth provider within the Descope console, you must create and configure an application within your Spotify developer account.

You can follow the Spotify App Guide for details on creating your application. While creating your app within Spotify, you must configure the redirect URI and what APIs you will be using.

The configured redirect URI should be https://api.descope.com/v1/oauth/callback for a US project, https://api.euc1.descope.com/v1/oauth/callback for a EU project - unless you have a customized domain. If you have a customized domain, you will use your CNAME as configured within Project Settings. Example: auth.example.com would utilize the redirect URI of https://auth.example.com/v1/oauth/callback.

Creating Descope Custom Provider

Within the Customize Authentication Methods page, click the blue + Add custom provider in the top right corner. You can then give the provider the name of your choice, for this example, we will set the Provider Name to Spotify. You can configure the logo which will be shown on the Social Auth button in your flow by selecting the edit button on the logo. You can also configure the Provider Description.

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 created within Spotify
Client Secret: This is the client secret of the application created within Spotify
Scopes: These are the configured scopes granted to Descope for the user within Spotify. Scopes provides Spotify users using third-party apps the confidence that only the information they choose to share will be shared. The minimum needed Spotify scope for Descope to be able to capture the user's email and basic account details from Spotify is user-read-email.
Grant Type: 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.

Configure Connection Settings

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

Authorization Endpoint: The endpoint to request authorization from the user. For Spotify, this endpoint is https://accounts.spotify.com/authorize.
Token Endpoint: The endpoint to exchange the authorization code for an access token. For Spotify this endpoint is https://accounts.spotify.com/api/token.
User Info Endpoint: The endpoint to get user details for attribute mapping. For Spotify, this endpoint is https://api.spotify.com/v1/me.

Configure the 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.

Configure User Attribute Mapping

Given the user-read-email and user-read-private scopes, Descope can capture any items from the user info endpoint response. Per the below example, we have mapped email and display name.

Configure Advanced Settings

There are a few advanced options that can be configured within the custom provider in descope.

Optionally, you can choose to Manage tokens from provider if you want Descope to store the provider's access token in an encrypted state for later use.
Optionally, you can configure the Callback Domain which is only applicable if you have more than one CNAME associated with your application. If you have only one CNAME configured, it will default to your customized CNAME. Example: auth.example.com
Optionally, you can configure the Redirect URL which is the location to send the user upon successful OAuth authentication. If redirect URL is specified in the SDK/API call, it will override this value.
Optionally, you can choose Merge user accounts based on returned email address from provider, when selected, if an email is returned from this provider, it will automatically qualify as a login ID of the user; if the user already has an account with that email - the two accounts will be merged into one.

Check the configuration

Now that you have stepped through the above steps, your configuration should appear similar to the below.

Utilize within Descope Flow

We will now cover how to utilize the custom provider within a flow.

Within your Descope flow, update your login screen, adding the Spotify button.

If your flow does not currently have the Sign Up or In / OAuth action, click on the blue + symbol in the top left, add a Sign Up or In / OAuth action.

Connect the Flow Actions

Now that you have configured the Sign Up or In action, connect the action to the Socials section of the login screen then to the next applicable step within your flow. Note that Spotify does not store whether the email has been verified. It is suggested to check if the email is verified via a condition, then verify the email for the user.

Test your Flow

You can now test your flow within your application, the flow builder via clicking run, or within Descope Explorer.

Utilize within Descope SDK

When utilizing your Spotify custom provider within the Descope SDKs, you will pass the provider as Spotify which is the name of the provider which you configured. Note that this is case sensitive to how you configured here.

Was this helpful?

On this page