Skip to main content

Single Sign-On (SAML)

KnoxCall is a SAML 2.0 service provider. Your identity provider authenticates the person; KnoxCall accepts the signed assertion, links or creates the account, and issues a session scoped to the workspace whose IdP asserted. Set-up is the same four moves everywhere:
  1. Prove the email domains your IdP will assert. See Verifying a domain.
  2. Give your IdP the KnoxCall URLs below (or upload our metadata document).
  3. Bring the IdP’s sign-in URL and signing certificate back to KnoxCall.
  4. Test with one account before you assign the app to everyone.
Per-provider walkthroughs: Microsoft Entra ID · Okta · Google Workspace · JumpCloud · Auth0 · OneLogin · PingOne. Running something else? Any SAML 2.0 identity provider works — ADFS, Shibboleth, Keycloak, PingFederate, a vendor we have not met. There is no walkthrough for yours, so take the generic route: give it our metadata document, import its federation metadata back, and read the two sections that are provider-independent — choosing the NameID and what an assertion may and may not do. The PingFederate notes are the closest thing to a template for a self-hosted server.
If you configured KnoxCall before 8 September 2026, re-upload our SP metadata to your IdP. The document changed in three ways that an IdP only learns about by re-reading it: KnoxCall now signs AuthnRequests, publishes an encryption key so your IdP can encrypt assertions to us, and publishes a Single Logout endpoint. An app configured from the old document will not offer token/assertion encryption at all, may reject our now-signed requests as unexpectedly signed, and cannot have Single Logout switched on — none of which is visible from KnoxCall’s side. Re-uploading the metadata (or re-importing the metadata URL, which is a snapshot in Entra, Okta and JumpCloud alike) is the whole fix.

What KnoxCall publishes

Replace acme with your workspace slug. Every URL is on your own workspace origin. These are the default connection’s URLs; a connection created in the setup wizard has its own set, shown on step 2 of the wizard — see more than one identity provider. The dashboard shows the ACS, metadata and login URLs ready to copy under Settings → Single sign-on. The metadata document is public and unauthenticated: you can fetch it before anything is configured, which is what makes it usable as step one. It is served for a connection in Draft or Testing as well as Active — only a Disabled connection has none — so you can upload it to your identity provider before KnoxCall holds a single one of its values. Sign-in itself still needs the connection Active. Your metadata document is the authoritative copy of all five values. Fetch it and read them off it rather than assembling them by hand — a self-hosted or single-tenant KnoxCall serves the same endpoints on a different origin, and the entity ID your IdP is configured with has to be byte-identical to the audience KnoxCall enforces.
These are the default connection’s URLs — the connection every workspace starts with — and they are permanent: metadata you upload today never needs replacing, and adding a second identity provider later does not disturb them. The /saml/<workspace>/… alias is that connection: it resolves there whenever a connection named default is active, so its entity ID, its ACS and the audience it enforces are the alias’s, byte for byte. A connection with any other handle publishes its own SP identity at /sso/<workspace>/<connection>/… instead. See more than one identity provider.

Importing your IdP’s metadata

The exchange runs both ways. Your IdP publishes a SAML 2.0 metadata document of its own, carrying the entity ID, the sign-on endpoints, the logout endpoint and every signing certificate at once — and KnoxCall will read it, so that none of those has to be transcribed by hand. A truncated certificate and an entry point copied from the wrong tenant are the two commonest reasons a first login fails. Hand KnoxCall the document itself, or the address it is published at:
One or the other, never both — “Send either — the document itself — or , where to fetch it from — but not both.” The <id> is the connection’s id, which is in the address bar when you have the connection open. The call previews by default; nothing is written until you send it again with "apply": true. The preview reports:
  • entry point and entity ID — what would be stored, plus every HTTP-Redirect and HTTP-POST SingleSignOnService endpoint the document publishes (redirect first, which is the one KnoxCall would use);
  • the Single Logout endpoints, same shape;
  • the certificates, each with its fingerprint, its validity dates, whether it has expired, and a state: new, already_active, or retired — that last one matters, because applying the import brings a certificate you deliberately retired back into service, and the preview is where you find that out;
  • the NameID formats the document offers. A format is a label, not the value: offering the email-address format is expected — it is the one KnoxCall’s sign-in request names, and the provider guides tell you to keep it — and it says nothing about whether the NameID value is the person’s login address, which is what choosing the NameID is about. So when the document offers it and nothing has signed in through the connection yet, the preview carries a notice asking you to run a test sign-in and read the NameID, not one saying the NameID is an address. Once people have signed in, the notice is decided by the NameIDs they actually sent, exactly as on the connection’s page;
  • changes — field by field, the stored value against the incoming one.
