Create an OIDC app integration 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 detailed specification, see Welcome to OpenID Connect.

Before you begin

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 you can set up user consent as part of creating the integration. Consent grants are different from tokens because a consent grant can outlast a token, and 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 does not need to prompt the user for consent if they have 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 Add Application.
  3. Click Create New App.
  4. To create an OIDC app integration, select either Web, Native App, or Single Page App (SPA) as the Platform and OpenID Connect for the Sign on method.
  5. Click Create.

Task 1: Launch the Wizard (new entry path)

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

  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-on method.
  4. Choose what type of application you plan to integrate with Okta. Select either Web Application, Single-Page Application, or Native Application.
  5. Click Next.

Task 2: Configure initial settings

The Open ID Connect App Integration Wizard has two sections:

  1. In General Settings:
    • App name — Specify a name for your integration.
      Info

      Note

      The name can only consist of UTF-8, 3-byte characters.

    • A default name is automatically provided for you, based on the platform you selected. If there is already an app integration in your Okta org with that default name, then a number is also added to the app name field to differentiate between the two app integrations.

    • Optional. App logo — Add a logo to accompany your integration in the Okta org. The logo file must be PNG, JPG, or GIF format and be smaller than 1 MB in size. 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.
  2. In Configure OpenID Connect:
    • Login redirect URIs — The Login redirect URI is where Okta sends the authentication response and ID token for the user's sign-in request. The URIs must be absolute URIs. You can specify more than one. As your OIDC application must explicitly request which redirect_uri is used, 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.
    • Optional. Logout redirect URIs — After your application contacts Okta to close the user session, Okta then redirects the user to one of these URIs. The URIs must be absolute URIs. You can specify more than one.
  3. Click Save. This creates the integration and opens the settings page to configure additional options.

Task 2: Configure initial settings (new App Wizard format)

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

The App Integration Wizard for OIDC has three sections:

  1. In General Settings:
    • App integration name — Specify a name for your app integration.
      Info

      Note

      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 is 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 PNG, JPG, or GIF format and be smaller than 1 MB in size. 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.
    • 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.
  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 navigating 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. Instead, you can choose to Limit access to selected groups and use the field to enter the names of specific groups found in your org.
  4. Click Save. This action creates the app integration and opens the settings page to configure additional 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 has the Client ID and Client secret values for your app integration, in case you need to copy them for other configuration work. If required, you can generate a new client secret. Click Edit then click Generate New Client Secret. Click Save to commit your changes.
  • In the General Settings section, you can configure many of the important 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. To prompt the user with a pop-up window to approve the integration's access to specified resources, check the Require consent box. 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.
    • Enter one or more Login redirect URIs where Okta sends OAuth responses.
    • Enter one or more Logout 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 is displayed 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.

      You can use the openid-configuration API endpoint to configure Okta interactions programmatically. When a web application contains the implicit value for grant_types_supported, admins can publish integrations with the Login Initiated By feature. For more information about OIDC clients and the API, see the OpenID Connect API.

    • Enter or change the Initiate login URI used to initiate the sign-in request.
    • Click Save to commit your General Settings changes.

Single page apps

  • The Client Credentials section, has the Client ID for your app integration. It also shows the Client authentication which defaults to using Proof Key for Code Exchange (PKCE). This option ensures that only the client that requested the access token can redeem it.
  • In the General Settings section, you can configure many of the important 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. To prompt the user with a pop-up window to approve the integration's access to specified resources, check the Require consent box. 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.
    • Enter one or more Login redirect URIs where Okta sends OAuth responses.
    • Enter one or more Logout 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 is displayed 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.

      You can use the openid-configuration API endpoint to configure Okta interactions programmatically. When a web application contains the implicit value for grant_types_supported, admins can publish integrations with the Login Initiated By feature. For more information about OIDC clients and the API, see the OpenID Connect API.

    • Enter or change the Initiate login URI used to initiate the sign-in request.
    • Click Save to commit your General Settings changes.

Native apps

  • The Client Credentials section, has the Client ID for your app integration. Also, you can select a Client authentication type:
    • Use PKCE (for public clients) — Recommended for native applications. By requiring a Proof Key for Code Exchange (PKCE), this option ensures that only the client that requested the access token can redeem it.
    • Use Client Authentication — This option is not recommended for distributed native applications. A client secret is embedded in the client and sent with requests to prove the client's identity.
    • Click Save to commit your Client Credentials changes.
  • In the General Settings section, you can configure many of the important 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.
    • Add or remove the user consent for an OIDC integration. To prompt the user with a pop-up window to approve the integration's access to specified resources, check the Require consent box. 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.
    • Enter one or more Login redirect URIs where Okta sends OAuth responses.
    • Enter one or more Logout 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 chose an Expression to create a custom filter on a different group claim. If the value you specify in 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.

Next steps