# Generic SAML, OIDC and SCIM

<!-- Generated by scripts/generate.ts. Do not edit. -->

:::note[Coming soon]
The setup guide on this page is being written. The Connection Doctor fixes below are complete.
:::

How to connect any SAML 2.0 or OIDC identity provider, and any SCIM 2.0 client, that does not have a dedicated guide.

## Optional: outage resilience

If our main network ever has an outage, sign-ins can continue through a standby address, but only for connections whose identity provider accepts it. The setup link shows the standby URL with a copy button; it is the second entry of the connection's `acs_urls`. See [standby route behavior](/trust/standby/).

<a id="standby-saml"></a>

### SAML: add the standby ACS URL

If the identity provider imports our SAML metadata, it already has both ACS URLs: index 0 is the primary and index 1 is the standby. Check that both are listed. Otherwise, if the app lets you add more than one ACS or reply URL, add the standby ACS URL as the second one and keep the primary as the default. If it uses indexed ACS URLs, give the standby URL index 1. If it allows only one ACS URL, skip this step: the connection has no standby path. Then confirm in the setup link that you added it.

<a id="standby-oidc"></a>

### OIDC: add the second redirect URI

Add the standby redirect URI as a second redirect URI of the application in the identity provider, next to the primary one. Nothing else changes. Then confirm in the setup link that you added it.

## Connection Doctor fixes

Connection Doctor shows these steps when a test or sign-in fails and no IdP-specific fix applies. Values in braces are filled in with the connection's own settings in the dashboard and portal.

<a id="oidc_discovery_unreachable"></a>

### Fix for `oidc_discovery_unreachable`

We could not read the identity provider's OpenID configuration at the issuer URL.

1. Check that the issuer URL is correct and that `{issuer}`/.well-known/openid-configuration opens publicly over HTTPS.

See the [`oidc_discovery_unreachable` error reference](/errors/oidc_discovery_unreachable/).

<a id="oidc_email_missing"></a>

### Fix for `oidc_email_missing`

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

1. Allow the email scope for this application and make sure the user has an email address.

See the [`oidc_email_missing` error reference](/errors/oidc_email_missing/).

<a id="oidc_email_not_verified"></a>

### Fix for `oidc_email_not_verified`

The identity provider says the user's email address is not verified.

1. Verify the user's email address in the identity provider, or ask the user to complete email verification, then retry.

See the [`oidc_email_not_verified` error reference](/errors/oidc_email_not_verified/).

<a id="oidc_id_token_invalid"></a>

### Fix for `oidc_id_token_invalid`

The ID token could not be verified (signature, issuer, audience or time).

1. Check that the issuer URL configured here is exactly the identity provider's issuer and that the client ID matches the application.

See the [`oidc_id_token_invalid` error reference](/errors/oidc_id_token_invalid/).

<a id="oidc_idp_error"></a>

### Fix for `oidc_idp_error`

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. Check that the user (or a group the user belongs to) is assigned to the application in the identity provider, then retry the sign-in. The provider's error value is in the sign-in log.

See the [`oidc_idp_error` error reference](/errors/oidc_idp_error/).

<a id="oidc_personal_account_refused"></a>

### Fix for `oidc_personal_account_refused`

A personal Google or Microsoft account signed in, and this connection only accepts work accounts.

1. Ask the user to sign out of personal Google or Microsoft accounts and sign in with their work account.

See the [`oidc_personal_account_refused` error reference](/errors/oidc_personal_account_refused/).

<a id="oidc_tenant_claim_missing"></a>

### Fix for `oidc_tenant_claim_missing`

Microsoft Entra sent an ID token without a tenant ID (tid claim), so the account cannot be matched to your organization.

1. Sign in with a Microsoft Entra work or school account, then retry; contact support if a work account keeps failing.

See the [`oidc_tenant_claim_missing` error reference](/errors/oidc_tenant_claim_missing/).

<a id="oidc_tenant_mismatch"></a>

### Fix for `oidc_tenant_mismatch`

The account signed in from a Google Workspace domain or Microsoft Entra tenant that is not the one this organization verified.

1. Ask the user to sign out of other Google or Microsoft accounts and sign in again with their work account in your organization's domain or tenant.
2. If your organization uses another Google Workspace domain or Entra tenant, verify that domain or tenant in this setup first.

See the [`oidc_tenant_mismatch` error reference](/errors/oidc_tenant_mismatch/).

<a id="oidc_token_exchange_failed"></a>

### Fix for `oidc_token_exchange_failed`

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

1. Check the client ID and client secret entered here, and add `{redirect_uri}` as an allowed redirect URI.

See the [`oidc_token_exchange_failed` error reference](/errors/oidc_token_exchange_failed/).

<a id="saml_assertion_count_invalid"></a>

### Fix for `saml_assertion_count_invalid`

The response must contain exactly one assertion.

1. Configure the application to send a single assertion per response.

See the [`saml_assertion_count_invalid` error reference](/errors/saml_assertion_count_invalid/).

<a id="saml_audience_mismatch"></a>

### Fix for `saml_audience_mismatch`

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

1. Set the SP Entity ID (Audience) to `{sp_entity_id}`.

See the [`saml_audience_mismatch` error reference](/errors/saml_audience_mismatch/).

<a id="saml_decryption_failed"></a>

### Fix for `saml_decryption_failed`

The assertion is encrypted with a key we cannot use.

1. Upload this connection's current SP encryption certificate in the identity provider (from `{metadata_url}`), or turn assertion encryption off.

See the [`saml_decryption_failed` error reference](/errors/saml_decryption_failed/).

<a id="saml_destination_mismatch"></a>

### Fix for `saml_destination_mismatch`

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

