Enterprise identity provider

OpenID Connect

This document explains how to configure

OpenID Connect

as an external Identity Provider for your application by creating an application at

OpenID Connect

, creating an Identity Provider (IdP) in Okta, testing the configuration, and creating a sign-in button.

---

Learning outcomes

Configure an external IdP so that your users can quickly sign up or sign in to your app using their IdP account.

What you need

• Okta Integrator Free Plan org (opens new window)
• An app that you want to add authentication to. You can create an app integration by using AIW (opens new window) or use an existing one.
• An account

  at the external Identity Provider that you want to use

  .

---

About the connection to the IdP for your app

Okta manages the connection to the IdP for your app. The connection sits between your app and the IdP that authenticates your users. The industry-standard term for this is Inbound Federation. When a user signs in, you can link the user's IdP account to an existing Okta user profile. You can also choose to create a user profile by using Just-In-Time (JIT) provisioning.

Note: Okta also supports other services such as directories and credential providers. See the Okta Integration Network Catalog (opens new window) to browse all integrations by use case.

Create an app at the Identity Provider

At the

OpenID Connect

IdP, create the client application that you want to use for authenticating and authorizing your users.

Use the documentation of the IdP to create a client application.

You also need to add the redirect URI to the appropriate section. The redirect URI sent in the authorize request from the client needs to match the redirect URI in the OIDC IdP. This is the URL where the IdP returns the authentication response (the access token and the ID token). It needs to be a secure domain that you own. This URL has the same structure for most IdPs in Okta and is constructed using your Okta subdomain and then the callback endpoint.

For example, if your Okta subdomain is called company, then the URL would be: https://company.okta.com/oauth2/v1/authorize/callback. If you’ve configured a custom domain in your Okta Org, use that value to construct your redirect URI, such as https://login.company.com/oauth2/v1/authorize/callback.

Include all base domains (Okta domain and custom domain) that your users interact with in the allowed redirect URI list.

Note: If you've built your own custom IdP, you need the client ID and the client secret generated for the IdP. Add the client ID and client secret to the Okta configuration in the next section.

Create an Identity Provider in Okta

To connect your org to the IdP, add and configure that IdP in Okta.

Note: See the Identity Providers API (opens new window) for request and response examples of creating an IdP in Okta using the API.

1. In the Admin Console, go to Security > Identity Providers.

2. Select Add Identity Provider and then select

   OpenID Connect

   IdP. Click Next.

