# 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](/en/docs/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](/en/docs/sso/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](/en/docs/sso/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”](/en/docs/sso/policy) 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.