教學課程 - 在 Microsoft Entra ID 中自定義 SaaS 應用程式的使用者布建屬性對應
Microsoft Entra ID 為非 Microsoft SaaS 應用程式提供使用者布建的支援,例如 Salesforce、G Suite 和其他應用程式。 如果您為非 Microsoft SaaS 應用程式啟用使用者布建,Microsoft Entra 系統管理中心會透過屬性對應控制其屬性值。
開始之前,請確定您已熟悉應用程式管理和 單一登錄 (SSO) 概念。 查看以下連結:
Microsoft Entra 用戶物件與每個 SaaS 應用程式的使用者對象之間有一組預先設定的屬性和屬性對應。 某些應用程式會與使用者一起管理其他類型的物件,例如群組。
您可以根據您的業務需求自定義預設屬性對應。 因此,您可以變更或刪除現有的屬性對應,或建立新的屬性對應。
注意
除了透過 Microsoft Entra 介面設定屬性對應之外,您還可以檢閱、下載和編輯架構的 JSON 表示法。
編輯使用者屬性對應
提示
本文中的步驟可能會根據您從開始的入口網站稍有不同。
請遵循下列步驟來存取 使用者布建的對應 功能:
以至少應用程式 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
流覽至 [身分>識別應用程式企業應用程式]。>
會顯示所有已設定的應用程式清單,包括從資源庫新增的應用程式。
選取任何應用程式以載入其應用程式管理窗格,您可以在其中檢視報表及管理應用程式設定。
選取 [ 布建 ] 以管理所選應用程式的用戶帳戶布建設定。
展開 [ 對應] 以檢視和編輯在 Microsoft Entra ID 與目標應用程式之間流動的用戶屬性。 如果目標應用程式支援,本節可讓您選擇性地設定群組和用戶帳戶的布建。
選取 [ 對應] 組 態以開啟相關的 [屬性對應 ] 畫面。 SaaS 應用程式需要特定屬性對應才能正常運作。 針對必要的屬性, 「刪除 」功能無法使用。
在此螢幕快照中,您可以看到 Salesforce 中 Managed 物件的 Username 屬性已填入 連結 Microsoft Entra 物件的 userPrincipalName 值。
注意
清除 [建立 ] 不會影響現有的使用者。 如果未 選取 [建立 ],則您無法建立新的使用者。
選取現有的 [屬性對應 ] 以開啟 [ 編輯屬性 ] 畫面。 您可以在這裏編輯在 Microsoft Entra ID 與目標應用程式之間流動的使用者屬性。
瞭解屬性對應類型
透過屬性對應,您可以控制非 Microsoft SaaS 應用程式中的屬性填入方式。 支援四種不同的對應類型:
- Direct – 目標屬性會填入 Microsoft Entra ID 中鏈接物件的屬性值。
- 常數 – 目標屬性會填入您指定的特定字串。
- 表達式 - 目標屬性會根據類似腳本的表達式結果填入。 如需表達式的詳細資訊,請參閱 在 Microsoft Entra ID 中撰寫屬性對應表達式。
- 無 - 目標屬性保持未修改。 不過,如果目標屬性是空的,它會填入您指定的預設值。
除了這四種基本類型之外,自定義屬性對應也支援選擇性 預設值 指派的概念。 如果 Microsoft Entra ID 或目標對象中沒有值,預設值指派可確保目標屬性會填入值。 最常見的組態是將此設定保留空白。 如需對應屬性的詳細資訊,請參閱 應用程式布建在 Microsoft Entra ID 中的運作方式。
瞭解屬性對應屬性
在上一節中,您已介紹屬性對應類型屬性。 除了此屬性之外,屬性對應也支援屬性:
- 來源屬性 - 來源系統的使用者屬性(例如:Microsoft Entra ID)。
- 目標屬性 – 目標系統中的用戶屬性(例如:ServiceNow)。
- 如果為 null 的預設值 (選擇性) - 如果來源屬性為 Null,則會傳遞至目標系統的值。 只有在建立使用者時,才會布建此值。 更新現有使用者時,不會布建「null 時的預設值」。 例如,使用表達式建立使用者時,新增職稱的預設值:
Switch(IsPresent([jobTitle]), "DefaultValue", "True", [jobTitle])
。 如需表達式的詳細資訊,請參閱 在 Microsoft Entra ID 中撰寫屬性對應表達式的參考。 - 比對使用這個屬性 的物件 – 是否應該使用此對應來唯一識別來源和目標系統之間的使用者。
userPrincipalName
用於 Microsoft Entra ID 中的 或 mail 屬性,並對應至目標應用程式中的使用者名稱欄位。 - 比對優先順序 – 可以設定多個比對屬性。 當有多個時,會依照此欄位所定義的順序進行評估。 一旦找到相符專案,就不會評估任何進一步的相符屬性。 雖然您可以視需要設定盡可能多的相符屬性,但請考慮您使用做為比對屬性的屬性是否真正是唯一的,而且需要比對屬性。 一般而言,客戶的設定中有一或兩個相符的屬性。
- 套用對應。
- 一律 – 在使用者建立和更新動作上套用此對應。
- 僅在建立 期間 - 只在使用者建立動作上套用此對應。
比對來源和目標系統中的使用者
Microsoft Entra 布建服務可以部署在「綠地」案例中(其中使用者不存在於目標系統中)和「棕色地帶」案例(其中使用者已存在於目標系統中)。 為了支援這兩種案例,布建服務會使用比對屬性的概念。 比對屬性可讓您判斷如何唯一識別來源中的使用者,並比對目標中的使用者。 在規劃部署的過程中,請識別可用來唯一識別來源和目標系統中用戶的屬性。 注意事項:
- 比對屬性應是唯一的: 客戶通常會使用 userPrincipalName、mail 或對象識別碼等屬性作為比對屬性。
- 多個屬性可以做為比對屬性: 您可以在比對用戶時定義要評估的多個屬性,以及評估用戶的順序(定義為UI中的比對優先順序)。 例如,如果您將三個屬性定義為相符的屬性,而且在評估前兩個屬性之後,使用者會唯一比對,服務將不會評估第三個屬性。 服務會依指定的順序評估相符屬性,並在找到相符專案時停止評估。
- 來源和目標中的值不需要完全相符: 目標中的值可以是來源中值的函式。 因此,在來源和目標中的userPrincipalName中,可能會有 emailAddress 屬性,並符合 emailAddress 屬性的函式,以一些常數值取代某些字元。
- 不支援根據屬性組合進行比對: 大部分的應用程式都不支持根據兩個屬性進行查詢。 因此,無法根據屬性的組合進行比對。 可以在另一個屬性之後評估單一屬性。
- 所有使用者至少必須有一個相符屬性的值: 如果您定義一個比對屬性,則所有使用者都必須在來源系統中具有該屬性的值。 例如,如果您將userPrincipalName定義為比對屬性,則所有用戶都必須有userPrincipalName。 如果您定義多個比對屬性(例如 extensionAttribute1 和 mail),並非所有的使用者都必須具有相同的比對屬性。 一個使用者可以有 extensionAttribute1,但不能有郵件,而另一個使用者可以有郵件,但沒有 extensionAttribute1。
- 目標應用程式必須支援比對屬性的篩選: 應用程式開發人員允許篩選其使用者或群組 API 上的屬性子集。 對於資源庫中的應用程式,我們確定預設屬性對應適用於目標應用程式 API 支援篩選的屬性。 變更目標應用程式的預設比對屬性時,請檢查非 Microsoft API 檔,以確保可以篩選屬性。
編輯群組屬性對應
選取的應用程式數目,例如 ServiceNow、Box 和 G Suite,可支援布建群組和用戶物件的能力。 群組物件可以包含群組屬性,例如顯示名稱和電子郵件別名,以及群組成員。
選取 [對應] 底下的群組對應,並將 [啟用] 設定為 [屬性對應] 畫面中您想要的選項,即可選擇性地啟用或停用群組布建。
布建為 Group 物件一部分的屬性,可以與先前所述的 User 物件相同的方式來自定義。
提示
布建群組物件(屬性和成員)是將群組指派給應用程式的不同概念。 可以將群組指派給應用程式,但只布建群組中包含的用戶物件。 布建完整群組物件不需要在指派中使用群組。
編輯支援的屬性清單
預先設定指定應用程式所支援的用戶屬性。 大部分應用程式的使用者管理 API 都不支援架構探索。 因此,Microsoft Entra 布建服務無法藉由呼叫應用程式來動態產生支援的屬性清單。
不過,某些應用程式支援自定義屬性,而 Microsoft Entra 布建服務可以讀取和寫入自定義屬性。 若要在 Microsoft Entra 系統管理中心輸入其定義,請選取 [屬性對應] 畫面底部的 [顯示進階選項] 複選框,然後選取應用程式的 [編輯屬性清單]。
支援自訂屬性清單的應用程式和系統包括:
- Salesforce
- ServiceNow
- Workday 至 Active Directory / Workday 至 Microsoft Entra ID
- SuccessFactors 至 Active Directory / SuccessFactors 至 Microsoft Entra ID
- 支援 Microsoft Entra ID(支援 Microsoft Entra ID Graph API 預設屬性 和自定義目錄延伸模組)。 如需建立延伸模組的詳細資訊,請參閱 同步處理 Microsoft Entra 應用程式佈 建的延伸模塊屬性和 Microsoft Entra 識別碼中布建的已知問題
- 支援 跨網域身分識別系統的應用程式 (SCIM) 2.0
- Microsoft Entra ID 支援 XPATH 和 JSONPath 元數據的 Workday 或 SuccessFactors 回寫。 Microsoft Entra ID 不支援默認架構中未包含的新 Workday 或 SuccessFactors 屬性
注意
僅針對已自定義其應用程式和系統的架構的系統管理員,建議編輯支援的屬性清單,並具備其自定義屬性定義方式的第一手知識,或如果來源屬性未自動顯示在 Microsoft Entra 系統管理中心 UI 中。 這有時需要熟悉應用程式或系統所提供的 API 和開發人員工具。 預設會鎖定編輯支援屬性清單的功能,但客戶可以瀏覽至下列 URL 來啟用功能: https://portal.azure.com/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true 。 然後,您可以瀏覽至應用程式以檢視 屬性清單。
注意
當 Microsoft Entra ID 中的目錄延伸屬性未自動顯示在您的屬性對應下拉式清單中時,您可以手動將其新增至 「Microsoft Entra 屬性清單」。 手動將 Microsoft Entra 目錄擴充屬性新增至布建應用程式時,請注意目錄擴充屬性名稱會區分大小寫。 例如:如果您有名為 的 extension_53c9e2c0exxxxxxxxxxxxxxxx_acmeCostCenter
目錄擴充屬性,請確定您輸入的格式與目錄中定義的格式相同。 不支援布建多重值目錄擴充屬性。
當您編輯支援的屬性清單時,會提供下列屬性:
- 名稱 - 屬性的系統名稱,如目標對象的架構中所定義。
- Type - 屬性所儲存的數據類型,如目標對象的架構中所定義,它可以是下列其中一種類型。
- Binary - 屬性包含二進位數據。
- 布爾值 - 屬性包含 True 或 False 值。
- DateTime - 屬性包含日期字串。
- Integer - 屬性包含整數。
- 參考 - 屬性包含識別碼,參考儲存在目標應用程式中另一個數據表中的值。
- 字串 - 屬性包含文字字串。
- 主鍵? - 屬性是否定義為目標物件架構中的主鍵欄位。
- 是必要的嗎? - 屬性是否需要在目標應用程式或系統中填入。
- 多重值? - 屬性是否支援多個值。
- 確切的情況? - 屬性值是否以區分大小寫的方式進行評估。
- API 運算式 - 除非由特定布建連接器的檔指示這麼做,否則請勿使用 (例如 Workday)。
- 參考的物件屬性 - 如果是 [參考類型] 屬性 ,則此功能表可讓您在包含與 屬性相關聯的值的目標應用程式中選取資料表和屬性。 例如,如果您有名為 「Department」 的屬性,其預存值參考個別 「Departments」 資料表中的物件,您會選取
Departments.Name
。 指定應用程式支援的參考數據表和主要標識符欄位已預先設定,且無法使用 Microsoft Entra 系統管理中心編輯。 不過,您可以使用 Microsoft Graph API 加以編輯。
將自定義擴充屬性布建至符合 SCIM 規範的應用程式
SCIM 批註要求 (RFC) 會定義核心使用者和群組架構,同時允許架構的延伸模組符合應用程式的需求。 若要將自訂屬性新增至 SCIM 應用程式:
- 以至少應用程式 管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
- 流覽至 [身分>識別應用程式企業應用程式]。>
- 選取您的應用程式,然後選取 [ 布建]。
- 在 [對應] 底下,選取您要新增自定義屬性的物件(使用者或群組)。
- 在頁面底部,選取 [ 顯示進階選項]。
- 針對 AppName 選取 [編輯屬性清單]。
- 在屬性清單底部,輸入所提供字段中自定義屬性的相關信息。 然後選取 [ 新增屬性]。
針對 SCIM 應用程式,屬性名稱必須遵循範例中顯示的模式。 您可以根據應用程式的需求自定義 「CustomExtensionName」 和 「CustomAttribute」,例如:urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User:CustomAttribute
這些指示僅適用於已啟用 SCIM 的應用程式。 ServiceNow 和 Salesforce 之類的應用程式不會使用 SCIM 與 Microsoft Entra ID 整合,因此在新增自定義屬性時不需要此特定命名空間。
自訂屬性不能是引用屬性、多重值或複雜類型屬性。 自定義多重值和複雜類型的擴充屬性目前僅支援資源庫中的應用程式。 範例中會省略自定義延伸模組架構標頭,因為它不會在來自 Microsoft Entra SCIM 用戶端的要求中傳送。
具有擴充屬性之使用者的範例表示法:
{
"schemas":[
"urn:ietf:params:scim:schemas:core:2.0:User",
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
],
"userName":"bjensen",
"id": "48af03ac28ad4fb88478",
"externalId":"bjensen",
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
"employeeNumber": "701984",
"costCenter": "4130",
"organization": "Universal Studios",
"division": "Theme Park",
"department": "Tour Operations",
"manager": {
"value": "26118915-6090-4610-87e4-49d8ca9f808d",
"$ref": "../Users/26118915-6090-4610-87e4-49d8ca9f808d",
"displayName": "John Smith"
}
},
"urn:ietf:params:scim:schemas:extension:CustomExtensionName:2.0:User": {
"CustomAttribute": "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"
}
}
將角色布建至 SCIM 應用程式
使用範例中的步驟,將使用者的應用程式角色佈建至您的應用程式。 描述專屬於自定義 SCIM 應用程式。 對於 Salesforce 和 ServiceNow 等資源庫應用程式,請使用預先定義的角色對應。 項目符號描述如何將AppRoleAssignments屬性轉換為應用程式預期的格式。
- 將 Microsoft Entra ID 中的 appRoleAssignment 對應至應用程式中的角色時,您必須使用 運算式來轉換屬性。 appRoleAssignment 屬性不應該直接對應至角色屬性,而不需要使用表達式來剖析角色詳細數據。
注意
從企業應用程式佈建角色時,SCIM 標準會以不同的方式定義企業使用者角色屬性。 如需詳細資訊,請參閱 在 Microsoft Entra ID 中開發和規劃 SCIM 端點的布建。
SingleAppRoleAssignment
使用時機: 使用SingleAppRoleAssignment 表達式為使用者布建單一角色,並指定主要角色。
如何設定: 使用描述的步驟流覽至屬性對應頁面,並使用SingleAppRoleAssignment 表達式對應至角色屬性。 有三個角色屬性可供選擇(roles[primary eq "True"].display
、 roles[primary eq "True"].type
和 roles[primary eq "True"].value
)。 您可以選擇在對應中包含任何或所有角色屬性。 如果您想要包含一個以上的對應,只要新增對應並納入為目標屬性即可。
考量的事項
- 請確定未將多個角色指派給使用者。 不保證已布建哪個角色。
SingleAppRoleAssignments
檢查屬性。 屬性與 將範圍設定為Sync All users and groups
不相容。
範例要求 (POST)
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"externalId": "alias",
"userName": "alias@contoso.OnMicrosoft.com",
"active": true,
"displayName": "First Name Last Name",
"meta": {
"resourceType": "User"
},
"roles": [{
"primary": true,
"type": "WindowsAzureActiveDirectoryRole",
"value": "Admin"
}
]}
範例輸出 (PATCH)
"Operations": [
{
"op": "Add",
"path": "roles",
"value": [{
"value": "{\"id\":\"06b07648-ecfe-589f-9d2f-6325724a46ee\",\"value\":\"25\",\"displayName\":\"Role1234\"}"
}
]
}]
PATCH 和 POST 中的要求格式不同。 若要確保 POST 和 PATCH 以相同的格式傳送,您可以使用此處所述的功能旗標。
AppRoleAssignmentsComplex
使用時機: 使用 AppRoleAssignmentsComplex 運算式為使用者布建多個角色。 如何設定: 編輯支援的屬性清單,如描述以包含角色的新屬性:
然後使用 AppRoleAssignmentsComplex 表達式對應至自定義角色屬性,如下圖所示:
考量的事項
- 所有角色都會布建為主要 = false。
id
SCIM 角色中不需要屬性。 請改用value
屬性。 例如,如果value
屬性包含角色的名稱或標識符,請使用它來布建角色。 您可以使用這裡的功能旗標來修正 id 屬性問題。 不過,僅依賴 value 屬性並不一定足夠;例如,如果有多個具有相同名稱或標識碼的角色。 在某些情況下,必須使用id屬性來正確布建角色
限制
- AppRoleAssignmentsComplex 與將範圍設定為 「同步所有使用者和群組」不相容。
範例要求 (POST)
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"externalId": "alias",
"userName": "alias@contoso.OnMicrosoft.com",
"active": true,
"displayName": "First Name Last Name",
"meta": {
"resourceType": "User"
},
"roles": [
{
"primary": false,
"type": "WindowsAzureActiveDirectoryRole",
"displayName": "Admin",
"value": "Admin"
},
{
"primary": false,
"type": "WindowsAzureActiveDirectoryRole",
"displayName": "User",
"value": "User"
}
]
}
範例輸出 (PATCH)
"Operations": [
{
"op": "Add",
"path": "roles",
"value": [
{
"value": "{"id":"06b07648-ecfe-589f-9d2f-6325724a46ee","value":"Admin","displayName":"Admin"}
},
{
"value": "{"id":"06b07648-ecfe-599f-9d2f-6325724a46ee","value":"User","displayName":"User"}
}
]
}
]
AssertiveAppRoleAssignmentsComplex (建議用於複雜角色)
使用時機: 使用 AssertiveAppRoleAssignmentsComplex 來啟用 PATCH Replace 功能。 對於支援多個角色的 SCIM 應用程式,這可確保在目標應用程式中也會移除 Microsoft Entra ID 中移除的角色。 取代功能也會移除使用者未反映在 Entra ID 中的任何其他角色
AppRoleAssignmentsComplex 和 AssertiveAppRoleAssignmentsComplex 之間的差異是修補程式呼叫的模式,以及對目標 systen 的影響。 前者只會新增 PATCH,因此不會移除目標上的任何現有角色。 後者會取代 PATCH,如果尚未將角色指派給 Entra ID 上的使用者,則會移除目標系統中的角色。
如何設定: 編輯支援的屬性清單,如描述以包含角色的新屬性:
然後使用 AssertiveAppRoleAssignmentsComplex 運算式對應至自定義角色屬性,如下圖所示:
考量的事項
- 所有角色都會布建為主要 = false。
id
SCIM 角色中不需要屬性。 請改用value
屬性。 例如,如果value
屬性包含角色的名稱或標識符,請使用它來布建角色。 您可以使用這裡的功能旗標來修正 id 屬性問題。 不過,僅依賴 value 屬性並不一定足夠;例如,如果有多個具有相同名稱或標識碼的角色。 在某些情況下,必須使用id屬性來正確布建角色
限制
- AssertiveAppRoleAssignmentsComplex 與將範圍設定為 「同步所有使用者和群組」不相容。
範例要求 (POST)
{"schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
"externalId":"contoso",
"userName":"contoso@alias.onmicrosoft.com",
"active":true,
"roles":[{
"primary":false,
"type":"WindowsAzureActiveDirectoryRole",
"display":"User",
"value":"User"},
{"primary":false,
"type":"WindowsAzureActiveDirectoryRole",
"display":"Test",
"value":"Test"}],
}
範例輸出 (PATCH)
{"schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations":[{
"op":"replace",
"path":"roles",
"value":[{
"primary":false,
"type":"WindowsAzureActiveDirectoryRole",
"display":"User",
"value":"User"},
{"primary":false,
"type":"WindowsAzureActiveDirectoryRole",
"display":"Test",
"value":"Test"}
]
}
]
}
布建多重值屬性
某些屬性,例如 phoneNumbers 和電子郵件是多重值屬性,您必須指定不同類型的電話號碼或電子郵件。 使用多重值屬性的表達式。 它可讓您指定屬性類型,並將它對應至值對應的 Microsoft Entra 使用者屬性。
phoneNumbers[type eq "work"].value
phoneNumbers[type eq "mobile"]
。價值phoneNumbers[type eq "fax"].value
"phoneNumbers": [ { "value": "555-555-5555", "type": "work" }, { "value": "555-555-5555", "type": "mobile" }, { "value": "555-555-5555", "type": "fax" } ]
還原預設屬性和屬性對應
如果您需要重新開始,並將現有的對應重設為其默認狀態,您可以選取 [還原預設對應 ] 複選框並儲存組態。 這樣做會設定所有對應和範圍篩選,就像從應用連結庫將應用程式新增至您的 Microsoft Entra 租使用者一樣。
選取此選項會在布建服務執行時強制所有使用者重新同步處理。
重要
強烈建議在叫用此選項之前, 將 [布建狀態 ] 設定為 [ 關閉 ]。
您應該知道的事情
- Microsoft Entra ID 提供同步處理程式的有效實作。 在初始化的環境中,同步處理週期期間只會處理需要更新的物件。
- 更新屬性對應會影響同步處理週期的效能。 屬性對應組態的更新需要重新評估所有 Managed 物件。
- 建議的最佳做法是至少保留屬性對應連續變更的數目。
- 目前不支援將相片屬性布建至應用程式,因為您無法指定同步相片的格式。 您可以在 User Voice 上要求此功能。
- 屬性
IsSoftDeleted
通常是應用程式預設對應的一部分。IsSoftdeleted
在四個案例中的其中一個中,可能是 true:1) 使用者因為未從應用程式指派而脫離範圍。 2) 使用者因為不符合範圍篩選而不在範圍中。 3) 在 Microsoft Entra ID 中虛刪除使用者。4) 屬性AccountEnabled
在用戶上設定為 false。 請嘗試將屬性保留在IsSoftDeleted
屬性對應中。 - Microsoft Entra 布建服務不支援布建 Null 值。
- 它們主要索引鍵通常
ID
不應該包含在屬性對應中作為目標屬性。 - 角色屬性通常需要使用運算式進行對應,而不是直接對應。 如需角色對應的詳細資訊,請參閱 將角色布建至 SCIM 應用程式。
- 雖然您可以從對應停用群組,但不支援停用使用者。