3. In the Configure

   OpenID Connect

   IdP dialog, define the following:

   • Name: Enter a name for the IdP configuration.

   • Scopes: Leave the defaults. These scopes are included when Okta makes an OpenID Connect request to the IdP.

     Note: By default, Okta requires the email attribute for a user. The email scope is required to create and link the user to the Okta Universal Directory.

   • Client ID: Paste the app ID or client ID that you obtained when you configured the IdP in the previous section.

   • Authentication type: Leave the default of Client secret or select Public key/private key to automatically generate a public and private key pair. The public key is available for download when you click Finish.

   • Client Secret: If you're using Client secret as the Authentication type, paste the secret that you obtained in the previous section.

   • Authorize requests: Select Enable signed requests to send request parameters to the OpenID provider as an encoded JWT instead of passing the parameters in the URL.

   • Application context: Early Access To send the app name (app_name) and app ID (app_instance_id) to the IdP, select the Send Okta application context checkbox. Okta sends the app_instance_id and app_name parameters to the IdP. The IdP response to Okta contains the same information as claims in the ID token. Use application context to help external IdPs make more informed, context-aware authentication decisions.

   • Algorithm: Select the algorithm to use for the signed requests from the dropdown list. If you're using the Public key/private key option, you must specify a signing algorithm, for example: RSA256.

     Note: The Algorithm is used to sign the authorize requests and to generate bearer assertions when you use a private/public key pair for /token endpoint authentication.

   In the Endpoints section:

   Add the following endpoint URLs for the OpenID Connect IdP that you're configuring. You can obtain the appropriate endpoints and the required scopes in the well-known configuration document for the IdP (for example, https://{theIdPdomain}/.well-known/openid-configuration).

   • Issuer: The identifier of the OpenID Connect provider. For example, https://{theIdPdomain}/.
   • Authorization endpoint: The URL of the IdP's OAuth 2.0 authorization endpoint. For example: https://{theIdPdomain}/oauth2/v1/authorize
   • Token endpoint: The URL of the IdP's token endpoint for obtaining access and ID tokens. For example: https://{theIdPdomain}/oauth2/v1/token
   • JWKS endpoint: The URL of the IdP's JSON Web Key Set document. This document contains signing keys that are used to validate the signatures from the provider. For example: https://{theIdPdomain}/oauth2/v1/keys
   • Userinfo endpoint (optional): The endpoint for getting identity information about the user. For example: https://{theIdPdomain}/oauth2/v1/userinfo.

   Note: Okta requires an access token returned from the IdP if you add the /userinfo endpoint URL.

   In the optional Authentication Settings section:

   • IdP Username: This is the expression (written in Okta Expression Language) that is used to convert an IdP attribute to the app user's username. This IdP username is used for matching an app user to an Okta user.

     For example, the value idpuser.email means that it takes the email attribute passed by the IdP and maps it to the Okta app user's username property.

     You can enter an expression to reformat the value, if desired. For example, if the social username is john.doe@mycompany.com, then you could specify the replacement of mycompany with endpointA.mycompany to make the transformed username john.doe@endpointA.mycompany.com. See Okta Expression Language.

   • Filter > Only allow usernames that match defined RegEx Pattern: Select this option to only authenticate users with transformed usernames that match a regular expression pattern in the text field that appears. This filters the IdP username to prevent the IdP from authenticating unintended users. Users are only authenticated if the transformed username matches the regular expression pattern.

     Note: When you use Okta for B2B or multi-tenancy use cases, select this checkbox. This helps you scope a subset of users in the org and enforce identifier constraints, such as email suffixes.

     For example, you could restrict an IdP for use only with users who have @company.com as their email address using the following expression: ^[A-Za-z0-9._%+-]+@company\.com.

   • Account Link Policy > Enable automatic linking: Select this option for Okta to automatically link the user's IdP account with a matching Okta account. See Account link.

     If the automatic linking policy is selected, and any validated OIDC JWT is provided, Okta searches the Universal Directory for a user's profile to link. The user profile is found when the IdP username value (email) passed by the IdP matches the Match against value (username). If there's a match, then the user is linked by mapping the required, static sub claim provided in the JWT to that user.

     After an account is linked, any validated JWT token with the same sub claim (which is mapped to the idp.externalId in the IdP profile) is automatically mapped to the same user. This happens regardless of the content of claims in the JWT. Also, the matching happens even if the values for IdP username and Match against no longer result in a match.

   • Auto-link filters: If the automatic linking policy is selected, you can configure linking to users in specific groups, exclude linking to specific users, and exclude linking to admin users. Early Access

     • Include specific groups: Include users in these groups for account linking.

     • Exclude specific users: Exclude these specific users from account linking.

     • Exclude admins: Exclude users who are assigned admin roles or have admin privileges from account linking.

4. Click Finish. A page appears that displays the IdP's configuration.

Note: If you want to use a specific Redirect Domain instead of the Dynamic default, you can use either Org URL or Custom URL. See issuerMode in the Identity Providers API (opens new window).

5. Copy both the Authorize URL and the Redirect URI, and then paste into a text editor for use in upcoming steps. If you’re using a public and private key pair, click Download public key. The key is downloaded in JSON format.

Account link

You can automatically link external IdP accounts to Okta accounts when the user signs in using the external IdP.

When Account Link Policy is set to automatic (AUTO), Okta searches the Universal Directory for a user's profile to link. The user profile is found when the IdP username value (email) passed by the IdP matches the Match against value (username). See Account Linking and JIT Provisioning.

To remove an existing account link or validate account linking with every sign-in flow, Okta recommends that you make a DELETE call to the /api/v1/idps/{idpId}/users/{userId} endpoint (opens new window). This removes the link between the Okta user and the IdP user before authentication.

See Create an Identity Provider (opens new window) for API examples of account-linking JSON payloads.

For security best practices, consider disabling account linking after all existing users from the external IdP have signed in to your Okta org. At this point, all links have been created. After you disable linking, and JIT provisioning is enabled, Okta adds new users that are created in the external IdP.

Test the integration

You can test your integration by configuring a routing rule (opens new window) to use

OpenID Connect

as the IdP.

Alternatively, you can use the authorize URL to simulate the authorization flow. The Okta IdP generates an authorize URL with several blank parameters that you can fill in to test the flow with the IdP. The authorize URL initiates the authorization flow that authenticates the user with the IdP.

Note: Use this step to test your authorization URL as an HTML link. For information on testing your authorization URL using the Sign-In Widget, Okta-hosted sign-in page, or AuthJS, see the next section.

If you're using Authorization Code with PKCE as the grant type, you must generate and store the PKCE. See Implement authorization by grant type. Okta recommends that you use the AuthJS SDK (opens new window) with this grant type.

