Add a SAML Identity Provider

Adding a SAML Identity Provider (IdP) is the first step when you configure inbound SAML.

Start this task

1. In the Admin Console, go to SecurityIdentity Providers.

2. Click Add identity provider, and then select SAML 2.0 IdP.
3. Click Next.
4. Configure the General Settings options. If a View Setup Instructions link appears, click it first. Some providers have their own detailed instructions.

   Name	Enter a name for this IdP.

5. Configure the Authentication Settings options.

   IdP Usage	Select an option: SSO only: Use this IdP only for single sign-on. Factor only: Use this IdP only for multifactor authentication.
   Account matching with Persistent Name ID	Select Use Persistent Name ID (Higher Security) to determine the associated user account by matching the Name ID with the External ID. If no match is found, Okta uses the IdP username value for account matching. The incoming assertion must use this format for the Name ID: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent. See Link a User to IdP.

6. Configure the Account matching with IdP Username options.

   IdP username	Select the entity in the SAML assertion that contains the username. You can enter an expression to reformat the value. For example, if the username in the SAML assertion is john.doe@mycompany.okta.com, you could specify the replacement of mycompany.okta with endpointA.mycompany. This makes the transformed username john.doe@endpointA.mycompany.com. To enter an expression, use the Okta Expression Language syntax.
   Filter	Select Only allow usernames that match defined RegEx Pattern if you want to enter an expression as a username filter. Specifying a filter limits the selection of usernames before authentication.
   Match against	Select the field in Okta that the transformed username is authenticated against.
   Account Link Policy	Specify whether Okta automatically links the user's IdP account with a matching Okta account. Disabled: Disable account linking. Automatic: Account linking occurs automatically. For enhanced security, enable Account matching with Persistent Name ID or Account Link Policy for SAML IdPs. See Security best practices.
   Auto-Link Restrictions	When automatic account linking is enabled, indicate whether you want to restrict linking to specific user groups. When you restrict linking to specific user groups, this restriction also applies to any previously linked users unless you use persistent Name ID matching.
   If no match is found	Specify whether to create a user account with Just-In-Time (JIT) provisioning or to redirect the user to the Okta sign-in page. Create new user (JIT): Create user accounts with JIT. If you select this option, you must also go to SettingsCustomizationJust In Time Provisioning and click Enable Just In Time Provisioning. Redirect to Okta sign-in page: Redirect the user to the Okta sign-in page to create their account.

7. Configure the JIT Settings options.

   Profile Source

   Select Update attributes for existing users to update user accounts with the information in this SAML assertion. Profile information isn't pushed if you don't select this checkbox.

   Group Assignments

   Select an option to specify the groups you want to add the users in the SAML assertion to: None: Don't assign the authenticated users to any groups. No other information is required. Assign to specific groups: Assign users to groups. The Specific Groups field appears. Enter the name of the group that you want to add users to. Okta displays group names that match your text. Select the group that you want to add. Repeat these steps to add more groups. Add user to missing groups: Add users to any groups in the SAML assertion that they don't already belong to. Users aren't removed from any groups they already belong to. The SAML Attribute Name field appears. Enter the name of the SAML attribute whose values represent group memberships. The values appear in the attribute statements from the SAML assertion. Those values are compared to those in the Group Filter field. Matching values determine which groups the user is assigned to during JIT. The Group Filter field acts as a security allowlist. Enter the name of the group that you want to add users to. Okta displays group names that match your text. Select the group that you want to add. Repeat these steps to add more groups. Full sync of groups: Assign users to the group represented by the attribute specified in the SAML Attribute Name field. Ensure that this group appears in the Group Filter field. If the user is a member of any group that doesn't match the values in the SAML Attribute Name field, the user is deleted from the group.

