教學課程：在 Microsoft Entra ID 中開發和規劃 SCIM 端點的布建

發行項
02/15/2024

身為應用程式開發人員，您可以使用跨網域身分識別管理系統 (SCIM) 使用者管理 API 來自動佈建應用程式與 Microsoft Entra ID 之間的使用者與群組。本文說明如何建置 SCIM 端點，並與 Microsoft Entra 布建服務整合。 SCIM 規格針對佈建提供常見的使用者結構描述。搭配 SAML 或 OpenID 連線等同盟標準使用時，SCIM 會為系統管理員提供端對端、以標準為基礎的存取管理解決方案。

Provisioning from Microsoft Entra ID to an app with SCIM

SCIM 2.0 是兩個端點的標準化定義： /Users 端點和 /Groups 端點。它會使用一般 REST API 端點來建立、更新和刪除物件。 SCIM 是由一般屬性的預先定義架構所組成，例如組名、用戶名稱、名字、姓氏和電子郵件。

提供 SCIM 2.0 REST API 的應用程式可以減少或排除使用專屬使用者管理 API 的不便。例如，任何相容的 SCIM 用戶端都知道如何將 JSON 對象的 /Users 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 Common Language Infrastructure （CLI）連結庫和程式代碼範例來建置您的端點。這些範例僅供參考和測試之用;建議您在生產應用程式中使用它們作為相依性。
將 SCIM 端點與 Microsoft Entra 布建服務整合。 Microsoft Entra ID 支援數個實作 SCIM 2.0 的第三方應用程式。如果您使用其中一個應用程式，您可以快速自動布建和取消布建使用者和群組。
[選擇性] 將您的應用程式發佈至 Microsoft Entra 應用連結庫 - 讓客戶輕鬆探索您的應用程式，並輕鬆地設定布建。

Diagram that shows the required steps for integrating a SCIM endpoint with Microsoft Entra ID.

設計您的使用者和群組架構

每個應用程式都需要不同的屬性來建立使用者或群組。藉由識別應用程式所需的必要物件（使用者、群組）和屬性（名稱、管理員、職稱等），來開始整合。

SCIM 標準會定義管理使用者和群組的架構。

核心使用者架構只需要三個屬性（所有其他屬性都是選擇性的）：

id、服務提供者定義的標識碼
userName，使用者的唯一標識碼（通常對應至 Microsoft Entra 用戶主體名稱）
meta， 由服務提供者維護的唯讀 元數據

除了核心用戶架構之外，SCIM 標準還定義企業使用者延伸模組，其模型可用來擴充用戶架構，以符合應用程式的需求。

例如，如果您的應用程式需要使用者的電子郵件和使用者的管理員，請使用核心架構來收集使用者的電子郵件和企業使用者架構來收集使用者的管理員。

若要設計架構，請遵循下列步驟：

列出應用程式所需的屬性，然後分類為驗證所需的屬性（例如loginName和電子郵件）。管理使用者生命週期需要屬性（例如狀態/作用中），以及應用程式運作所需的所有其他屬性（例如管理員、標籤）。
檢查屬性是否已在核心用戶架構或企業用戶架構中定義。如果沒有，您必須定義涵蓋遺漏屬性的用戶架構延伸模組。請參閱使用者延伸模組的範例，以允許布建使用者 tag。
將 SCIM 屬性對應至 Microsoft Entra ID 中的用戶屬性。如果您在 SCIM 端點中定義的其中一個屬性在 Microsoft Entra 使用者架構上沒有明確的對應專案，請引導租用戶系統管理員擴充其架構，或使用擴充屬性，如屬性的範例 tags 所示。

下表列出必要屬性的範例：

必要的應用程式屬性/範例	對應的 SCIM 屬性	對應的 Microsoft Entra 屬性
loginName	userName	userPrincipalName
firstName	name.givenName	givenName
lastName	name.familyName	姓
workMail	emails[type eq “work”].value	郵件
manager	manager	manager
標籤	`urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:tag`	extensionAttribute1
status	作用中	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/2819c223-7f76-453a-919d-413861904646"
   }
}

注意

除了應用程式所需的屬性之外，JSON 表示法也包含必要的 id、 externalId和 meta 屬性。

