Create OpenID Connect app integrations

An OpenID Connect (OIDC) app integration provides an identity layer on top of the OAuth 2.0 protocol to verify end users' identities and obtain profile information.

Okta supports all parameters for the OIDC protocol. To view these parameters, see OpenID Connect & OAuth 2.0 API.

Before you begin

  • Review Welcome to OpenID Connect to learn about the OpenID Connect Foundation (OIDF) and to review the full protocol specification.
  • Choose the platform for your app integration. You can choose web, native, and single-page apps (SPA).
    • If your target app is a web or a native app, decide if you want to use refresh tokens.
    • If your target app is a single-page app (SPA), decide what kind of visibility and sign-in flow you want. You can initiate a sign-in flow in the background (without an Okta tile), or enable the app or Okta to initiate the sign-in request.

      If you decide that either the app or Okta can initiate the sign-in request, there are two flow options:

      • Redirect to your OIDC app to start the sign-in request. This conforms to Section 4 of the OpenID Connect specification. When end users click an Okta tile, they're redirected to the initiate_login_uri of the client app. The client app constructs an authorization request and redirects the end user back to Okta.
      • Send an ID token directly to your OIDC app. This is a simpler flow. Okta creates an ID token and posts it directly to the first redirect URI registered for the target app. This flow is the same as with sign-in requests for SAML apps. You can configure which OIDC scopes to grant. This flow uses the form_post response mode. There's no state parameter included in the request since it's a one-way request.
  • Verify that any redirect Uniform Resource Identifier (URI) endpoints are functional. A redirect URI is where Okta sends the authentication response and ID token.

  • If your app integration contains links to instructions, prevent access issues by adding Okta to your list of sites that can always use cookies. See Mitigate the impact of third-party cookie deprecation.

Launch the wizard

  1. In the Admin Console, go to ApplicationsApplications.
  2. Click Create App Integration.
  3. Select OIDC - OpenID Connect as the Sign-in method.
  4. Choose the type of app to integrate with Okta:
    • Web Application
    • Single-Page Application
    • Native Application
  5. Click Next.

Configure general settings

The App Integration Wizard (AIW) for OIDC has three sections:

  1. In General Settings:
    • App integration name: Specify a name for your app integration. The app integration name can only consist of UTF-8, three-byte characters.

      Okta automatically assigns a default name to your app integration based on the platform that you select. If an app integration with the default name exists in your Okta org, then a number is appended to the default name to differentiate the integrations.

    • Optional. Logo: Add a logo to appear on the app tile in the Okta org. The logo file must be in .png, .jpg, or .gif format and be smaller than one megabyte. For best results, use a .png image with a transparent background and a landscape orientation. Use a minimum resolution of 420 by 120 pixels to prevent up-scaling.
    • Application notes for end users: Enter text in the field to display a note about the app on the Okta End-User Dashboard.
    • Application notes for admins: Enter text in the field to display a note about the app to admins on the OIDC app page.
    • Require Demonstrating Proof of Possession (DPoP) header in token requests: Select this option to require a client to prove possession of a public/private key pair for token requests. The authorization server rejects token requests from this client that don't contain the DPoP header. You can't select Implicit (hybrid) from the Grant type options when you require DPoP.
    • Grant type: Select the grant types that you want to use. Click Advanced to see more grant types. See Configure Direct Authentication grant types for descriptions of each grant type. The grant types available for your app integration depend on the platform that you select. See OAuth 2.0 and OpenID Connect overview.
    • Sign-in redirect URIs: This is where Okta sends the authentication response and ID token for the sign-in request. The URIs must be absolute URIs.

      You can specify multiple URIs, and sort them in any order. Users see an error message if they try to sign in to a URI that isn't registered with your integration.

      If your OIDC client is configured to support multiple subdomains, you can use a single redirect URI with a wildcard. Select Allow wildcard in sign-in redirect URI. See the Apps API for more configuration guidance for wildcards.

      The use of wildcards for subdomains is discouraged. Wildcards can allow malicious actors to have tokens or authorization codes sent to unexpected or attacker-controlled pages.

    • Optional. Sign-out redirect URIs: After your app contacts Okta to close the user session, Okta redirects the user to this URI. The URIs must be absolute URIs. You can specify more than one URI. You can't use wildcards in subdomains for sign-out redirect URIs.

  2. Trusted Origins (for web and native app integrations):
    • Optional. Base URIs: Specify any base URIs for which you want to permit cross-origin requests to the Okta APIs. These URIs are added to the Trusted Origins for your Okta org. You can manage these base URIs by going to SecurityAPI and selecting the Trusted Origins tab. See Overview of Cross-Origin Resource Sharing (CORS).
  3. Assignments: The default option lets you assign and grant access to this app integration for everyone in your Okta org.
    • Controlled access:
      • Limit access to selected groups: Enter the groups names that you want to grant access to.
      • Skip group assignment for now: Create the app without assigning a group.
  4. Click Save. The settings page appears.