1. Set the Assertion Consumer Service (ACS) URL, Recipient and Destination to `{acs_url}`.

See the [`saml_destination_mismatch` error reference](/errors/saml_destination_mismatch/).

<a id="saml_dtd_forbidden"></a>

### Fix for `saml_dtd_forbidden`

The response contained a DOCTYPE declaration, which is never accepted.

1. Configure the identity provider to send a standard SAML response without a DOCTYPE; contact the identity provider's support if you cannot change it.

See the [`saml_dtd_forbidden` error reference](/errors/saml_dtd_forbidden/).

<a id="saml_email_missing"></a>

### Fix for `saml_email_missing`

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

1. Add an attribute named email with the user's email address, or send the email as the NameID.

See the [`saml_email_missing` error reference](/errors/saml_email_missing/).

<a id="saml_idp_status_error"></a>

### Fix for `saml_idp_status_error`

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

1. Check that the user is assigned to the application in your identity provider.
2. Look at the identity provider's sign-in log for the reason it gave.

See the [`saml_idp_status_error` error reference](/errors/saml_idp_status_error/).

<a id="saml_in_response_to_mismatch"></a>

### Fix for `saml_in_response_to_mismatch`

The response answers a different sign-in request (for example a sign-in started from the identity provider's dashboard).

1. Start the sign-in from the app (or the test button), not from the identity provider's dashboard or bookmarks.

See the [`saml_in_response_to_mismatch` error reference](/errors/saml_in_response_to_mismatch/).

<a id="saml_issuer_mismatch"></a>

### Fix for `saml_issuer_mismatch`

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

1. Upload the metadata of the application you are signing in with, so the configured IdP Entity ID matches its issuer.

See the [`saml_issuer_mismatch` error reference](/errors/saml_issuer_mismatch/).

<a id="saml_nameid_missing"></a>

### Fix for `saml_nameid_missing`

The response has no user identifier (NameID).

1. Send a NameID for every user (for example the user's email or a persistent ID).

See the [`saml_nameid_missing` error reference](/errors/saml_nameid_missing/).

<a id="saml_response_altered"></a>

### Fix for `saml_response_altered`

The response was signed with the certificate we have on file, but its content was changed after signing (a rewriting proxy, a browser extension, or a hand-edited response).

1. Keep the certificate you have; it is correct.
2. Turn off any proxy, security gateway or browser extension that rewrites sign-in traffic, then sign in again.

See the [`saml_response_altered` error reference](/errors/saml_response_altered/).

<a id="saml_response_expired"></a>

### Fix for `saml_response_expired`

The response arrived after it expired, usually because of a clock difference or a slow sign-in.

1. Retry the sign-in. If it keeps failing, check that the identity provider's server clock is correct.

See the [`saml_response_expired` error reference](/errors/saml_response_expired/).

<a id="saml_response_malformed"></a>

### Fix for `saml_response_malformed`

The identity provider sent something that is not a readable SAML response.

1. Make sure the application is a SAML 2.0 application using the HTTP-POST binding.
2. Set the Assertion Consumer Service (ACS) URL to `{acs_url}`.

See the [`saml_response_malformed` error reference](/errors/saml_response_malformed/).

<a id="saml_response_not_yet_valid"></a>

### Fix for `saml_response_not_yet_valid`

The response is dated in the future, usually because of a clock difference.

1. Check that the identity provider's server clock is correct (NTP), then retry.

See the [`saml_response_not_yet_valid` error reference](/errors/saml_response_not_yet_valid/).

<a id="saml_signature_algorithm_weak"></a>

### Fix for `saml_signature_algorithm_weak`

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

1. Change the signature algorithm for this application to RSA-SHA256.

See the [`saml_signature_algorithm_weak` error reference](/errors/saml_signature_algorithm_weak/).

<a id="saml_signature_invalid"></a>

### Fix for `saml_signature_invalid`

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

1. Download the identity provider's current signing certificate or metadata and upload it again in this setup.

See the [`saml_signature_invalid` error reference](/errors/saml_signature_invalid/).

<a id="saml_signature_missing"></a>

### Fix for `saml_signature_missing`

The SAML response or assertion is not signed.

1. Enable signing of the assertion (or the whole response) for this application.

See the [`saml_signature_missing` error reference](/errors/saml_signature_missing/).

<a id="saml_wrapping_detected"></a>

### Fix for `saml_wrapping_detected`

The response's structure looks tampered with, so it was refused.

1. Retry the sign-in. If it keeps failing, contact the identity provider's support and share the error code.

See the [`saml_wrapping_detected` error reference](/errors/saml_wrapping_detected/).

<a id="sp_key_rotation_not_ready"></a>

### Fix for `sp_key_rotation_not_ready`

A signing-key rotation cannot be confirmed yet: the notice is not acknowledged, the thirty-day wait has not passed, or the next key has no passing test.

1. Have an authorized IT administrator for this organization acknowledge the rotation notice in the portal.
2. Wait thirty elapsed days after the acknowledgment.
3. Run a fresh, passing test for the rotation's next signing key. The current signing key stays active until then.

See the [`sp_key_rotation_not_ready` error reference](/errors/sp_key_rotation_not_ready/).

<a id="sp_key_rotation_retirement_warning"></a>

### Fix for `sp_key_rotation_retirement_warning`

This connection still keeps a rollback signing key from an earlier rotation, or its age cannot be verified.

1. Review this connection's current signing-key rotation and retained rollback key.
2. An authorized administrator can explicitly retire the rollback key when it is no longer needed.

See the [`sp_key_rotation_retirement_warning` error reference](/errors/sp_key_rotation_retirement_warning/).