它有助於在和 /Group 之間/User分類，將 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`
displayName	displayName
employeeId	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:employeeNumber`
Facsimile-TelephoneNumber	phoneNumbers[type eq “fax”].value
givenName	name.givenName
jobTitle	title
郵件	emails[type eq “work”].value
mailNickname	externalId
manager	`urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager`
行動	phoneNumbers[type eq “mobile”].value
郵遞區號	addresses[type eq “work”].postalCode
proxy-Addresses	emails[type eq “other”]。價值
physical-Delivery-OfficeName	addresses[type eq “other”]。格式化
streetAddress	addresses[type eq “work”].streetAddress
surname	name.familyName
電話號碼	phoneNumbers[type eq “work”].value
user-PrincipalName	userName

下表列出群組屬性的範例：

Microsoft Entra 群組	`urn:ietf:params:scim:schemas:core:2.0:Group`
displayName	displayName
成員	成員
objectId	externalId

注意

您不需要同時支援使用者和群組，或此處顯示的所有屬性，這隻是 Microsoft Entra ID 中屬性通常對應至 SCIM 通訊協定中屬性的參考。

SCIM RFC 中定義了數個端點。您可以從端點開始 /User ，然後從該處展開。下表列出一些 SCIM 端點：

端點	描述
/使用者	在用戶物件上執行 CRUD 作業。
/Group	在群組物件上執行 CRUD 作業。
/模式	每個客戶端和服務提供者所支援的屬性集可能會有所不同。服務提供者可能包含 `name`、 `title`與 `emails`，而另一個服務提供者則使用 `name`、 `title`與 `phoneNumbers`。架構端點允許探索支援的屬性。
/散裝	大量作業可讓您在單一作業中對大型資源物件集合執行作業（例如，更新大型群組的成員資格）。
/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`擷取使用者，並使用和查詢，`usernameexternalId`並使用查詢群組`displayName`。
查詢群組資源時的 filter excludedAttributes=members	第 3.4.2.2節
支援列出使用者和分頁	第 3.4.2.4 節。
虛刪除使用者 `active=false` 並還原使用者 `active=true`	不論使用者是否為使用中，都應該在要求中傳回用戶物件。使用者不應該傳回的唯一時間是從應用程式硬式刪除。
支援 /Schemas 端點	第 7 節使用架構探索端點來探索更多屬性。
接受單一持有人令牌，以向您的應用程式驗證和授權 Microsoft Entra ID。

實作 SCIM 端點時，請使用一般指導方針，以確保與 Microsoft Entra 標識符的相容性：

一般：

id 是所有資源的必要屬性。傳回資源的每個回應都應該確保每個資源都有這個屬性，但零個元素除外 ListResponse 。
傳送的值應該以傳送的相同格式儲存。無效的值應該以描述性且可採取動作的錯誤訊息來拒絕。數據轉換不應該發生在 Microsoft Entra ID 的數據與儲存在 SCIM 應用程式中的數據之間。（例如。傳送為55555555555的電話號碼不應儲存/傳回為 +5（555） 555-5555）
不需要在 PATCH 回應中包含整個資源。
針對 SCIM 中的結構元素，特別是 PATCHop 作業值，不需要區分大小寫的比對，如第 3.5.2 節中所定義。 Microsoft Entra ID 會發出作為 [新增]、[取代] 和 [移除] 的值op。
Microsoft Entra ID 會提出擷取隨機使用者和群組的要求，以確保端點和認證有效。它也會做為測試連線 流程的一部分。
支援 SCIM 端點上的 HTTPS。
支援自定義複雜和多重值屬性，但 Microsoft Entra ID 沒有許多複雜的數據結構可從這些情況下提取數據。名稱/值屬性可以輕易地對應到，但不支援將數據流向具有三個或多個子屬性的複雜屬性。
多重值複雜屬性的「type」子屬性必須是唯一的。例如，「工作」子類型不能有兩個不同的電子郵件位址。
所有回應的標頭應為 content-Type：application/scim+json

擷取資源：

查詢/篩選要求的回應應一律為 ListResponse。
只限 Microsoft Entra 會使用下列運算子：、 eqand
可以查詢資源的屬性應該設定為應用程式上的相符屬性，請參閱自定義使用者布建屬性對應。

/使用者：

不支援 entitlements 屬性。
任何針對使用者唯一性而考慮的屬性，都必須作為篩選查詢的一部分使用。（例如，如果針對 userName 和 emails[type eq “work”] 評估使用者唯一性，則具有篩選條件的 GET to /Users 必須同時允許 userName eq “user@contoso.com” 和 emails[type eq “work”].value eq “user@contoso.com” 查詢。

/組：

群組是選擇性的，但只有在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_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "active": true,
    "emails": [{
        "primary": true,
        "type": "work",
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@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_ab6490ee-1e48-479e-a20b-2d77186b5dd1",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_fd0ea19b-0777-472c-9f96-4f70d2226f2e@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_feed3ace-693c-4e5a-82e2-694be1b39934",
    "name": {
        "formatted": "givenName familyName",
        "familyName": "familyName",
        "givenName": "givenName",
    },
    "active": true,
    "emails": [{
        "value": "Test_User_22370c1a-9012-42b2-bf64-86099c2a1c22@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_dfeef4c5-5681-4387-b016-bdf221e82081”

回應

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_dfeef4c5-5681-4387-b016-bdf221e82081",
        "name": {
            "familyName": "familyName",
            "givenName": "givenName"
        },
        "active": true,
        "emails": [{
            "value": "Test_User_91b67701-697b-46de-b864-bd0bbe4f99c1@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_fbb9dda4-fcde-4f98-a68b-6c5599e17c27",
    "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_49dc1090-aada-4657-8434-4995c25a00f7@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 標識符的 IP 範圍下運作，如下所示。您可以新增 Microsoft Entra 識別符標籤下所列的 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 端點，然後進行測試。使用作為參考程序代碼一部分提供的Postman測試集合，或透過提供的範例要求/回應執行。

注意

參考程式代碼旨在協助您開始建置 SCIM 端點，並提供「AS IS」。歡迎社群的貢獻來協助建置和維護程序代碼。

此解決方案由兩個項目組成： Microsoft.SCIM 和 Microsoft.SCIM.WebHostSample。

Microsoft.SCIM 專案是定義符合 SCIM 規格之 Web 服務元件的連結庫。它會宣告 Microsoft.SCIM.IProvider 介面，要求會轉譯成對提供者方法的呼叫，其程式設計為在身分識別存放區上運作。

Breakdown: A request translated into calls to the provider's methods

Microsoft.SCIM.WebHostSample 專案是以空白範本為基礎的 ASP.NET Core Web 應用程式。它可讓範例程式代碼部署為獨立、裝載於容器或網際網路資訊服務內。它也會實作 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 令牌。測試令牌不應該用於生產環境。
Microsoft Entra 持有人令牌。如果 [秘密令牌 ] 字段保留空白，Microsoft Entra ID 會包含每個要求從 Microsoft Entra ID 簽發的 OAuth 持有人令牌。使用 Microsoft Entra ID 作為識別提供者的應用程式可以驗證此 Microsoft Entra ID 簽發的令牌。
- 接收要求的應用程式應該將令牌簽發者驗證為預期的 Microsoft Entra 租使用者的 Microsoft Entra 識別符。
- iss宣告會識別令牌的簽發者。例如： "iss":"https://sts.windows.net/12345678-0000-0000-0000-000000000000/" 。在此範例中，宣告值的基位址會將 https://sts.windows.net Microsoft Entra 標識符識別為簽發者，而相對位址區段 12345678-0000-0000-0000-00000000000000，是發行令牌之 Microsoft Entra 租使用者的唯一標識符。
- 令牌的對像是 資源庫中應用程式的應用程式標識碼 。在單一租用戶中註冊的應用程式會收到與 SCIM 要求相同的 iss 宣告。所有自定義應用程式的應用程式標識碼為 8adf8e6e-67b2-4cf2-a259-e3dc5476c621。 Microsoft Entra 識別碼所產生的令牌應該只用於測試。它不應該用於生產環境。

在範例程式代碼中，要求會使用 Microsoft.AspNetCore.Authentication.JwtBearer 套件進行驗證。下列程式代碼會強制使用 Microsoft Entra ID 針對指定租使用者的 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/12345678-0000-0000-0000-000000000000/";
                options.Audience = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621";
                ...
            });
    }
    ...
}

public void Configure(IApplicationBuilder app)
{
    ...
    app.UseAuthentication();
    app.UseAuthorization();
    ...
}

持有人令牌也需要使用提供的 Postman測試，並使用localhost執行本機偵錯。範例程式代碼會使用 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 的範例。

注意

這隻是一個範例。並非所有的用戶都會有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 方法的自變數值為：

參數。AlternateFilters.Count： 1
參數。AlternateFilters.ElementAt（0）。AttributePath：“externalId”
參數。AlternateFilters.ElementAt（0）。ComparisonOperator：ComparisonOperator.Equals
參數。AlternateFilter.ElementAt（0）。ComparisonValue：“jyoung”

範例 2.布建使用者

如果使用者的 SCIM 端點查詢回應符合 externalId 使用者 mailNickname 屬性值的使用者不會傳回任何使用者，則 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);

在使用者布建的要求中，資源自變數的值是類別的 Microsoft.SCIM.Core2EnterpriseUser 實例。此類別定義於 Microsoft.SCIM.Schemas 連結庫中。如果布建使用者的要求成功，則方法的實作應該會傳回類別的 Microsoft.SCIM.Core2EnterpriseUser 實例。屬性的值 Identifier 會設定為新布建使用者的唯一標識碼。

範例 3.查詢使用者的目前狀態

Microsoft Entra ID 會向服務要求指定使用者的目前狀態，並要求如下：

GET ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 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自變數值的物件屬性值如下：

標識符：“54D382A4-2050-4C03-94D1-E769F1D15682”
SchemaIdentifier： urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

範例 4.查詢要更新之參考屬性的值

Microsoft Entra ID 會先檢查身分識別存放區中的目前屬性值，再進行更新。不過，只有管理員屬性會先檢查使用者。以下是判斷用戶物件的管理員屬性目前是否有特定值的範例：在範例程式代碼中，要求會轉譯成對服務提供者 QueryAsync 方法的呼叫。提供做為 parameters 自變數值的物件屬性值如下：

參數。AlternateFilters.Count： 2
參數。AlternateFilters.ElementAt（x）。AttributePath：“ID”
參數。AlternateFilters.ElementAt（x）。ComparisonOperator：ComparisonOperator.Equals
參數。AlternateFilter.ElementAt（x）。ComparisonValue：“54D382A4-2050-4C03-94D1-E769F1D15682”
參數。AlternateFilters.ElementAt（y）。AttributePath：“manager”
參數。AlternateFilters.ElementAt（y）。ComparisonOperator：ComparisonOperator.Equals
參數。AlternateFilter.ElementAt（y）。ComparisonValue：“2819c223-7f76-453a-919d-413861904646”
參數。RequestedAttributePaths.ElementAt（0）： “ID”
參數。SchemaIdentifier： urn:ietf:params:scim:schemas:extension:enterprise:2.0:User

索引 x 的值可以是 0 ，而索引 y 的值可以是 1。或者 x 的值可以是 1 ，而 y 的值可以是 0。這取決於篩選查詢參數的表達式順序。

範例 5.向 SCIM 端點要求 Microsoft Entra ID 以更新使用者

以下是從 Microsoft Entra ID 到 SCIM 端點的要求範例，以更新使用者：

PATCH ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 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/2819c223-7f76-453a-919d-413861904646",
              "value":"2819c223-7f76-453a-919d-413861904646"}]}]}

在範例程式代碼中，要求會轉譯成對服務提供者 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`	“54D382A4-2050-4C03-94D1-E769F1D15682”
`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/2819c223-7f76-453a-919d-413861904646`
`(PatchRequest as PatchRequest2).Operations.ElementAt(0).Value.ElementAt(0).Value`	2819c223-7f76-453a-919d-413861904646

