SSO troubleshooting
What Botyard's SSO sign-in error codes mean and how to fix them, plus SAML security-policy rejections, single logout caveats and SSO settings errors.
Sign-in errors
Known SSO errors have readable messages. For example, sso_connection_disabled shows: "Single
sign-on is turned off for your organization. Ask an organization owner, or sign in another way."
Unknown codes show Authentication failed (<code>). The table below explains the underlying
codes; it is not a list of literal UI messages.
| Code | Meaning | What to do |
|---|---|---|
sso_connection_disabled | The organization's identity provider connection is disabled. | An owner turns Enabled back on, on the Identity provider card. |
sso_tenant_mismatch | The user signed in to a different Entra tenant than the one the connection is pinned to. | Sign in with an account from your organization's tenant. Personal Microsoft accounts are refused. |
sso_link_confirmation_required | The email address Entra sent already belongs to an existing Botyard account, and that account isn't linked to this Entra identity. | Start SSO again to open the linking flow. Sign in directly to the existing account in the same browser, complete TOTP if enrolled, choose Link account, and complete the new SSO sign-in; see Link an existing Botyard account. |
sso_identity_conflict | The Botyard account is already linked to a different Entra identity in this organization. | Ask an organization owner to check it, or sign in another way. Botyard does not replace that binding just because the email matches. |
sso_subject_missing | The token had no usable tenant ID and object ID for the user. | For SAML, check that the tenantid and objectidentifier claims are not removed or renamed under Attributes & Claims. |
sso_browser_mismatch | The SAML response didn't belong to a sign-in started in this browser. A sign-in started in another tab or browser, or one that took more than 10 minutes, also lands here. | Start the sign-in again. Only the most recent SAML sign-in per browser can complete. |
sso_connection_not_found | The Sign on URL names a SAML connection that doesn't exist. | Check the Sign on URL in Entra against the one on the Identity provider card. The connection may have been disconnected. |
sso_start_failed | Botyard couldn't start the SAML sign-in. | Try again. If it keeps happening, refresh the metadata, or contact Botyard support. |
sso_connection_unbound, sso_provider_unattached, sso_provider_not_persisted, sso_provider_changed, sso_provider_unsupported | The connection the sign-in came through doesn't match your organization's current setup, for example because it was changed or disconnected while the sign-in was in progress. | Sign in again. If it keeps happening, contact Botyard support. |
If Also ask for Botyard two-factor after SSO is on and the connection is disabled while a member
is entering their code, the code is refused with SSO_CONNECTION_DISABLED.
Sign-in does not start
"We couldn't start single sign-on for that organization. Check the organization ID, or sign in another way." is the same message for every refused start. Check the organization slug (not an email address), then ask an owner to check the connection. The message does not distinguish an unknown organization, a missing or disabled connection, or a service failure.
Account linking
See Link an existing Botyard account for the full flow.
On Link single sign-on, follow the instruction shown:
| Message | What to do |
|---|---|
| For your security, sign in again before linking. | Choose Sign in again. The confirming Botyard sign-in must happen after this linking request started; an older session is not enough. |
| You're signed in to a different account. Sign in to the account for this email. | Choose Sign in again and use the existing Botyard account for the displayed email address. |
| Sign in with your Botyard account directly, not through single sign-on. | Use Sign in again to sign in directly, not through SSO. |
| Sign in again and verify with your authenticator app before linking. | Choose Sign in again and complete Botyard TOTP for the enrolled account. This check is separate from the organization's post-SSO two-factor setting. |
| This request has expired. Sign in with SSO again to start over. | Start SSO again in this browser. Requests expire after 10 minutes and can be used only once. |
| Your organization changed its sign-in settings. Sign in with SSO again. | Start SSO again using the current connection. |
| Single sign-on is turned off for your organization. Ask an admin to turn it on. | Ask an organization owner to enable the connection, then start SSO again. |
| This account is already linked to your organization's single sign-on. | Start SSO again; if the identity still conflicts, ask an owner to check the binding. |
| Your organization's sign-in settings are being updated. Try again in a moment. | Wait briefly, then choose Link account again. |
After Link account, the app normally starts SSO again. If you see Your account is linked. instead, choose Go to sign in and start SSO from the login page. Linking alone does not grant an SSO session. The flow is not an email-click-only confirmation.
SAML responses refused by policy
Some SAML responses are refused before sign-in starts, with an HTTP 400 and one of these codes:
| Code | Cause | Fix |
|---|---|---|
SAML_SIGNATURE_ALGORITHM_NOT_ALLOWED | The response or assertion is signed with SHA-1. | Set Signing Algorithm to SHA-256 under SAML Certificates. |
SAML_DIGEST_ALGORITHM_NOT_ALLOWED | The signature uses SHA-1 digests. | Set Signing Algorithm to SHA-256. |
SAML_MESSAGE_TOO_LARGE | The SAML message is larger than 256 KiB. | Remove unneeded claims, such as large group claims. |
SAML_MALFORMED_XML, SAML_MALFORMED_MESSAGE | The message could not be parsed. | Check the application's SAML configuration. |
A sign-in also fails if:
- Entra signs only the SAML response. Set Signing Option to Sign SAML assertion or Sign SAML response and assertion.
- Entra signs with a certificate Botyard doesn't have. After a certificate change, click Refresh metadata on the Identity provider card.
- The sign-in was started from Entra rather than from Botyard. IdP-initiated sign-in is off, so make sure Entra's Sign on URL is set to Botyard's Sign on URL. The My Apps tile then works.
Single logout
- Signing out of Entra ends the user's Botyard sessions from this connection. Requests that need organization access stop at once. A browser session can stay valid elsewhere for up to 10 minutes, and an access token for non-organization pages for up to an hour.
- Signing out of Botyard doesn't sign the user out of Entra.
sso_logout_incompletemeans Entra answered a logout request but reported that its side did not complete. The Botyard session has already ended.- Logout requests from Entra are refused unless they are signed with a SHA-256 or stronger
algorithm. They are also refused if they name another issuer or destination, fall outside their
validity window, or have been seen before. The refusal is an HTTP 400 with a
SAML_SLO_…code, and nothing is signed out.
SSO settings errors
Errors in the Single sign-on settings show a short title, usually with details from Botyard:
| Title | Common cause |
|---|---|
| Your identity provider rejected these settings | The metadata, tenant ID or client details are invalid. The details say which: for example, metadata that isn't from an Entra tenant, a personal-account tenant ID, or a metadata URL not on login.microsoftonline.com. |
| The identity provider connection couldn't be changed | The organization already has a connection, or another change landed at the same time. |
| Turn off “Require SSO” first | You tried to disable or disconnect the connection while Require SSO is on. |
| SSO can't be required yet | A prerequisite for Require SSO is missing; the list says which. |
| This role is managed by your identity provider | You tried to change the role of a member that SCIM provisioning manages. Change their Entra groups or the group mappings. |
| Owner sync and owner mappings must agree | You mapped a group to Owner with Let groups grant the owner role off, or tried to turn that off while owner mappings exist. |
| Only organization owners can manage SSO | Ask an owner to make the change. |
| SSO isn't available here yet | Single sign-on management isn't enabled in this environment. Contact Botyard. |
| Your plan doesn't include this | The organization's plan no longer includes single sign-on or SCIM provisioning, for example after a plan change while the page was open. Reload the page; see Availability. |
Require SSO
Require members to sign in through Microsoft Entra ID: prerequisites, the owner break-glass, effect on existing sessions, and Botyard two-factor after SSO.
Audit logs
View and filter Botyard audit logs: who can read them, the event model, Runtime Vault secret events, and how to search events in the app or through the API.