Add a SAML Identity Provider

Adding a SAML Identity Provider (IdP) is the first step in the process of configuring inbound SAML.

Start this task

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

  2. Click Add Identity Provider, and then select Add SAML 2.0 IdP.

  3. Configure the General Settings. If a View Setup Instructions link appears, click it first. Some providers have their own detailed instructions.

    Name The name that you choose for this IdP.
    Protocol Only SAML 2.0 is supported.

  4. Configure Authentication Settings.

    IdP username The entity in the SAML assertion than contains the username. The drop-down list contains the default value, saml.subjectNameId.

    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 to make the transformed username john.doe@endpointA.mycompany.com. If you want to enter an expression, use the Okta Expression Language syntax.
    Filter Select Filter only 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 against which the transformed username is authenticated.
    Account Link Policy

    Specify whether Okta automatically links the user's IdP account with a matching Okta account.

    For enhanced security, disable account linking if possible. If you need account linking, follow Security best practices.
    Auto-Link Restrictions When automatic account linking is enabled, indicate whether you want to restrict linking to specified user groups.
    If no match is found Specify whether to create a new user account with Just In Time (JIT) provisioning or to redirect the end user to the Okta Sign-In page.

    Note that for the first option, JIT provisioning must be enabled in two places:

    1. On this page, by clicking Create new user (JIT).

    2. In Settings > Customization > Just In Time Provisioning, by clicking Enable Just In Time Provisioning.

  5. Configure JIT Settings.

    Profile Source When this box is selected, existing users are updated with the information in this SAML assertion. Profile information will not push if this box is not selected.
    Reactivation Settings These options are visible if you selected Update attributes for existing users.

    • Reactivate users who are deactivated in Okta: Allow admins to choose if a deactivated Okta user should be reactivated when reactivated in the app.

    • Unsuspend users who are suspended in Okta: Allow admins to choose if a suspended Okta user should be unsuspended when reactivated in the app.
    Group Assignments Specify the groups to which the users in the SAML assertion should be added. Choose one of the options from the drop-down menu. Each option requires different information.

    • None: Do not assign the authenticated users to any groups. No other information is required.

    • Assign to specific groups: Assign each user to the groups listed in the Specific Groups field. You must enter one or more groups in the field.

    • Add user to missing groups: Users are added to any groups in the SAML assertion of which they are not already members. (Users are not removed from any groups of which they are already members.) In the SAML Attribute Name field, enter the name of the SAML attribute (in the attribute statements from the SAML assertion) whose values represent group memberships. Those values are compared to the groups specified in the Group Filter field, and matching values determine the groups to which the user is assigned during JIT. The Group Filter field acts as a security allowlist. List the groups that you want the IdP to assign to users dynamically. This allows you to control which users are assigned to certain groups. You must enter the SAML Attribute Name and list one or more Okta groups in the Group Filter field.

    • Full sync of groups: This option assigns users to the group represented by the attribute specified in the SAML Attribute Name if that group is listed in the Group Filter.

    Note that If the user is a member of any Okta group that does not match the values represented by the attribute in the SAML Attribute Name field, the user is deleted from the Okta group.

  6. Configure SAML Protocol Settings.

    IdP Issuer URI The issuer URI from the IdP.
    IdP Single Sign-On URL The sign-on URL from the IdP. If you sign the authN request by selecting the Request Signature option but do not specify a destination in the Destination field (see Advanced Settings), Okta automatically sends the authN request to the IdP Single Sign-On URL.
    IdP Signature Certificate Certificate from the IdP used to sign the assertion.

  7. Optional. Configure Advanced Settings.

    Request Binding The SAML Authentication Request Protocol binding used by Okta to send SAML AuthNRequest messages to the IdP. Usually HTTP POST.
    Request Signature Specify whether to sign SAML AuthnRequest messages that are sent from Okta. If you sign the authN request by selecting this option, Okta automatically sends the authN request to the URL specified in the IdP Single Sign-On URL field
    Request Signature Algorithm Specify the signature algorithm used to sign SAML authN messages sent to the IdP.
    Response Signature Verification Specify the types of response signatures Okta will accept when validating incoming responses: Response, Assertion, or Response or Assertion.
    Response Signature Algorithm Specify the minimum signature algorithm when validating SAML messages and assertions issued by the IdP: SHA-1 or SHA-256.
    Destination The destination attribute sent in the SAML authN request. If you do not enter a destination and you sign the authN request by selecting the Request Signature option, Okta automatically sends the destination attribute as the URL specified in the IdP Single Sign-On URL field (the SSO URL).
    Okta Assertion Consumer Service URL Specify whether to use a trust-specific assertion consumer service (ACS) URL or one that is shared across the organization.
    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 to verify that the difference is not more than the Max Clock Skew value.

  8. Click Add Identity Provider.

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 these best practices:

IdP configuration

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: Consider disabling account linking after all existing users from the external IdP signed in to your Okta org. At this point, all links were created. After you disable linking, new users that are created in the external IdP are added to Okta by JIT provisioning.

  • 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: ^[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)).)*$

      Allowed users defined by this expression are privileged accounts.

      The expression is not 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.

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

    Configure authentication policy rules to require phishing-resistant authenticators.

Monitoring

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

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

Next steps

Add metadata for an Identity Provider