範例 6.取消布建使用者

若要從 SCIM 端點前端的身分識別存放區取消布建使用者，Microsoft Entra ID 會傳送要求，例如：

DELETE ~/scim/Users/54D382A4-2050-4C03-94D1-E769F1D15682 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： “54D382A4-2050-4C03-94D1-E769F1D15682”
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 識別碼。聯機之後，Microsoft Entra ID 會執行同步處理程式。進程每隔 40 分鐘執行一次。此程式會查詢應用程式的SCIM端點以取得指派的使用者和群組，並根據指派詳細資料建立或修改它們。

若要連線支援 SCIM 的應用程式：

以至少應用程式管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
流覽至 [身分>識別應用程式企業應用程式]。>
會顯示所有已設定的應用程式清單，包括從資源庫新增的應用程式。
選取 [+ 新增應用程式>+ 建立您自己的應用程式]。
輸入應用程式的名稱，選擇 [整合您在資源庫中找不到的任何其他應用程式] 選項，然後選取 [新增] 以建立應用程式物件。新的應用程式會新增至企業應用程式清單，並開啟至其應用程式管理畫面。

下列螢幕快照顯示 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 同步處理到您的應用程式的屬性。選取為 [比對] 屬性的屬性可用來比對應用程式中的使用者和群組以進行更新作業。選取 [ 儲存] 以認可任何變更。

