OIDC Applications

By setting up an OIDC Application in Descope, it becomes your federated Identity Provider for your users. This positions Descope as a singular hub for storing user identities across various applications (or Service Providers). This guide delves into the process of establishing an OIDC Application within Descope and its subsequent integration with your application/service provider. If you're looking to set up Descope as your IdP with SAML, read about on our docs page here.

If you're interested to learn more about how to utilize the Descope OIDC endpoints (e.g. /authorize, /token, etc.) you can visit our guide on how to do this. Our OIDC endpoints documentation will also cover how to use all of the different OAuth grant types (authorization grant, implicit grant, etc.) supported by Descope. Or if you're interested in how to use Silent Authentication with OAuth, you can view our documentation here.

Note: Configuring a Custom Applications is an enterprise-tier feature.

How does it work?

When Descope is acting as the federated IdP, with OpenID Connect, Descope handles the authentication service aspect while your provider acts as the user and identity information store. If a user is a new user, the user will be created within the provider's user pool. Suppose the user is an existing user that wants to sign in with Descope's supported authentication methods instead of a password.

Descope implements this process via the standard protocols set by the OIDC Foundation.


This image shows OIDC federated authentication flow with Descope.

Creating an OIDC Application

Within Descope, navigate to Applications and click the + Application at the top right. When creating your application, you must provide it with an Application Name, and optionally provide an Application ID and Description. Then, select OIDC.

Create an OIDC Application within Descope.

Configure the OIDC Application

Once the OIDC application has been created in the console, you will need to configure your Flow Hosting URL as well and retrieve the necessary Issuer or Discovery URLs to configure Descope in your OIDC client. Below you can find the available configurations for OIDC Applications within Descope.

Configuring an OIDC Application within Descope.

All Settings

