SSO troubleshooting

This page helps organization owners and admins narrow down the cause when SSO sign-in or connection setup fails. Actagate never shows raw IdP responses or internal errors. It shows a reason code and an explanation instead. Look the code up in the table for the place where it appeared: the login screen, the settings screen or Login methods.

A failed sign-in is recorded in the audit log as auth.failed, with the reason code and the channel (sso:<preset ID>). Connection test results are recorded as sso.connection_tested.

Messages on the login screen

The login screen shows these messages instead of reason codes. You can read the reason code from the error= value in the URL.

Reason code	Message	What to do
test_required	The SSO settings changed. Start sign-in again.	The connection settings changed during sign-in, or the connection went back to draft. An admin tests and activates the connection, then the user signs in again
invalid_callback	The login response could not be verified. Please try again.	More than 10 minutes passed since sign-in started, or the user came back in another browser. Start over
issuer_mismatch, invalid_identity	Single sign-on could not verify your identity. Try again or contact your administrator.	The ID token issuer or the user ID does not match. An admin checks the connection settings
invalid_connection	This login connection is unavailable.	The connection is disabled or cannot be found. An admin checks the connection status
not_registered	This Slack user is not registered in the user ledger.	The person was not invited, or the account is disabled. The same message appears when the IdP sends no verified email address. An admin checks the invitation and the email address
link_requires_login	To add an administrator login method, sign in with an existing method first.	Owners and admins cannot link SSO from a signed-out state. Sign in with an existing method and add it under Settings > Login methods
identity_conflict	This email address is linked to a different identity. Contact your organization administrator.	Another IdP account from the same connection is already linked to that member. Contact an admin
domain_forbidden	Your email domain is not allowed to sign in.	The organization does not allow this email domain
ip_forbidden	Sign-in is not allowed from this network.	The organization does not allow access from this network
sso_required	Sign in with SSO for this organization.	SSO is required, so email links and Slack cannot be used. Use the SSO button on the login screen
tenant_forbidden	This Microsoft tenant is not allowed.	The tenant is not in “Allowed Microsoft tenant IDs”
email_unverified	Your Google email address is not verified.	Verify the email address in Google
hosted_domain_forbidden	This Google account’s domain is not allowed.	The domain is not in “Allowed Google Workspace domains”
saml_browser_mismatch	Restart login in the browser where you started it.	Start the SAML sign-in again from the browser where it began

For reason codes not in the table above (such as authentication_failed and the codes that start with saml_), the screen shows “Slack sign-in could not be completed. Please try again.” This wording also appears when SSO fails. Admins can find the reason code in the auth.failed audit event and look it up in the tables below.

Reason codes on the settings screen

When saving, testing, activating or disabling a connection fails, an explanation and the reason code appear above Single sign-on.

Reason code	Meaning and what to do
invalid_issuer	The Issuer URL does not fit the preset. For an Okta custom domain, choose Generic OIDC
unsafe_endpoint	The URL is not HTTPS, or it points to an address on an internal network. Use an HTTPS URL reachable from the internet
invalid_oidc_configuration	The display name, issuer, client ID or secret is missing. Or an endpoint in discovery is not an HTTPS URL
issuer_locked	After users have signed in through this connection, the issuer cannot change. Add a new connection
encryption_unavailable	SSO_SECRET_ENCRYPTION_KEY is missing or differs from the key used when saving. Ask your operator. After a key change, enter the client secret again and test again
discovery_failed	The IdP discovery document could not be read. Check the Issuer URL
issuer_mismatch	The issuer in discovery does not match the issuer you entered
pkce_unsupported	The IdP does not support PKCE (S256)
unsupported_client_auth	The IdP client authentication method is neither client_secret_post nor client_secret_basic
provider_unavailable	The IdP could not be reached. Timeouts, redirects and responses that are too large count here. Try again later
provider_rejected	The IdP refused the sign-in. Check the app assignment and the callback URL
token_exchange_failed	No token came back from the IdP. Check the client ID and secret
id_token_invalid	The ID token signature, issuer, audience, expiry or nonce does not match. Check the issuer and client ID
invalid_identity	The ID token has no user ID (sub)
invalid_callback	The test request is invalid or older than 10 minutes. Test again in the admin session that started it
test_required	No test has passed with the current settings. This code also appears when the settings changed during a test. Test, then activate
invalid_connection	The connection cannot be found
authentication_failed	A failure that matches none of the codes above. Review the connection settings

SAML connections can also return these codes.

Reason code	Meaning and what to do
saml_invalid_xml	The XML could not be read. It has a DOCTYPE or ENTITY declaration, or it is larger than 256 KiB
saml_invalid_metadata	Check the IdP metadata. It needs an SSO URL with the HTTPS HTTP-Redirect binding and one or two signing certificates
saml_invalid_response	The SAML response could not be validated. Check that assertions are signed, that SHA-1 is not used and that the lifetime is 10 minutes or less
saml_destination_mismatch	The response destination does not match the ACS URL
saml_recipient_mismatch	The assertion recipient does not match the ACS URL
saml_request_mismatch	No valid sign-in request was found. Start the sign-in again
saml_relay_state_mismatch	RelayState does not match the sign-in request
saml_idp_initiated	IdP-initiated login is not allowed
saml_assertion_replayed	This assertion has already been used. Start the sign-in again
saml_transient_nameid	The NameID is transient. Change it to persistent
saml_expired	The assertion is outside its validity period. Check the IdP and server clocks
saml_browser_mismatch	Start again in the browser where you began

Reason codes for domain verification and required SSO

Reason code	Meaning and what to do
invalid_domain	Check the domain format
domain_taken	Another organization has verified this domain. Only one organization can verify a given domain
dns_not_found	The TXT record was not found. Check that the name is _actagate-challenge.<domain> and that DNS has picked up the change
token_mismatch	The TXT record value does not match the displayed actagate-domain-verification=<token>
dns_error	The DNS check failed. Wait a while, then press “Verify” again
enforcement_active	While SSO is required, the last active connection cannot be disabled. Turn off “Require SSO” first
no_active_connection	Requiring SSO needs an active connection
not_signed_in_with_sso	Sign in through an active connection yourself before you require SSO. A test or an added login method does not count

If an IdP outage locks everyone out after you require SSO, an owner signs in with an email link and turns the requirement off.

Messages when adding a login method

These appear after you press “Add ” under Settings > Login methods.

Result	Message	What to do
identity_conflict	This identity is already linked to an account.	That IdP account is linked to another member. Contact an admin
invalid_callback	Identity verification failed. Try again.	Add it again in the same browser and session
invalid_connection	This connection is unavailable.	The connection is disabled or cannot be found
last_identity	You must keep at least one login method.	Add another login method before you remove this one

Related pages

• Single sign-on basics
• The Troubleshooting section of each provider guide