An import never clears what the document does not carry: an export made before you switched Single Logout on has no SingleLogoutService, and KnoxCall leaves your existing 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. What the document must be: a single <EntityDescriptor> in the SAML 2.0 metadata namespace, carrying an <IDPSSODescriptor>. A whole-federation <EntitiesDescriptor> is refused rather than guessed at, and so is the SP half — that is the document KnoxCall gives you. Every refusal, with its code, is in refusals from the IdP metadata import.
The dashboard runs the same import. Open the connection under Settings → Single sign-on: step 3 of its Setup tab takes the metadata URL or the downloaded file, shows you this preview, and writes nothing until you press Apply. The Add a certificate box on the Certificates tab is still the by-hand path. KnoxCall does store the URL you imported from, but nothing re-reads it on a schedule: when your IdP rolls its signing certificate, run the import again, or paste the new certificate. That is rotation, with overlap, unchanged.

What KnoxCall requires of the assertion

Our metadata carries the SP certificate twice, as use="signing" (so your IdP can verify our AuthnRequests) and as use="encryption" (so your IdP can offer assertion/token encryption at all). It is one certificate in both roles, which is what every IdP’s upload flow expects. The use="encryption" descriptor also lists the four content algorithms above, which is what an IdP configured from our document is offered. The algorithm rule applies wherever KnoxCall decrypts: an encrypted assertion at the ACS and at the connection test, and an encrypted NameID (<EncryptedID>) in a logout request. A message that names a refused algorithm, or one KnoxCall has never heard of, is turned away before it is decrypted. If your IdP offers a key transport setting, choose RSA-OAEP. Some IdPs label the refused one RSA1_5 or RSA15. The refusal names the algorithm; see troubleshooting.

The claims KnoxCall reads

Email. The address decides whether a person may be admitted at all — its domain must be one you have verified — and it is how KnoxCall finds an existing account the first time someone signs in. After that, the person is recognised by their NameID (see choosing the NameID). KnoxCall reads the address, in order, from: the attribute you named on the connection, then the IdP’s own email field, then the first of these attributes that is present —
— and finally the NameID itself when it looks like an address. That last step is a fallback, not a recommendation: send the address as its own attribute, and make the NameID a stable identifier instead. Every provider guide here maps an email attribute for exactly that reason. Display name. Same shape: the attribute you named, then the IdP’s displayName, then .../claims/displayname, .../claims/name, urn:oid:2.16.840.1.113730.3.1.241, displayName, name, cn. Absent, the local part of the email is used. Groups. KnoxCall reads the attribute you name in the connection’s attribute_map.groups, and otherwise the first of —
Groups only matter if you map them (below). Everything else in the assertion is ignored.

Choosing the NameID

KnoxCall remembers each person by the NameID your identity provider sends, per connection, and asks that question before it looks at the email address. That is what lets someone change their address inside KnoxCall without ending up with two accounts. It only protects against a rename in your directory if the NameID does not change when the person is renamed. If the NameID is the login address — the default in several identity providers — then renaming someone in your directory (a legal name change, a domain migration) changes the very value KnoxCall recognises them by. Their next sign-in looks like a stranger: KnoxCall creates a second account and a second membership for the same person, with its own audit trail and its own grants, and removing one of them does not remove the other. KnoxCall does not merge the two automatically, because merging on anything weaker than the NameID risks merging two different people. So: make the NameID a stable directory identifier — one that stays the same when the person is renamed — and send the email address as its own attribute. Each provider guide shows where:
  • Microsoft Entra ID — the objectid source attribute.
  • Okta — a Custom application username holding the Okta user ID.
  • Google Workspace and JumpCloud — a custom attribute holding a value that does not change.
  • OneLogin — the OneLogin ID, on the NameID value parameter.
  • PingOne — the User ID, on the saml_subject mapping.
  • Auth0 — already the Auth0 user id by default; the guide names the two edits that lose it.
People who have already signed in keep the account they have; only the identifier that future sign-ins carry changes. Make the change before your next rename, not after it. KnoxCall tells you when a connection is set up the way that forks. The connection’s page shows a notice when the NameIDs it has admitted are addresses, and a test sign-in shows it when the assertion it just checked carries one. A metadata import sees no NameID at all — only the formats your provider’s document advertises — so before anyone has signed in it says only what it can: if the document offers the email-address format, it asks you to run a test sign-in and read the NameID, because that format is expected and does not tell anyone what the value is. It is a warning, never a refusal — sign-ins keep working, and a workspace may run this configuration knowingly. It clears as people sign in again with a stable identifier. Prove it with a test sign-in. KnoxCall’s sign-in request names the email-address NameID format (the table above), and providers treat a requested format differently: Microsoft documents that Entra ID “honors the format in the request” when the request names one, and Okta documents that when the request includes a NameID policy, the application’s Name ID format “must match it”. Neither documents exactly what value accompanies that format once you have pointed the NameID at a stable identifier. So after changing it, run a sign-in from the connection’s Test tab and read the NameID the verdict reports — that request carries the same format as a real sign-in, so what it shows is what your people will send. If it still shows an address, the notice stays up, and it is telling you the truth.