When you add an app integration from the OIN, Okta generates an Update application event that appears in the System Log. This event reflects the creation of a new instance of an existing app.

When you create an app using the App Integration Wizard (AIW), Okta generates a Create application event that appears in the System Log. This event reflects the creation of a new app.

Configure OIDC settings

The options in the General tab are similar for all OIDC integration types. Click Edit to change the options.

Web apps

The Client Credentials section contains important information necessary for authentication flows.

  • Client ID: This is the public identifier required by all OAuth flows. This identifier is randomly generated when you create the app integration.

  • Client authentication: Choose the client authentication method.

    • Client secret: Display a panel where you can generate a secret for use by the client. This value is known only to Okta and your app integration. Click Save to generate the client secret and then view or copy the client secret. If you have a second client secret, you can change the status to select the active secret. See Rotate a client secret by creating a second client secret.

    • Public key / Private key: Display a panel where you can generate or add a public/private key pair for use by the client connection. See Manage secrets and keys for OIDC apps.
  • Proof Key for Code Exchange (PKCE): Indicates if a PKCE code challenge is required to verify client requests. This is optional for both the Client secret and Public key / Private key authentication methods. See Change client authentication methods if you switch between a client secret and a public or private key.

  • Click Save.

In the General Settings section, you can configure the following settings for your app integration:

  • App integration name: Change the name if required.
  • Require Demonstration of Proof-of-Possession (DPoP) header in token requests: Select this option to require a client to prove possession of a public/private key pair for token requests. The authorization server rejects token requests from this client that don't contain the DPoP header. You can't select Implicit (hybrid) from the Grant type options when you require DPoP.
  • Grant type: Select grant type options:
    • Client credentials: Use client credentials for a client acting on behalf of itself.
    • Authorization code: Use an authorization code for a client acting on behalf of a user.
    • Refresh Token: Rotate your token after every use or use a persistent token. If you choose to rotate your token after every use, you can set a persistence period for how long that token remains active.
    • Device Authorization: Use device authorization as the grant type for a client acting on behalf of a user.
    • Implicit (hybrid): Use an implicit grant type for a client acting on behalf of a user. Select the type of token that you want to use:
      • Allow ID token with implicit grant type
      • Allow Access token with implicit grant type

  • Require consent: Add or remove the user consent for an OIDC integration. Select this option to prompt the user with a pop-up window to approve the integration's access to specified resources. You can set up the consent for an OIDC scope in your custom authorization, as described in Create API access scopes . This checkbox only appears if Okta API Access Management is enabled for your org. See Request user consent.

  • Sign-in redirect URIs: This is where Okta sends OAuth responses. Enter one or more URIs.

  • Sign-out redirect URIs: This is where Okta redirects the browser after signing out from the relying-party and terminating its end-user session. Enter one or more URIs.

  • Login initiated by: Specify if the app initiates the sign-in process in the background, or if either the app or Okta can initiate the sign-in request.

    • App Only: The app starts in the background, and the Okta tile doesn't appear.

    • Either Okta or App: The app integration uses an Okta tile:

      • Application visibility: Select whether you want the app to be visible to end users or not.
      • Login flow: Select an option:
      • Send ID Token directly to app (Okta Simplified): Select the OIDC scopes for the flow.
      • Implicit: An App Embed Link section appears at the bottom of the settings page. This shows the URL that you can use to sign in to the OIDC client from outside of Okta.
  • Initiate login URI: The URI used to initiate a sign-in request. When Okta is redirected to this endpoint, it triggers the client to send an authorization request. Enter or change the URI.

  • Click Save.

Single page apps

The Client Credentials section contains important information necessary for authentication flows.

  • Client ID: This is the public identifier required by all OAuth flows. This identifier is randomly generated when you create the app integration.

  • Client authentication: Choose the method to use for client authentication:

    • None: The default option for SPA integrations. This option requires a Proof Key for Code Exchange (PKCE) for additional verification. PKCE ensures that only the client that requested the access token can redeem it.

In the General Settings section, you can configure the following settings for your app integration:

  • App integration name: Change the name if required.
  • Require Demonstration of Proof-of-Possession (DPoP) header in token requests: Select this option to require a client to prove possession of a public/private key pair for token requests. The authorization server rejects token requests from this client that don't contain the DPoP header. You can't select Implicit (hybrid) from the Grant type options when you require DPoP.

  • Grant type: Select grant type options:

    • Authorization Code: Use an authorization code as the grant type for a client acting on behalf of a user.
    • Refresh Token: Rotate your token after every use or use a persistent token. If you choose to rotate your token after every use, you can set a persistence period for how long that token remains active.
    • Device Authorization: Use device authorization as the grant type for a client acting on behalf of a user.
    • Implicit (hybrid): Use an implicit grant type for a client acting on behalf of a user. Select the type of token that you want to use:
      • Allow ID token with implicit grant type
      • Allow Access token with implicit grant type
  • Sign-in redirect URIs: This is where Okta sends OAuth responses. Enter one or more URIs.
  • Sign-out redirect URIs: This is where Okta redirects the browser after signing out from the relying-party and terminating its end-user session. Enter one or more URIs.
  • Login initiated by: Specify whether the app initiates the sign-in in the background, or if either the app or Okta can initiate the sign-in request.
    • App Only: The app is started in the background, and the Okta tile doesn't appear.
    • Either Okta or App: The app integration uses an Okta tile:
      • Application visibility: Select whether you want the app to be visible to end users or not.
      • Login flow: Select an option:
      • Send ID Token directly to app (Okta Simplified): Select the OIDC scopes for the flow.
      • Implicit: An App Embed Link section appears at the bottom of the settings page. This shows the URL that you can use to sign in to the OIDC client from outside of Okta.
  • Initiate login URI: The URI used to initiate a sign-in request. When Okta is redirected to this endpoint, it triggers the client to send an authorization request. Enter or change the URI.
  • Click Save.

