教學課程：在 Microsoft Entra ID 中開發和規劃 SCIM 端點的佈建
身為應用程式開發人員，您可以使用跨網域身分識別管理系統 (SCIM) 使用者管理 API 來自動佈建應用程式與 Microsoft Entra ID 之間的使用者與群組。 本文說明如何建置 SCIM 端點，並與 Microsoft Entra 佈建服務整合。 SCIM 規格針對佈建提供常見的使用者結構描述。 與 SAML 或 OpenID Connect 等同盟標準使用時，SCIM 可為管理員提供端對端、以標準為基礎的存取管理解決方案。
SCIM 2.0 是兩個端點的標準化定義：/Users 端點和 /Groups 端點。 其會使用常見的 REST API 端點來建立、更新及刪除物件。 SCIM 是由預先定義的一般屬性 (例如群組名稱、使用者名稱、名字、姓氏和電子郵件) 結構描述組成。
提供 SCIM 2.0 REST API 的應用程式可以減少或排除使用專屬使用者管理 API 的不便。 例如，任何符合規範的 SCIM 用戶端都知道如何對 /Users 端點進行 JSON 物件的 HTTP POST，以建立新的使用者項目。 符合 SCIM 標準的應用程式可以立即利用預先存在的用戶端、工具及程式碼，而不需要適用於相同基本動作的略微不同 API。
定義於 SCIM 2.0 中用於管理的標準使用者物件結構描述和 REST API (RFC 7642、7643、7644)，可讓識別提供者和應用程式更容易互相整合。 建置 SCIM 端點的應用程式開發人員可與任何符合 SCIM 規範的用戶端整合，而無須執行自訂工作。
若要自動佈建至應用程式，需要建置並整合 Microsoft Entra 佈建服務所存取的 SCIM 端點。 請使用下列步驟，開始將使用者和群組佈建至您的應用程式。
設計您的使用者和群組結構描述：識別應用程式的物件和屬性，以判斷其如何對應至 Microsoft Entra SCIM 實作所支援的使用者和群組結構描述。
了解 Microsoft Entra SCIM 實作：了解如何實作 Microsoft Entra 佈建服務，以建立 SCIM 通訊協定要求處理和回應的模型。
建置 SCIM 端點：端點必須與 SCIM 2.0 相容，才能與 Microsoft Entra 佈建服務整合。 您可以選擇使用 Microsoft 通用語言基礎結構 (CLI) 程式庫和程式碼範例來建置您的端點。 這些範例僅供參考和測試之用；建議您在生產應用程式中不要依賴它們。
整合 SCIM 端點 與 Microsoft Entra 佈建服務。 Microsoft Entra ID 支援數個可實作 SCIM 2.0 的第三方應用程式。 如果您使用這些應用程式中的一個，即可快速自動執行使用者和群組的佈建與取消佈建。
[選用] 將應用程式發佈至 Microsoft Entra 應用程式資源庫：讓客戶輕鬆探索您的應用程式，並輕鬆地設定佈建。
設計您的使用者和群組結構描述
每個應用程式都需要不同的屬性來建立使用者或群組。 識別應用程式所需的必要物件 (使用者、群組) 和屬性 (名稱、管理員、職稱等)，以開始整合。
SCIM 標準定義了用來管理使用者和群組的結構描述。
「核心」使用者結構描述只需要三個屬性 (其他所有屬性都是選用屬性)：
-
id，服務提供者定義的識別碼 -
userName，即使用者的唯一識別碼 (一般對應至 Microsoft Entra 使用者主體名稱) -
meta由服務提供者維護的唯讀中繼資料
除了「核心」使用者結構描述之外，SCIM 標準還定義「企業」使用者延伸模組來擴充使用者結構描述，以符合應用程式的需求。
例如，如果您的應用程式需要使用者的電子郵件和使用者的管理員，請使用「核心」結構描述來收集使用者的電子郵件，並使用「企業」使用者結構描述來收集使用者的管理員。
若要設計結構描述，請遵循下列步驟：
列出您的應用程式所需的屬性，然後分類為驗證所需的屬性 (例如 loginName 和 email)。 需要屬性來管理使用者生命週期 (例如狀態 / 使用中)，以及應用程式 (運作所需的其他所有屬性，例如管理員、標記)。
檢查這些屬性已定義於「核心」使用者結構描述還是「企業」使用者結構描述中。 如果沒有，則您必須將延伸模組定義為涵蓋遺漏屬性的使用者結構描述。 請參閱下列範例，以取得允許佈建使用者
tag的使用者延伸模組。將 SCIM 屬性對應至 Microsoft Entra ID 中的使用者屬性。 如果您在 SCIM 端點中定義的其中一個屬性在 Microsoft Entra 使用者結構描述中沒有明確的對應項目，請引導租用戶系統管理員擴展其結構描述，或使用
tags屬性範例中所示的擴展屬性。
下表列出必要屬性的範例：
| 必要的應用程式屬性/範例 | 映射的 SCIM 屬性 | 對應的 Microsoft Entra 屬性 |
|---|---|---|
| 登入名稱 | userName | 使用者主體名稱 |
| 名字 | name.givenName | givenName |
| lastName | name.familyName | surName |
| 工作郵件 | emails[type eq "work"].value | 郵件 |
| 經理 | 經理 | 經理 |
| 標籤 | urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag |
extensionAttribute1 |
| 狀態 | 活動的 | isSoftDeleted（不會儲存於使用者上的計算出來的值） |
下列 JSON 有效負載顯示 SCIM 結構描述範例：
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User"],
"userName":"bjensen@testuser.com",
"id": "48af03ac28ad4fb88478",
"externalId":"bjensen",
"name":{
"familyName":"Jensen",
"givenName":"Barbara"
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"manager": "123456"
},
"urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {
"tag": "701984",
},
"meta": {
"resourceType": "User",
"created": "2010-01-23T04:56:22Z",
"lastModified": "2011-05-13T04:42:34Z",
"version": "W\/\"3694e05e9dff591\"",
"location":
"https://example.com/v2/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}
}
注意
除了應用程式所需的屬性以外，JSON 表示法還包括必要的 id、externalId 和 meta 屬性。
其有助於分類 /User 與 /Group，以將 Microsoft Entra ID 中的任何預設使用者屬性對應至 SCIM RFC，請參閱 如何在 Microsoft Entra ID 與 SCIM 端點之間對應自訂屬性。
下表列出使用者屬性的範例：
| Microsoft Entra 使用者 | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
|---|---|
| IsSoftDeleted | 啟用中 |
| 部門 | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department |
| 顯示名稱 | 顯示名稱 |
| 員工編號 | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber |
| 傳真電話號碼 | phoneNumbers[type eq "fax"].value |
| givenName | name.givenName |
| 職稱 | 標題 |
| 郵件 | emails[type eq "work"].value |
| 郵件暱稱 | externalId |
| 經理 | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager |
| 行動裝置 | phoneNumbers[type eq "mobile"].value |
| 郵遞區號 | 地址[type eq "work"].郵遞區號 |
| 代理地址 | emails[type eq "other"].Value |
| 實體-投遞-辦公室名稱 | addresses[type eq "other"].Formatted |
| 街道地址 | addresses[type eq "work"].streetAddress |
| surname | 名字.姓氏 |
| 電話號碼 | phoneNumbers[type eq "work"].value |
| 使用者主名稱 | userName |
下表列出群組屬性的範例：
| Microsoft Entra 群組 | urn:ietf:params:scim:schemas:core:2.0:Group |
|---|---|
| 顯示名稱 | 顯示名稱 |
| 成員 | 成員 |
| objectId | 外部識別碼 |
注意
您不需要同時支援使用者和群組，或支援此處顯示的所有屬性，這僅是 Microsoft Entra ID 中屬性通常如何對應至 SCIM 通訊協定中屬性的參考例示。
SCIM RFC 中定義了數個端點。 您可以從 /User 端點開始，然後再向外擴充。 下表列出一些 SCIM 端點：
| 端點 | 描述 |
|---|---|
| /使用者 | 對使用者物件執行 CRUD 作業。 |
| /群組 | 對群組物件執行 CRUD 作業。 |
| /Schemas | 每個用戶端和服務提供者所支援的屬性集可能有所不同。 一個服務提供者可能包括 name、title 和 emails，而另一個服務提供者則使用 name、title 和 phoneNumbers。 結構描述端點可讓您探索支援的屬性。 |
| /Bulk | 大量作業可讓您在單一作業中對大型資源物件集合執行作業 (例如，更新大型群組的成員資格)。 |
| /ServiceProviderConfig | 提供支援之 SCIM 標準功能的詳細資料，例如，支援的資源和驗證方法。 |
| /ResourceTypes | 列出每個資源的中繼資料。 |
注意
使用 /Schemas 端點可支援自訂屬性，或您的結構描述經常變更時，因為它可讓用戶端自動擷取最新的結構描述。 使用 /Bulk 端點來支援群組。
了解 Microsoft Entra SCIM 實作
Microsoft Entra 佈建服務的設計目的是支援 SCIM 2.0 使用者管理 API。
重要
Microsoft Entra SCIM 實作行為的上次更新日期為 2018 年 12 月 18 日。 如需變更項目的相關資訊，請參閱 Microsoft Entra 使用者佈建服務的 SCIM 2.0 通訊協定合規性。
在 SCIM 2.0 通訊協定規格內，您的應用程式必須支援下列需求：
| 需求 | 參考注意事項 (SCIM 通訊協定) |
|---|---|
| 建立使用者，也可選擇性地建立群組 | 第 3.3 節。 |
| 使用 PATCH 要求來修改使用者或群組 | 第 3.5.2 節。 支援可確保以高效能的方式佈建群組和使用者。 |
| 為稍早建立的使用者或群組擷取已知的資源 | 第 3.4.1 節。 |
| 查詢使用者或群組 |
第 3.4.2 節。 根據預設，會使用其 id 來擷取使用者、使用其 username 和 externalId 進行查詢，並使用 displayName 查詢群組。 |
| 在查詢群組資源時，使用篩選器 excludedAttributes=members。 | 第 3.4.2.2 節 |
| 支援列出使用者並提供分頁功能 | 第 3.4.2.4 節。 |
將使用者 active=false 軟刪除並還原使用者 active=true |
不論使用者是否活躍，都應該在要求中傳回使用者物件。 使用者只有在從應用程式中被永久刪除時，才不應被返回。 |
| 支持 /Schemas API 端點 | 第 7 節 結構描述探索端點是用來探索更多屬性。 |
| 接受單一持有者權杖，以對您的應用程式進行 Microsoft Entra ID 的驗證和授權。 |
實作 SCIM 端點時，請使用一般指導方針，以確保與 Microsoft Entra ID 的相容性：
一般：
-
id是所有資源的必要屬性。 傳回資源的每個回應均應確保每個資源都具有此屬性，但不含元素的ListResponse除外。 - 傳送的值應該以傳送時的相同格式儲存。 應該使用描述性、可採取動作的錯誤訊息來拒絕不正確值。 Microsoft Entra ID 的資料與 SCIM 應用程式中所儲存的資料之間不應該發生資料轉換。 (例如。 傳送成 55555555555 的電話號碼不應該被儲存/傳回成 +5 (555) 555-5555。
- 您不需要在 PATCH 回應中包含整個資源。
- 在 SCIM 中，結構元素不需要大小寫區分匹配，尤其是 PATCH
op操作值，如第 3.5.2 節中所定義。 Microsoft Entra ID 會將op的值以 Add、Replace 和 Remove 的形式發出。 - Microsoft Entra ID 提出擷取隨機使用者和群組的要求，以確保端點和認證有效。 這也是「測試連線」流程的一部分。
- 您的 SCIM 端點支援 HTTPS。
- 支援自訂複雜和多重值屬性，然而，在這些情況下，Microsoft Entra ID 沒有許多可供提取資料的複雜資料結構。 名稱/值屬性可以輕易地映射，但不支援將資料流入具有三個或多個子屬性的複雜屬性。
- 多重值複雜屬性的 "type" 子屬性值必須是唯一的。 例如，不能有兩個不同的電子郵件地址具有 "work" 子類型。
- 所有回應的標頭都應為 content-Type: application/scim+json
擷取資源：
- 查詢/篩選要求的回應應一律為
ListResponse。 - Microsoft Entra 僅使用下列運算子：
eq、and - 可以查詢資源的屬性應設定為應用程式上的相符屬性，請參閱自訂使用者佈建屬性對應。
/Users：
- 不支援授權屬性。
- 任何視為使用者唯一性的屬性都必須可作為已篩選查詢的一部分使用。 (例如，如果同時評估 userName 和 emails[type eq "work"] 的使用者唯一性，則使用篩選對 /Users 進行的 GET 作業必須允許 userName eq "user@contoso.com" 和 emails[type eq "work"].value eq "user@contoso.com" 查詢。
/Groups：
- 群組是選用項目，但只有在 SCIM 實作支援 PATCH 要求時，才受到支援。
- 群組的 'displayName' 值必須具有唯一性，才能與 Microsoft Entra ID 和 SCIM 應用程式相符。 唯一性不是 SCIM 通訊協定的需求，而是整合 SCIM 端點與 Microsoft Entra ID 的需求。
/Schemas (架構發現)：
- 範例要求/回應
- 資料架構探索用於特定圖庫應用程式。 架構發現是將更多屬性新增至現有的圖庫 SCIM 應用程式架構的唯一方法。 自訂非預設 SCIM 應用程式目前不支援架構發現。
- 如果值不存在，請勿傳送 Null 值。
- 屬性值應該是駝峰式大小寫 (例如 readWrite)。
- 必須傳回清單回應。
- 儲存佈建設定時，Microsoft Entra 佈建服務會提出 /schemas 要求。 開啟編輯佈建頁面時，也會提出該要求。 在目標屬性清單的屬性對應中，會向客戶顯示發現的其他屬性。 結構描述探索只會導致新增其他目標屬性。 未移除屬性。
使用者設置和解除設置
下圖顯示 Microsoft Entra ID 傳送至 SCIM 端點的訊息，以管理應用程式身分識別存放區中的使用者生命週期。
群組佈建和取消佈建
群組配置和取消配置是可選的。 實作並啟用時，下圖顯示 Microsoft Entra ID 傳送至 SCIM 端點的訊息，以管理應用程式身分識別存放區中的群組生命週期。 這些訊息與使用者的訊息有兩方面的不同：
- 擷取群組的要求會指定將成員屬性從回應要求中提供的任何資源中排除。
- 要求判斷參考屬性是否具有特定值，會是有關成員屬性的要求。
下圖顯示群組撤銷佈建順序：
SCIM 通訊協定要求和回應
本文提供 Microsoft Entra 佈建服務發出的 SCIM 要求和預期回應範例。 為了獲得最佳結果，您應撰寫應用程式程式碼，以按此格式處理這些要求，並發出預期的回應。
重要
若要了解 Microsoft Entra 使用者佈建服務發出範例中所述作業的方式和時機，請參閱佈建運作方式中的佈建週期：初始和增量一節。
- 建立使用者 (要求 / 回應)
- 取得使用者 (要求 / 回應)
- 透過查詢取得使用者 (請求 / 回應)
- 透過查詢獲取使用者 - 零個結果 (請求 / 響應)
- 更新使用者 [多重值屬性] (要求 / 回應)
- 更新使用者 [單一值屬性] (要求 / 回應)
- 停用使用者 (要求 / 回應)
- 刪除使用者 (要求 / 回應)
- 建立群組 (要求 / 回應)
- 取得群組 (要求 / 回應)
- 依 displayName 取得群組 (要求 / 回應)
- 更新群組 [非成員屬性] (要求 / 回應)
- 更新群組 [新增成員] (要求 / 回應)
- 更新群組 [移除成員] (要求 / 回應)
- 刪除群組 (要求 / 回應)
使用者作業
- 使用
userName或emails[type eq "work"]屬性來查詢使用者。
建立使用者
請求
POST /Users
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"],
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"active": true,
"emails": [{
"primary": true,
"type": "work",
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com"
}],
"meta": {
"resourceType": "User"
},
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName"
},
"roles": []
}
回應
HTTP/1.1 201 已建立
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "48af03ac28ad4fb88478",
"externalId": "0a21f0f2-8d2a-4f8e-bf98-7363c4aed4ef",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName",
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}
取得使用者
請求
GET /Users/5d48a0a8e9f04aa38008
回應 (找到的使用者)
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "5d48a0a8e9f04aa38008",
"externalId": "58342554-38d6-4ec8-948c-50044d0a33fd",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName",
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}
請求
GET /Users/5171a35d82074e068ce2
回應 (找不到使用者。詳細資料並非必要，只需要提供狀態。)
HTTP/1.1 404 找不到
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:Error"
],
"status": "404",
"detail": "Resource 23B51B0E5D7AE9110A49411D@7cca31655d49f3640a494224 not found"
}
根據查詢條件取得使用者
請求
GET /Users?filter=userName eq "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
回應
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"Resources": [{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "2441309d85324e7793ae",
"externalId": "7fce0092-d52e-4f76-b727-3955bd72c939",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"familyName": "familyName",
"givenName": "givenName"
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}],
"startIndex": 1,
"itemsPerPage": 20
}
透過查詢取得使用者 - 無結果
請求
GET /Users?filter=userName eq "non-existent user"
回應
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 0,
"Resources": [],
"startIndex": 1,
"itemsPerPage": 20
}
更新使用者 [多重值屬性]
請求
PATCH /Users/6764549bef60420686bc HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "Replace",
"path": "emails[type eq \"work\"].value",
"value": "updatedEmail@microsoft.com"
},
{
"op": "Replace",
"path": "name.familyName",
"value": "updatedFamilyName"
}
]
}
回應
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "6764549bef60420686bc",
"externalId": "6c75de36-30fa-4d2d-a196-6bdcdb6b6539",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "Test_User_00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"name": {
"formatted": "givenName updatedFamilyName",
"familyName": "updatedFamilyName",
"givenName": "givenName"
},
"active": true,
"emails": [{
"value": "updatedEmail@microsoft.com",
"type": "work",
"primary": true
}]
}
更新使用者 [單一值屬性]
要求
PATCH /Users/5171a35d82074e068ce2 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Replace",
"path": "userName",
"value": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com"
}]
}
回應
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
"id": "5171a35d82074e068ce2",
"externalId": "aa1eca08-7179-4eeb-a0be-a519f7e5cd1a",
"meta": {
"resourceType": "User",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"userName": "5b50642d-79fc-4410-9e90-4c077cdd1a59@testuser.com",
"name": {
"formatted": "givenName familyName",
"familyName": "familyName",
"givenName": "givenName",
},
"active": true,
"emails": [{
"value": "Test_User_11bb11bb-cc22-dd33-ee44-55ff55ff55ff@testuser.com",
"type": "work",
"primary": true
}]
}
停用使用者
請求
PATCH /Users/5171a35d82074e068ce2 HTTP/1.1
{
"Operations": [
{
"op": "Replace",
"path": "active",
"value": false
}
],
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
]
}
回應
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"id": "CEC50F275D83C4530A495FCF@834d0e1e5d8235f90a495fda",
"userName": "deanruiz@testuser.com",
"name": {
"familyName": "Harris",
"givenName": "Larry"
},
"active": false,
"emails": [
{
"value": "gloversuzanne@testuser.com",
"type": "work",
"primary": true
}
],
"addresses": [
{
"country": "ML",
"type": "work",
"primary": true
}
],
"meta": {
"resourceType": "Users",
"location": "/scim/5171a35d82074e068ce2/Users/CEC50F265D83B4530B495FCF@5171a35d82074e068ce2"
}
}
刪除使用者
請求
DELETE /Users/5171a35d82074e068ce2 HTTP/1.1
回應
HTTP/1.1 204 沒有內容
群組作業
- 群組建立時，成員清單是空的。
- 使用
displayName屬性來查詢群組。 - 群組 PATCH 要求的更新應會在回應中產生 HTTP 204 沒有內容。 不建議傳回包含所有成員列表的內容。
- 不需要支援傳回群組的所有成員。
建立群組
請求
POST /Groups HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group", "http://schemas.microsoft.com/2006/11/ResourceManagement/ADSCIM/2.0/Group"],
"externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
"displayName": "displayName",
"meta": {
"resourceType": "Group"
}
}
回應
HTTP/1.1 201 已建立
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "927fa2c08dcb4a7fae9e",
"externalId": "8aa1a0c0-c4c3-4bc0-b4a5-2ef676900159",
"meta": {
"resourceType": "Group",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"displayName": "displayName",
"members": []
}
取得群組
請求
GET /Groups/40734ae655284ad3abcc?excludedAttributes=members HTTP/1.1
回應
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "40734ae655284ad3abcc",
"externalId": "60f1bb27-2e1e-402d-bcc4-ec999564a194",
"meta": {
"resourceType": "Group",
"created": "2018-03-27T19:59:26.000Z",
"lastModified": "2018-03-27T19:59:26.000Z"
},
"displayName": "displayName",
}
依據 displayName 取得群組
請求
GET /Groups?excludedAttributes=members&filter=displayName eq "displayName" HTTP/1.1
回應
HTTP/1.1 200 OK
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
"totalResults": 1,
"Resources": [{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
"id": "8c601452cc934a9ebef9",
"externalId": "0db508eb-91e2-46e4-809c-30dcbda0c685",
"meta": {
"resourceType": "Group",
"created": "2018-03-27T22:02:32.000Z",
"lastModified": "2018-03-27T22:02:32.000Z",
},
"displayName": "displayName",
}],
"startIndex": 1,
"itemsPerPage": 20
}
更新群組 [非成員屬性]
請求
PATCH /Groups/fa2ce26709934589afc5 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Replace",
"path": "displayName",
"value": "1879db59-3bdf-4490-ad68-ab880a269474updatedDisplayName"
}]
}
回應
HTTP/1.1 204 沒有內容
更新群組 [新增成員]
請求
PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Add",
"path": "members",
"value": [{
"$ref": null,
"value": "f648f8d5ea4e4cd38e9c"
}]
}]
}
回應
HTTP/1.1 204 沒有內容
更新群組 [移除成員]
請求
PATCH /Groups/a99962b9f99d4c4fac67 HTTP/1.1
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [{
"op": "Remove",
"path": "members",
"value": [{
"$ref": null,
"value": "f648f8d5ea4e4cd38e9c"
}]
}]
}
回應
HTTP/1.1 204 沒有內容
刪除群組
請求
DELETE /Groups/cdb1ce18f65944079d37 HTTP/1.1
回應
HTTP/1.1 204 沒有內容
模式探索
發現資料庫架構
請求
GET /Schemas
回應
HTTP/1.1 200 OK
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:ListResponse"
],
"itemsPerPage": 50,
"startIndex": 1,
"totalResults": 3,
"Resources": [
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:core:2.0:User",
"name" : "User",
"description" : "User Account",
"attributes" : [
{
"name" : "userName",
"type" : "string",
"multiValued" : false,
"description" : "Unique identifier for the User, typically
used by the user to directly authenticate to the service provider.
Each User MUST include a non-empty userName value. This identifier
MUST be unique across the service provider's entire set of Users.
REQUIRED.",
"required" : true,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "server"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:User"
}
},
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:core:2.0:Group",
"name" : "Group",
"description" : "Group",
"attributes" : [
{
"name" : "displayName",
"type" : "string",
"multiValued" : false,
"description" : "A human-readable name for the Group.
REQUIRED.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:core:2.0:Group"
}
},
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Schema"],
"id" : "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
"name" : "EnterpriseUser",
"description" : "Enterprise User",
"attributes" : [
{
"name" : "employeeNumber",
"type" : "string",
"multiValued" : false,
"description" : "Numeric or alphanumeric identifier assigned
to a person, typically based on order of hire or association with an
organization.",
"required" : false,
"caseExact" : false,
"mutability" : "readWrite",
"returned" : "default",
"uniqueness" : "none"
},
],
"meta" : {
"resourceType" : "Schema",
"location" :
"/v2/Schemas/urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
}
}
]
}
安全性需求
TLS 通訊協定版本
唯一可接受的通訊協定版本是 TLS 1.2。 不允許其他 SSL/TLS 版本。
- RSA 金鑰必須至少有 2,048 位元。
- ECC 金鑰必須至少有 256 位元，並使用已核准的橢圓曲線產生
金鑰長度
所有服務都必須使用以長度足夠的密碼編譯金鑰產生的 X.509 憑證，亦即：
加密套件
所有服務都必須設定為使用下列加密套件，以範例中指定的確切順序。 如果您只有一個 RSA 憑證，則安裝的 ECDSA 加密套件不會有任何作用。
TLS 1.2 加密套件的最低標準：
- TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
- TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
IP 範圍
Microsoft Entra 佈建服務目前在 Microsoft Entra ID 的 IP 範圍下方運作，如此處所列。 您可以新增 AzureActiveDirectory 標籤下方列出的 IP 範圍，以允許來自 Microsoft Entra 佈建服務的流量進入您的應用程式。 您必須仔細檢閱計算位址的 IP 範圍清單。 '40.126.25.32' 這類位址可能會在 IP 範圍清單中表示為 '40.126.0.0/18'。 您也可以使用下列 API，以程式設計方式取出 IP 範圍清單。
Microsoft Entra ID 也支援代理程式型解決方案，以提供對私人網路 (內部部署、託管於 Azure、託管於 AWS 等等) 中應用程式的連線能力。 客戶可以在其私人網路的伺服器上部署輕量型代理程式，這不需要開啟任何輸入連接埠，即可提供與 Microsoft Entra ID 的連線能力。 在這裡深入了解。
建置 SCIM 端點
既然您已設計結構描述，並了解 Microsoft Entra SCIM 實作，就可以開始開發 SCIM 端點。 您可以利用 SCIM 社群所發佈的一些開放原始碼 SCIM 程式庫，而不要從頭開始完全靠自己建立實作。
如需如何建置 SCIM 端點 (包括範例) 的指導，請參閱開發範例 SCIM 端點。
Microsoft Entra 佈建小組所發佈的開放原始碼 .NET Core 參考程式碼範例是這類資源的一種，可快速啟動您的開發。 建置 SCIM 端點，然後透過提供的範例要求/回應執行來測試它。
注意
參考程式碼以「原狀」提供，目的是要協助您開始建置 SCIM 端點。歡迎社群供稿，以協助建置和維護程式碼。
解決方案是由兩個專案所組成：Microsoft.SCIM 和 Microsoft.SCIM.WebHostSample。
Microsoft.SCIM 專案是一個程式庫，會定義符合 SCIM 規格的 Web 服務元件。 這會宣告介面 Microsoft.SCIM.IProvider，並將請求轉譯為對提供者方法的呼叫，這些方法可被編程以在身分識別存放區上進行操作。
Microsoft.SCIM.WebHostSample 專案是 ASP.NET Core Web 應用程式，藉以空白範本為基礎。 此專案可讓範例程式碼獨立部署，裝載於容器中或在 Internet Information Services 內。 此外也會實作 Microsoft.SCIM.IProvider 介面，將類別保存在記憶體中作為範例身分識別存放區。
public class Startup
{
...
public IMonitor MonitoringBehavior { get; set; }
public IProvider ProviderBehavior { get; set; }
public Startup(IWebHostEnvironment env, IConfiguration configuration)
{
...
this.MonitoringBehavior = new ConsoleMonitor();
this.ProviderBehavior = new InMemoryProvider();
}
...
建置自訂 SCIM 端點
SCIM 端點必須具有 HTTP 位址，而其伺服器驗證憑證的根憑證授權單位是下列其中一個名稱：
- CNNIC
- Comodo
- CyberTrust
- DigiCert
- GeoTrust
- GlobalSign
- Go Daddy
- VeriSign
- WoSign
- DST Root CA X3
.NET Core SDK 包括開發期間使用的 HTTPS 開發憑證。 數位憑證會在首次運行時安裝為用戶體驗的一部分。 根據您執行 ASP.NET Core Web 應用程式的方式，其會接聽不同的連接埠：
- Microsoft.SCIM.WebHostSample：
https://localhost:5001 - IIS Express：
https://localhost:44359
如需 ASP.NET Core 中 HTTPS 的詳細資訊，請使用下列連結：在 ASP.NET Core 中強制執行 HTTPS
處理端點驗證
來自 Microsoft Entra 佈建服務的要求包括 OAuth 2.0 持有者權杖。 授權伺服器會發出持有人權杖。 Microsoft Entra ID 是受信任授權伺服器的範例。 設定 Microsoft Entra 佈建服務以使用下列其中一個令牌：
長時間存留的持有人權杖。 如果 SCIM 端點需要來自非 Microsoft Entra ID 的簽發者的 OAuth 持有人權杖，請將所需的 OAuth 持有人權杖複製至選用 [祕密權杖] 欄位。 在開發環境中，您可以使用
/scim/token端點提供的測試 token。 測試權杖不應該用於生產環境。Microsoft Entra 承載者令牌。 如果 [祕密權杖] 欄位留空，則每次要求時，Microsoft Entra ID 會包含從 Microsoft Entra ID 簽發的 OAuth 持有人權杖。 使用 Microsoft Entra ID 作為識別提供者的應用程式可以驗證這個由 Microsoft Entra ID 所簽發的權杖。
- 接收請求的應用程式應驗證權杖簽發者是否為目標 Microsoft Entra 租用戶的 Microsoft Entra ID。
-
iss宣告會識別權杖的簽發者。 例如："iss":"https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/"。 在此範例中，宣告值的基底位址https://sts.windows.net會將 Microsoft Entra ID 識別為簽發者，而相對位址區段 aaaabbbb-0000-cccc-1111-dddd2222eeee 是簽發權杖之 Microsoft Entra 租用戶的唯一識別碼。 - 權杖的對象是應用程式庫中應用程式的應用程式識別碼。 在單一租用戶中註冊的應用程式會收到與 SCIM 要求相同的
iss宣告。 所有自訂應用程式的應用程式識別碼都是 8adf8e6e-67b2-4cf2-a259-e3dc5476c621。 Microsoft Entra ID 產生的令牌應該只用於測試。 請勿在生產環境中加以使用。
在範例程式碼中，會使用 Microsoft.AspNetCore.Authentication.JwtBearer 套件來驗證要求。 下列程式碼會強制要求，對任何服務端點的請求都必須使用 Microsoft Entra ID 為指定租用戶簽發的持有人權杖進行身份驗證：
public void ConfigureServices(IServiceCollection services)
{
if (_env.IsDevelopment())
{
...
}
else
{
services.AddAuthentication(options =>
{
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
options.Authority = " https://sts.windows.net/aaaabbbb-0000-cccc-1111-dddd2222eeee/";
options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
...
});
}
...
}
public void Configure(IApplicationBuilder app)
{
...
app.UseAuthentication();
app.UseAuthorization();
...
}
範例程式碼會使用 ASP.NET Core 環境在開發階段變更驗證選項，並啟用自我簽署權杖。
如需 ASP.NET Core 中多個環境的詳細資訊，請參閱在 ASP.NET Core 中使用多個環境。
下列程式碼會強制執行使用以自訂金鑰簽署的持有者權杖來對任何服務端點的請求進行驗證：
public void ConfigureServices(IServiceCollection services)
{
if (_env.IsDevelopment())
{
services.AddAuthentication(options =>
{
options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
options.TokenValidationParameters =
new TokenValidationParameters
{
ValidateIssuer = false,
ValidateAudience = false,
ValidateLifetime = false,
ValidateIssuerSigningKey = false,
ValidIssuer = "Microsoft.Security.Bearer",
ValidAudience = "Microsoft.Security.Bearer",
IssuerSigningKey = new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"))
};
});
}
...
請將 GET 要求傳送至權杖控制器以取得有效的持有人權杖，GenerateJSONWebToken 方法會負責建立與針對開發而設定的參數相符的權杖：
private string GenerateJSONWebToken()
{
// Create token key
SymmetricSecurityKey securityKey =
new SymmetricSecurityKey(Encoding.UTF8.GetBytes("A1B2C3D4E5F6A1B2C3D4E5F6"));
SigningCredentials credentials =
new SigningCredentials(securityKey, SecurityAlgorithms.HmacSha256);
// Set token expiration
DateTime startTime = DateTime.UtcNow;
DateTime expiryTime = startTime.AddMinutes(120);
// Generate the token
JwtSecurityToken token =
new JwtSecurityToken(
"Microsoft.Security.Bearer",
"Microsoft.Security.Bearer",
null,
notBefore: startTime,
expires: expiryTime,
signingCredentials: credentials);
string result = new JwtSecurityTokenHandler().WriteToken(token);
return result;
}
處理使用者的配置和解除配置
範例 1.查詢服務以取得相符的使用者
Microsoft Entra ID 會查詢服務，以尋找 externalId 屬性值符合 Microsoft Entra ID 中使用者 mailNickname 屬性值的使用者。 此查詢會以超文字傳輸通訊協定 (HTTP) 要求來表示，例如此範例，其中 jyoung 是 Microsoft Entra ID 中一位使用者的電子郵件暱稱範例。
注意
這只是範例。 並非所有使用者都有 mailNickname 屬性，且使用者的值在目錄中可能不是唯一的。 此外，用於比對的屬性 (在此案例中為 externalId) 可在 Microsoft Entra 屬性對應中設定。
GET https://.../scim/Users?filter=externalId eq jyoung HTTP/1.1
Authorization: Bearer ...
在範例程式碼中，要求會轉譯成對服務提供者 QueryAsync 方法的呼叫。 以下是該方法的簽章：
// System.Threading.Tasks.Tasks is defined in mscorlib.dll.
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.Resource is defined in
// Microsoft.SCIM.Schemas.
// Microsoft.SCIM.IQueryParameters is defined in
// Microsoft.SCIM.Protocol.
Task<Resource[]> QueryAsync(IRequest<IQueryParameters> request);
在範例查詢中，針對具有給定 externalId 屬性值的使用者，傳至 QueryAsync 方法的引數值為：
- parameters.AlternateFilters.Count: 1
- parameters.AlternateFilters.ElementAt(0).AttributePath: "externalId"
- parameters.AlternateFilters.ElementAt(0).ComparisonOperator: ComparisonOperator.Equals
- parameters.AlternateFilter.ElementAt(0).ComparisonValue: "jyoung"
範例 2.佈建使用者
如果針對其 externalId 屬性值與某一使用者的 mailNickname 屬性值相符的使用者，查詢 SCIM 端點時未傳回任何使用者，則 Microsoft Entra ID 會要求服務建立一個與 Microsoft Entra ID 中使用者對應的使用者。 以下是這類要求的範例：
POST https://.../scim/Users HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
"schemas":
[
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0User"],
"externalId":"jyoung",
"userName":"jyoung@testuser.com",
"active":true,
"addresses":null,
"displayName":"Joy Young",
"emails": [
{
"type":"work",
"value":"jyoung@Contoso.com",
"primary":true}],
"meta": {
"resourceType":"User"},
"name":{
"familyName":"Young",
"givenName":"Joy"},
"phoneNumbers":null,
"preferredLanguage":null,
"title":null,
"department":null,
"manager":null}
在範例程式碼中，要求會轉譯為對服務提供者 CreateAsync 方法的呼叫。 以下是該方法的簽名：
// System.Threading.Tasks.Tasks is defined in mscorlib.dll.
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.Resource is defined in
// Microsoft.SCIM.Schemas.
Task<Resource> CreateAsync(IRequest<Resource> request);
在使用者配置的要求中，resource 引數的值是 Microsoft.SCIM.Core2EnterpriseUser 類別的執行個體。 這個類別定義於 Microsoft.SCIM.Schemas 程式庫中。 如果佈建使用者的要求成功，則方法的實作預期會傳回 Microsoft.SCIM.Core2EnterpriseUser 類別的執行個體。
Identifier 屬性的值會設定為新佈建使用者的唯一識別碼。
範例 3。查詢使用者的目前狀態
Microsoft Entra ID 會向服務發出請求，以查詢指定使用者的目前狀態，例如：
GET ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
在範例程式碼中，要求會轉譯成呼叫服務提供者的 RetrieveAsync 方法。 這是該方法的簽名：
// System.Threading.Tasks.Tasks is defined in mscorlib.dll.
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.Resource and
// Microsoft.SCIM.IResourceRetrievalParameters
// are defined in Microsoft.SCIM.Schemas
Task<Resource> RetrieveAsync(IRequest<IResourceRetrievalParameters> request);
在範例要求中，若要擷取使用者的目前狀態，提供為 parameters 引數值的物件屬性值如下：
- 識別碼："a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
- SchemaIdentifier：
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
範例 4.查詢要更新的參考屬性的值
Microsoft Entra ID 會先檢查身分識別存放區中的目前屬性值，再進行更新。 然而，只有管理員屬性是首個被檢查的使用者屬性。 以下是判斷使用者物件的管理員屬性目前是否有特定值的範例：在範例程式碼中，要求會轉譯成對服務提供者 QueryAsync 方法的呼叫。 提供的物件的屬性作為參數引數的值，其數值如下所示：
- parameters.AlternateFilters.Count: 2
- parameters.AlternateFilters.ElementAt(x).AttributePath: "ID"
- parameters.AlternateFilters.ElementAt(x).ComparisonOperator: 比較運算子.Equals
- parameters.AlternateFilter.ElementAt(x).ComparisonValue: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
- parameters.AlternateFilters.ElementAt(y).AttributePath: "manager"
- parameters.AlternateFilters.ElementAt(y).ComparisonOperator: ComparisonOperator.Equals
- parameters.AlternateFilter.ElementAt(y).ComparisonValue: "00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
- parameters.RequestedAttributePaths.ElementAt(0): "ID"
- parameters.SchemaIdentifier：
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
索引 x 的值可以是 0，索引 y 的值可以是 1。 或者，x 的值可以是 1，y 的值可以是 0。 這取決於篩選查詢參數的運算式順序。
範例 5.從 Microsoft Entra ID 對 SCIM 端點發出要求，以更新使用者
以下是從 Microsoft Entra ID 對 SCIM 端點發出要求以更新使用者的範例：
PATCH ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
Content-type: application/scim+json
{
"schemas":
[
"urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":
[
{
"op":"Add",
"path":"manager",
"value":
[
{
"$ref":"http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee",
"value":"00aa00aa-bb11-cc22-dd33-44ee44ee44ee"}]}]}
在範例程式碼中，要求會轉譯成對服務提供者 UpdateAsync 方法的呼叫。 以下是該方法的簽名：
// System.Threading.Tasks.Tasks and
// System.Collections.Generic.IReadOnlyCollection<T> // are defined in mscorlib.dll.
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.IPatch,
// is defined in Microsoft.SCIM.Protocol.
Task UpdateAsync(IRequest<IPatch> request);
在更新使用者的範例要求中，提供為 patch 引數值的物件具有這些屬性值：
| 引數 | 值 |
|---|---|
ResourceIdentifier.Identifier |
"a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1" |
ResourceIdentifier.SchemaIdentifier |
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User |
(PatchRequest as PatchRequest2).Operations.Count |
1 |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).OperationName |
OperationName.Add |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Path.AttributePath |
經理 |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.Count |
1 |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Reference |
http://.../scim/Users/00aa00aa-bb11-cc22-dd33-44ee44ee44ee |
(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value |
00aa00aa-bb11-cc22-dd33-44ee44ee44ee |
範例 6.取消佈建使用者
若要從透過 SCIM 端點管理的身分識別存放區中解除使用者的佈建，Microsoft Entra ID 會傳送要求，例如：
DELETE ~/scim/Users/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1 HTTP/1.1
Authorization: Bearer ...
在範例程式碼中，要求會轉譯成對服務提供者 DeleteAsync 方法的呼叫。 以下是該方法的簽名：
// System.Threading.Tasks.Tasks is defined in mscorlib.dll.
// Microsoft.SCIM.IRequest is defined in
// Microsoft.SCIM.Service.
// Microsoft.SCIM.IResourceIdentifier,
// is defined in Microsoft.SCIM.Protocol.
Task DeleteAsync(IRequest<IResourceIdentifier> request);
提供作為 resourceIdentifier 引數值的對象，在取消佈建使用者的請求範例中，會具有這些屬性值。
- ResourceIdentifier.Identifier: "a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1"
- ResourceIdentifier.SchemaIdentifier：
urn:ietf:params:scim:schemas:extension:enterprise:2.0:User
將 SCIM 端點與 Microsoft Entra 佈建服務整合
Microsoft Entra ID 可以設定為將指派的使用者和群組自動佈建至實作 SCIM 2.0 通訊協定特定設定檔的應用程式。 設定檔的具體細節記載於了解 Microsoft Entra SCIM 實作。
洽詢應用程式提供者，或參閱應用程式提供者文件中的相關陳述，以了解是否符合這些需求。
重要
Microsoft Entra SCIM 實作是根據 Microsoft Entra 使用者佈建服務所建置，其設計目的是在 Microsoft Entra ID 與目標應用程式之間持續保持使用者同步，並實作一組非常明確的標準作業。 請務必了解這些行為，以了解 Microsoft Entra 佈建服務的行為。 如需詳細資訊，請參閱佈建運作方式中的佈建週期：初始和增量一節。
開始使用
支援本文所述 SCIM 設定檔的應用程式可以使用 Microsoft Entra 應用程式資源庫中的「非資源庫應用程式」功能，以連線至 Microsoft Entra ID。 連線之後，Microsoft Entra ID 會執行同步處理程序。 流程每隔 40 分鐘執行一次。 此程式會查詢應用程式的 SCIM 端點以取得指派的使用者和群組，並根據指派詳細資料建立或加以修改。
若要連接支援 SCIM 的應用程式：
以至少應用程式系統管理員的身分登入 Microsoft Entra 系統管理中心。
瀏覽至身分識別>應用程式>企業應用程式。
此時會顯示所有已設定的應用程式清單，包括已從資源庫新增的應用程式。
選取 [+ 新增應用程式] > [+ 建立您自己的應用程式]。
輸入應用程式的名稱，並選擇 [整合您在資源庫中找不到的其他任何應用程式] 選項，然後選取 [新增] 以建立應用程式物件。 新的應用程式會新增至企業應用程式清單，並在開啟後進入其應用程式管理畫面。
下列螢幕擷取畫面顯示 Microsoft Entra 應用程式資源庫：
在應用程式管理畫面中，選取左側面板中的 [佈建]。
選取 [+ 新增組態]。
在 [租用戶 URL] 欄位中，輸入應用程式 SCIM 端點的 URL。 範例:
https://api.contoso.com/scim/如果 SCIM 端點需要來自非 Microsoft Entra ID 的簽發者的 OAuth 持有人權杖，請將所需的 OAuth 持有人權杖複製至選用 [祕密權杖] 欄位。 如果此欄位留空，則每次要求中，Microsoft Entra ID 會包含由 Microsoft Entra ID 簽發的 OAuth 持有人權杖。 使用 Microsoft Entra ID 作為識別提供者的應用程式可以驗證這個由 Microsoft Entra ID 所簽發的權杖。
注意
不建議將此欄位留空並依賴來自 Microsoft Entra ID 產生的權杖。 此選項主要供測試之用。
選取 [測試連線]，讓 Microsoft Entra ID 嘗試連線至 SCIM 端點。 如果嘗試失敗，將會顯示錯誤資訊。
注意
[測試連線] 會查詢 SCIM 端點以尋找不存在的使用者，並使用隨機 GUID 作為在 Microsoft Entra 設定中選取的相符屬性。 預期的正確回應是 HTTP 200 OK 和空白的 SCIM ListResponse 訊息。
如果成功連線至應用程式，請選取 建立 以建立布建作業。
如果僅同步處理指派的使用者和群組 (建議選項)，請選取 [使用者和群組] 索引標籤。然後，指派您要同步處理的使用者或群組。
請在左側面板選取 屬性對應。 有兩組可選取
的屬性對應：一組用於用戶物件，另一組用於群組物件。 選取每一個屬性，來檢閱從 Microsoft Entra ID 同步到您應用程式的屬性。 選取為 [比對] 屬性的屬性會用來比對應用程式中的使用者和群組以進行更新作業。 點選 儲存 以提交任何變更。 您可以選擇停用「groups」對應來關閉群組物件的同步處理。
請選取左側面板中的隨選佈署。 搜尋在配置範圍內的使用者，並按需配置。 請對其他您想進行布建測試的用戶重複此操作。
設定完成後，請在左側面板選取 概觀。
選取 [屬性]。
選取鉛筆以編輯屬性。 啟用通知電子郵件，並提供電子郵件以接收隔離電子郵件。 啟用意外刪除防護。 按兩下 [套用]，以儲存變更。
選取 開始布建 以啟動 Microsoft Entra 布建服務。
初始週期開始後，您可以在左側面板中選取 [佈建記錄] 以監視進度，其中會顯示佈建服務對您的應用程式執行的所有動作。 如需如何讀取 Microsoft Entra 佈建記錄的詳細資訊，請參閱自動使用者帳戶佈建的報告。
注意
初始週期執行時會比後續的同步處理耗時；在服務執行期間，大約每 40 分鐘會執行一次同步處理。
將您的應用程式發佈至 Microsoft Entra 應用程式資源庫
如果您要建置多個租用戶所使用的應用程式，請讓該應用程式可在 Microsoft Entra 應用程式資源庫中使用。 組織能夠輕鬆地探索應用程式和設定佈建。 在 Microsoft Entra 資源庫中發佈您的應用程式，並讓佈建可供其他人使用十分容易。 請在 這裡查明步驟。 Microsoft 可協助您將應用程式整合到資源庫、測試您的端點，以及發行客戶上線文件。
藝廊入門檢查清單
使用檢查清單快速讓您的應用程式上線，並讓客戶擁有順暢的部署體驗。 入館流程時將向您收集資訊。
- 支援 SCIM 2.0 使用者和群組端點 (只需要一個，但建議兩者都使用)
- 每個租用戶每秒至少能處理 25 個請求，以確保使用者和群組能無延遲地被啟用和停用 (必要)
- 建立工程和技術支援聯繫人員，以便在畫廊上線後引導客戶 (必要)
- 應用程式需要 3 個不會過期的測試憑證 (必需)
- 支援 OAuth 授權碼授與或長時間有效的權杖，如範例中的描述 (必要)
- OIDC 應用程式必須至少定義 1 個角色 (自訂或預設)
- 建立工程和支援的聯絡窗口，以便在畫廊接入後支援客戶 (必要)
- 支援結構描述探索 (必要)
- 支持使用單一 PATCH 更新多個群組成員資格
- 公開記載您的 SCIM 端點
在應用程式庫中佈建連接器的授權
SCIM 規格並未定義 SCIM 特有的驗證和授權機制，並且依賴現有產業標準的使用。
| 授權方法 | 優點 | 缺點 | 支援 |
|---|---|---|---|
| 使用者名稱和密碼 (不建議或 Microsoft Entra ID 不予支援) | 易於實作 | 不安全 - 您的 Pa$$word 無關緊要 | 新的圖庫或非圖庫應用程式不予支援。 |
| 長期有效的持有者憑證 | 長時間有效的令牌不需要使用者在場。 在設置供應時，系統管理員能輕鬆使用這些工具。 | 若未使用不安全的方法 (例如電子郵件)，長時間存留的權杖可能難以與管理員共用。 | 支援畫廊和非畫廊應用程式。 |
| OAuth 授權碼授與 | 存取權杖的存留期比密碼短，而且具有長期持有人權杖沒有的自動化重新整理機制。 在初始授權期間必須有實際的使用者存在，因而增加了一層責任。 | 必須要有使用者存在。 如果使用者離開組織，該權杖會變成無效，而且必須再次完成授權。 | 支援資源庫應用程式，但不支援非資源庫應用程式。 不過，您可以在 UI 中提供存取權杖，做為短期測試用途的秘密權杖。 我們的待辦項目中包括對非資源庫 OAuth 代碼授予的支援，以及在資源庫應用程式上對可設定驗證/權杖 URL 的支援。 |
| OAuth 用戶端認證授與 | 存取權杖的存留期比密碼短，而且具有長期持有人權杖沒有的自動化重新整理機制。 授權碼授與和用戶端認證授與會建立相同類型的存取權杖，因此，這些方法的切換對 API 而言是透明的。 佈建可以自動化，且可以無通知地要求新的代幣，而不需要使用者介入。 | 支援相簿應用程式，但不支援非相簿應用程式。 不過，您可以在 UI 中提供存取權杖，做為短期測試用途的秘密權杖。 對於非精選集 OAuth 用戶端憑證授權的支援已列入我們的待辦項目中。 |
注意
不建議在 Microsoft Entra 佈建設定自訂應用程式 UI 中讓權杖欄位空白。 產生的權杖主要供測試之用。
OAuth 代碼授與流程
佈建服務支援授權碼授與，而且，提交您在資源庫中發佈應用程式的要求之後，我們的小組會與您一起收集下列資訊：
授權 URL：用戶端透過使用者代理程式重新導向對資源擁有者取得授權時所使用的 URL。 使用者會重新導向至此 URL 以授與存取權。
權杖交換 URL：用戶端用來交換存取權杖的授權的 URL (通常是使用用戶端驗證)。
用戶端識別碼：授權伺服器會向已註冊的用戶端發出用戶端識別碼，而這個唯一字串代表用戶端所提供的註冊資訊。 用戶端識別碼不是祕密，而會向資源擁有者公開，且不得單獨用於用戶端驗證。
用戶端祕密：授權伺服器所產生的祕密，而這應該是只有授權伺服器才知道的唯一值。
注意
目前無法針對每個租用戶設定 [授權 URL] 和 [權杖交換 URL]。
注意
因為用戶端祕密曝光，所以不支援 OAuth v1。 OAuth v2 則受支援。
使用 OAuth 代碼授與流程時，您需要支援模型，讓每位客戶在設定佈建執行個體時提交自己的用戶端識別碼和用戶端密碼。 不支援整個應用程式使用的用戶端識別碼/用戶端密碼配對。
如何設定 OAuth 代碼授與流程
以至少應用程式系統管理員的身分登入 Microsoft Entra 系統管理中心。
瀏覽至 [身分識別]>[應用程式]>[企業應用程式]>[應用程式]>[佈建]，然後選取 [授權]。
以至少應用程式系統管理員的身分登入 Microsoft Entra 系統管理中心。
瀏覽至「身分識別」>，然後「應用程式」>，然後「企業應用程式」。
選擇您的應用程式，然後前往 [佈建]。
選取授權。
系統會將使用者重新導向至授權 URL (第三方應用程式的登入頁面)。
管理員會提供認證給第三方應用程式。
第三方應用程式會將使用者重新導向回來，並提供授與碼
佈建服務會呼叫權杖 URL，並提供授與碼。 第三方應用程式會回應存取權杖、重新整理權杖，以及到期日。
當佈建週期開始時，服務會檢查目前的存取權杖是否有效，並視需要將其與新的權杖交換。 存取權杖會在對應用程式提出的每個要求中提供，而且會在提出每個要求之前檢查要求的有效性。
備註
儘管目前無法在非資源庫應用程式上設定 OAuth，但是您可以從授權伺服器手動產生存取權杖，並將它輸入為非資源庫應用程式的祕密權杖。 這可讓您先確認 SCIM 伺服器與 Microsoft Entra 佈建服務的相容性，再上線至支援 OAuth 程式碼授與的應用程式資源庫。
長時間存留的 OAuth 持有人權杖：如果您的應用程式不支援 OAuth 授權碼授與流程，則您也可以產生長時間存留的 OAuth 持有人權杖，而管理員可用它來設定佈建整合。 此權杖應該是永久的，否則當權杖到期時，佈建作業會被 隔離。
如需其他驗證和授權方法的相關資訊，請在 UserVoice 上告訴我們。
圖庫上市策略檢查清單
為了提升對我們合作整合的認識並帶動需求，建議您更新現有文件，並在您的行銷通路中強化此整合的推廣。 建議您完成下列檢查清單以支援啟動：
- 請確定您的銷售和客戶支援小組熟知整合功能，且有能力加以宣傳。 對您的小組進行簡報，為其提供常見問題集，並將整合納入您的銷售資料中。
- 製作一篇部落格文章或新聞稿，說明聯合整合的性質、優點，以及如何開始使用。 範例：Imprivata 和 Microsoft Entra 新聞稿
- 利用您的社交媒體 (例如 X、Facebook 或 LinkedIn)，向您的客戶推廣整合。 請務必包括 @Microsoft Entra ID，以讓我們可以轉推您的貼文。 範例：Imprivata X 貼文
- 建立或更新您的行銷頁面/網站 (例如整合頁面、合作夥伴頁面、價格頁面等等)，以包含聯合整合的可用性。 範例：Pingboard 整合頁面、 Smartsheet 整合頁面、 Monday.com 價格頁面
- 撰寫說明中心文章或技術文件，向客戶解說應從何著手。 範例：Envoy + Microsoft Entra 整合。
- 透過您的客戶通訊 (每月電子報、電子郵件行銷活動、產品版本資訊)，提醒客戶有新的整合。