Plain-English SAML error map

Every SAML error you'll see in the SSO Setup Portal, translated from the W3C spec into something an IT admin can actually act on.

SAML errors are notoriously cryptic. This page lists the errors you're most likely to see when wiring up a new IdP, what they actually mean, and the one-line fix.

The same mapping powers the inline diagnostic in the SSO Setup Portal — when an IT admin tests a connection, the technical error appears alongside the plain-English message below. The source of truth is authio_sso/internal/saml/error_map.go; this page is rendered from the same catalogue.

Don't branch your application code on these messages — branch on the stable code field. Messages may evolve; codes are versioned and don't change without a deprecation cycle.

Clock skew

Technical	Code	What it means	Fix
`NotBefore validation failed`	`clock_skew_not_before`	Your IdP's clock is ahead of ours — the assertion looks like it was issued in the future.	Sync the IdP's clock via NTP. Drift of more than ~5 minutes will fail validation.
`NotOnOrAfter validation failed`	`clock_skew_not_on_or_after`	The IdP's clock is behind ours — the assertion has already expired by our reckoning.	Sync via NTP, or extend the IdP's assertion lifetime if it's set artificially short.
`SubjectConfirmationData NotOnOrAfter elapsed`	`subject_confirmation_window`	The Subject Confirmation window expired between IdP sign-in and our ACS callback.	Sync both clocks via NTP. Network latency >5 min between IdP and Authio also triggers this.

Signature

Technical	Code	What it means	Fix
`Signature verification failed`	`signature_verification_failed`	The IdP's signing certificate doesn't match what's registered with Authio.	Re-export metadata from your IdP and upload it via the SSO Setup Portal. If you rotated the IdP cert in the last 24 hours, this is expected.
`missing X509Certificate in IdP metadata`	`missing_signing_cert`	The IdP's response doesn't include a signing certificate, and our metadata doesn't pin one either.	Confirm your IdP signs responses (not just the assertion) and that its metadata includes <X509Certificate> under IDPSSODescriptor.

Audience / entity ID

Technical	Code	What it means	Fix
`AudienceRestriction failed`	`audience_mismatch`	Your IdP-side SP entity ID is wrong.	Copy the entity ID from the SSO Setup Portal (it looks like https://sso.authio.com/v1/sso/connections/<id>/metadata) and paste it into your IdP's SP configuration. Treat it as case-sensitive.

Binding & flow

Technical	Code	What it means	Fix
`InResponseTo unknown`	`in_response_to_unknown`	The IdP returned a SAMLResponse we didn't ask for, or asked for a long time ago.	Usually a stale SP entity ID on the IdP side, or the user took >5 minutes between IdP-initiated start and our ACS callback. Retry; if it persists, double-check the SP entity ID.
`AssertionConsumerServiceURL mismatch`	`acs_url_mismatch`	The ACS URL the IdP posted to doesn't match the one in our SP metadata.	Re-import our SP metadata into the IdP. Copy the ACS URL exactly — including the connection ID at the end of the path.
`Destination mismatch`	`destination_mismatch`	The IdP's response Destination URL doesn't match our ACS URL.	Re-import our SP metadata into the IdP, or update the SP configuration's ACS URL to the value shown in the SSO Setup Portal.
`StatusCode Responder`	`idp_responder_error`	The IdP rejected our request because of something on its side.	Open the IdP's sign-on log for this user / app and read the detailed error. Common cause: SP isn't enabled for this user's group.
`StatusCode Requester`	`idp_requester_error`	The IdP rejected our AuthnRequest as malformed.	Usually a stale SP metadata import on the IdP side. Re-export from the SSO Setup Portal and re-import on the IdP.
`StatusCode AuthnFailed`	`idp_authn_failed`	The IdP told us the user didn't authenticate successfully.	Check the IdP-side sign-in logs for this user. Common cases: account locked, MFA missing, conditional-access policy blocked the sign-in.
`StatusCode NoAuthnContext`	`no_authn_context`	We requested an AuthnContext the IdP can't satisfy (e.g. PasswordProtectedTransport).	Either relax the AuthnContext requirement in the Authio connection config, or have the IdP admin enable the requested context for this user.
`ResponseID already received`	`replay_detected`	We've already processed this exact SAMLResponse once.	Have the user start sign-in again from your app's login button. If the user used the browser back/forward buttons, that's harmless — the second attempt mints a fresh response.

Attributes & NameID

Technical	Code	What it means	Fix
`no NameID in assertion`	`missing_name_id`	The IdP's assertion doesn't include a NameID for the user.	Configure the IdP to release NameID with format emailAddress, mapped to the user's primary email.
`unsupported NameID format`	`name_id_format_unsupported`	The IdP is sending NameID in a format we don't accept (typically unspecified or transient).	Set the NameID format to emailAddress on the IdP's SP configuration for this Authio connection.
`missing email attribute`	`missing_email_attribute`	We couldn't find an email address in the assertion's attributes or NameID.	Map the user's email to one of: NameID (preferred), 'email' attribute, or the schemas.xmlsoap.org/.../emailaddress claim.

XML & encoding

Technical	Code	What it means	Fix
`expected element type SAMLResponse`	`xml_unexpected_element`	The IdP sent XML we can't parse — wrong root element where we expected SAMLResponse.	Confirm the IdP is posting to the ACS endpoint (not the metadata endpoint), and that the response is form-encoded with key SAMLResponse=<base64-XML>.
`base64 decode failed`	`base64_decode_failed`	We couldn't base64-decode the SAMLResponse form field.	Some IdPs URL-encode the field twice. Confirm the IdP is sending SAMLResponse as standard base64, not URL-safe base64.
`unable to unmarshal SAMLResponse`	`xml_unmarshal_failed`	The decoded XML is malformed — we couldn't read it as a SAMLResponse.	Capture the raw POST body via your browser's network panel and open a support ticket; this usually means the IdP is emitting non-conforming XML.

Metadata

Technical	Code	What it means	Fix
`parse idp metadata failed`	`metadata_parse_failed`	We couldn't parse the IdP metadata XML you uploaded for this connection.	Re-export from the IdP, confirm it's a single XML file (not a zip), and re-upload via the SSO Setup Portal.
`no IDPSSODescriptor in metadata`	`metadata_missing_idp_descriptor`	The metadata you uploaded is for an SP, not an IdP — we couldn't find IDPSSODescriptor.	On the IdP, look for an 'IdP metadata' or 'Federation metadata' download (not 'SP metadata').
`no SingleSignOnService binding`	`metadata_missing_sso_binding`	The IdP metadata doesn't declare a SingleSignOnService with a binding we support.	Configure the IdP to expose HTTP-Redirect or HTTP-POST SSO bindings, then re-export and re-upload metadata.

How to capture a SAML error for debugging

If the message above doesn't match what you're seeing, capture the raw failure so support can match it precisely:

Open the browser's network panel before clicking sign in.
Look for the POST to https://sso.authio.com/v1/sso/connections/<id>/acs.
Save the request payload (the SAMLResponse form field) and the response body.
Capture the response's X-Request-Id header.
Email support@authio.com with the request id, the connection id, and the captured payload.

Saved SAMLResponse blobs contain user attributes (email, name); treat them with the same care as any other authentication data.

Plain-English SAML errors