連接 Microsoft Entra ID
（SSO、SCIM）

事前準備

• 在 Microsoft Entra admin center（https://entra.microsoft.com）中，具有 Application Administrator 以上的角色。
• SSO（OpenID Connect）在 Entra ID 的免費方案中即可使用。
• Aiyori 不在資源庫（gallery）中，因此 SCIM（自動佈建）需要 Entra ID P1 以上（包含在 Microsoft 365 E3、E5、Business Premium 等方案中）。
• Aiyori 組織的管理員能開啟講師畫面的「設定」→「連接公司的身分管理平台」。

SSO 與 SCIM 都在同 1 個應用程式上設定。建立企業應用程式時，也會一起建立同名的應用程式註冊。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（租用戶 ID）與 Application (client) ID。
3. Authentication → + Add a platform → Web → 在重新導向 URI 填入 https://app.aiyori.app/api/web/sso/callback → Configure。implicit grant 的 2 個核取方塊都不要勾選（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 的畫面被擋下（因為已設為需要指派）。
• 用 Provision on demand 傳送的人出現在 Aiyori 的學員中，並已加入小組。
• 取消該人員的指派，再用 Provision on demand 傳送一次後，在 Aiyori 會顯示為「已因公司設定停用」，無法登入。恢復後即可再次進入。
• 已把用戶端密碼的到期日排入 IT 負責人的行事曆。

Entra ID 與 Aiyori 的搭配方式

• 發行者依租用戶而不同。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 分鐘同步一次。急用時，請用 Provision on demand 傳送。
• SCIM 金鑰沒有期限。請每年 1 次左右建立新金鑰，重新填入 Entra ID，再於 Aiyori 將舊金鑰設為「停用」。
• Microsoft Entra SCIM Validator 的項目中，只有 1 項沒有符合：對已刪除的人 GET 時傳回 404。這是因為 Aiyori 在刪除時不會清除紀錄，而是改為停用。平常的同步在取消指派時會傳送 active: false，因此沒有影響。