On this page
Enterprise Identity Provider
This document explains how to configure
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 Developer Edition organization (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
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
Create an Identity Provider in Okta
To connect your org to the IdP, add and configure that IdP in Okta.
In the Admin Console, go to Security > Identity Providers.
Select Add Identity Provider and then select
In the Configure
Click Finish. A page appears that displays the IdP's configuration.
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.
Test the integration
You can test your integration by configuring a routing rule (opens new window) to use
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 theclient_id
value that you obtained from the OpenID Connect client app in the previous section. This isn't theclient_id
from the IdP.response_type
: Determines which flow is used. For the Implicit flow, useid_token
. For the Authorization Code flow, usecode
.response_mode
: Determines how the authorization response is returned. Usefragment
.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 theopenid
scope. You can request any of the standard OpenID Connect scopes about users, such asprofile
andemail
, 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 withhttps
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.