注意

您可以停用「群組」對應，選擇性地停用群組物件的同步處理。
在 [設定] 下，[範圍] 字段會定義哪些使用者和群組已同步處理。選取 [僅同步指派的使用者和群組 ] [建議] ，只同步處理 [使用者和群組] 索引標籤中 指派的使用者和群組 。
設定完成後，請將 [ 布建狀態 ] 設定為 [ 開啟]。
選取 [ 儲存 ] 以啟動 Microsoft Entra 布建服務。
如果只同步處理指派的使用者和群組（建議），請選取 [ 使用者和群組] 索引標籤 。然後，指派您要同步處理的使用者或群組。

啟動初始周期之後，您可以在左面板中選取 [布建記錄 ] 來監視進度，其中顯示布建服務在您的 app 上完成的所有動作。如需如何讀取 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中提供存取令牌作為短期測試用途的秘密令牌。除了支援資源庫應用程式上可設定的驗證/令牌 URL 之外，還支援非資源庫上的 OAuth 程式代碼授與。
OAuth 客戶端認證授與	存取令牌的存留期比密碼短，而且具有長期持有人令牌沒有的自動化重新整理機制。授權碼授與和客戶端認證授與會建立相同類型的存取令牌，因此在這些方法之間移動對 API 而言是透明的。布建可以自動化，而且不需要用戶互動，就可以以無訊息方式要求新的令牌。		支援資源庫應用程式，但不支援非資源庫應用程式。不過，您可以在UI中提供存取令牌作為短期測試用途的秘密令牌。支援非資源庫上的 OAuth 用戶端認證授與是在待辦專案中。

