The Identity Providers page allows you to do the following:
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, Microsoft, 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.
You can use Social IdPs like Facebook and Google as target IdPs within IdP Discovery Routing Rules. For more information about IdP Discovery, see Identity Provider Discovery.
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.
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.
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 additional 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.
- You can enable or disable automatic account linking between SAML identity providers and Okta. You could also restrict automatic account linking based on whether the Okta user is a member of any specified groups.
- 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.
The following algorithms are supported for inbound SAML.
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.
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.
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. 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 five parts to setting up inbound SAML:
- Go to Security > Identity Providers.
- Click Add Identity Provider and select Add SAML 2.0 IdP.
- In the dialog box, configure the following.
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 email@example.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.
Account Link Policy: Specify whether Okta will automatically link the user's IdP account with a matching Okta account.
Auto-Link Restrictions: When automatic account linking is enabled, indicate whether you want to restrict linking to specified user groups.
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.
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.
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 that does not match the values represented by the attribute in the SAML Attribute Name field, the user is deleted from the Okta group.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 Authentication Context: Specifies the context of the authentication request. For example, if you are configuring a SAML-based IdP in the context of a Device Trust flow, select Device Trust.
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.
- In the dialog box, configure the following.
- Click Add Identity Provider to save the configuration.
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.
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.
- Add a SAML Template App to your org.
- On the General Settings screen enter all known information. For fields that are not yet known, type PLACEHOLDER.
- Select Next.
- Do not assign the app to any users, select Next.
- Select Done.
- Select the Sign On tab.
- 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.
- The necessary information is at the bottom of the new page under the section Configuration Data.
- 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)
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.
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.
You can specify an error page to which users are redirected in case Okta fails to process a social IdP login, inbound SAML assertion, or IWA SSO token.
- Go to Security > Identity Providers.
- Click the gear icon next to the Add Identity Provider button.
- Configure settings:
- Use the default Okta error page: Users are redirected to the default Okta error page.
- Use a 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.
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.
- Click Save.
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.
You can add multiple Smart Card/PIV identity providers depending upon the number of CA chains required.
When a user authenticates using a Smart Card, Okta checks each configured identity provider within the org and determine if the user certificate belongs to one of them.
Please confirm with Okta that this feature is enabled for your org.
About PIV Cards
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 IAL3/AAL3, per NIST guidance), which can replace the username and password as an authentication method where supported.
Add and Configure a Smart Card
You can add a Smart Card/PIV identity provider by clicking the Add Identity Provider button and choosing it from the list. To add a Smart Card identity provider, 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.
Format a PKI Certificate Chain
If you 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.
trust-chain.pemwhen creating the the Smart Card Identity Provider and make sure that no other Smart Cards IDPs exist.
Enable Smart Card/PIV Authentication
- 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.
- Sign in to Okta as an admin and navigate to Security > Identity Providers on the main menu.
- Click Add Identity Provider and select Add Smart Card from the drop down.
- 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.
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.
With this feature, the "Okta Username or Email" combination is not available.
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 Smart Card/PIV Card as an end user
- Ensure that your Smart Card/PIV Card reader is plugged in and your Smart Card/PIV Card is inserted.
- In a fresh browser session, navigate to the Okta login page for your Okta org.
- On the login page, click Sign in with PIV / CAC Card.
If presented with the PIV/CAC card dialog, ensure your card reader is properly connected and your PIV/CAC card is inserted.
- 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.
- The browser will prompt for the end user's PIN. Enter the Pin and hit Enter or click OK.
Okta will sign you in to your end user dashboard.
If your org has an MFA policy configured, you will be prompted for the configured authentication factor first.
The following process is followed to validate client certificates:
- A client certificate is provided as described in step 6 of the Sign in with a Smart Card/PIV Card as an end user procedure. The provided certificate is validated as issued by a known issuer. A known issuer is an issuing certificate authority that has been uploaded explicitly to Okta as part a certificate chain provided during the Enable Smart Card/PIV Authentication procedure. Validation will fail if the provided client certificate was issued by an unknown issuer.
- The certificate is then verified against a Certificate Revocation List (CRL). Okta periodically downloads and caches CRLs for the known issuers. If the CRL has expired or the associated CRL is not in the cache then Okta will try to download the CRL in real-time.
- If the client certificate is valid, verified as active, and not revoked against a CRL, the user is then matched against the rule specified in the IDP configuration, and the user is signed in.
If the log in fails, check the following items:
- 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.
- Ensure that the entire certificate chain of issuers is uploaded in the correct format. See Format the PKI Certificate Chain, above for formatting instructions.
- 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.
- Always start with a brand new browser session to avoid caching issues. Close out all browser windows before testing the feature.
- 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.
- 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.
For information on allowing users to sign in to an Okta org using their credentials from their existing account at an OIDC Identity Provider, see Generic OpenID Connect.