Skip to main content

​
Verifying a Domain for SSO

Your identity provider signs its own assertions. Nothing in SAML stops it asserting ceo@some-other-company.com — the signature proves the message came from your IdP, not that your IdP speaks for that address. KnoxCall therefore admits an assertion only for domains the workspace has proven it controls, by publishing a DNS TXT record. Until at least one domain is proven, SAML sign-in cannot create or link any account for the workspace: just-in-time provisioning is refused outright, and a pre-existing account that is not already a member is refused too.

​
The record

Claim the domain in KnoxCall first — the value contains a token minted for your workspace, so there is nothing to publish until you have it. The name is the label _knoxcall-verify beneath the domain you are proving — proving eu.acme.com means publishing at _knoxcall-verify.eu.acme.com. The value must match exactly, including the knoxcall-domain-verification= prefix; a provider that splits long TXT strings into chunks is fine, KnoxCall re-joins them before comparing.

​
Adding and verifying a domain

Settings → Single sign-on, open the connection, then the Domains tab.
  1. Type the domain and press Claim domain. The row appears straight away, marked Waiting for the TXT record, carrying the three values to publish — Record name, Record type and Record value — each with a copy button.
  2. Publish that TXT record in your DNS, and give it time to propagate.
  3. Press Verify. KnoxCall resolves the name and compares the value. On success the row becomes Proven, with the date. On failure the claim stays exactly where it was and the row shows what the check actually saw, under Last check reported — fix the record and press Verify again.
Remove deletes a claim or a proof. Removing a proof stops it admitting logins at the very next sign-in. A domain proven on that tab admits every connection in the workspace. (KnoxCall can also honour a proof bound to a single connection, but nothing creates one yet, so every proof you make today is workspace-wide.) Re-claiming a domain you have already claimed returns the same token rather than rotating it, so reloading the page, or retrying, never invalidates a record you have already published.

​
The same thing from a script

The tab is the supported flow; these are the routes underneath it, if you provision workspaces from code. They need an authenticated dashboard session belonging to an owner or admin who has re-authenticated in the last 5 minutes.
The response carries the record to publish. Publish it, wait for DNS to propagate, then:
GET /admin/saml/domains lists what you have claimed and proven; DELETE /admin/saml/domains/<id> removes a claim or a proof.

​
What a proven domain covers

  • Exactly the domain, and anything beneath it. Proving acme.com admits alice@acme.com and bob@eu.acme.com.
  • Never a parent. Proving eu.acme.com does not admit alice@acme.com. That direction is the one an attacker would want.
  • Proof is read live, on every assertion. Removing a proof stops it admitting logins at the next sign-in — there is no cached grant to expire.
You can also narrow admission further with the connection’s verified email domains list. That list is a filter over your proven domains, not an authority of its own: putting a domain in it that you have not proven is refused, and a domain on it whose proof you later delete admits nobody at the very next sign-in. The settings form requires at least one entry; a connection carrying none admits every domain you have proven.
A domain verified for sending mail does not admit an SSO login. They are two proofs about two different questions, and since 8 September 2026 tenant_sso_domains — the table this page writes — is the only authority KnoxCall consults when deciding whose IdP-asserted address may claim a KnoxCall account. Mail verification is written by an onboarding flow and by an unattended job, and its rules were written for undelivered mail, not for account takeover. If you verified a domain for email, verify it again here: the same style of TXT record, under a different name, and it takes a minute.Nothing broke at the changeover — every mail-verified domain that a configured SSO connection was relying on was carried across once. New domains are proven here only.

​
Rules a domain has to satisfy

​
When verification fails

Each of these leaves the claim in place; fix the cause and verify again.

​
Two refusals you will meet on the connection, not the domain

  • “At least one verified email domain is required. Without it, SAML sign-in cannot create or link any account for this tenant — just-in-time provisioning is refused outright, and a pre-existing account that is not already a member is refused too.” — you saved a connection with an empty domain list.
  • “eu.acme.com is not covered by a domain you have verified for single sign-on (acme-corp.com). A SAML assertion is signed by your own IdP, so KnoxCall only lets it claim addresses at domains you have proven you control under Settings → Single sign-on → Domains.” — the list names a domain whose proof does not cover it. Prove that domain on the Domains tab, or list one that is covered.
  • “You have not verified any domain for single sign-on yet, so acme.com cannot be trusted for SAML sign-in. … A domain verified for sending mail is a separate proof and does not count here…” — you have proven nothing under Single sign-on → Domains. Do that first; a mail-sending proof is not accepted here (see the note above).
Next: pick your provider — Microsoft Entra ID, Okta, Google Workspace or JumpCloud.