Roles: what an assertion may and may not do

A SAML assertion is signed by your IdP, so as far as KnoxCall is concerned it is an unauthenticated door. It may confer member or readonly and nothing else:
  • The connection’s default role is what a new member gets. Saving anything else is refused: “Default role must be one of member, readonly. Just-in-time provisioning may never create an owner or an admin — elevate members on the team page.”
  • A group → role map overrides the default when the assertion carries a mapped group; if several map, the strongest wins. The same bound applies — “Group 'Engineering' maps to 'owner'; an IdP group may only map to member or readonly — an IdP-asserted login may never mint an administrator (elevate members on the team page).”
  • Owner and admin are always granted by a human, on the team page. No IdP configuration, group name or attribute can produce one.
Group mapping decides the role a person gets when they are first added to the workspace. Moving someone between groups in your IdP later does not currently change their KnoxCall role — change it on the team page. Removing their access in the IdP does stop them signing in, and Single Logout ends the sessions they already hold.

Domain proof, in one paragraph

Your IdP signs its own assertions, so it could assert any address at all. KnoxCall therefore only lets an assertion claim addresses at domains you have proven you control, by publishing a TXT record we give you. Proving acme.com covers eu.acme.com; proving a subdomain never covers its parent. Without a proven domain, just-in-time provisioning is refused outright and a pre-existing account that is not already a member is refused too. Only an SSO domain proof admits a login — a domain you verified for sending mail is a different proof about a different question and does not count here. The full flow, the exact record and every refusal are in Verifying a domain.

IdP-initiated sign-in

Off unless you turn it on, per connection.
  • SP-initiated (the default): the person starts at KnoxCall, on the connection’s login URL — https://acme.knoxcall.com/saml/acme/login for the default connection. Bookmark it, or publish it as the sign-in link for your workspace — KnoxCall sends a signed AuthnRequest, and the assertion that comes back is bound to that request.
  • IdP-initiated: the person clicks a tile in the IdP’s app launcher and an unsolicited assertion is POSTed to the ACS. It answers no request of ours, so anyone holding one can post it into a browser at a time of their choosing. That is why it is opt-in. With it off, an unsolicited assertion is refused with saml_idp_initiated_disabled.
The control is the Accept sign-ins started at the identity provider toggle, under Who may sign in on the connection’s Connection tab (allow_idp_initiated on the API). Turn it on and save. Use the page rather than the API for this. PUT /admin/saml and PUT /admin/saml/connections/<handle> are whole-object replaces, not patches: a field you leave out is reset to its default — null for most of them — rather than left alone. So send the whole connection, and send a real boolean, because the string "true" is refused: “Allow IdP-initiated sign-in must be true or false.” A one-field body does not get you a patch, it gets you a refusal: PUT /admin/saml answers “The IdP sign-in URL is required.”, and PUT /admin/saml/connections/<handle> answers “Verified email domains are required — list at least one domain your company controls.” Four fields are exceptions — they keep whatever is stored when your body does not mention them — and they are not the same four on both routes: On the IdP-initiated flow only, KnoxCall honours RelayState as a deep link — but only as a relative path inside the app, such as /secrets. An absolute URL is dropped and the person lands on the default page. KnoxCall issues no RelayState of its own, so the box for it in your identity provider stays blank unless you want the tile to open a particular page. Each provider names that box differently: Entra ID’s Relay State, Okta’s and JumpCloud’s Default RelayState, OneLogin’s RelayState, Google Workspace’s Start URL and PingOne’s Target Application URL. The last two read like a sign-in address and are not one: a KnoxCall login URL there is a full URL, and is dropped.

More than one identity provider

