Identity Providers Skip to main content
https://support.okta.com/help/oktaarticledetailpage?childcateg=&id=ka02a0000005uh7saa&source=documentation&refurl=http%3a%2f%2fsupport.okta.com%2fhelp%2fdocumentation%2fknowledge_article%2fidentity-providers-1257079263
How satisfied are you with the Okta Help Center?
Thank you for your feedback!
How satisfied are you with the Okta Help Center?
1
2
3
4
5
Very Dissatisfied
Very satisfied
Enter content less than 200 characters.
Average Rating:
Identity Providers
Published: Jan 31, 2018   -   Updated: May 15, 2018

okta-doc-source

Identity Providers

The Identity Providers page allows you to do the following:

Add a Social Identity Provider

This is an Early Access feature. To enable it, please contact Okta Support.

Adding a Social Identity Provider in Okta allows your end users to self-register with your custom applications by first authenticating through their existing social identity accounts such as Facebook, Google, or LinkedIn. For new users of your custom app, you can configure Okta to create a Just In Time (JIT) Okta user profile based on attributes stored in your end users' social profiles.

To add a social identity provider, click Add Identity Provider, and then select a social IdP. Detailed information is available on the Social Authentication article on the Okta Developer Site.

Key Benefits of Social Authentication

  • No need to build and maintain your own user database, engineer a sign-on and authentication infrastructure, or manage usernames and passwords.
  • Ensure quick and easy self-registration to your custom applications.
  • Okta profiles are updated automatically when your users update their social profiles.
  • Users do not need to remember an additional password.
Configure Inbound SAML

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.

The System Log provides information about the Inbound SAML events that occur in the system. This information can be useful for debugging your configuration.

Overview

Supported Scenarios

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.

Customization Options

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.

Capabilities

  • Because Inbound SAML is built on Universal Directory (UD), you can store rich attributes in Okta from incoming assertions.
  • Define any number of identity providers and define an unlimited number of attributes for each provider using the Profile Editor. You are not limited to just the first name, last name, email, and phone attributes
  • Control over JIT provisioning. A per-IdP toggle allows you to enable/disable JIT provisioning on a per-IdP trust basis.
  • Username filtering to enhance security. You can specify an analyzing username suffix that must be matched.
  • Support for encrypted assertions.
  • Support for both a shared ACS URL or a trust-specific ACS URL.
  • Support for configurable signature algorithm requirements and configurable clock skew.

Supported Algorithms

The following algorithms are supported for inbound SAML.

Encryption

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.

Digest

Signature

Canonicalization

Transform

About 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.

Inbound_1

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.

Workflow

There are five parts to setting up inbound SAML:

Part 1 – Add a SAML Identity Provider
  1. Go to Security > Identity Providers.
  2. Click the Add Identity Provider button.
    1. From the modal, configure the following.
      General Settings

      There are detailed instructions for some providers. If a View Setup Instructions link appears, follow it for these instructions..

      Name: The name that you choose for this identity provider.

      Protocol: Only SAML 2.0 is supported.

      Authentication Settings

      IdP username: The entity in the SAML assertion than contains the username. The dropdown list contains the default value, saml.subjectNameId.

      You can enter an expression to reformat the value, if desired. 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 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 Transform username is authenticated. Choose an option from the dropdown menu.

      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.

      Warning:

      Please note that JIT provisioning must be enabled in two places:

      • This modal, by clicking the Create new user (JIT) radio button, and
      • Navigating to Settings > Customization > Just In Time Provisioning and clicking the Enable Just In Time Provisioning button.
      JIT Settings

      Profile Master: When enabled, existing users are updated with the information in this SAML assertion. Profile information will not push if this box is not selected.

      Update attributes for existing users - Choose how Inbound SAML should handle sign on for deactivated or suspended end-users in Okta.

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

      Unsuspend users who are suspended in Okta: Allows admins to choose if a suspended Okta user should be unsuspended when reactivated in the app.

      Group Assignment Settings: 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.

      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.

      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: 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.

  1. Click Add Identity Provider to save the configuration.
Part 2 – Send Okta Metadata

After you create an Identity Provider, click the Download metadata link to access the Okta SAML metadata for this provider. Follow instructions from the IdP to provide them the metadata.

Part 3 – Add 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.