注意

不建議在 Microsoft Entra 布建設定自定義應用程式 UI 中將令牌欄位保留空白。產生的令牌主要用於測試。

OAuth 程式代碼授與流程

布建服務支援授權碼授與，並在提交您在資源庫中發佈應用程式的要求之後，小組會與您合作收集下列資訊：

授權 URL，用戶端透過使用者代理程式重新導向從資源擁有者取得授權。用戶會重新導向至此 URL 以授權存取權。
令牌交換 URL，用戶端用來交換存取令牌的授權授與，通常是使用客戶端驗證。
用戶端標識碼，授權伺服器會發出已註冊用戶端的用戶端標識碼，這是代表用戶端所提供註冊資訊的唯一字串。用戶端標識碼不是秘密;它會向資源擁有者公開，且不得單獨用於客戶端驗證。
用戶端密碼，授權伺服器所產生的秘密，應該只有授權伺服器才知道的唯一值。

注意

授權 URL 和 令牌交換 URL 目前無法為每個租用戶設定。

注意

由於客戶端密碼暴露，因此不支援 OAuth v1。支援 OAuth v2。

建議您，但並非必要，您支援多個秘密，以便輕鬆更新，而不需要停機。

如何設定 OAuth 程式代碼授與流程

以至少應用程式管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
流覽至 [身分>識別應用程式>企業應用程式>佈>建]，然後選取 [授權]。
以至少應用程式管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
流覽至 [身分>識別應用程式企業應用程式]。>
選取您的應用程式，然後移至 [ 布建]。
選取授權。
1. 系統會將使用者重新導向至授權 URL（第三方應用程式的登入頁面）。
2. 管理員提供第三方應用程式的認證。
3. 第三方應用程式會將使用者重新導向回來，並提供授與碼
4. 布建服務會呼叫令牌 URL，並提供授與碼。第三方應用程式會以存取令牌、重新整理令牌和到期日回應
布建周期開始時，服務會檢查目前的存取令牌是否有效，並視需要交換給新的令牌。存取令牌會在每個對應用程式提出的要求中提供，並在每個要求之前檢查要求的有效性。

