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

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

    • Redirecting 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 are redirected to the initiate_login_uri of the client application, which constructs an authorization request and redirects the end user back to Okta.
    • Sending 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 is 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 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 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 either 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.
      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.

      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 additional configuration guidance for wildcards.

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

      Caution

      The use of wildcards for subdomains is discouraged, since it may 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.
  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, or Skip group assignment for now and create the app without assigning a group.
  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.
  • 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 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 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 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, 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 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 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 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 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