Organization Domains

An organization domain is a DNS domain that an AISIX Cloud organization has proved it controls, by publishing a TXT record. Once a domain is verified, the organization's identity provider (IdP) is trusted for the email addresses in that domain: single sign-on connects people to their accounts by email address without the Connect page, and SCIM directory sync provisions them as members directly.

Organization domains exist only on the SaaS service. Every organization there controls its own IdP and SCIM token, which could assert any email address, so AISIX Cloud trusts an address only when the organization has proved it owns the address's domain. An On-Premises control plane trusts its IdP for every address, has no Domains page, and does not serve the domain endpoints.

Who Can Manage Domains

Only an organization owner can add, verify, or remove domains, for the same reason that only an owner can configure SSO: whoever controls the trusted IdP can sign in as the accounts in a verified domain. The Domains page in the organization menu shows other roles an explanation only.

Add and Verify a Domain

1. Open Domains in the organization menu.

2. Enter the domain, such as example.com, and select Add domain.

3. The page shows the TXT record to publish for the domain:

   Type	Name	Value
   TXT	_aisix-verification.<domain>	aisix-verification=<token>

   The token is generated when the domain is added. Copy the name and value with the Copy buttons.

4. Publish the record at the domain's DNS provider.

5. Back on the Domains page, select Verify. AISIX Cloud looks the record up at once. When it finds the value, the domain becomes Verified.

If the record is not found, the domain stays Pending, and you can select Verify again after the DNS change has propagated. If the DNS lookup itself fails, for example because it times out, the page reports the failure without treating the record as missing. Verification is rate-limited to 10 attempts per minute.

The rules for a domain name:

• Enter the bare domain name, such as example.com. It is stored in lowercase, without a trailing dot.
• Enter an internationalized domain name in its punycode form, starting with xn--.
• Public email domains, such as gmail.com, outlook.com, qq.com, and 163.com, cannot be added.
• An organization can hold up to 50 domains, pending and verified together.

Exact Match and Ownership

A verified domain covers exactly that name and not its subdomains. Verifying example.com does not cover mail.example.com. Add and verify each domain that your email addresses use.

A verified domain belongs to one organization. Once an organization has verified a domain, no other organization can verify it. A pending domain reserves nothing, so several organizations can add the same domain, and the first one to verify it gets it.

Re-Checks and Lapsing

AISIX Cloud checks every verified domain again about every 24 hours. When the record is missing or carries another value in 3 checks in a row, about 72 hours, the domain reverts to unverified and shows as Lapsed. Another organization can then verify it. The page shows how many checks in a row have failed. Select Verify at any time to check again, including for a lapsed domain.

A check whose DNS lookup fails, rather than finding no record, does not count as a failure. It is retried an hour later, so a resolver outage does not make domains lapse.

Keep the TXT record published for as long as the organization relies on the domain.

What a Verified Domain Changes

For an email address in a verified domain:

• SSO links accounts by email address. On a person's first SSO sign-in, the account that uses the address is connected to their identity directly, without the Connect page. When no account uses the address, one is created if the organization admits the person, through just-in-time provisioning or an invitation. See First Sign-In.
• SCIM provisions members directly. A user that SCIM provisions at the address becomes a member at once, on the account that uses the address, or on a new account without a password. Addresses outside the verified domains become members waiting to join instead.
• Unverified accounts are taken over. An account that was registered for an address in the domain but never verified it is taken over when SSO or SCIM claims it. It loses its password, its sessions, its pending email verification links, and its links to other organizations' SSO connections. It is then reset to the account the organization would have created for the person: it takes the name that SSO or SCIM would have given a new account, the registrant's acceptance of the User Agreement and Privacy Policy is cleared, and its email address is marked verified. An account that already verified its address is only connected, and keeps its name.

Removing a domain, or a domain lapsing, does not disconnect anyone. Accounts already connected to the organization's SSO keep signing in. Only first sign-ins of new people go through the Connect page again.

Deleting the organization releases its domains at once, so another organization can verify them right away.

Audit Records

Domain changes are recorded in the audit log with the resource type org_domain and the actions create, verify, lapse, and delete. The entries name the domain, and a lapse entry also carries the number of failed checks. The verification token is never recorded.

Each takeover of an unverified account is recorded in the audit log of the organization whose domain took it over, with the resource type verified_domain_claim, the action create, and the account's ID as the resource ID. Its recorded after state carries:

Field	Value
via	sso for a single sign-on, or scim for directory sync.
domain	The verified domain of the address.
user_id	The account's ID.
previous_name	The account's name before the takeover.
password_revoked	true when the account had a password that was removed.
sessions_revoked	The number of sessions ended.
verification_links_revoked	The number of pending email verification links retired.
identity_links_removed	The number of links to other organizations' SSO connections removed.

For a single sign-on, the actor is the account itself, as on other SSO entries. For directory sync, the actor is the owner of the SCIM token. Each removed SSO link is also recorded in the log of the organization it belonged to, as an sso_identity_link deletion.

Next Steps

Configure Single Sign-On (SAML) and SCIM Directory Sync for the people in your verified domains.