If you are asked by the SP to provide the IDP.XML file, the needed information can be acquired from the partially configured app. This metadata is dynamically generated at app creation.

  1. Add a SAML Template App to your org.
  2. On the General Settings screen enter all known information. For fields that are not yet known, type PLACEHOLDER.
  3. Select Next.
  4. Do not assign the app to any users, select Next.
  5. Select Done.
  6. Select the Sign On tab.
  7. In the Settings subsection, locate the SAML 2.0 checkbox and click the link beneath it that says, "SAML 2.0 setup instructions for Template SAML 2.0 App."

    CAUTION - This information is dynamically generated. If you provide this metadata to your SP, you MUST use this template app to perform your integration. If testing requires a new app be made, the newly generated metadata will need to be provided to the SP again.

  8. The necessary information is at the bottom of the new page under the section Configuration Data.
  9. The needed info to configure the SP endpoint is in block 1-3. Alternatively, the IdP metadata in block 4 contains the information as well and can be saved as an XML file (i.e. IDP.XML)
Part 4 – Configure UD Mappings

Inbound SAML works with the Universal Directory (UD) that is set up for your organization. You can customize the UD mappings for each identity provider. This part of the setup is optional.

To modify the UD mappings for a created identity provider, click Configure for that identity provider, 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 from Directory > Profile Editor > Profile Mappings. Click the down arrow next to Identity Providers.

All the identity providers that you have added are displayed. Click on the provider to edit.

When you select the provider name, the provider information is shown in the right panel. 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.
  • You can customize the mapping between the identity provider and Okta by clicking Map Attributes.
Part 5 (optional) – Specify a default IdP and configure an error page URL
  1. Go to Security > Identity Providers.
  2. Click the gear icon next to the Add Identity Provider button.
  3. Configure settings:
  • Default Identity Provider: Enter the name of the IdP that you want to designate as the default endpoint to which unauthenticated users are redirected for authentication.
  • Error Page URL: Specify the error page to which users are redirected in case Okta fails to process a social IdP login, Inbound SAML assertion, or IWA SSO token.
    • Default Okta error page: Users are redirected to the default Okta error page.
    • Custom error page: Users are redirected to the fully qualified URL of your custom error page. This option is useful if you embed Okta into your solution and you want to control end-to-end branding to enhance the end user experience. The custom error page you specify applies to all IdP and IWA users in your organization.

      Note: The custom error page setting does not apply to login failures caused by an unknown user or a JIT failure. In these cases, users are redirected to their Okta sign-in page. Also, the ability to redirect users to a custom URL in the event of failed IWA logins is an Early Access feature. To enable it, contact Okta Support.

  1. Click Save.
Add a Smart Card

You can specify a Smart card as an identity provider by clicking the Add Identity Provider button and choosing it from the list. To add a Smart card, you must provide a name, the certificate chain, and specify the amount of time for Okta to consider the CRL valid after a successful download, as shown below.

add_smart_card

Add a PIV Card

This is an Early Access feature. To enable it, please contact Okta Support.

The Smart Card feature in Okta allows your end users to use smart cards with a x.509 compliant digital certificate, such as a PIV card, as a primary authentication factor to sign in to Okta.

PIVCard1

A personal identity verification (PIV) card is a United States federal smart card that contains the necessary data for the cardholder to be granted to federal facilities and information systems and assure appropriate levels of security for all applicable federal applications. PIV cards are very strong authenticators (up to LOA 4, per NIST guidance), which can replace the username and password as an authentication method where supported.

Setup

Format a PKI Certificate Chain

If your are using more than one certificate, follow this procedure to combine them into a single file.

  1. Convert DER encoded root and intermediate certificates (with .cer, .crt extension) into PEM format using the following openssl command: openssl x509 -inform der -in $input-cert-file-name -out $out-cert-file-name-with-pem-extension
  2. Concatenate all the PEM certificates into a single file with root certificate being the last one using the following command: cat $intermediate-cert-file-1 ... $intermediate-cert-file-N $root-cert-file-with-pem-extension > trust-chain.pem

    Important: Be sure the root certificate is last.

  3. Upload trust-chain.pem when creating the the Smart Card Identity Provider and make sure that no other Smart Cards IDPs exist.