In the URL, replace {yourOktaDomain} with your org's base URL, and then replace the following values:

• client_id: Use the client_id value that you obtained from the OpenID Connect client app in the previous section. This isn't the client_id from the IdP.

• response_type: Determines which flow is used. For the Implicit flow, use id_token. For the Authorization Code flow, use code.

• response_mode: Determines how the authorization response is returned. Use fragment.

• scope: Determines the claims that are returned in the ID token. Include the scopes that you want to request authorization for and separate each by a space. Include at least the openid scope. You can request any of the standard OpenID Connect scopes about users, such as profile and email, and any custom scopes specific to your IdP.

• redirect_uri: The location where Okta returns a browser after the user finishes authenticating with their IdP. This URL must start with https and must match one of the redirect URIs that you configured in the previous section.

• state: Protects against cross-site request forgery (CSRF). Can be any value.

• nonce: A string included in the returned ID token. Use it to associate a client session with an ID token and to mitigate replay attacks. Can be any value.

For a full explanation of all of these parameters, see: /authorize Request parameters (opens new window).

An example of a complete URL looks like this:

https://{yourOktaDomain}/oauth2/v1/authorize?idp={idp_id}&client_id={client_id}&response_type=id_token&response_mode=fragment&scope=openid%20email&redirect_uri=https%3A%2F%2FyourAppUrlHere.com%2F&state=WM6D&nonce=YsG76jo

Use the Identity Provider to sign in

To test your authorization URL, enter the complete authorization URL in a browser. Do this in your browser's privacy or incognito mode to avoid false positive or negative results.

If everything is configured properly:

• The user is redirected to the IdP's sign-in page.
• After successful authentication, the user is redirected to the redirect URI that you specified, along with an #id_token= fragment in the URL. The value of this parameter is your Okta OpenID Connect ID token.

If something is configured incorrectly, the authorization response contains error information to help you resolve the issue.

There are four primary ways to kick off the sign-in flow.

HTML Link

Create a link that the user clicks to sign in. The HREF for that link is the authorize URL that you created in the previous section:

`<a href="https://{yourOktaDomain}/oauth2/v1/authorize?idp=0oaaq9pjc2ujmFZexample&client_id=GkGw4K49N4UEE1example&response_type=id_token&response_mode=fragment&scope=openid&redirect_uri=https%3A%2F%2FyourAppUrlHere.com%2F&state=WM6D&nonce=YsG76jo">Sign in with Identity Provider</a>`

After the user clicks the link, they're prompted to sign in with the IdP. After the user successfully signs in, the user is returned to the specified redirect_uri along with an ID token in JWT format.

Okta Sign-In Widget

Note: This section only applies to Classic Engine.
If you're using Identity Engine, the Sign in with IdP option is available on the widget. It's available after you create an Identity Provider in your Okta org and configure the routing rule (opens new window). No additional code is required. See Identify your Okta solution (opens new window) to determine your Okta version and Upgrade your widget for upgrade considerations to Identity Engine.

Okta also offers an easily embeddable JavaScript widget that reproduces the look and behavior of the standard Okta sign-in page. You can add a Sign in with {IdentityProviderName} button by adding the following code to your Okta Sign-In Widget configuration:

config.idps= [
  { type: 'IdentityProviderName', id: 'Your_IDP_ID_Here' }
];
config.idpDisplay = "SECONDARY";

You can find out more about the Okta Sign-In Widget on GitHub (opens new window). Implementing a sign-in flow with an IdP uses the widget's OpenID Connect authentication flow (opens new window).

Custom Okta-hosted sign-in page

Note: This section only applies to Classic Engine.
If you're using Identity Engine, the Sign in with IdP option is available on the widget. It's available after you create an Identity Provider in your Okta org and configure the routing rule (opens new window). See Identify your Okta solution (opens new window) to determine your Okta version.

If you configured a Sign-In Widget, you can add a Sign in with {IdentityProviderName} button by adding the following code beneath the var config = OktaUtil.getSignInWidgetConfig(); line:

config.idps= [
  {type: 'IdentityProviderName', id: 'Your_IDP_ID_Here'}
];
config.idpDisplay ="SECONDARY";

AuthJS

If you don't want pre-built views, or need deeper levels of customization, use the same AuthJS SDK that the Sign-In Widget is built with. See the AuthJS GitHub repo (opens new window). Implementing sign in with an IdP uses the SDK's OpenID Connect authentication flow (opens new window).

Next steps

• To map Okta attributes to app attributes, use the Profile Editor (opens new window).

• To add another IdP, start by choosing an external Identity Provider.