Create OIDC app integrations

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

For detailed information about the OpenID Connect Foundation and to review the full protocol specification, see Welcome to OpenID Connect.

Before you begin

  • Decide on the platform for your app integration. Available platforms are web, native, and single page application (SPA).
  • If your target application is a web or a native application, decide if you want to use refresh tokens.
  • If your target application is a single page application (SPA), decide what kind of visibility and sign-in flow you want. You can configure your integration to initiate a sign-in flow in the background—without an Okta tile—or enable the application or Okta initiate the sign-in request.

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

    • Redirect to your OIDC application to start the sign-in request. This conforms to Section 4 of the OpenID Connect specification. When the end users click an Okta tile, they're redirected to the initiate_login_uri of the client application. The client application constructs an authorization request and redirects the end user back to Okta.
    • Send an ID token directly to your OIDC application. This is a simpler flow, where Okta creates an ID token and posts it directly to the first redirect URI registered for the target application. 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.

Context

User Consent for OAuth 2.0 and OpenID Connect Flows

A consent grant is a user's explicit permission to allow an application to access resources protected by scopes. As part of an OAuth 2.0 or OpenID Connect authentication flow, you can prompt the user to approve your integration's access to specified resources. You can also set up user consent as part of creating the integration.

Consent grants are different from tokens because a consent grant can outlast a token. There can be multiple tokens with varying sets of scopes derived from a single consent.

When an application needs to get a new access token, it doesn't need to prompt the user for consent if they've already consented to the specified scopes. Consent grants remain valid until the user manually revokes them or the user, integration, authorization server, or scope is deactivated or deleted. User consent requires that your org has the API Access Management feature enabled.

Task 1: Launch the Wizard

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

Task 2: Configure initial settings

The App Integration Wizard 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, 3-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 accompany your app integration in the Okta org. The logo file must be in .png, .jpg, or .gif format and be smaller than 1 MB. For best results, use a PNG image with a transparent background and a landscape orientation. Use a minimum resolution of 420 x 120 pixels to prevent up-scaling.
    • 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: The sign-in redirect URI is where Okta sends the authentication response and ID token for the sign-in request. The URIs must be absolute URIs.

      You can specify more than one URI. As your OIDC application must explicitly request which redirect_uri to use, the order doesn't matter. If your application sends a request to a URI that isn't registered with your integration, your users are sent to an error page when they try to sign in.

      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 application 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. The use of wildcards for subdomains isn't currently supported for sign-out redirect URIs.

  2. In 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. In Assignments:
    • Controlled access: The default access option assigns and grants access to this new app integration for everyone in your Okta org. You can choose to Limit access to selected groups and then enter the specific groups names found in your org. Or Skip group assignment for now and create the app without assigning a group.

  4. Click Save. This creates the app integration and opens the settings page to configure more options.

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.

Task 3: Configure OIDC settings

The options in the General tab are similar for all OIDC integration types. Click Edit to change any of the listed 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 method to use for client authentication.
      • Client secret: Selecting this option displays 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. 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 second client secret.

      • Public key / Private key: Selecting this option displays a panel where you can generate or add a public key / 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.
    • Click Save to commit any changes to your Client Credentials. If you switch between a client secret and a public key / private key, see Change client authentication methods for information on removal of existing secrets or keys.

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

    • Change the App integration name if you need to modify this from your initial name.

    • Select Require Demonstration of Proof-of-Possession (DPoP) header in token requests 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. Additionally, you can't select Implicit (hybrid) from the Grant type options.

    • Select from among the different Grant type options.

      • Client credentials: Use client credentials as the grant type for a client acting on behalf of itself.
      • 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 you want to use:
        • Allow ID token with implicit grant grant type
        • Allow Access token with implicit grant type
    • Add or remove the user consent for an OIDC integration. Select Require consent 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 . The Require consent checkbox only appears if Okta API Access Management is enabled for your org.

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

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

    • Select a Login initiated by setting to specify if the sign-in process is initiated by the application in the background, or if either the application or Okta can initiate the sign-in request.

      • If you select App Only, the application is started in the background, without an Okta tile appearing.

      • If you select Either Okta or App, your integration uses an Okta tile:

        • Select the appropriate Application visibility option.

        • Select the appropriate Login flow option. If you choose Send ID Token directly to app (Okta Simplified), you're also able to choose OIDC scopes for the flow.

        • If you are using the Implicit flow, an App Embed Link section appears at the bottom of the settings page, showing the URL that you can use to sign in to the OIDC client from outside of Okta.

    • Enter or change the Initiate login URI used to initiate a sign-in request. When Okta is redirected to this endpoint, it triggers the client to send an authorization request.

    • Click Save to commit your General Settings changes.

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: Default 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:

    • Change the App integration name if you need to modify this from your initial name.

    • Select Require Demonstration of Proof-of-Possession (DPoP) header in token requests 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. Additionally, you can't select Client credentials or Implicit (hybrid) from the Grant type options.

    • Select from among the different 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.
    • Enter one or more Sign-in redirect URIs where Okta sends OAuth responses.

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

    • Select a Login initiated by setting. Specify whether the application initiates the sign-in in the background, or if either the application or Okta can initiate the sign-in request.

      • If you select App Only, the application is started in the background, without an Okta tile appearing.

      • If you select Either Okta or App, your integration uses an Okta tile:

        • Select the appropriate Application visibility option.

        • Select the appropriate Login flow option. If you choose Send ID Token directly to app (Okta Simplified), you can also select OIDC scopes for the flow.

        • If you're using the Implicit flow, an App Embed Link section appears at the bottom of the settings page. This section shows the URL that you can use to sign in to the OIDC client from outside of Okta.

    • Enter or change the Initiate login URI used to initiate the sign-in request.

    • Email Verification Experience: This setting allows you to customize the end-user experience when using an email magic link as an authenticator. When end users click the one-time magic link to verify their identity on orgs that use an embedded sign-in widget, Okta validates the token and redirects their browser request to this URI location. You can set this URI value to send the end user to specific OIDC app integrations, the end-user dashboard for your org, or any custom website. If this URI is not present, Okta uses the redirect sign-in flow and sends the end user to the Okta End-User Dashboard.

    • Click Save to commit your General Settings changes.

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: Recommended for native applications.

        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: Selecting this option displays 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. 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 second client secret.

      • Public key / Private key: Selecting this option displays a panel where you can generate or add a public key / 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.
    • Click Save to commit any changes to your Client Credentials. If you changed your client authentication method, see Change client authentication methods for information on how existing secrets and keys are affected.

  • In the General Settings section, you can configure the following settings:
    • Change the App integration name if you need to modify this from your initial name.

    • Select Require Demonstration of Proof-of-Possession (DPoP) header in token requests 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. Additionally, you can't select Implicit (hybrid) from the Grant type options.

    • Select from among the different 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.
    • Enter one or more Sign-in redirect URIs where Okta sends OAuth responses.

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

    • Enter or change the Initiate login URI used to initiate the sign-in request.

    • Click Save to commit your General Settings changes.

Task 4: Configure optional settings

Set the Groups Claim Filter

  1. Go to the Sign On tab and scroll down to the OpenID Connect ID Token section.
  2. Select the 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.

    If the value you specify in the Groups claim filter matches more than 100 groups and your grant type is neither Authorization Code or Authorization Code with PKCE , then an error occurs when the API tries to create ID tokens.

    For more information about Group claims for Single Sign-On, see Customize tokens returned from Okta.

Set the application rate limits

You can configure a percentage rate limit capacity for individual OAuth 2.0 applications. By default, all new applications 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 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