Native apps

The Client Credentials section contains important information necessary for authentication flows.

  • Client ID: This is the public identifier required by all OAuth flows. This identifier is randomly generated when you create the app integration.
  • Client authentication: Choose the method to use for client authentication:
    • None: This option is recommended for native apps. This option requires a Proof Key for Code Exchange (PKCE) for additional verification. PKCE ensures that only the client that requested the access token can redeem it.
    • Client secret: Display a panel and generate a secret for use by the client. This value is known only to Okta and your app integration. Click Save to generate the client secret. You can view or copy the client secret. If you have a second client secret, you can change the status to select the active secret. See Rotate a client secret by creating a second client secret.
    • Public key / Private key: Display a panel where you can generate or add a public/private key pair for use by the client connection. See Manage secrets and keys for OIDC apps.
  • Proof Key for Code Exchange (PKCE): Indicates if a PKCE code challenge is required to verify client requests. If you select None as the authentication method, a PKCE challenge is required by default. The PKCE code verification is optional for the Client secret and Public key / Private key authentication methods. If you changed your client authentication method, see Change client authentication methods for information on how existing secrets and keys are affected.
  • Click Save.

In the General Settings section, you can configure the following settings:

  • App integration name: Change the name if required.
  • Require Demonstration of Proof-of-Possession (DPoP) header in token requests: Select this option to require a client to prove possession of a public/private key pair for token requests. The authorization server rejects token requests from this client that don't contain the DPoP header. You can't select Implicit (hybrid) from the Grant type options when you require DPoP.

  • Grant type: Select grant type options:

    • Authorization Code: Use an authorization code as the grant type for a client acting on behalf of a user.
    • Interaction Code: Use an interaction code as the grant type for a client acting on behalf of a user.
    • Refresh Token: Rotate your token after every use or use a persistent token. If you choose to rotate your token after every use, you can set a persistence period for how long that token remains active.
    • Resource Owner Password: Use a resource owner password as the grant type for a client acting on behalf of a user.
    • SAML 2.0 Assertion: Use a SAML 2.0 assertion as the grant type for a client acting on behalf of a user.
    • Device Authorization: Use device authorization as the grant type for a client acting on behalf of a user.
    • Token Exchange: Use a token exchange as the grant type for a client acting on behalf of a user.
    • Implicit (hybrid): Use an implicit grant type for a client acting on behalf of a user. Select the type of token that you want to use:
      • Allow ID token with implicit grant type
      • Allow Access token with implicit grant type
  • Sign-in redirect URIs: This is where Okta sends OAuth responses. Enter one or more URIs.
  • Sign-out redirect URIs: This is where Okta redirects the browser after signing out from the relying-party and terminating its end-user session. Enter one or more URIs.
  • Initiate login URI: The URI used to initiate a sign-in request. When Okta is redirected to this endpoint, it triggers the client to send an authorization request. Enter or change the URI.
  • Click Save.

Configure optional settings

You can optionally configure a group claims filter, set app rate limits, and set the issuer.

Set the groups claim filter

  1. Go to the Sign On tab and scroll down to the OpenID Connect ID Token section.

  2. Select Groups claim type. You can select either a Filter for existing group claims, or choose an Expression to create a custom filter on a different group claim.

    The API can't create ID tokens if both of these conditions appear in your configuration:

    • There are more than 100 groups that match the Groups claim filter.
    • You use any grant type except Authorization Code or Authorization Code with PKCE.

    For more information about group claims for SSO, see Customize tokens returned from Okta.

Set the app rate limits

You can configure a rate limit for individual OAuth 2.0 apps. By default, all new apps consume 50% of every API's rate limits.

  1. In the Application rate limits tab, click Edit.
  2. Move the slider to the desired percentage.
  3. Click Save.

See Rate Limit dashboard.

Set the issuer

If you enabled and defined a custom URL domain, the Issuer field defaults to the custom URL and appears in the format Custom URL (https://id.example.com). Use the dropdown arrow in the field to select the organization URL.

Alternatively, you can choose Dynamic, which allows either the organizational or custom domain to be used, depending on the request domain.

Next steps