教學課程:在 Azure Active Directory 中開發和規劃 SCIM 端點的布建

如果您是應用程式開發人員,您可以使用系統進行跨網域身分識別管理 (SCIM) 使用者管理 API,以在您的應用程式和 Azure AD (AAD) 之間啟用自動布建使用者和群組。 本文說明如何建立 SCIM 端點並與 AAD 布建服務整合。 SCIM 規格提供一般的使用者佈建結構描述。 與 SAML 或 OpenID Connect 等同盟標準搭配使用時,SCIM 可為管理員提供端對端、以標準為基礎的存取管理解決方案。

使用 SCIM 從 Azure AD 佈建至應用程式

SCIM 是兩個端點的標準化定義: /Users 端點和 /Groups 端點。 它會使用一般 REST 動詞來建立、更新和刪除物件,以及針對一般屬性 (例如群組名稱、使用者名稱、名字、姓氏和電子郵件) 預先定義的結構描述。 提供 SCIM 2.0 REST API 的應用程式,可減輕或消除使用專屬使用者管理 API 的麻煩。 例如,任何符合規範的 SCIM 用戶端都知道如何將 JSON 物件的 HTTP POST 建立至 /Users 端點,以建立新的使用者專案。 符合 SCIM 標準的應用程式可以立即運用既有的用戶端、工具和程式碼,而無須使用略為不同的 API 來執行相同的基本動作。

定義於 SCIM 2.0 中用於管理的標準使用者物件結構描述和 REST API (RFC 764276437644),可讓識別提供者和應用程式更容易互相整合。 建置 SCIM 端點的應用程式開發人員可與任何符合 SCIM 規範的用戶端整合,而無須執行自訂工作。

若要自動布建至應用程式,必須建立 SCIM 端點並將其與 Azure AD SCIM 用戶端整合。 使用下列步驟,開始將使用者和群組布建到您的應用程式。

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

    識別應用程式的物件和屬性,以判斷它們如何對應至 AAD SCIM 執行所支援的使用者和群組架構。

  2. 瞭解 AAD SCIM 的執行

    瞭解如何實行 AAD SCIM 用戶端,以建立 SCIM 通訊協定要求處理和回應的模型。

  3. 建立 SCIM 端點

    端點必須 SCIM 2.0 相容,才能與 AAD 布建服務整合。 您可以選擇使用 Microsoft 通用語言基礎結構 (CLI) 程式庫和程式碼範例來建立您的端點。 這些範例僅供參考和測試之用;建議您不要在生產應用程式中使用它們作為相依性。

  4. 將您的 SCIM 端點與 AAD SCIM 用戶端整合

    如果您的組織使用協力廠商應用程式來執行 AAD 支援的 SCIM 2.0 設定檔,您可以快速地自動布建和解除布建使用者和群組。

  5. 將您的應用程式發佈至 AAD 應用程式資源庫

    讓客戶輕鬆探索您的應用程式及設定佈建。

整合 SCIM 端點與 Azure AD 的步驟

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

每個應用程式都需要不同的屬性來建立使用者或群組。 藉由找出需要的物件 (使用者、群組) 和屬性 (名稱、經理、職稱等 ) 您的應用程式所需的專案,來開始整合。

SCIM 標準定義了用來管理使用者和群組的結構描述。

核心 使用者架構只需要三個屬性 (其他所有屬性都是選擇性的) :

  • id,服務提供者定義的識別碼
  • userName,使用者 (的唯一識別碼一般會對應至 Azure AD 使用者主體名稱)
  • meta,由服務提供者維護的 唯讀 中繼資料

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

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

若要設計架構,請遵循下列步驟:

  1. 列出您的應用程式所需的屬性,然後分類為驗證所需的屬性 (例如 loginName 和電子郵件) 、管理使用者生命週期所需的屬性 (例如狀態/使用中) ,以及應用程式運作所需的所有其他屬性 (例如管理員、標記) 。

  2. 檢查是否已在 核心 使用者架構或 企業 使用者架構中定義屬性。 如果沒有,您必須將延伸模組定義為涵蓋遺漏屬性的使用者架構。 請參閱下列範例,以取得使用者的擴充功能,以允許布建使用者 tag

  3. 將 SCIM 屬性對應至 Azure AD 中的使用者屬性。 如果您在 SCIM 端點中定義的其中一個屬性沒有 Azure AD 使用者架構上的明確對應項,請引導租使用者系統管理員擴充其架構,或使用延伸屬性,如下所示 tags 屬性。