A workspace may run several active connections at once — one per identity provider, or one per business unit that brought its own. They do not authenticate for each other: each connection has its own SP identity, and an assertion is only ever accepted by the connection whose audience it names. The connection named default owns the /saml/<workspace>/… URLs above; a workspace set up before the setup wizard has one. The wizard names a new connection after its provider — entra, okta, google-workspace, jumpcloud, auth0, onelogin, ping — unless you change it, and every connection other than default publishes at its own path, built from its Handle — chosen when the connection is created, and shown under its name: Two things worth knowing before you add the second one:
  • The /saml/<workspace>/… alias is the default connection. It resolves to the connection named default whenever one is active, so the first IdP keeps working exactly as it did — that connection’s own URLs are the alias, and nothing you configured before adding the second IdP has to change. The alias answers 409 with saml_connection_ambiguous in one case only: two or more connections are active and none of them is named default. Then it will not guess, and each connection has to be reached at its own /sso/<workspace>/<handle>/{metadata,acs,login,slo}. The practical rule follows from that: keep your first identity provider on the connection named default, and give the second one its own handle and its own URLs.
  • The dashboard shows each connection’s own URLs. Open the connection under Settings → Single sign-on and its Certificates tab lists five values for that connection — SP entity ID, sign-on / ACS URL, login URL, Single Logout URL and metadata URL — each with a copy button, above a link that opens its metadata document. A connection whose handle is not default shows its /sso/… set there, not the alias. The metadata document stays authoritative for all five: https://acme.knoxcall.com/sso/acme/<connection>/metadata is public, so a browser will do, and GET /admin/saml/connections/<id>/sp-metadata returns the same document as a download for an authenticated owner or admin — which is the reason to prefer uploading it to your IdP over typing anything.

If your IdP was configured with an identifier of its own

The connection form has an optional SP entity ID. Leave it empty and KnoxCall uses this connection’s own metadata URL, which is what the metadata document publishes and is unique by construction. Set it only when your identity provider already knows KnoxCall by another identifier — and then two rules apply, because that one string becomes both the issuer KnoxCall sends and the audience every assertion must name:
  • It may not be a KnoxCall-shaped URL. Any value whose path sits under /saml/ or /sso/, on any host, is refused: “That service-provider entity ID is shaped like one of ours: its path is under /saml/ or /sso/, which is the address family KnoxCall computes SP identities in…” Otherwise a connection could claim the identity another connection’s sign-on URL enforces, and an assertion minted for that one would be accepted here.
  • It must be unique across every KnoxCall workspace, not only yours: “That service-provider entity ID is already in use. An SP entity ID is a name in one global namespace…” The refusal deliberately names no other workspace or connection — you are told the string is taken and nothing more, so pick another identifier your IdP owns, or empty the field and take the computed one.

Single Logout

KnoxCall supports SLO in both directions at one URL per connection, on both bindings. For the default connection that is the alias, https://acme.knoxcall.com/saml/acme/slo; every other connection ends its own sessions at https://acme.knoxcall.com/sso/acme/<connection>/slo. A logout message only ever ends the sessions the connection it arrived at authenticated.
  • Your IdP ends the session. A signed LogoutRequest naming the person’s NameID (and, when present, the SessionIndex) ends the sessions this workspace’s IdP authenticated — access tokens stop being accepted and the refresh family is revoked. Sessions the same person holds in a different workspace are untouched: that workspace’s IdP and policy never participated.
  • The person signs out of KnoxCall. If their session was minted by SAML, KnoxCall answers the sign-out with a signed LogoutRequest aimed at your IdP’s SLO endpoint. The KnoxCall session is revoked either way — never conditionally on the IdP leg.
Three requirements:
  • Your IdP’s SLO URL is a connection setting (idp_slo_url) and must be https. It is a real destination — a browser is redirected there carrying a NameID, which is usually a person’s email address. Empty means “this connection does not do SP-initiated Single Logout”; it never falls back to the sign-in URL.
  • A redirect-binding logout message must be signed. An unsigned one is refused (saml_logout_unsigned) — otherwise anyone who could reach the URL could sign out any user whose email address they could guess.
  • Logout messages are accepted for 5 minutes and once (saml_logout_stale, saml_logout_replay).
Single Logout is deliberately not plan-gated: refusing to end a session because a subscription lapsed is the wrong direction of that control.

Certificate rotation, with overlap

Your IdP’s signing certificate expires. Rotate it add-first — never retire-then-add.
  1. Add the new certificate while the old one is still active. Paste it into Settings → SSO → your connection → Certificates → Add a certificate. Pasting a certificate adds it; it does not replace the one already there.
  2. Check that both are listed as active. The Certificates tab shows every certificate on the connection with its fingerprint and its expiry date. An assertion signed by any active certificate verifies while that certificate is within its validity dates, so while both are listed and unexpired you are covered whichever key your IdP signs with.
  3. Switch your IdP over to signing with the new key. In every provider documented here this is a setting on the application or the account, not something KnoxCall can trigger. In Auth0 the signing key is the tenant’s and rotating it re-signs every SAML app in that tenant; in OneLogin and PingOne the certificate is the account’s or the environment’s and each app selects one, so switching is per app.
  4. Sign in once, to confirm the new certificate is the one being used.
  5. Retire the old certificate. It stops being able to verify an assertion or a logout message immediately; the row stays for the audit trail, with the time you retired it.