8. Configure the SAML Protocol Settings options.

   IdP Issuer URI	Enter the issuer URI from the IdP.
   IdP Single Sign-On URL	Enter the sign-on URL from the IdP. If you select Sign SAML Authentication Requests but don't specify a destination in Destination, Okta automatically sends the authorization request to the IdP Single Sign-On URL.
   IdP Signature Certificate	Upload the certificate from the IdP that's used to sign the assertion. Click Browse files, select the certificate file, and then click Open.
   Request Binding	Select the SAML Authentication Request Protocol binding that Okta uses to send SAML authorization request messages to the IdP. HTTP POST: Select the HTTP POST method. HTTP REDIRECT: Select the HTTP REDIRECT method.
   Request Signature	Select Sign SAML Authentication Requests to sign SAML authorization request messages that Okta sends. If you select this option, Okta automatically sends the authorization request to the URL specified in the IdP Single Sign-On URL field.
   Request Signature Algorithm	Select the signature algorithm that Okta uses to sign the SAML authorization messages that it sends to the IdP: SHA-1: Select the SHA-1 algorithm. SHA-256: Select the SHA-256 algorithm.
   Response Signature Verification	Select the type of response signatures Okta accepts when validating incoming responses: Response Assertion Response or Assertion
   Response Signature Algorithm	Select the signature algorithm that Okta uses to validate the SAML messages and assertions that it receives from the IdP: SHA-1: Select the SHA-1 algorithm. SHA-256: Select the SHA-256 algorithm.
   Destination	Enter the destination attribute that Okta sends in the SAML authorization request. If you don't enter a destination and you select Sign SAML Authentication Requests, Okta automatically sends the destination attribute as the URL specified in the IdP Single Sign-On URL field.
   Okta Assertion Consumer Service URL	Select an option to specify whether to use a trust-specific assertion consumer service (ACS) URL or one that is shared across the organization. Trust-specific Organization (shared)
   Max Clock Skew	Specify how long the assertion is valid. Enter a number and select the units. The authentication process calculates the difference between the current time and the time on the assertion timestamp. Okta verifies that the difference isn't more than the Max Clock Skew value.

9. Click Finish.

Send Okta metadata

After you create an IdP, click Download metadata to access the Okta SAML metadata for this provider. Follow the IdP's instructions to provide metadata to them.

Security best practices

If you enable account linking, consider the following these best practices:

• Configure an IdP

• Authentication policies

• Monitor events in the System Log

Configure an IdP

Use these settings:

• Group Assignment: Specify the groups that you created for each external IdP.

• If no match is found: Select Create new user (JIT) to provision users into your Okta org.

• Account Link Policy: Strict account linking is enforced. This helps match the incoming user from the IdP to the correct user in Okta. For SAML IdPs, enable Account matching with Persistent Name ID. Otherwise, select Account Link Policy.

• Filter: Select Only allow usernames that match defined RegEx Pattern.

  • If users from an external IdP have a different username domain than users from the Okta org, use a Regex pattern such as this example:

    ^[A-Za-z0-9._%+-]+@spokedomain\.com

  • If all users share the same domain, use a Regex pattern that excludes specific users. The list should include all known administrators in your Okta org. To allow any user except the ones explicitly mentioned, use this expression:

    ^((?!(admin\.user\.1@company\.com|admin\.user\.2@othercompany\.com)).)*$

    Users created by this expression are privileged accounts.

    The expression isn't dynamically updated. If new administrators or privileged users are created in your Okta org, you must update the expression manually.

Authentication policies

• Prevent Okta admins from signing in to the parent org through federation from an external IdP. Create a global session policy to deny access for users in the Okta Administrators group if they're from an external IdP. You can select multiple IdPs. Set this policy to be evaluated first.
• Prevent access to the Admin Dashboard for any users who sign in through federation from an external IdP. Create an authentication policy for each external IdP. Configure the policy to deny access to selected apps, such as the Admin Dashboard. You can restrict access to any sensitive apps.
• If possible, require all Okta admins to use phishing-resistant authenticators. Create a global session policy to require multifactor authentication (MFA) for the Okta Administrators group. Configure authentication policy rules to require phishing-resistant authenticators.

  Users with custom admin roles are considered part of the Okta Administrators group. Therefore, users with custom admin roles are included in policies that affect Okta Administrators.

Monitor events in the System Log

Use the System Log to review authentication events through the IdP.

Search for eventType eq "user.authentication.auth_via_IDP" and review events that have an Okta System (SystemPrincipal) actor and an end user target. These events indicate that an account linking operation occurred. If the target user is a privileged user or an administrator, review all events to ensure that any potential incidents are addressed.

Next steps

Add metadata for an Identity Provider