Enterprise Identity Provider

SAML

This document explains how to configure

SAML

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

SAML

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

---

Learning outcomes

Configure an external Identity Provider so that your users can quickly sign up or sign in to your application using their Identity Provider account.

What you need

• Okta Developer Edition organization (opens new window)
• An application that you want to add authentication to. You can create a new app integration using AIW (opens new window) or use an existing one.
• An account

  at the external SAML Identity Provider that you want to use

  .

---

About the connection to the IdP for your application

Okta manages the connection to the IdP for your application. The connection sits between your application 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 Identity Provider account to an existing Okta user profile or choose to create a user profile using Just-In-Time (JIT) provisioning.

Note: Okta also support 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

SAML

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

Access the external SAML Identity Provider (IdP) you want to integrate with and gather the following information. You use this information to configure the SAML Identity Provider in Okta in the next step. Make sure the SAML IdP supports Service Provider-initiated SAML.

Note: If you need a quick and easy SAML IdP to use for testing purposes, you can try using this SAML Identity Provider on GitHub (opens new window).

Sometimes the Issuer, Single Sign-On URL, and Certificate aren't available from the external IdP until the metadata (the Assertion Consumer Service URL (ACS URL) and Audience URI) is uploaded to the external IdP. And, the ACS URL and Audience URI values aren't available until the IdP in Okta is configured. If that is the case with your external IdP, continue to the next step.

• IdP Issuer URI: The issuer URI of the IdP. This value is usually the SAML Metadata entityID of the IdP EntityDescriptor.
• IdP Single Sign-On URL: The binding specific IdP authentication request protocol endpoint that receives SAML AuthN Request messages from Okta.
• IdP Signature Certificate: The PEM or DER encoded public key certificate of the Identity Provider used to verify SAML message and assertion signatures.

Note: When you add the attribute statement for the client app at the SAML IdP, be sure to add session.amr as an attribute and session.amr as the value. This allows Okta to accept Authentication Method Reference (AMR) claims sent in the SAML IdP response. Early Access

Create an Identity Provider in Okta

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

Note: See the Identity Providers API for request and response examples of creating an Identity Provider in Okta using the API.

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

2. Select Add Identity Provider and then select

   SAML 2.0

   IdP. Click Next.

3. In the Configure

   SAML 2.0

   IdP dialog, define the following:
   • Name: Enter the name that you would expect to see on a button, such as Sign in with

     SAML

     2.0.

   In the Authentication Settings section:

   • Authentication method reference (AMR) claims: Select Trust AMR claims from this identity provider to have Okta evaluate that AMR claims sent in the IdP response meet sign-on policy requirements. Early Access

     Note: Ensure that the IdP includes the correct AMR claims in the IdP response and that the claims match the requirements of your sign-on policies. If the claims don't satisfy the requirements, then users can't sign in to the application.

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

     For example, the value idpuser.subjectNameId means that it takes the subject's username, from the SAML assertion passed by the Identity Provider, and maps it to the Okta application 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 for more information.

   • 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: Specify whether Okta automatically links the user's IdP account with a matching Okta account. See Account link.

   In the

   SAML

   Protocol Settings section:

   When you set up an IdP in Okta, sometimes the Issuer, Single Sign-On URL, and Certificate values aren't available from the external IdP. This information may not be available until the metadata is uploaded to the IdP. Futhermore, the ACS URL and Audience URI values aren't available until the IdP in Okta is configured.

   Okta recommends that if the external IdP requires information from Okta for setup before you have that information, do the following:

   • Enter any text for the IdP Issuer URI.
   • Enter https://URL for the IdP Single Sign-On URL.
   • Upload a temporary certificate.

   After you upload the metadata to the external IdP in the next step, you can edit the IdP in Okta. Then, you can enter the appropriate IdP Issuer URI, IdP Single Sign-On URL, and Certificate information.

   • IdP Issuer URI: The issuer. The Identity Provider provides this value.

   • IdP Single Sign-On URL: The sign-on URL from the Identity Provider. If you sign the authN request by selecting the Request Signature option, but don't specify a Destination, Okta automatically sends the authN request to the IdP SSO URL.

   • IdP Signature Certificate: Click Browse files to upload the certificate from the Identity Provider used to sign the assertion.

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

• Save the value at the end of the Assertion Consumer Service URL (ACS URL). The string after the last slash is the Identity Provider's id value. For example, if your ACS URL is https://{yourOktaDomain}/sso/saml2/0adb8rlfooi5Atqv60h7, then your Okta Identity Provider's id is 0adb8rlfooi5Atqv60h7.

• Save the Audience URI value, and then download the metadata by clicking Download metadata. The metadata URL is similar to this: https://{yourOktaDomain}/api/v1/idps/{idpId}/metadata.xml.

• Follow the SAML IdP instructions on how to upload the metadata. If your IdP doesn't support uploading metadata, enter the ACS URL and Audience URI values at the IdP manually.

Account link

You can automatically link external IdP accounts to Okta accounts when the user signs in using the external IdP. If 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 to remove the link between the Okta user and the IdP user before authentication.

If Account Link Policy is disabled, no account linking occurs. You can manually create an account link without a transaction by making a POST call to the /api/v1/idps/{idps}/users/{userId} endpoint.

See Add an Identity Provider 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

SAML

as the Identity Provider.

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 Identity Provider.

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 application in the previous section. This isn't the client_id from the Identity Provider.

• 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 Identity Provider.

• redirect_uri: The location where Okta returns a browser after the user finishes authenticating with their Identity Provider. 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.

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 Identity Provider'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 Identity Provider. After successful sign 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 Okta Classic Engine.
If you're using Okta Identity Engine, the Sign in with IdP option is available on the widget 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 sign in with an Identity Provider uses the Widget's OpenID Connect authentication flow (opens new window).

Custom Okta-hosted sign-in page

Note: This section only applies to Okta Classic Engine.
If you're using Okta Identity Engine, the Sign in with IdP option is available on the widget 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, then you can use the same AuthJS SDK that the Sign-in Widget is built with. For further information see the AuthJS GitHub repo (opens new window). Implementing sign in with an Identity Provider uses the SDK's OpenID Connect authentication flow (opens new window).

Next steps

You should now understand how to add an external Identity Provider and have successfully added and tested the integration.

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

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