注意

雖然無法在非資源庫應用程式上設定 OAuth，但您可以從授權伺服器手動產生存取令牌，並將其輸入為非資源庫應用程式的秘密令牌。這可讓您先確認 SCIM 伺服器與 Microsoft Entra 布建服務的相容性，再上線至支援 OAuth 程式代碼授與的應用程式庫。

長時間運作的 OAuth 持有人令牌： 如果您的應用程式不支援 OAuth 授權碼授與流程，請改為產生系統管理員可用來設定布建整合的長期 OAuth 持有人令牌。令牌應該是永久的，否則當令牌到期時，布建作業會隔離。

如需更多驗證和授權方法，請在UserVoice上告訴我們。

資源庫上市上市檢查清單

為了協助提升我們聯合整合的認知和需求，建議您更新現有的檔，並放大行銷管道中的整合。建議您完成下列檢查清單以支援啟動：

請確定您的銷售和客戶支援小組已瞭解、就緒，並可與整合功能交談。簡短您的小組，提供常見問題，並納入銷售數據的整合。
製作部落格文章或新聞稿，描述聯合整合、優點和如何開始使用。範例：Imprivata 和 Microsoft Entra 新聞稿
利用 Twitter、Facebook 或 LinkedIn 等社交媒體，將整合推廣給您的客戶。請務必包含 @Microsoft Entra 識別碼，讓我們可以重新發佈您的文章。範例：Imprivata Twitter Post
建立或更新您的行銷頁面/網站（例如整合頁面、合作夥伴頁面、定價頁面等），以包含聯合整合的可用性。範例：Pingboard 整合頁面、 Smartsheet 整合頁面、 Monday.com 定價頁面
建立客戶如何開始使用的說明中心文章或技術檔。範例：Envoy + Microsoft Entra 整合。
透過客戶通訊提醒客戶新整合（每月電子報、電子郵件活動、產品版本資訊）。

下一步

開發範例 SCIM 端點將使用者布建和取消布建自動化至 SaaS 應用程式自定義使用者布建的屬性對應：針對使用者布建屬性對應撰寫表達式的範圍篩選器範圍設定使用者布建通知如何整合 SaaS 應用程式的教學課程清單

教學課程：在 Microsoft Entra ID 中開發和規劃 SCIM 端點的布建

設計您的使用者和群組架構

瞭解 Microsoft Entra SCIM 實作

一般：

擷取資源：

/使用者：

/組：

/Schemas （架構探索）：

使用者布建和取消布建

群組布建和取消布建

SCIM 通訊協定要求和回應

用戶作業

建立使用者

要求

回應

取得使用者

要求

回應 （找到的使用者）

要求

回應 （找不到使用者。詳細資料並非必要，只有狀態。）

依查詢取得使用者

要求

回應

依查詢取得使用者 - 零結果

要求

回應

更新使用者 [多重值屬性]

要求

回應

更新使用者[單一值屬性]

要求

回應

停用使用者

要求

回應

刪除使用者

要求

回應

群組作業

建立群組

要求

回應

取得群組

要求

回應

依 displayName 取得群組

要求

回應

更新群組 [非成員屬性]

要求

回應

更新群組 [新增成員]

要求

回應

更新群組 [移除成員]

要求

回應

刪除群組

要求

回應

架構探索

探索架構

要求

回應

安全性需求

IP 範圍

建置 SCIM 端點

建置自定義 SCIM 端點

處理端點驗證

處理使用者的布建和取消布建

整合 SCIM 端點與 Microsoft Entra 布建服務

開始使用

將您的應用程式發佈至 Microsoft Entra 應用連結庫

資源庫上線檢查清單

在應用連結庫中布建連接器的授權

OAuth 程式代碼授與流程

如何設定 OAuth 程式代碼授與流程

資源庫上市上市檢查清單

下一步

其他資源

回應（找到的使用者）

回應（找不到使用者。詳細資料並非必要，只有狀態。）