Single sign-on (SSO)
Troubleshooting
What single sign-on error messages mean and how to fix them: provider setup, redirect URI, signature, certificate, clock, email.
The error is shown to the employee in words on the sign-in screen; the same reason is recorded in the organisation’s audit log (the session.sso_login event with the result “failure”), so the owner sees it without anyone having to retell it.
On the “Company SSO sign-in” screen
| Message | Cause | What to do |
|---|---|---|
| Single sign-on is not set up for the domain … | the domain is not verified (or is verified by another organisation) | verify the domain (Company domains) or sign in by the organisation name |
| Single sign-on is not set up for the organisation … | the organisation has no connection | the owner sets up the “Single sign-on” section |
| enter a work email or an organisation name | something was entered that looks like neither an email nor a name | check the spelling |
After returning from the provider
Messages begin with “the IdP did not confirm the sign-in:” followed by the reason.
| Reason | What it means | What to do |
|---|---|---|
invalid_client / unauthorized_client | the provider did not accept the client_id or client_secret | double-check both; the secret is re-entered in the form |
invalid_grant / redirect_uri mismatch | the provider has a different Redirect URI registered, or the authorisation code has already been used or has expired | copy the Redirect URI from the “Values for setting up” block exactly, to the last character |
unexpected JWT "iss" / issuer mismatch | the Issuer URL in Buff does not match what the provider writes in the token | enter the issuer exactly as in the discovery document (without a trailing /, the same host and scheme) |
nonce / state mismatch | sign-in was started in one tab and finished in another, or more than 15 minutes passed | start signing in again |
| Invalid signature / Invalid document signature | SAML: the signature does not match the certificate in Buff | paste the provider’s current signing certificate; during rotation — both |
| Unable to verify without a signature / wantAssertionsSigned | SAML: the provider does not sign the assertion | turn on assertion signing at the provider (Keycloak: Sign assertions = On) |
| SAML assertion audience mismatch | the Entity ID at the provider differs from ours | register the Entity ID from the “Values for setting up” block with the provider (each organisation has its own) |
| SAML assertion expired / not yet valid | the provider’s and Buff’s clocks differ by more than 5 minutes | synchronise the time on the provider’s side (NTP) |
| InResponseTo … not found / the IdP answer has already been used | the answer does not match the request Buff sent, or it was sent again | start signing in again; IdP-initiated sign-in is not supported |
| the IdP did not pass an email | the token or assertion has no email address | OIDC: add the email scope and claim; SAML: add the email attribute (see the examples in Setup) |
| account not found, and automatic member creation is turned off | a new employee while the checkbox is off | turn on “Create an account on first sign-in” or invite the employee in advance |
| the sign-in session was not found or has expired | more than 15 minutes passed between the start of sign-in and the return, or sign-in was started in another browser | start again from the same tab |
On the password sign-in screen
“Password sign-in is turned off: the organisation … requires single sign-on” — “Single sign-on only” mode is on. Press “Sign in with company SSO”. The organisation owner can always sign in with a password.
Saving the settings
| Message | What to do |
|---|---|
| the IdP is unavailable or answers wrongly | check the Issuer URL in a browser: <issuer>/.well-known/openid-configuration must open as JSON; the provider must be reachable from the internet over https |
| issuer: https only / entry_point: https only | a provider without TLS is not accepted; the only exception is test environments |
| idp_certs: paste the IdP’s signing certificate in PEM format | the certificate must be wrapped in the -----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- lines |
| The TXT record … was not found | the record has not propagated through DNS yet, or was published with a different name/value; check with dig TXT _buff-sso.<domain> |
| this domain is already verified by another organisation | the domain is taken; write to support if it is your domain |
If nothing helps
Write to support with the event time and the reason text from the audit log — that is enough to investigate. There are no secrets in the log, and there is no need to send them.