Federated domains and domain verification

Registering an identity provider tells Qorionix that a provider exists. It does not tell Qorionix who should be sent to it. That is what a federated domain does: it says that anybody typing an address in yourfirm.com at the sign-in prompt should be handed to your identity provider rather than asked for a Qorionix password.

Because that is a statement about who controls a namespace, it has to be proved rather than asserted. A tenant that could route any domain it named could route yours.

Where it lives

Identity → Domain routing. The page itself is headed Email domain routing — the two names differ, so search for either. Its description is the whole feature in one line: Home-realm discovery: which email domain sends a person to which identity provider instead of asking for a password.

Reading the list needs iam:federation.read; claiming, verifying and reissuing need iam:federation.write; removing a domain needs iam:federation.delete. A role named delegated_admin receives read and write but deliberately not delete, on the reasoning that a registered provider is an outside authority whose assertions become logins here — see Delegated administration.

The table columns are Domain, Routes to, Ownership, Added, Routes logins and Last checked. The two to read together are Ownership and Routes logins: the first is a verification state, the second is a plain Yes or No answering the only question that matters operationally.

Claiming a domain

1. 1

   Press Add domain

   The wizard is headed Route an email domain and explains itself: Someone typing an address in this domain at the sign-in prompt is sent to the provider you choose, without being asked for a Qorionix password.

2. 2

   Enter the bare domain

   The field is Email domain, and its help is precise about scope: The part after the @, for example contoso.com. Subdomains are not included — add mail.contoso.com separately if your people use it. A value with an @, a scheme or a path is refused with Enter a bare domain such as contoso.com — no @, no https://, no path.

3. 3

   Choose the provider

   Send these people to, with the help Only providers configured in this organization can be chosen. If the list is empty you have no federated provider yet, and the wizard says so: A domain has to route to something, and this organization has no federated providers yet. Add a provider first.

4. 4

   Read the toast, because it tells you the state you are now in

   {domain} claimed. It routes no logins until you publish the TXT record and it is verified. A claim on its own does nothing.

The DNS record

Press DNS record on the domain's row. The panel is headed DNS record for {domain} and gives you three values, each with its own Copy control.

Record type:  TXT
Record name:  _qorionix-challenge.yourfirm.com
Record value: qorionix-domain-verification=zq1-<43 random characters>

The panel explains why the record sits where it does, and the reason is worth understanding before somebody on your team tidies it away:

The proof is simply that only somebody who controls the zone can create that record. There is no cleverness in it and none is needed.

Publish it, then press Check ownership. The panel warns that DNS changes can take up to an hour to propagate, which in practice means: if the first check says the record is absent, wait rather than assuming you made a mistake.

The states, and what each one means

There is a sixth thing you may see, and it is not a state: Could not check. That means the DNS lookup itself did not complete — a resolver problem, a timeout, a zone that failed to answer. It is reported separately from the record was absent on purpose, because the two mean opposite things and treating an outage as an absence is how a working federation gets switched off during somebody else's incident.

Rechecking, and the seven-day grace period

Verification is not a one-off. A background job rechecks domains on a cadence that depends on their state, so a record deleted a year after setup is noticed rather than trusted forever.

The practical consequence: put the challenge record in whatever documentation your DNS zone has, next to the SPF and DMARC entries. It looks like debris to anybody who does not know what it is, and the person tidying the zone is rarely the person who set up federation.

Two organisations claiming the same domain

Claims are not exclusive until one is proven. Several organisations can hold an unverified claim on the same domain — that is the state a shared contractor's domain, or a typo, naturally produces — and none of them routes anything.

When one of them verifies, it wins and the others are released. The console reports it plainly:

That is the right resolution: proof beats assertion, and an unproven claim by somebody else should not be able to block you. If you are on the receiving end of a release, you claimed a domain you cannot prove you control, and the fix is to prove it or to remove the claim.

Reissuing a challenge

Issue a new challenge mints a fresh token. It is the right action if the old value leaked, or if you have lost track of which record is current. It is not a repair for a failed check, and it makes things worse if you use it as one, because the confirmation says exactly what it costs:

So reissuing demotes a verified domain immediately, with no grace period. If federation is working, do not press it to see what happens.

Removing a domain

Deleting the routing rule sends those people back to a password prompt, and the confirmation says so: Stop routing {domain} to {provider}? People with an address in this domain will be asked for a Qorionix password again instead of being sent to the provider.

That is worth thinking about for a moment before you confirm it. If your people were provisioned through federation and never set a Qorionix password, sending them back to a password prompt is not a fallback — it is a lockout. Check that they have another way in before removing the last domain that routes to a provider.

Checking it worked

1. Confirm the record from outside our infrastructure: dig TXT _qorionix-challenge.yourfirm.com +short should return the value the panel shows, quoted. If it returns nothing, the record has not propagated or is on the wrong name.
2. Press Check ownership and read the result rather than the row. Every outcome returns success at the HTTP level and carries its own reason, so a client that only looks at the status code will think every check passed.
3. Confirm the Routes logins column reads Yes.
4. Test the actual journey with a real address in that domain. The identifier-first sign-in flow explains what should happen and which endpoint answers.

If the domain verifies and sign-in still asks for a password, the problem is not here — it is either the provider itself or which discovery endpoint your sign-in page is calling, and the identifier-first article covers both.