There is no window in which sign-in is down, because at every step at least one active, unexpired certificate matches the key your IdP is signing with. Finish before the old certificate expires: from that moment KnoxCall refuses anything it signs, even while it is still listed as active.

What happens if you retire the last one

You cannot. The writer refuses it: “This is the connection’s only active IdP certificate. Add the new certificate first, then retire this one.” The same rule applies when you try to switch a connection on without one: “An SSO connection cannot be activated without at least one active IdP certificate.” — and one with no sign-in URL: “An SSO connection cannot be activated without an IdP entry point.” That refusal protects you from the obvious mistake, and only from that one. It cannot stop you from keeping a single active certificate that your IdP has already stopped using — which is why the expiry mail below exists.

The expiry email

Nothing re-reads your IdP’s metadata on a schedule (see the note under importing your IdP’s metadata), so the certificate KnoxCall holds is the one you last gave it. What KnoxCall does watch is that certificate’s own expiry date: it reads not_after on every active certificate of every active connection and emails the workspace’s owners and admins at 30 days, 14 days, 3 days, and again once it has expired. Each of those four fires once per certificate. Nobody has to be looking at the page. The expiry date is when sign-in through that certificate stops. KnoxCall accepts a signature only when a certificate that is valid at that moment verifies it, so from the second a certificate expires, anything signed with it is refused — at sign-in, at a connection test and at Single Logout — with the code saml_idp_certificate_expired and the reason idp_certificate_expired in the audit log’s login refused entry. That holds for every connection. Two things the mail will tell you, because they lead to different actions:
  • Another active certificate outlives this one. Sign-in keeps working past the date as long as your IdP is signing with that newer certificate by then. Finish the rotation — confirm it is, then retire this one.
  • No other certificate outlives this one. Sign-in through this connection stops when it expires. The remedy is step 1 above: add the new certificate, after rotating it in your IdP if it has not issued one yet. If the date has already passed, get your IdP’s current signing certificate — paste it into Add a certificate, or re-run the metadata import, which reads every signing certificate the document carries — add it, and sign-in resumes on the next attempt. There is nothing else to switch back on.
If a certificate was uploaded before KnoxCall recorded expiry dates, its expiry is filled in the first time the check runs. A certificate KnoxCall cannot parse at all is reported to the operator rather than assumed healthy.

Doing it over the API

Adding a certificate out-of-band is POST /admin/saml/connections/<id>/certificates; retiring one is DELETE /admin/saml/connections/<id>/certificates/<certId>. Both need the owner or admin role and a re-authentication in the last 5 minutes, like every other write on this surface; one re-authentication covers every SSO write from the same signed-in session for fifteen minutes after it.

Plan and permissions

  • SSO is included on the Pro and Enterprise plans. If the subscription lapses, existing connections keep authenticating your members — only configuration is refused: “Single sign-on configuration requires a current plan that includes single sign-on. Existing SSO connections keep authenticating your members; adding or changing one needs the subscription brought up to date.”
  • Configuring SSO needs the owner or admin role plus a re-authentication in the last 5 minutes (one re-authentication covers every SSO write from the same signed-in session for fifteen minutes after it, so a connection set up in one sitting asks once). Anyone else is refused: “Managing the SAML connection requires the owner or admin role — this row is the tenant’s authentication policy: it names the identity provider allowed to assert who your users are, and the email domains whose accounts it may claim.”
  • KnoxCall staff cannot write your SSO configuration. It is refused at the same surface an operator would have to use.

Rate limits and safety rails

  • The ACS and the SLO endpoint each accept 30 requests per minute per (workspace, source address) pair, with separate budgets so a logout storm cannot spend your sign-in allowance.
  • The ACS is public, so refusals are deliberately uninformative to the caller; the detail is in your workspace’s audit and security events, and the connection’s Setup tab lists the most recent refused sign-ins with their reasons.
  • The /saml/<slug>/… alias resolves to the connection named default, however many others are active alongside it. It refuses to guess — 409, saml_connection_ambiguous — only when two or more connections are active and none carries that name. The connection-scoped /sso/<workspace>/<connection>/… URLs name one connection and are never ambiguous.

When it does not work

Every refusal message and every error code, with what to do about each: SSO troubleshooting.