SettingSection title in ConsoleDetails
Application NameApplication DetailsThis is the chosen name of your application and can be updated.
Application IDApplication DetailsUnique identifier for your application which can't be updated. Also, it can be used in the flow to render unique logic depending on the Application (identified via ssoAppID).
Application DescriptionApplication DetailsConcise description of the application's purpose.
Flow Hosting URLIdentity ProviderWhere the authentication flow is hosted.
Issuer URLIdentity ProviderValidates discovery URL.
Discovery URLIdentity ProviderReturns OIDC provider configuration info.
Note: Under Flow Hosting URL, Descope automatically hosts the Sign Up or In Flow at the URL (https://auth.descope.io/<Project ID>?flow=sign-up-or-in). If you would like to change the flow used for authentication, you can do so with the query parameter (e.g. https://auth.descope.io/<Project ID>?flow=step_up). Click here to learn more about our hosted Flows application.

Application ID Check in flow.

Configuring the Service Provider

To use these custom Applications, you'll also need to configure certain parameters in the respective app/client. With OIDC, each app is also known as the Service Provider (or SP). Head to either the app/SP, or whatever client you want to use, and input the following information:

  • Client id: Identifier for the client or service provider. This is your Descope Project ID which can be found here.
  • Client secret: A secret shared between the app and the authorization server. This corresponds to your Descope Access Key available here.
  • Scopes: Permissions determining the access levels. The available scopes can be inferred from the Discovery URL and are also listed here:
    • openid: For authenticating users.
    • profile: For accessing user's profile data.
    • email: For accessing user's email.
    • phone: For accessing user's phone number.
    • descope.custom_claims: Gives access to custom claims. To set the claims in the JWT, one way is to include the custom claims action in your flow.
  • Descope OIDC Endpoints: Either include the Discovery or Issuer URL, which can be found in your Descope Application Configuration, or include the endpoints individually.
    • Logout URL: Endpoint to end an authenticated session. This is the Descope API URL to the logout endpoint: https://api.descope.com/oauth2/v1/logout.
    • Authorization URL: Endpoint for application authorization requests. This is the Descope API URL to the Authorization endpoint: https://api.descope.com/oauth2/v1/authorize.
    • Access token URL: Endpoint to get the access token. This is the Descope API URL to the Access Token endpoint: https://api.descope.com/oauth2/v1/token.

You can find a detailed list of available OIDC endpoints in the official Descope documentation here.

Additional Details

Issuer VS Discovery URL

You use the Issuer URL if you need a scheme that can be verified (most commonly used), or if you are configuring your OIDC to use the Discovery spec and just require a JSON, you’ll use the discovery URL instead.

Note: If you’re using a CNAME with Descope, make sure that the Issuer URL contains your custom domain name, rather than api.descope.com (e.g. https://example.company.com/<Project ID>)

Issuer URL


Verifiable identifier for an issuer containing all of the information in the discovery URL. 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.

Ex:

https://api.descope.com/__ProjectID__

Discovery URL


This URL returns a JSON listing of the OpenID/OAuth endpoints, supported scopes and claims, public keys used to sign the tokens, and other details. The clients can use this information to construct a request to the OpenID server.

Ex:

https://api.descope.com/__ProjectID__/.well-known/openid-configuration

Example Well-known OIDC configuration


{
  "issuer": "https://api.descope.com/__ProjectID__",
  "jwks_uri": "https://api.descope.com/__ProjectID__/.well-known/jwks.json",
  "authorization_endpoint": "https://api.descope.com/oauth2/v1/authorize",
  "response_types_supported": [
    "code"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "token_endpoint": "https://api.descope.com/oauth2/v1/token",
  "userinfo_endpoint": "https://api.descope.com/oauth2/v1/userinfo",
  "scopes_supported": [
    "openid",
    "profile",
    "email",
    "phone",
  ],
  "claims_supported": [
    "iss",
    "aud",
    "iat",
    "exp",
    "sub",
    "name",
    "email",
    "email_verified",
    "phone_number",
    "phone_number_verified",
    "picture"
  ],
  "end_session_endpoint": "https://api.descope.com/oauth2/v1/logout",
  "revocation_endpoint": "https://api.descope.com/oauth2/v1/revoke"
}

Custom OIDC Scopes

Custom Claims

In OIDC, your ID tokens (JWTs) can carry claims, which are pieces of information about the user.

Some of these claims are standard, such as sub (the subject, usually the user ID), name, email, and others. However, you can also define custom claims, which can carry application-specific user details.

Custom claims in Descope are handled by following these steps:

  1. In your application configuration settings, add descope.custom_claims to the scopes that your app requests:
{
  "scopes": ["openid", "profile", "email", "descope.custom_claims"]
}
  1. Then, you will need to map your custom claims to a specific custom user attribute and return it in your flow. If you're curious on how to do this, you can see the first section of this guide. You may also update your JWT with custom claims from our Management SDK or API, provided you have a valid Managment Key.

Picture of custom claims used with OIDC


Picture of flow used with OIDC

Note: You must remember to map the custom claim attributes exactly to how they are defined in your JWT.

And that's it, you're done! You can also see this working in our Descope + Cognito blog, where we utilize custom claims with OIDC.

Tenant, Roles, and Permissions Claim

In addition to the aforementioned options, Descope also supports the descope.claims scope, which returns the tenants, roles, and permissions associated with the user (find more details on how to configure these in the docs here). Simply add descope.claims to the scopes that your app requests, like so:
  "scopes": ["openid", "profile", "email", "descope.custom_claims", "descope.claims"]
The tenants, roles, and permissions associated with the user will be returned in the tenants claim of the ID token.
"tenants": {
    "<tenant_id>": {
      "permissions": ["<permission_name>"],
      "roles": [
        "<role_name>"
      ]
    }
  }

An example of the token returned with this scope is below:

{
  "amr": [
    "oauth"
  ],
  "drn": "DS",
  "exp": 1698175401,
  "iat": 1698174801,
  "iss": "P2SAc2Ou4l9d5GlpYWyUZRYtNHM6",
  "rexp": "2023-11-21T19:13:21Z",
  "sub": "U2XDs389PTVB8xtfRlixPb4luUD7",
  "tenants": {
    "<tenant_id>": {
      "permissions": [
        "SSO Admin",
        "User Admin"
      ],
      "roles": [
        "Tenant Admin"
      ]
    }
  }
}

Hosted Flow Application

When using OIDC, you will need to redirect your users to a Descope Flow for them to login. Descope offers a hosted application, that provides a redirect for your OIDC implementation. The app is deployed at https://auth.descope.io.

The Flow Hosting URL, in the Descope Console under OIDC SSO Configuration, will automatically show the URL for where your Flows are hosted:


Picture of custom claims used with OIDC

If you would like to change which flow to use, you can modify the query parameter at the end with the flow ID you wish to use. If you wish to host the flow on your own and not use https://auth.descope.io, you can do that by following the instructions below.

For more information about our hosted application and customization options, you can refer to our README in the Auth Hosting repository in GitHub.

Hosting Your Own Flow

If you want to have your own hosted page (customize styling, your own domain, etc.), you can use this repository as a template, host it (using Vercel, localhost, etc.), and change the Flow Hosting URL in the Descope Console. When using an OIDC client, like Auth.js, you should automatically be redirected here from the Flow Hosting URL you configured in the Console.

To host the app locally, follow these steps:

  1. Clone the app respository
  2. Replace the Flow Hosting URL in the Console with http://localhost:3000/<DESCOPE_PROJECT_ID>?flow=<FLOW_ID>
  3. Run the app with yarn install and yarn start

Your DESCOPE_PROJECT_ID can be found under Project Settings, and your FLOW_ID can be found under Flows

Your flow should appear automatically when you go to this URL: http://localhost:3000/<DESCOPE_PROJECT_ID>?flow=<FLOW_ID>.