必要的應用程式屬性 對應的 SCIM 屬性 對應的 Azure AD 屬性
loginName userName userPrincipalName
firstName name.givenName givenName
lastName name.familyName
workMail 電子郵件 [type eq "work"]。值 Mail
manager manager manager
tag urn: ietf: params: scim:架構: extension: CustomExtensionName:2.0: User: tag extensionAttribute1
status 作用中 isSoftDeleted (未儲存使用者的計算值)

必要屬性的範例清單

{
     "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 承載所定義的架構範例

注意

除了應用程式所需的屬性之外,JSON 標記法也包含必要的 idexternalIdmeta 屬性。

它有助於在和之間分類, /User /Group 以將 Azure AD 中的任何預設使用者屬性對應到 SCIM RFC,請參閱自訂屬性在 Azure AD 和您的 SCIM 端點之間的對應方式

Azure Active Directory 使用者 "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
IsSoftDeleted 作用中
department 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
mail emails[type eq "work"].value
mailNickname externalId
manager urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:manager
mobile phoneNumbers[type eq "mobile"].value
postalCode addresses[type eq "work"].postalCode
proxy-Addresses emails[type eq "other"].Value
physical-Delivery-OfficeName addresses[type eq "other"].Formatted
streetAddress addresses[type eq "work"].streetAddress
surname name.familyName
telephone-Number phoneNumbers[type eq "work"].value
user-PrincipalName userName

使用者和群組屬性的範例清單

Azure Active Directory 群組 urn:ietf:params:scim:schemas:core:2.0:Group
displayName displayName
members members
objectId externalId

群組屬性的範例清單

注意

您不一定要同時支援使用者和群組,或此處顯示的所有屬性,它只是有關 Azure AD 中的屬性通常會如何對應至 SCIM 通訊協定中的屬性的參考。

SCIM RFC 中定義了數個端點。 您可以 /User 從端點開始,然後從該處展開。

端點 描述
/User 對使用者物件執行 CRUD 作業。
/Group 對群組物件執行 CRUD 作業。
/Schemas 每個用戶端和服務提供者所支援的屬性集可能有所不同。 一個服務提供者可能包括 nametitleemails,而另一個服務提供者則使用 nametitlephoneNumbers。 結構描述端點可讓您探索支援的屬性。
/Bulk 大量作業可讓您在單一作業中對大型資源物件集合執行作業 (例如,更新大型群組的成員資格)。
/ServiceProviderConfig 提供支援之 SCIM 標準功能的詳細資料,例如,支援的資源和驗證方法。
/ResourceTypes 指定每個資源的相關中繼資料。

端點的範例清單

注意

使用 /Schemas 端點可支援自訂屬性,或如果您的架構經常變更,因為它可讓用戶端自動取得最新的架構。 使用 /Bulk 端點來支援群組。

瞭解 AAD SCIM 的執行

為了支援 SCIM 2.0 使用者管理 API,本節說明如何實行 AAD SCIM 用戶端,並示範如何建立 SCIM 通訊協定要求處理和回應的模型。

重要

Azure AD SCIM 實作行為的上次更新日期為 2018 年 12 月 18 日。 如需已變更內容的資訊,請參閱 Azure AD 使用者佈建服務的 SCIM 2.0 通訊協定合規性

SCIM 2.0 通訊協定規格內,您的應用程式必須支援下列需求:

需求 (SCIM 通訊協定) 的參考附注
建立使用者,也可選擇性地建立群組 第3.3 節
修改具有 PATCH 要求的使用者或群組 區段 3.5.2。 支援可確保以高效能的方式佈建群組和使用者。
為稍早建立的使用者或群組取出已知的資源 區段3.4。1
查詢使用者或群組 區段 3.4.2。 依預設會按 id 擷取使用者,並按 usernameexternalId 加以查詢,以及按 displayName 查詢群組。
篩選 excludedAttributes = 查詢群組資源時的成員 區段3.4.2。5
接受單一持有人權杖,以驗證 AAD 的應用程式和授權。
虛刪除使用者 active=false 及還原使用者 active=true 無論使用者是否為作用中,使用者物件都應該在要求中傳回。 只在從應用程式中將使用者實刪除時,才不應傳回該使用者。
支援/Schemas 端點 第7節 架構探索端點將用來探索其他屬性。

在執行 SCIM 端點時使用一般指導方針,以確保與 AAD 的相容性:

一般:
  • id 是所有資源的必要屬性。 傳回資源的每個回應均應確保每個資源都具有此屬性,但不含成員的 ListResponse 除外。
  • 傳送的值應該以與中傳送的相同格式儲存。 應以描述性、可採取動作的錯誤訊息來拒絕不正確值。 當 Azure AD 和儲存在 SCIM 應用程式中的資料之間傳送資料時,應該不會發生資料轉換。 (例如,以55555555555形式傳送的電話號碼不應儲存/傳回為 + 5 (555) 555-5555)
  • 不需要在 修補程式 回應中包含整個資源。
  • 不需要區分大小寫的 SCIM 中結構專案的相符專案,特別是 PATCH 作業 op 值(如 區段 3.5.2所定義)。 AAD 會發出的值 opAddReplaceRemove
  • Microsoft AAD 會要求提取隨機的使用者和群組,以確保端點和認證都有效。 它也會在 Azure 入口網站測試連接 流程中完成。
  • 在您的 SCIM 端點上支援 HTTPS。
  • 支援自訂複雜和多重值的屬性,但是 AAD 沒有許多複雜的資料結構,無法在這些情況下提取資料。 簡單的成對名稱/實值型別複雜屬性可以輕鬆地對應,但目前不支援以三個或多個 subattributes 將資料傳送至複雜屬性。
正在抓取資源:
  • 查詢/篩選要求的回應應一律為 ListResponse
  • Microsoft AAD 只會使用下列 eq 運算子:and
  • 您應該在 Azure 入口網站的應用程式上,將可查詢資源的屬性設定為相符的屬性,請參閱 自訂使用者布建屬性對應。
Users
  • 不支援權利屬性。
  • 任何視為使用者唯一性的屬性都必須可作為篩選查詢的一部分使用。 (例如,如果同時評估使用者名稱和電子郵件 [type eq "work"] 的使用者唯一性,具有篩選的 GET to/Users 必須允許 userName eq " user@contoso.com "電子郵件 [type eq "work"]. value eq " user@contoso.com " 查詢。
使用者
  • 群組是選擇性的,但只有在 SCIM 執行支援 PATCH 要求時才支援。
  • 群組必須在 ' displayName ' 值上具有唯一性,以符合 Azure Active Directory 和 SCIM 應用程式之間的比對。 這不是 SCIM 通訊協定的必要條件,而是將 SCIM 服務與 Azure Active Directory 整合的需求。
/Schemas (架構探索) :
  • 範例要求/回應
  • 自訂的非資源庫 SCIM 應用程式目前不支援架構探索,但它正用於某些資源庫應用程式。 接下來,架構探索將用來做為將其他屬性新增至現有資源庫 SCIM 應用程式之架構的唯一方法。
  • 如果值不存在,請勿傳送 null 值。
  • 屬性值的大小寫應該是 camel (例如 readWrite) 。
  • 必須傳回清單回應。
  • 每次有人將布建設定儲存在 azure 入口網站中,或每次使用者進入 azure 入口網站中的 [編輯布建] 頁面時,Azure AD SCIM 用戶端都會提出/schemas 要求。 系統會在 [目標屬性] 清單下的屬性對應中,向客戶顯示任何探索到的其他屬性。 架構探索只會導致加入其他目標屬性。 它不會導致移除屬性。

使用者佈建和取消佈建

下圖顯示 AAD 傳送至 SCIM 服務的訊息,以管理應用程式的身分識別存放區中的使用者生命週期。

顯示使用者佈建和取消佈建順序
使用者佈建和解除佈建順序

群組佈建和取消佈建

群組佈建和取消佈建是選擇性的。 當執行並啟用時,下圖會顯示 AAD 傳送至 SCIM 服務的訊息,以管理應用程式身分識別存放區中群組的生命週期。 這些訊息與使用者的訊息有兩方面的不同:

  • 擷取群組的要求會指定將成員屬性從回應要求中提供的任何資源中排除。
  • 要求判斷參考屬性是否具有特定值,會是有關成員屬性的要求。

顯示群組佈建和取消佈建順序
群組佈建和解除佈建順序

SCIM 通訊協定要求和回應

本節提供 AAD SCIM 用戶端發出的範例 SCIM 要求,以及預期的回應範例。 為了獲得最佳結果,您應撰寫應用程式程式碼,以按此格式處理這些要求,並發出預期的回應。

重要

若要瞭解 AAD 使用者布建服務如何及何時發出如下所述的作業,請參閱布建週期:初始和累加式布建的運作方式

使用者作業

群組作業

架構探索

使用者作業

  • 可依 userNameemail[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

回應 (找不到使用者。 請注意,不一定要提供詳細資料,只需要狀態。)
{
    "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 沒有內容

架構探索

探索架構

要求

取得/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 通訊協定版本只有 TLS 1.2 和 TLS 1.3。 不允許其他 TLS 版本。 不允許任何版本的 SSL。

  • 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 範圍

Azure AD 佈建服務目前可在 AzureActiveDirectory 的 IP 範圍下運作,如這裡所列出的。 您可以新增 AzureActiveDirectory 標籤底下所列的 IP 範圍,以允許來自 Azure AD 佈建服務的流量進入您的應用程式。 請注意,您必須仔細檢閱計算位址的 IP 範圍清單。 如 '40.126.25.32' 的位址可能會在 IP 範圍清單中表示為 '40.126.0.0/18'。 您也可以使用下列 API,以程式設計方式取出 IP 範圍清單。

Azure AD 也支援以代理程式為基礎的解決方案,可在內部部署、裝載于 Azure、裝載于 AWS 等 ) 的專用 (網中,提供應用程式的連線能力。 客戶可以部署輕量代理程式,以在其私人網路的伺服器上,不需開啟輸入埠即可連接 Azure AD。 在此深入了解。

建立 SCIM 端點

現在,您已設計結構描述並了解 Azure AD SCIM 實作,接著即可開始開發您的 SCIM 端點。 您可以利用 SCIM 社群所發佈的一些開放原始碼 SCIM 程式庫,而不要從頭開始完全靠自己建置實作。

如需有關如何建立 SCIM 端點(包括範例)的指引,請參閱 開發範例 SCIM 端點

Azure AD 布建小組所發佈的開放原始碼 .net Core參考程式碼範例,是可讓您開始進行開發的其中一個資源。 建置 SCIM 端點後,您會想要加以測試。您可以使用在參考程式碼中提供的 postman 測試集合,或透過上方提供的範例要求/回應來執行。

注意

參考程式碼以「原狀」提供,目的是要協助您開始建置 SCIM 端點。 歡迎社群供稿,以協助建置和維護程式碼。

解決方案是由兩個專案所組成:Microsoft.SCIMMicrosoft.SCIM.WebHostSample

Microsoft.SCIM 專案是一個程式庫,會定義符合 SCIM 規格的 Web 服務元件。 此專案會宣告 Microsoft.SCIM.IProvider 介面,要求會轉譯為對提供者方法的呼叫,而這些方法會設計為程式在身分識別存放區上運作。

明細:要求轉譯為對提供者方法的呼叫

Microsoft.SCIM.WebHostSample 專案是一個 Visual Studio 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

處理端點驗證

來自 Azure Active Directory 的要求包括 OAuth 2.0 持有人權杖。 接收要求的任何服務均應為驗證簽發者為預期 Azure Active Directory 租用戶的 Azure Active Directory。

在權杖中,會用 iss 宣告來識別簽發者,例如 "iss":"https://sts.windows.net/cbb1a5ac-f33b-45fa-9bf5-f37db0fed422/"。 在此範例中,宣告值的基礎位址 https://sts.windows.net 會將 Azure Active Directory 識別為簽發者,而相對位址區段 cbb1a5ac-f33b-45fa-9bf5-f37db0fed422 則是獲得權杖的 Azure Active Directory 租用戶的唯一識別碼。

權杖的適用對象是應用程式在資源庫中的應用程式範本識別碼,在單一租用戶中註冊的每個應用程式,可能會收到與 SCIM 要求相同的 iss 宣告。 所有自訂應用程式的應用程式範本識別碼都是 8adf8e6e-67b2-4cf2-a259-e3dc5476c621。 Azure AD 佈建服務所產生的權杖僅供測試之用。 請勿在生產環境中加以使用。

在範例程式碼中,會使用 Microsoft.AspNetCore.Authentication.JwtBearer 套件來驗證要求。 下列程式碼會強制使用 Azure Active Directory 針對指定的租用戶發出的持有人權杖,對任何服務端點的要求進行驗證:

        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/cbb1a5ac-f33b-45fa-9bf5-f37db0fed422/";
                        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.查詢服務中是否有相符的使用者

Azure Active Directory (AAD) 會查詢服務的使用者,其 externalId 屬性值符合 AAD 中使用者的 mailNickname 屬性值。 查詢會以類似於此範例的超文字傳輸通訊協定 (HTTP) 要求表示,其中,jyoung 是 Azure Active Directory 中使用者的 mailNickname 範例。

注意

這只是範例。 並非所有使用者都有 mailNickname 屬性,且使用者的值在目錄中可能不是唯一的。 此外,用來比對 (的屬性(在此案例中為 externalId) 可在AAD 屬性對應中進行設定)。

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 屬性值的使用者,對 web 服務之查詢的回應不會傳回任何使用者,則 AAD 要求服務會在 AAD 中布建對應的使用者。 以下是這類要求的範例:

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 類別的執行個體,並將識別碼屬性的值設定為新佈建之使用者的唯一識別碼。

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

為了更新已知存在於前端為 SCIM 之身分識別存放區中的使用者,Azure Active Directory 會以類似下方的要求向服務要求該使用者的目前狀態,來繼續執行:

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);

在擷取使用者目前狀態之要求的範例中,提供作為參數引數值的物件具有的屬性值如下所示:

  • 識別碼:"54D382A4-2050-4C03-94D1-E769F1D15682"
  • SchemaIdentifier: "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"

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

如果要更新某個參考屬性,Azure Active Directory 就會查詢服務,以判斷以該服務作為前端之身分識別存放區中參考屬性目前的值,是否已經與 Azure Active Directory 中該屬性的值相符。 對於使用者,以這種方式可查詢目前值的唯一屬性會是管理員屬性。 下列範例說明要判斷使用者物件的管理員屬性目前是否具有某個值的要求:在範例程式碼中,要求會轉譯為對服務提供者的 QueryAsync 方法的呼叫。 提供物件的屬性值作為參數引數的值,如下所示:

  • parameters.AlternateFilters.Count:2
  • parameters.AlternateFilters.ElementAt(x).AttributePath:「識別碼」
  • parameters.AlternateFilters.ElementAt(x).ComparisonOperator:ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(x).ComparisonValue:"54D382A4-2050-4C03-94D1-E769F1D15682"
  • parameters.AlternateFilters.ElementAt(y).AttributePath: "manager"
  • parameters.AlternateFilters.ElementAt(y).ComparisonOperator:ComparisonOperator.Equals
  • parameters.AlternateFilter.ElementAt(y).ComparisonValue:"2819c223-7f76-453a-919d-413861904646"
  • parameters.RequestedAttributePaths.ElementAt(0):「識別碼」
  • parameters.SchemaIdentifier: "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"

在此處,索引 x 的值可能會是 0,而索引 y 的值可能是 1,或 x 值可能是 1 而 y 的值可能是 0,視篩選查詢參數運算式的順序而定。

範例 5.Azure AD 對 SCIM 服務發出以更新使用者的要求

以下是由 Azure Active Directory 對 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);

在更新使用者之要求的範例中,提供作為修補程式引數值的物件具有這些屬性值:

引數
ResourceIdentifier 識別碼 "54D382A4-2050-4C03-94D1-E769F1D15682"
ResourceIdentifier. Resourceidentifier.schemaidentifier "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
(Patchrequest as 為 PatchRequest2) 。作業計數 1
(Patchrequest as 為 PatchRequest2) 。Parameters.alternatefilters.elementat (0) 。OperationName OperationName.Add
(Patchrequest as 為 PatchRequest2) 。Parameters.alternatefilters.elementat (0) 。路徑. .Attributepath 管理
(Patchrequest as 為 PatchRequest2) 。Parameters.alternatefilters.elementat (0) 。值。計數 1
(Patchrequest as 為 PatchRequest2) 。Parameters.alternatefilters.elementat (0) 。Parameters.alternatefilters.elementat (0) 。參考 HTTP://.../scim/Users/2819c223-7f76-453a-919d-413861904646
(Patchrequest as 為 PatchRequest2) 。Parameters.alternatefilters.elementat (0) 。Parameters.alternatefilters.elementat (0) 。價值 2819c223-7f76-453a-919d-413861904646

範例 6.取消佈建使用者

若要從 SCIM 服務所前端的身分識別存放區取消布建使用者,AAD 傳送如下所示的要求:

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 端點與 AAD SCIM 用戶端整合

Azure AD 可設定為將已指派的使用者和群組自動佈建至實作 SCIM 2.0 通訊協定之特定設定檔的應用程式。 設定檔的詳細資訊記載于瞭解 Azure AD SCIM 的執行

洽詢應用程式提供者,或參閱應用程式提供者文件中的相關陳述,以了解是否符合這些需求。

重要

Azure AD SCIM 實作建置於 Azure AD 使用者佈建服務之上,其設計目的是要讓使用者在 Azure AD 與目標應用程式之間保持同步,並實作一組非常明確的標準作業。 請務必了解這些行為,以了解 Azure AD SCIM 用戶端的行為。 如需詳細資訊,請參閱佈建週期:初始和增量一節 (位於佈建運作方式中)。

開始使用

支援本文所述 SCIM 設定檔的應用程式,可使用 Azure AD 應用程式庫中的「不在資源庫內的應用程式」功能連線到 Azure Active Directory。 連線之後,Azure AD 會每隔 40 分鐘執行一次同步處理程序,此程序會為指派的使用者和群組查詢應用程式的 SCIM 端點,並根據指派詳細資料加以建立或修改。

若要連接支援 SCIM 的應用程式:

  1. 登入AAD 入口網站。 請注意,您可以註冊開發人員計劃,以取得具有 P2 授權的 Azure Active Directory 免費試用版

  2. 在左側窗格中,選取 [企業應用程式]。 此時會顯示所有已設定的應用程式清單,包括已從資源庫新增的應用程式。

  3. 選取 [ + 新增應用程式 > + 建立您自己的應用程式]。

  4. 輸入應用程式的名稱,選擇 [整合您在資源庫中找不到的任何其他應用程式] 選項,然後選取 [ 新增 ] 以建立應用程式物件。 新的應用程式會新增至企業應用程式清單,並在開啟後進入其應用程式管理畫面。

    螢幕擷取畫面顯示 Azure AD 應用程式庫 Azure AD 應用程式資源庫

    注意

    如果您使用舊的應用程式資源庫體驗,請遵循以下的螢幕指南。

    螢幕擷取畫面顯示 Azure AD 舊有應用程式資源庫 的 Azure AD 舊有應用程式資源庫體驗

  5. 在應用程式管理畫面中,選取左側面板中的 [佈建]。

  6. 在 [佈建模式] 功能表上,選取 [自動]。

    範例:應用程式在 Azure 入口網站中的 [佈建] 頁面
    在 Azure 入口網站中設定佈建

  7. 在 [租用戶 URL] 欄位中,輸入應用程式 SCIM 端點的 URL。 範例: https://api.contoso.com/scim/

  8. 如果 SCIM 端點需要來自非 Azure AD 簽發者的 OAuth 持有人權杖,那麼便將所需的 OAuth 持有人權杖複製到選擇性 [祕密權杖] 欄位。 如果將此欄位保留空白,則 Azure AD 會在每個要求包含從 Azure AD 簽發的 OAuth 持有人權杖。 應用程式若使用 Azure AD 作為識別提供者,便可以驗證此 Azure AD 簽發的權杖。

    注意

    建議將此欄位保留空白並使用 Azure AD 所產生的權杖。 此選項主要供測試之用。

  9. 選取 [測試連線],讓 Azure Active Directory 嘗試連線至 SCIM 端點。 如果嘗試失敗,將會顯示錯誤資訊。

    注意

    [測試連線] 會查詢 SCIM 端點中是否有不存在的使用者,並使用隨機 GUID 作為 Azure AD 設定中選取的比對屬性。 預期的正確回應是 HTTP 200 OK 和空白的 SCIM ListResponse 訊息。

  10. 如果嘗試連線至應用程式成功,請選取 [儲存] 以儲存管理員認證。

  11. 在 [對應] 區段中,有兩組可選取的屬性對應:一個用於使用者物件,一個用於群組物件。 選取其中一個以檢閱從 Azure Active Directory 同步處理至應用程式的屬性。 選取為 [比對] 屬性的屬性會用來比對應用程式中的使用者和群組以進行更新作業。 選取 [儲存] 認可任何變更。

    注意

    您可以選擇性地藉由停用「群組」對應以停用同步處理群組物件。

  12. 在 [設定] 底下,[範圍] 欄位會定義要同步的使用者和群組。 選取 [僅同步處理指派的使用者和群組] (建議選項),僅同步處理 [使用者和群組] 索引標籤中指派的使用者和群組。

  13. 設定完成後,請將 [佈建狀態] 設定為 [開啟]。

  14. 選取 [儲存] 以啟動 Azure AD 佈建服務。

  15. 如果僅同步處理指派的使用者和群組 (建議選項),請務必選取 [使用者和群組] 索引標籤,並指派您要同步處理的使用者或群組。

初始週期開始後,您可以在左側面板中選取 [佈建記錄] 以監視進度,其中會顯示佈建服務對您的應用程式執行的所有動作。 如需如何讀取 Azure AD 佈建記錄的詳細資訊,請參閱關於使用者帳戶自動佈建的報告

注意

初始週期執行時會比後續的同步處理耗時;在服務執行期間,大約每 40 分鐘會執行一次同步處理。

如果您要建立將由多個租用戶使用的應用程式,您可以在 Azure AD 應用程式庫中加以提供。 這可讓組織輕鬆地探索應用程式和設定佈建。 在 Azure AD 資源庫中發佈您的應用程式並供其他人佈建,是很簡單的作業。 請在 這裡查明步驟。 Microsoft 會與您合作,將您的應用程式整合到我們的資源庫中、測試您的端點,以及發行上線文件供客戶使用。

使用檢查清單快速讓您的應用程式上線,並讓客戶有順暢的部署體驗。 當您上線至資源庫時,系統將會向您收集資訊。

  • 支援 SCIM 2.0 使用者和群組端點 (只需要一個,但建議兩者都使用)
  • 每個租用戶每秒支援至少 25 個要求,以確保在沒有延遲的情況下佈建和取消佈建使用者和群組 (必要)
  • 建立工程和支援連絡人,以便在資源庫上線後引導客戶 (必要)
  • 應用程式有 3 個未過期的測試認證可使用 (必要)
  • 支援 OAuth 授權碼授與或長時間存留的權杖,如下所述 (必要)
  • 建立工程和支援連絡點,以便在資源庫上線後支援客戶 (必要)
  • 支援架構探索 (必要)
  • 支援使用單一修補程式更新多個群組成員資格
  • 公開記錄您的 SCIM 端點

SCIM 規格不會定義用於驗證和授權的 SCIM 專屬配置,並且依賴現有產業標準的使用。

授權方法 優點 缺點 支援
使用者名稱和密碼 (Azure AD 不建議使用或加以支援) 易於實作 不安全 - 您的 Pa$$word 無關緊要 不支援新的資源庫或非資源庫應用程式。
長時間存留的持有人權杖 長時間存留的權杖不需要有使用者存在。 在設定佈建時,管理員很容易就能使用這些權杖。 若未使用不安全的方法 (例如電子郵件),長時間存留的權杖可能難以與管理員共用。 支援資源庫和非資源庫應用程式。
OAuth 授權碼授與 存取權杖的存留期遠比密碼短,且具有長期持有人權杖所沒有的自動化重新整理機制。 在初始授權期間必須有實際的使用者存在,因而增加了一層責任。 必須要有使用者存在。 如果使用者離職,權杖就會失效,而必須重新完成授權。 支援資源庫應用程式,但不支援非資源庫應用程式。 不過,您可以在 UI 中提供存取權杖,做為短期測試用途的秘密權杖。 針對非資源庫的 OAuth 程式碼授與支援,除了支援資源庫應用程式上可設定的驗證/權杖 Url 之外,還在我們的待處理專案中。
OAuth 用戶端認證授與 存取權杖的存留期遠比密碼短,且具有長期持有人權杖所沒有的自動化重新整理機制。 授權碼授與和用戶端認證授與會建立相同類型的存取權杖,因此,這些方法的切換對 API 而言是透明的。 佈建可以完全自動化,且可以無訊息方式要求新的權杖,而不需要使用者介入。 不支援資源庫和非資源庫應用程式。 我們已將支援列入待處理項目中。

注意

不建議在 AAD 布建設定的自訂應用程式 UI 中,將 [權杖] 欄位保留空白。 產生的權杖主要供測試之用。

OAuth 程式碼授與流程

布建服務支援 授權碼授 與,提交您在資源庫中發佈應用程式的要求之後,我們的小組會與您一起收集下列資訊:

  • 授權 url、用戶端用來透過使用者代理程式重新導向取得資源擁有者授權的 url。 使用者會重新導向至此 URL 以授與存取權。

  • 權杖交換 url、用戶端用來交換存取權杖授權授與的 url,通常是透過用戶端驗證。

  • 用戶端 識別碼,授權伺服器會將用戶端識別碼簽發給已註冊的用戶端,這是代表用戶端所提供之註冊資訊的唯一字串。 用戶端識別碼不是秘密,而會向資源擁有者公開,且 不得 單獨用於用戶端驗證。

  • 用戶端密碼,授權伺服器所產生的秘密,應該是唯一的唯一值,只知道授權伺服器。

注意

授權 url權杖交換 url 目前無法針對每個租使用者設定。

注意

因為公開用戶端密碼,所以不支援 OAuth v1。 OAuth v2 則受支援。

建議的最佳作法 (,但不是必要的) :

  • 支援多個重新導向 URL。 管理員可從 "portal.azure.com" 和 "aad.portal.azure.com" 設定佈建。 支援多個重新導向 URL 可確保使用者可從任一入口網站授與存取權。
  • 支援多個秘密以方便續約,而不需要停機。

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

  1. 登入 Azure 入口網站,移至 Enterprise 應用 > 程式應用程式 布建 > ,然後選取 [授權]。

    1. Azure 入口網站會將使用者重新導向至授權 URL (第三方應用程式的登入頁面)。

    2. 管理員會提供認證給第三方應用程式。

    3. 第三方應用程式會將使用者重新導向回到 Azure 入口網站並提供授權碼

    4. Azure AD 佈建服務會呼叫權杖 URL,並提供授權碼。 第三方應用程式會以存取權杖、重新整理權杖和到期日回應

  2. 當佈建週期開始時,服務會檢查目前的存取權杖是否有效,並視需要將其與新的權杖交換。 存取權杖會在對應用程式提出的每個要求中提供,而且會在提出每個要求之前檢查要求的有效性。

注意

雖然無法在非資源庫的應用程式上設定 OAuth,但您可以從授權伺服器手動產生存取權杖,並將它當作秘密權杖輸入至非資源庫應用程式。 這可讓您在上架到應用程式資源庫(支援 OAuth 程式碼授與)之前,先驗證 SCIM 伺服器與 AAD SCIM 用戶端的相容性。

長時間存留的 OAuth 持有人權杖: 如果您的應用程式不支援 OAuth 授權碼授與流程,請改為產生長期的 OAuth 持有人權杖,讓系統管理員可用來設定布建整合。 此權杖應該是永久的,否則,當權杖過期時,佈建作業將遭到隔離

如需其他驗證和授權方法的相關資訊,請在 UserVoice 上告訴我們。

為了協助您了解我們的聯合整合並帶動其需求,建議您更新現有的建,並在您的行銷通路中詳細說明此整合。 建議您完成以下這一系列的檢查清單活動,以支援上市投入

下一步