连接 Microsoft Entra ID
（SSO、SCIM）

需要准备的

• 在 Microsoft Entra admin center（https://entra.microsoft.com）中，拥有 Application Administrator 或更高的角色。
• SSO（OpenID Connect）在 Entra ID 的免费版中即可使用。
• Aiyori 不在应用库中，所以 SCIM（自动预配）需要 Entra ID P1 或更高版本（Microsoft 365 E3、E5、Business Premium 等都包含）。
• Aiyori 组织的管理员能打开讲师画面的“设置”→“连接公司的身份管理平台”。

SSO 和 SCIM 都在同一个应用上设置。创建企业应用后，也会生成同名的应用注册（App registrations）。SSO 在应用注册中设置，SCIM 在企业应用中设置。

1. 创建应用

1. Entra admin center → Entra ID → Enterprise applications → + New application → + Create your own application。
2. 名称填入 Aiyori，选择 Integrate any other application you don’t find in the gallery (Non-gallery)，然后 Create。
3. 在该应用的 Properties 中，把 Assignment required? 设为 Yes（只有被分配的人才能登录）。如果要在 My Apps 中放置磁贴，在 Home page URL 中填入 https://app.aiyori.app/api/web/sso/start?code=（组织代码）。最后 Save。

2. SSO（OpenID Connect）

1. Entra ID → App registrations → All applications → 打开第 1 节创建的 Aiyori。
2. 在 Overview 中，记下 Directory (tenant) ID 和 Application (client) ID。
3. Authentication → + Add a platform → Web → 在重定向 URI 中填入 https://app.aiyori.app/api/web/sso/callback → Configure。不要勾选隐式授权的两个复选框（Aiyori 使用授权码流程和 PKCE）。
4. Certificates & secrets → Client secrets → + New client secret → 说明填 Aiyori，有效期建议 12 个月（最长 24 个月）→ Add → 记下 Value（只在此画面显示）。
5. Token configuration → + Add optional claim → ID → 勾选 email → Add。如果询问是否开启 Microsoft Graph 的 email 权限，勾选后添加。
6. API permissions 保持默认的 User.Read 即可（Aiyori 只请求 openid email profile，不需要管理员同意）。
7. 在 Aiyori 的讲师画面 →“设置”→“连接公司的身份管理平台”→“SSO”中填入下表的值，然后按“保存”。
8. Enterprise applications → Aiyori → Users and groups → + Add user/group，分配 1 位测试人员。
9. 如果此人能从 Aiyori 的登录画面 →“使用公司账号登录”→ 组织代码 → Microsoft 登录 → 回到 Aiyori，就说明已经连接成功。如果还没有连接 SCIM，请先把此人登记为学员（填入公司邮箱地址），或开启“尚未登记的人员登录时，将其登记为学员”。
10. 确认所有人都能登录后，如有需要，再开启“停用密码登录，仅允许使用公司账号”。

颁发者 URL（Issuer）

https://login.microsoftonline.com/（租户 ID）/v2.0

客户端 ID

Application (client) ID

客户端密钥

第 4 步记下的 Value（不是 Secret ID）

允许的邮箱域名

公司邮箱的域名（如 example.com）。如果使用 onmicrosoft.com 地址的人也要登录，也另起一行填入。令牌中没有 email 的人会用 UPN 的域名来检查，所以如果 UPN 的域名与邮箱不同，也要填入。

客户端密钥过期后，所有人都无法用公司账号登录。请在过期前创建新的客户端密钥，并在 Aiyori 的画面上替换。把到期日记入 IT 负责人的日程，会更放心。

颁发者为 common、organizations、consumers，或末尾没有 /v2.0 时，保存时会说明原因并拒绝（因为任何租户的人都能通过）。如果填入 contoso.onmicrosoft.com 这样的租户名称代替租户 ID，保存时会统一转换为租户 ID 的形式。

即使 UPN 与邮箱地址不同，通过 SCIM 导入的人也能按 UPN 找到，所以不做第 5 步的添加 email 也能运作。不使用 SCIM，而用名单批量登记或自动登记导入时，请在第 5 步中添加 email（否则会以 UPN 地址登记为另一个人）。

3. SCIM（自动预配）

1. 在 Aiyori 的“连接公司的身份管理平台”→“SCIM”中，在“密钥名称”里填入 Entra ID，按“创建密钥”→ 记下显示的密钥（只在此画面显示）。
2. Enterprise applications → Aiyori → Provisioning → + New configuration（旧画面为 Get started → 把 Provisioning Mode 设为 Automatic）。
3. 在 Admin Credentials 中，认证方式选择 Bearer authentication，Tenant URL 填入 https://app.aiyori.app/api/scim/v2，Secret Token 填入第 1 步的密钥。
4. Test Connection → 成功后 Create（或 Save）。Entra ID 会查找 1 个不存在的人，确认返回空列表。
5. Mappings 保持默认即可（要检查的地方见下表）。
6. 在 Settings 中，Scope 保持 Sync only assigned users and groups（默认）。Notification Email（同步停止时的通知邮件）填入 IT 负责人的地址，并开启 Prevent accidental deletion。
7. 在 Users and groups 中，分配要使用 Aiyori 的组（部门、入职年份等）。
8. 用 Provision on demand 只发送 1 个人，确认此人出现在 Aiyori 的学员列表中。
9. Start provisioning。第 1 次所需的时间取决于人数，之后约每 40 分钟同步一次。结果可以在 Provisioning logs 中查看。

4. 连接当天要确认的事

• 被分配的 1 个人能用公司账号登录。未被分配的人会被拦在 Microsoft 的画面上（因为设置了需要分配）。
• 按需发送的人出现在 Aiyori 的学员中，并且在对应的小组里。
• 取消此人的分配，再按需发送一次后，在 Aiyori 中显示为“已因公司设置停用”，无法登录。恢复后又能登录。
• 已把客户端密钥的到期日记入 IT 负责人的日程。

使用 Entra ID 时的规则

• 颁发者按租户区分。ID 令牌中的 iss 和 tid（租户 ID）都必须与登记的租户一致，否则无法登录（其他公司租户的人无法通过）。
• Entra ID 不发送 email_verified。Aiyori 先按颁发者、租户和允许的域名进行限定，再使用收到的 email（没有时使用 UPN）。
• SCIM PATCH 中的 "op": "Replace"（首字母大写，Add、Remove 也一样）、字符串 "False"，以及没有 path 的 PATCH，都可以接受。请求正文的格式为 application/scim+json。
• 可以用 filter=userName eq（UPN，不区分大小写）或 externalId 查找人员。也接受组成员的添加和移除（members 的 Add、Remove）。
• 约每 40 分钟同步一次。着急时，请按需单独发送。
• SCIM 密钥没有有效期。可以每年一次左右创建新密钥，重新填入 Entra ID，再在 Aiyori 中把旧密钥设为“停用”。
• Microsoft Entra SCIM Validator 的检查项中，只有一项没有对应：对已删除的人执行 GET 时返回 404。这是因为 Aiyori 在删除时也不抹去记录，而是改为停用。日常同步在取消分配时会发送 active: false，所以没有影响。