SSO Troubleshooting
Two surfaces produce SSO errors, and they behave differently on purpose.- The sign-in path —
/saml/<slug>/login,/saml/<slug>/acs,/saml/<slug>/slo— is public and unauthenticated. Anyone who knows a workspace slug can reach it. So its answers are deliberately uninformative: the person is sent to the login page with a shorterrorcode, and the reason is recorded in your workspace’s audit log — a login refused entry (sso_connection.login_refused) on the connection, carrying a short reason code and a sentence saying what to fix — where only an administrator can read it. The connection’s Setup tab lists the most recent of them under Refused sign-ins: the time, the reason code and that sentence. A public endpoint that explained itself would explain itself to anybody. While you are setting a connection up, its Test tab is faster still: it runs every check a sign-in runs and shows you the result directly. - The settings form — everything under
/admin/saml— is behind the owner-or-admin role and a recent re-authentication, so it says exactly what is wrong with the value you typed. Those messages are quoted verbatim below.
Start here for almost everything. Most first-login failures are one of three things: the audience does not match (KnoxCall’s SP entity ID is its metadata URL,
https://acme.knoxcall.com/saml/acme/metadata, not the origin), the assertion is older than five minutes, or the asserted address is at a domain the workspace has not proven. Those /saml/<workspace>/… URLs are the default connection’s — the /saml/ alias is that connection. Any other connection has its own set at https://acme.knoxcall.com/sso/<workspace>/<connection>/{metadata,acs,login,slo}, so check the one you are debugging on its Certificates tab before comparing anything. Fetch your own metadata document and compare it against what your IdP has, before anything else.Error codes on the login path
The code arrives as?error=<code> on the login page, or as a JSON { "error": "<code>" } from the metadata and logout endpoints.
An encryption algorithm KnoxCall refuses
If your IdP encrypts the assertion, KnoxCall reads which algorithms it used before decrypting anything. The content must be AES-GCM or AES-CBC (128 or 256), and the key must be wrapped with RSA-OAEP. Two algorithms are refused: RSA PKCS#1 v1.5 key transport (rsa-1_5) and Triple DES (tripledes-cbc). So is any algorithm KnoxCall does not recognise.
- At the ACS the person sees
saml_failed. The workspace’s security events carryauth.login_failed, and the detail names the algorithm, for example…encryption algorithm not accepted (http://www.w3.org/2001/04/xmlenc#rsa-1_5). - At the connection test the verdict is refused, and its summary names the algorithm.
- In a logout request whose NameID is encrypted, the SLO endpoint answers
saml_logout_invalid.
What is really behind saml_failed
The assertion verified, and then an account rule refused it. The person sees saml_failed; you see one of these in the login refused entry in the workspace’s audit log, and in the connection test’s result. All six are quoted verbatim.
Before any of them, a verified assertion that carries no email address at all is refused with the reason email_missing. KnoxCall looks in the connection’s email attribute, the standard email claims and the NameID. On Entra ID the email claim is filled from user.mail, which is empty for an account with no mailbox — see the Entra guide’s claims step.
There is a seventh, for a misconfigured connection rather than a person: if the connection’s default role is anything an IdP-asserted login may not confer, every login fails cleanly with a message naming the role and telling you to lower it. That state is unreachable through the settings form, which refuses the value at save time.
An expired signing certificate
KnoxCall accepts an identity provider’s signature only when an active certificate on the connection verifies it and that certificate is valid at that moment: its not before date has passed and its not after date has not. That holds for sign-in, sign-in started at the identity provider, the connection test and Single Logout alike, for every connection. A certificate stops signing anyone in the second it expires; the expiry emails at 30, 14 and 3 days before, and once after, are the warning. The audit log’s login refused entry and a test verdict carry the reason, and the login page the code:
Each message names the certificate by its SHA-256 fingerprint, the one the Certificates tab shows, with the date.
What to do: rotate the signing certificate in your identity provider, then re-import its metadata on the connection — or paste the new certificate on the Certificates tab, which adds it beside the old one. If the identity provider already holds a newer certificate, make it the one it signs with. Sign-in works again on the next attempt; there is nothing to switch back on. A logout message signed with an expired certificate is refused the same way, as
saml_logout_invalid.
Refusals from the SSO settings form
These come back as a400 with the message shown to you directly. Fix the value and save again.
The IdP sign-in URL and the single-logout URL
Both are dereferenced — a browser is sent to them — so both are held to the same rule.
The IdP entity ID is not held to any of this: it is a name, not an address, nothing dereferences it, and Okta’s genuinely begins
http://www.okta.com/. It is checked only for length and control characters.
The signing certificate
A bare base64 body is fine; so is full PEM. KnoxCall normalises what you paste and stores the PEM form. Expiry is deliberately not refused when you save — refusing to save a config whose certificate expires next week would block the very edit that fixes it. Signing in is refused: see an expired signing certificate.
Roles, domains and the rest
Saving also needs a re-authentication in the last five minutes, and that one re-authentication then covers every SSO save from the same signed-in session for fifteen minutes after it. A
403 asking you to re-authenticate is that (or the fifteen minutes running out, or a save from another browser), not a permissions problem — it is the same bar as changing a password, because this row names the identity provider allowed to assert who your users are.Refusals from the IdP metadata import
POST /admin/saml/connections/<id>/metadata reads your identity provider’s federation metadata; the flow is importing your IdP’s metadata. Every refusal below is decided before anything is written, and each carries a machine-readable code alongside the message.
An import never clears what the document does not carry. A metadata export made before you switched Single Logout on has no
SingleLogoutService, and KnoxCall leaves your stored SLO URL exactly where it was rather than reading the absence as “turn it off”. It never retires a certificate either — rotation stays add-first — and it does not touch the domain list.Symptoms with no error code
Everything worked, then every login started failing at once. The IdP rotated its signing certificate, or the one on the connection expired (that one has its own code,saml_idp_certificate_expired). Add the new one to the connection — rotation, with overlap.
Logins fail only for people who have never signed in before. The account rules, not the assertion: check the connection’s verified email domains and whether just-in-time provisioning is on.
Everyone lands with the wrong role. Group mapping decides the role a person gets when they are first added. Moving someone between groups in your IdP later does not change their KnoxCall role — change it on the team page.
Sign-in works from KnoxCall but not from the IdP’s app tile. That tile is an IdP-initiated login. Where your IdP can point the tile at a sign-on URL (Entra ID’s Sign on URL, JumpCloud’s and OneLogin’s Login URL), point it at the connection’s login URL, such as https://acme.knoxcall.com/saml/acme/login, which is the better answer anyway. Google Workspace’s Start URL and PingOne’s Target Application URL are not such a setting — both are the RelayState — so for those, and for Okta, the tile needs IdP-initiated sign-in switched on.
Repeated attempts start failing. The ACS and the SLO endpoint each accept 30 requests per minute per workspace and source address, with separate budgets so a logout storm cannot spend your sign-in allowance. Wait a minute.
Assertion encryption is not offered by the IdP at all. The app was configured from SP metadata that predates our encryption key. Re-upload the metadata — this is the 8 September 2026 call-out on every guide.
Sign-ins are matched by email address
A connection’s page shows this notice — and a test sign-in shows it beside its verdict — when the NameID your identity provider sends is the person’s login address. It is advice, never a refusal: sign-ins keep working, and a workspace may run this configuration knowingly. Why it matters. KnoxCall remembers each person by the NameID their identity provider sends (choosing the NameID). If that NameID is the address, renaming someone in your directory — a legal name change, a domain migration — changes the very value KnoxCall knows them by. Their next sign-in arrives with a NameID KnoxCall has never seen, so it creates a second account and a second membership for the same person: two audit trails, two sets of grants, and a deprovisioning that reaches only one of them. Changing an address inside KnoxCall is unaffected; this is about renames in your directory. The fix is in your identity provider. Point the NameID at a stable directory identifier and keep the email address in its own attribute — KnoxCall reads the address from the attributes first. It is the value that matters, not the format URI. The provider guides show where: on Microsoft Entra ID, the Name identifier value under Attributes & Claims, set to the objectid source attribute; on Okta, a Custom application username holding the Okta user ID, with the Name ID format left on the email-address format, because Okta requires it to match the format KnoxCall’s sign-in request names. The overview lists every provider. Prove it with a test sign-in. KnoxCall’s sign-in request names the email-address NameID format, and providers honour a format the request names, so the setting on its own is not proof. Run a test sign-in from the connection’s Test tab and read the NameID it reports — that request carries the same format as a real sign-in, so what it shows is what your people will send. People who have already signed in keep the account they have. Only the identifier future sign-ins carry changes, so make the change before your next rename rather than after it. Before anyone has signed in, a metadata import can see only the formats your provider’s document advertises. If it offers the email-address format, the notice reads Check what sign-ins are matched by instead. That format is expected — KnoxCall’s sign-in request names it — and a format is a label, not the value. Run a test sign-in and read the NameID; if it is a stable identifier, nothing needs to change. A fix in progress. When some people who used to sign in with an address now arrive with a stable identifier, the notice says the fix looks under way. It stays up while anyone’s most recent sign-in still carried an address that may not predate the change, and it clears as they sign in again.Still stuck
Collect these before contacting support — they are what makes a report actionable, and none of them is a secret:- your workspace slug and the URL you signed in from;
- the
error=code on the login page, and roughly when; - your IdP’s SAML tracer output, if you can capture one (Entra, Okta and JumpCloud all have one; browser extensions work everywhere);
- the SP metadata document your IdP currently holds, so it can be diffed against
https://acme.knoxcall.com/saml/acme/metadata.