# 组织域名

组织域名是 AISIX Cloud 组织通过发布 TXT 记录、证明自己掌控的 DNS 域名。域名验证通过后，组织的身份提供方（IdP）对该域名下的邮箱地址受到信任：[单点登录](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md)按邮箱地址把人员关联到账号，无需经过关联页面；[SCIM 目录同步](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md)直接把他们预配为成员。

组织域名只存在于 AISIX Cloud 中。在 AISIX Cloud 上，每个组织都掌控自己的身份提供方和 SCIM Token，它们可以断言任意邮箱地址，因此只有当组织证明自己拥有某个地址所在的域名时，AISIX Cloud 才信任该地址。AISIX Enterprise 控制面信任其身份提供方断言的所有地址，没有 **域名** 页面，也不提供域名相关的接口。

## 谁可以管理域名[​](#who-can-manage-domains "谁可以管理域名的直接链接")

只有组织 **所有者** 可以添加、验证或移除域名，原因与只有所有者可以配置 SSO 相同：掌控受信任身份提供方的人，可以登录已验证域名内的账号。其他角色在组织菜单的 **域名** 页面上只能看到说明。

## 添加并验证域名[​](#add-and-verify-a-domain "添加并验证域名的直接链接")

1. 在组织菜单中打开 **域名**。

2. 输入域名，例如 `example.com`，然后选择 **添加域名**。

3. 页面会显示该域名需要发布的 TXT 记录：

   | 类型  | 名称                           | 值                           |
   | ----- | ------------------------------ | ---------------------------- |
   | `TXT` | `_aisix-verification.<domain>` | `aisix-verification=<token>` |

   Token 在添加域名时生成。可使用 **复制** 按钮复制记录名称和值。

4. 在该域名的 DNS 服务商处发布这条记录。

5. 回到 **域名** 页面，选择 **验证**。AISIX Cloud 会立即查询该记录，找到对应的值后，域名变为 **已验证**。

如果没有找到记录，域名保持 **待验证**，等 DNS 变更生效后可以再次选择 **验证**。如果 DNS 查询本身失败（例如超时），页面会报告查询失败，而不会把它当作记录不存在。验证请求限制为每分钟 10 次。

域名需满足以下规则：

* 输入裸域名，例如 `example.com`。域名以小写形式保存，并去掉末尾的点。
* 国际化域名需输入以 `xn--` 开头的 punycode 形式。
* 不能添加公共邮箱域名，例如 `gmail.com`、`outlook.com`、`qq.com` 和 `163.com`。
* 每个组织最多可以有 50 个域名，待验证和已验证的合计。

## 精确匹配与归属[​](#exact-match-and-ownership "精确匹配与归属的直接链接")

已验证的域名只覆盖这个名称本身，不包括子域名。验证 `example.com` 不会覆盖 `mail.example.com`。请为邮箱地址使用的每个域名分别添加并验证。

一个已验证的域名只属于一个组织。某个组织验证了一个域名后，其他组织就无法再验证它。待验证的域名不会占用任何东西，因此多个组织可以添加同一个域名，最先验证的组织获得它。

## 定期复查与失效[​](#re-checks-and-lapsing "定期复查与失效的直接链接")

AISIX Cloud 大约每 24 小时重新检查一次每个已验证的域名。如果连续 3 次检查（约 72 小时）发现记录不存在或值不匹配，域名会恢复为未验证，显示为 **已失效**，之后其他组织就可以验证它。页面会显示已经连续失败了几次检查。你可以随时选择 **验证** 重新检查，已失效的域名也可以。

DNS 查询本身失败（而不是没有找到记录）的检查不计为失败，一小时后重试，因此解析器故障不会让域名失效。

只要组织仍依赖该域名，就请保持这条 TXT 记录处于发布状态。

## 已验证域名带来的变化[​](#what-a-verified-domain-changes "已验证域名带来的变化的直接链接")

对于已验证域名内的邮箱地址：

* **SSO 按邮箱地址关联账号。** 此人首次通过 SSO 登录时，使用该地址的账号会直接与其身份关联，不经过[关联页面](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#the-connect-page)。没有账号使用该地址时，如果组织接纳此人（通过 JIT 预配或邀请），会为其创建账号。参见[首次登录](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md#first-sign-in)。
* **SCIM 直接预配成员。** SCIM 以该地址预配的用户会立即成为成员，使用该地址对应的账号，或者一个没有密码的新账号。已验证域名以外的地址则会成为[等待加入的成员](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md#members-waiting-to-join)。
* **未验证的账号会被接管。** 为该域名下的地址注册、但从未验证邮箱的账号，在被 SSO 或 SCIM 认领时会被接管：它失去密码、会话、尚未使用的邮箱验证链接，以及与其他组织 SSO 连接的关联。随后账号会被重置为组织本应为此人创建的样子：名称改为 SSO 或 SCIM 新建账号时会使用的名称，注册人对《用户协议》和《隐私政策》的同意记录被清除，邮箱地址被标记为已验证。已验证过邮箱的账号只会被关联，并保留原名称。

移除域名或域名失效都不会断开任何人的关联。已关联到组织 SSO 的账号照常登录，只有新人员的首次登录会重新经过关联页面。

删除组织会立即释放其域名，其他组织可以马上验证这些域名。

## 审计记录[​](#audit-records "审计记录的直接链接")

域名变更以资源类型 `org_domain` 记录在[审计日志](https://docs.apiseven.com/ai-gateway/cloud/logging-and-auditing.md)中，动作为 `create`、`verify`、`lapse` 和 `delete`。记录中包含域名，`lapse` 记录还包含失败检查的次数。验证 Token 从不写入审计记录。

每次接管未验证账号，都会记录在其域名接管该账号的组织的审计日志中，资源类型为 `verified_domain_claim`，动作为 `create`，资源 ID 为该账号的 ID。记录的变更后状态包含：

| 字段                         | 值                                      |
| ---------------------------- | --------------------------------------- |
| `via`                        | 单点登录为 `sso`，目录同步为 `scim`。   |
| `domain`                     | 该地址所属的已验证域名。                |
| `user_id`                    | 账号 ID。                               |
| `previous_name`              | 接管前的账号名称。                      |
| `password_revoked`           | 账号原有密码被移除时为 `true`。         |
| `sessions_revoked`           | 被结束的会话数。                        |
| `verification_links_revoked` | 被作废的待使用邮箱验证链接数。          |
| `identity_links_removed`     | 被移除的、与其他组织 SSO 连接的关联数。 |

单点登录时，操作者是该账号本身，与其他 SSO 记录一致；目录同步时，操作者是 SCIM Token 的所有者。每个被移除的 SSO 关联还会以 `sso_identity_link` 删除记录的形式，记录在该关联所属组织的审计日志中。

## 下一步[​](#next-steps "下一步的直接链接")

为已验证域名内的人员配置[单点登录（SAML）](https://docs.apiseven.com/ai-gateway/cloud/single-sign-on.md)和 [SCIM 目录同步](https://docs.apiseven.com/ai-gateway/cloud/scim-directory-sync.md)。
