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 custom applications is an Pro/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.

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.

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.

All Settings

Setting	Section title in Console	Details
Application Name	Application Details	This is the chosen name of your application and can be updated.
Application ID	Application Details	Unique 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 Description	Application Details	Concise description of the application's purpose.
Flow Hosting URL	Identity Provider	Where the authentication flow is hosted.
Issuer URL	Identity Provider	Validates discovery URL.
Discovery URL	Identity Provider	Returns OIDC provider configuration info.
Supported Claims	Identity Provider	A dynamic list of supported claims to include in the Well Known Configuration found at the Discovery URL
Force Authentication	Identity Provider	A checkbox to enable "forced" running of a flow, regardless of if the user is already signed in or not. This behavior is akin to the SP sending `prompt=login`

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.

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.
Prompt: Descope supports prompt values sent to it from the SP. These are the current values supported:
- login: This will force the running of a flow, regardless of if the user is already logged in.

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

Prompt

By default, if Descope as an OIDC provider recognizes that a user is already signed in, the user will be automatically redirected back to the SP and logged in (as per a traditional SSO experience).

However, you can include in prompt=login in the /authorize request from the OIDC SP, to force the running of the flow regardless of if the user is already logged in or not. You can also choose to check Force Authentication in the Application Configuration.

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

Descope 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",
  "token_endpoint_auth_methods_supported": []
}

Custom OIDC Scopes and Claims

Add Supported Claims to Well-Known Configuration

If you wish to add additional claims to the supported claims array that is included in every well-known configuration, you can do that with Descope OIDC Applications. Some applications like Docebo, will actually require you add specific claims to this JSON, in order to map the value of these claims to pre-exisiting attributes.

The default ones are:

{
  "claims_supported":["iss", "aud", "iat", "exp", "sub", "name", "email", "email_verified", "phone_number", "phone_number_verified", "picture", "family_name", "given_name"]
}

If you wish to add more, simply add to the list under the Application configuration here:

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:

In your application configuration settings, add descope.custom_claims to the scopes that your app requests:

{
  "scopes": ["openid", "profile", "email", "descope.custom_claims"]
}

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 our JWT Template Guide. You may also update your JWT with custom claims from our Management SDK or API, provided you have a valid Management Key.

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:

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 Auth Hosting Application doc, or the README in the Auth Hosting app 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:

Clone the app repository
Replace the Flow Hosting URL in the Console with http://localhost:3000/<DESCOPE_PROJECT_ID>?flow=<FLOW_ID>
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>.

Was this helpful?

On this page