Generic SAML, OIDC and SCIM
How to connect any SAML 2.0 or OIDC identity provider, and any SCIM 2.0 client, that does not have a dedicated guide.
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
Section titled “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.
SAML: add the standby ACS URL
Section titled “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.
OIDC: add the second redirect URI
Section titled “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
Section titled “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.
Fix for oidc_discovery_unreachable
Section titled “Fix for oidc_discovery_unreachable”We could not read the identity provider’s OpenID configuration at the issuer URL.
- 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.
Fix for oidc_email_missing
Section titled “Fix for oidc_email_missing”The identity provider did not release the user’s email claim.
- Allow the email scope for this application and make sure the user has an email address.
See the oidc_email_missing error reference.
Fix for oidc_email_not_verified
Section titled “Fix for oidc_email_not_verified”The identity provider says the user’s email address is not verified.
- 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.
Fix for oidc_id_token_invalid
Section titled “Fix for oidc_id_token_invalid”The ID token could not be verified (signature, issuer, audience or time).
- 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.
Fix for oidc_idp_error
Section titled “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).
- 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.
Fix for oidc_personal_account_refused
Section titled “Fix for oidc_personal_account_refused”A personal Google or Microsoft account signed in, and this connection only accepts work accounts.
- 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.
Fix for oidc_tenant_claim_missing
Section titled “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.
- 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.
Fix for oidc_tenant_mismatch
Section titled “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.
- 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.
- 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.
Fix for oidc_token_exchange_failed
Section titled “Fix for oidc_token_exchange_failed”The identity provider refused to exchange the sign-in code (often a wrong client secret or redirect URI).
- 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.
Fix for saml_assertion_count_invalid
Section titled “Fix for saml_assertion_count_invalid”The response must contain exactly one assertion.
- Configure the application to send a single assertion per response.
See the saml_assertion_count_invalid error reference.
Fix for saml_audience_mismatch
Section titled “Fix for saml_audience_mismatch”The identity provider uses a different SP Entity ID (Audience) than this connection’s.
- Set the SP Entity ID (Audience) to
{sp_entity_id}.
See the saml_audience_mismatch error reference.
Fix for saml_decryption_failed
Section titled “Fix for saml_decryption_failed”The assertion is encrypted with a key we cannot use.
- 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.
Fix for saml_destination_mismatch
Section titled “Fix for saml_destination_mismatch”The identity provider sends the response to a different address than this connection’s.
- Set the Assertion Consumer Service (ACS) URL, Recipient and Destination to
{acs_url}.
See the saml_destination_mismatch error reference.
Fix for saml_dtd_forbidden
Section titled “Fix for saml_dtd_forbidden”The response contained a DOCTYPE declaration, which is never accepted.
- 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.
Fix for saml_email_missing
Section titled “Fix for saml_email_missing”The response does not include the user’s email address.
- 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.
Fix for saml_idp_status_error
Section titled “Fix for saml_idp_status_error”The identity provider refused the sign-in before sending an assertion.
- Check that the user is assigned to the application in your identity provider.
- Look at the identity provider’s sign-in log for the reason it gave.
See the saml_idp_status_error error reference.
Fix for saml_in_response_to_mismatch
Section titled “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).
- 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.
Fix for saml_issuer_mismatch
Section titled “Fix for saml_issuer_mismatch”The response comes from a different identity provider (issuer) than the one configured here.
- 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.
Fix for saml_nameid_missing
Section titled “Fix for saml_nameid_missing”The response has no user identifier (NameID).
- Send a NameID for every user (for example the user’s email or a persistent ID).
See the saml_nameid_missing error reference.
Fix for saml_response_altered
Section titled “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).
- Keep the certificate you have; it is correct.
- 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.
Fix for saml_response_expired
Section titled “Fix for saml_response_expired”The response arrived after it expired, usually because of a clock difference or a slow sign-in.
- 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.
Fix for saml_response_malformed
Section titled “Fix for saml_response_malformed”The identity provider sent something that is not a readable SAML response.
- Make sure the application is a SAML 2.0 application using the HTTP-POST binding.
- Set the Assertion Consumer Service (ACS) URL to
{acs_url}.
See the saml_response_malformed error reference.
Fix for saml_response_not_yet_valid
Section titled “Fix for saml_response_not_yet_valid”The response is dated in the future, usually because of a clock difference.
- Check that the identity provider’s server clock is correct (NTP), then retry.
See the saml_response_not_yet_valid error reference.
Fix for saml_signature_algorithm_weak
Section titled “Fix for saml_signature_algorithm_weak”The response is signed with SHA-1, which is not accepted.
- Change the signature algorithm for this application to RSA-SHA256.
See the saml_signature_algorithm_weak error reference.
Fix for saml_signature_invalid
Section titled “Fix for saml_signature_invalid”The signature does not match the identity provider certificate we have on file (often after a certificate change).
- Download the identity provider’s current signing certificate or metadata and upload it again in this setup.
See the saml_signature_invalid error reference.
Fix for saml_signature_missing
Section titled “Fix for saml_signature_missing”The SAML response or assertion is not signed.
- Enable signing of the assertion (or the whole response) for this application.
See the saml_signature_missing error reference.
Fix for saml_wrapping_detected
Section titled “Fix for saml_wrapping_detected”The response’s structure looks tampered with, so it was refused.
- 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.
Fix for sp_key_rotation_not_ready
Section titled “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.
- Have an authorized IT administrator for this organization acknowledge the rotation notice in the portal.
- Wait thirty elapsed days after the acknowledgment.
- 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.
Fix for sp_key_rotation_retirement_warning
Section titled “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.
- Review this connection’s current signing-key rotation and retained rollback key.
- An authorized administrator can explicitly retire the rollback key when it is no longer needed.