Enable PIV Authentication

  1. Download the certificate chain for the Certificate Authority that issued your organization's smart cards. This should be in PEM or DER format, and if there are multiple certs in the chain, they should be in a single .DER or .PEM file, appended in order with the root certificate last, as described above.
  2. Sign in to Okta as an admin and navigate to Security > Identity Providers.
  3. Click Add Identity Provider and select Add Smart Card from the drop down.
  4. On the Add Identity Provider screen, enter information for your organization.
    • Name: Enter the Friendly Name of this Identity Provider.
    • Certificate Chain: Click Browse files... to launch a file picker. Choose the certificate chain for the issuing authority.
    • IdP Username: Specify which attribute of the certificate should be used to locate the Okta user. There are two options: idpuser.subjectAltNameUpn and idpuser.subjectAltNameEmail.
    • Match Against: To log a user into Okta a user account must already exist and either the email address or the Okta login name must match the attribute or expression defined above. In this field, choose which Okta attribute against which Okta should match. The options are Email, Okta Username, or Email or Okta Username.
    • PIVCard2

      attribute_matchine_default

      This is an Early Access feature. To enable it, please contact Okta Support.

      The IDP Extensible Matching feature allows you to choose from a list of custom attributes to use for matching. If this feature is enabled, the screen shown below appears.

      attribute_matchine_extended

      Note: With this feature, the "Okta Username or Email" combination is not available.

  5. Click Add Identity Provider or Save to continue. The org is now configured to accept PIV cards as an alternate form of authentication.

Sign in with a PIV card as an end user

  1. Ensure that your PIV Card reader is plugged in and your PIV card is inserted.
  2. In a fresh browser session, navigate to the Okta login page for your Okta org and click PIV Card on the login page.
  3. The browser will present a certificate picker. Choose the certificate with the Smart Card Logon value under the Enhanced Key Usage attribute. You might have to view more certificate details to find the right certificate.
  4. The browser will prompt for the end user's PIN. Enter the Pin and hit Enter or click OK.
  5. Okta will sign you in to your end user dashboard. Note: if your org has an MFA policy configured, you will be prompted for the configured authentication factor first.
Troubleshooting

If the log in fails, check the following items:

  1. Make sure that the Subject Alternate Name or expression result matches the Okta attribute that you specified. It must be either email or Okta username.
  2. Ensure that the entire certificate chain of issuers is uploaded in the correct format. See Format the PKI Certificate Chain, above for formatting instructions.
  3. Check that the user has an account in an active state. The user can be in a password reset state; however, the user must be activated.
  4. Always start with a brand new browser session to avoid caching issues. Close out all browser windows before testing the feature.
  5. Test the accessibility of CRL endpoints.

    Okta requires access to the Certificate Revocation List distribution points on a perpetual basis for PIV card authentication to work. This access is necessary so that Okta can verify that the certificate that the end user is presenting is not revoked, expired, or otherwise not trustworthy. Revocation checking is a critical process to ensure the security of PIV Authentication. Typically, Certificate Revocation Lists are posted in a publicly reachable HTTP location on the internet, but in some highly secure environments, the revocation iendpoints are not public.

    To verify that the CRL is posted in a location where Okta can reach it, copy the Certificate Revocation List Endpoint URL from the client's public X.509 certificate (that ends in .crl) and paste it into a browser on an off-network device. If the CRL is accessible, the .crl file will automatically download. If the URL returns a 401 error, then it is not public, and the Okta service cannot to access the endpoints, either. For more information, see Configuring Firewall Whitelisting. Ensure that the Okta IPs can access the CRL distribution point over HTTP.

    Revocation checking occurs for every certificate in the chain. It might be necessary to repeat this process for each intermediate certificate in the PKI chain.

  6. If your are using more than one certificate, follow this procedure to combine them into a single file.
    • Convert DER encoded root and intermediate certificates (with .cer, .crt extension) into PEM format using the following openssl command: openssl x509 -inform der -in $input-cert-file-name -out $out-cert-file-name-with-pem-extension
    • Concatenate all the PEM certificates into a single file with root certificate being the last one using the following command: cat $intermediate-cert-file-1 ... $intermediate-cert-file-N $root-cert-file-with-pem-extension > trust-chain.pem
    • Important: Be sure the root certificate is last.
    • Upload trust-chain.pem when creating the the Smart Card Identity Provider and make sure that no other Smart Cards IDPs exist.

Post a Comment