Create OIDC app integrations using AIW

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 login flow you want. You can configure your integration to be initiated only in the background - without an Okta tile - or configure the sign-in request to be initiated either by the application or by Okta.

    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 are granted. The form_post response mode is used for this flow. There is no state parameter included in the request since it’s a one-way request.
  • Verify any redirect Uniform Resource Identifier (URI) endpoints are functional. A redirect URI is where Okta sends the authentication response and ID token.
  • To prevent issues with inline instructions in your app integrations, open your browser settings and add Okta to your list of sites that can always use cookies. See Allow third-party cookies.

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, or 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 until 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 Applications > Applications.
  2. Click Create App Integration.
  3. To create an OIDC app integration, select OIDC - OpenID Connect as the Sign-in method.
  4. Choose what type of application you plan 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 you selected. If there’s already an app integration in your Okta org with that default name, then a number is added to the app integration name to differentiate them.

    • 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 upscaling.
    • Grant type: Select from among the different grant type options. The grant types available for your app integration depend on the platform you have selected. 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. However, if your OIDC application sends a request to a URI that isn’t registered with your Okta app integration, your users are sent to an error page when they try to sign on.

      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 and can be managed by going to Security > API 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.

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 from among the different Grant type options.

    • Add or remove the user consent for an OIDC integration. Check the Require consent box to prompt the user with a pop-up window to approve the integration's access to specified resources. Additionally, you can set up the consent for an OIDC scope in your custom authorization, as described in the Create Scopes section of API Access Management. Note that Require consent 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 directly 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 from among the different Grant type options.

      • If you select a Refresh Token grant type, you can then choose whether to 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.

    • Add or remove the user consent for an OIDC integration. Check the Require consent box to prompt the user with a pop-up window to approve the integration's access to specified resources. Additionally, you can set up the consent for an OIDC scope in your custom authorization, as described in the Create Scopes section of API Access Management. Note that Require consent 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 directly 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 can also select 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 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 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: 
    • Change the App integration name if you need to modify this from your initial name.

    • Select from among the different Grant type options.

      • If you select a Refresh Token grant type, you can choose to rotate your token after every use or utilize a persistent token.

    • Add or remove the user consent for an OIDC integration. Check the Require consent box to prompt the user with a pop-up window to approve the integration's access to specified resources. Additionally, you can set up the consent for an OIDC scope in your custom authorization, as described in the Create Scopes section of API Access Management. Note that Require consent 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.

    • 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, 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.

Using a Custom URL Domain

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.

This is an Early Access feature. To enable it, contact Okta Support.

Next steps