Skip to content
Dashboard
Theme
Theme

Okta

Setup guides for Okta.

View Markdown

Setup guides for Okta. IT administrators see the same steps, with their own values filled in, in the setup link they receive.

Connection Doctor shows these steps when a test or sign-in through Okta fails. Codes without their own Okta steps use the generic fixes. Values in braces are filled in with the connection’s own settings in the dashboard and portal.

The identity provider did not release the user’s email claim.

  1. In Okta, open the application > Okta API Scopes / Sign On and make sure the email scope is granted and the user profile has an email.

See the oidc_email_missing error reference.

The identity provider returned an error to the sign-in callback instead of signing the user in (most often the user is not assigned to the application, or canceled).

  1. In Okta, open Applications > the OIDC application > Assignments and assign the user or a group the user belongs to, then retry.

See the oidc_idp_error error reference.

The identity provider refused to exchange the sign-in code (often a wrong client secret or redirect URI).

  1. In Okta, open the OIDC application > General and check Client ID and Client secret; add {redirect_uri} to Sign-in redirect URIs.

See the oidc_token_exchange_failed error reference.

The identity provider uses a different SP Entity ID (Audience) than this connection’s.

  1. In Okta, open the application > General > SAML Settings > Edit and set Audience URI (SP Entity ID) to {sp_entity_id}.

See the saml_audience_mismatch error reference.

The assertion is encrypted with a key we cannot use.

  1. In Okta, open the application > General > SAML Settings > Show Advanced Settings and upload the encryption certificate from {metadata_url}, or set Assertion Encryption to Unencrypted.

See the saml_decryption_failed error reference.

The identity provider sends the response to a different address than this connection’s.

  1. In Okta, open the application > General > SAML Settings > Edit and set Single sign-on URL to {acs_url} (keep “Use this for Recipient URL and Destination URL” checked).

See the saml_destination_mismatch error reference.

The response does not include the user’s email address.

  1. In Okta, open the application > General > SAML Settings > Edit > Attribute Statements and add Name email with Value user.email.

See the saml_email_missing error reference.

The identity provider refused the sign-in before sending an assertion.

  1. In the Okta Admin Console, open the application > Assignments and assign the user or their group.
  2. Check Reports > System Log for the failed sign-in event.

See the saml_idp_status_error error reference.

The response comes from a different identity provider (issuer) than the one configured here.

  1. In Okta, open the application > Sign On > View SAML setup instructions (or the metadata URL) and upload that metadata here; the issuer is the “Identity Provider Issuer”.

See the saml_issuer_mismatch error reference.

The response has no user identifier (NameID).

  1. In Okta, open the application > General > SAML Settings > Edit and set Name ID format and Application username (for example Email).

See the saml_nameid_missing error reference.

The response is signed with SHA-1, which is not accepted.

  1. In Okta, open the application > General > SAML Settings > Show Advanced Settings and set Signature Algorithm to RSA-SHA256.

See the saml_signature_algorithm_weak error reference.

The signature does not match the identity provider certificate we have on file (often after a certificate change).

  1. In Okta, open the application > Sign On > SAML Signing Certificates, download the active certificate (or the metadata) and upload it here.

See the saml_signature_invalid error reference.

The SAML response or assertion is not signed.

  1. In Okta, open the application > General > SAML Settings > Edit, and set Assertion Signature to Signed.

See the saml_signature_missing error reference.