In addition to using Okta as an identity provider (IdP), you can also configure Okta as a service provider (SP). When Okta is used as a service provider, it integrates with an identity provider outside of Okta using SAML. Inbound SAML allows users from external identity providers to SSO into Okta.
This document includes the following topics:
Supported Encryption Algorithms
Entering Setup Information
Part 1: Add an Identity Provider
SAML Protocol Settings
Part 2: Send Okta Metadata
Part 3: Add Metadata
Part 4: Configure UD Mappings
Using the System Log
Inbound SAML allows you to set up the following scenarios.
- Your users can SSO into apps without needing an Okta password.
- You do not need to set up an Active Directory (AD) agent.
- You can connect to a partner.
- You can federate with another IdP.
When you connect your users to Okta with Inbound SAML, there are several customization options.
- Your users can SSO into Okta with no provisioning; that is, the users are mastered in Okta.
- Your users can be provisioned into Okta with Just In Time (JIT) provisioning that is managed by an IdP.
- Your users can be assigned to groups with JIT.
Okta has added several new capabilities to Inbound SAML.
- Inbound SAML is now built on Universal Directory (UD). You have the ability to feed richer assertions to UD, as UD can store attributes from an incoming assertion.
- You now have more control over JIT provisioning. A per-IdP toggle allows you to enable/disable JIT provisioning on a per-IdP trust basis.
- There is now username filtering to enhance security. You can specify an analyzing username suffix that must be matched.
- You can define any number of identity providers and define an unlimited number of attributes for each provider with UD. You are no longer limited to the first name, last name, email, and phone attributes.
- Inbound SAML now supports encrypted assertions.
- Inbound SAML now allows you to use a shared ACS URL instead of a trust-specific ACS URL.
- Inbound SAML now supports configurable signature algorithm requirements and configurable clock skew.
Supported Encryption Algorithms
Inbound SAML transparently supports encrypted SAML assertions. The IdP can encrypt using the public certificate from Okta and any of the following XML encryption algorithms.
Entering Setup Information
Certain information that you need to complete setup may not be available at the time that you are filling in the form. The following chart shows a typical information flow.
For example, when you are setting up the IdP in Okta, sometimes the Issuer, Login URL, and Certificate are not available from the IdP until the ACS URL and Audience are set up in the IdP. And, that information is also not available until Okta is configured.
Recommendation: If the IdP requires information from Okta for setup before you have the information, enter any text for the Issuer in Okta and enter https:url for the Login URL in Okta. Add the Identity Provider in Okta. Then, use the ACS URL and Audience that become available in Okta to set up the IdP. Finally, edit the Identity Provider that you just set up in Okta and enter the appropriate Issuer and Login URL information.
There are four parts to setting up inbound SAML.
- Add an Identity Provider
- Send the Okta SAML metadata to the existing IdP.
- Add the IdP metadata to Okta.
- Configure UD mappings for the inbound SAML connection.
On the Okta Dashboard, navigate to Security > Identity Providers. Click Add Identity Provider.
There are four sections on the Add Identity Provider form. Be sure to complete all the sections.
- Name – The name that you choose for this identity provider.
- Protocol – Only SAML 2.0 is supported.
- IdP username – The entity in the SAML assertion than contains the username. The dropdown list contains the default value, idpuser.subjectNameId.
You can enter an expression to reformat the value, if desired. For example, if the username in the SAML assertion is firstname.lastname@example.org, 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, follow the Okta Expression Language link for syntax requirements.
- Filter – Select only if you want to enter an expression as a username filter. Specifying a filter limits the selection of usernames before authentication.
- Match against – The field in Okta against which the IdP username is authenticated. Choose an option from the dropdown menu.
More user profile attributes are available for matching as an Early Access feature. To enable more choices, contact Support.
- If no match is found – Specify whether to provision the user with Just In Time (JIT) provisioning, or to redirect the user to the Okta Sign On page if the user is not found.
Note: Be sure to enable JIT provisioning by navigating to Security > Authentication > JIT Provisioning. You must enable JIT here and on that page.
- Profile Master – If an authenticated user exists, the user is updated with the information in this SAML assertion when this box is selected. If this box is not selected, the flow continues without updating information.
- Group Assignment Settings – Specify the groups to which the users in the SAML assertion should be added. Choose one of the options from the dropdown menu. Each option requires different information.
Group Assignment Option 1: None
Do not assign the authenticated users to any groups. No other information is required.
Group Assignment Option 2: Assign to specific groups
Assign each user to the group(s) listed in the Specific Groups field. You must enter one or more groups in the field.
Group Assignment Option 3: Add user to missing groups
If you select this option, 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 whitelist field (below), and matching values determine the group(s) to which the user is assigned during JIT.
The Group Filter field acts as a security whitelist. 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.
Group Assignment Option 4: 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. If the user is a member of any Okta group specified in the Group Filter field that does not match the values represented by the attribute in the SAML Attribute Name field, the user is deleted from the Okta group. You must enter the SAML Attribute Name and list one or more Okta groups in the Group Filter field.
SAML Protocol Settings
- IdP Issuer URI – The issuer. The IdP provides this value.
- 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.
- Request Binding – The SAML Authentication Request Protocol binding used by Okta to send SAML AuthNRequest messages to the IdP. Usually HTTP POST.
- Request Signature – Specifies 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 – Specifies the signature algorithm used to sign SAML authN messages sent to the IdP.
- Response Signature Verification – Specifies the type(s) of response signatures Okta will accept when validating incoming responses: Response, Assertion, or Response or Assertion
- Response Signature Algorithm – Specifies 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 – Specifies whether to use a trust-specific assertion consumer service (ACS) URL or one that is shared across the organization.
- Max Clock Skew – Sets 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.
When done, be sure to click Add Identity Provider to save the configuration.
After you create an Identity Provider, the following information is displayed on the Security > Identity Providers page. Click the Download metadata link to access the Okta SAML metadata for this provider. Follow instructions from the IdP to provide them the metadata.
If you need to update any information from the IdP, you can always open the Add Identity Provider dialog box and make the necessary changes. Select the pencil icon to edit an existing provider. Enter the logon URL and issuer that was provided by the IdP, as described in SAML Configuration above.
Inbound SAML works with the Universal Directory (UD) setup for your organization. You can customize the UD mappings for each identity provider. For more information on UD, see About Universal Directory. This part of the setup is optional.
To modify the UD mappings for a created identity provider, click Configure for that identity provider on the Security > Identity Providers screen, and then select Edit Mappings in the dropdown menu.
Note: The Edit Profile and Edit Mappings options are not available in the SSO and Legacy SSO 2013 editions of the platform.
When you select Edit Mappings, the Profile Editor opens. An alternate path to this screen is available. Navigate to the Directory > Profile Editor screen and select Profile Mappings. Click the down arrow next to Identity Providers, as shown below.
All the identity providers that you have added are displayed, as shown below. Click on the provider to edit.
When you select the provider name, the provider information is shown in the right panel, as shown below:
There are three options in this panel:
- Click on an attribute to display attribute information on the right. Make any permitted changes.
- Add an attribute. There are four default custom attributes. To add more, click Add Attribute. For detailed instructions, see Adding Custom Attributes in About Universal Directory.
- You can customize the mapping between the identity provider and Okta by clicking Map Attributes. For detailed instructions, see Mappings in About Universal Directory.
Using the System Log
The System Log (Reports > System Log
) provides information about the Inbound SAML events that occur in the system. This information can be useful for debugging your configuration. For more information, see Using the Okta Reports Page
After you complete any necessary changes to the UD mappings, your system is now configured to accept inbound SAML connections.