Microsoft Entra ID 支援使用者配置至非 Microsoft SaaS 應用程式,如 Salesforce、G Suite 等。 如果你啟用非 Microsoft SaaS 應用程式的使用者配置,Microsoft Entra 系統管理中心 會透過屬性映射來控制其屬性值。
開始之前,請確定您熟悉應用程式管理和「單一登入 (SSO)」概念。 查看以下連結:
Microsoft Entra ID 應用程式管理快速入門系列 - 什麼是單一登入 (SSO)?
Microsoft Entra 使用者物件與每個 SaaS 應用程式的使用者物件之間,都有一套預先設定好的屬性和屬性映射。 有些應用程式除了使用者以外,還會管理其他類型的物件,例如群組。
您可以根據您的業務需求進行自訂預設的屬性對應。 因此,您可以變更或刪除現有的屬性對應,或建立新的屬性對應。
注意
除了透過 Microsoft Entra 介面設定屬性映射外,你還可以檢視、下載並編輯結構的 JSON 表示。
編輯使用者屬性對應
請依照下列步驟存取使用者佈建的對應功能:
請瀏覽至 Entra ID 的 企業應用程式。
此時會顯示所有已設定的應用程式清單,包括已從資源庫新增的應用程式。
選取任何應用程式以載入其 [應用程式管理] 窗格,您可以在其中檢視報表及管理應用程式設定。
選取 [佈建],以管理所選應用程式的使用者帳戶佈建設定。
展開 Mappings 以檢視和編輯在 Microsoft Entra ID 與目標應用程式之間傳遞的使用者屬性。 如果目標應用程式可支援,則此區段可讓您選擇性地設定群組和使用者帳戶的佈建。
選取 對應 設定以開啟相關的 屬性對應畫面。 SaaS 應用程式需要特定屬性對應才能正常運作。 若為必要的屬性,[刪除] 功能就無法使用。
在這張截圖中,你可以看到 Salesforce 中受管理物件的 Username 屬性被填入了連結Microsoft Entra物件的 userPrincipalName 值。
注意
清除 [建立] 並不會影響現有使用者。 如果未選取 [建立],就無法建立新的使用者。
選擇現有的屬性對應,以開啟編輯屬性畫面。 在這裡你可以編輯 Microsoft Entra ID 與目標應用程式之間流動的使用者屬性。
了解屬性對應類型
透過屬性映射,你可以控制屬性在非 Microsoft SaaS 應用程式中的填充方式。 支援的對應類型有四種不同:
- Direct – 目標屬性會被賦予 Microsoft Entra ID 中所連結物件的屬性值。
- 常數 - 目標屬性會填入您所指定的特定字串。
- 運算式 - 目標屬性會根據類似指令碼的運算式結果填入。 欲了解更多關於表達式的資訊,請參閱Microsoft Entra ID 中的屬性對應撰寫表達式。
- 無 - 目標屬性保留未修改。 不過,如果目標屬性是空的,則會填入您所指定的預設值。
除了這四個基本類型以外,自訂屬性對應還支援選擇性的預設值指派的概念。 預設值指派確保如果 Microsoft Entra ID 或目標物件中沒有值,目標屬性會被填入該值。 最常見的設定是將其保留空白。 欲了解更多關於映射屬性的資訊,請參閱 應用程式配置如何在 Microsoft Entra ID 中運作。
了解屬性對應特性
在前一節中,您已經接觸到屬性映射類型屬性。 除了這個屬性之外,屬性映射也支援下列屬性:
- Source 屬性 - 來自來源系統的使用者屬性(例如: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 中的比對優先順序)。 例如,若將三個屬性定義為比對屬性,而且在評估前兩個屬性之後即找出唯一相符的使用者,則服務將不會評估第三個屬性。 服務會依指定的順序來評估比對屬性,並在找到相符項目時停止評估。
- 來源和目標中的值不需要完全相符:目標中的值可以是來源中值的函數。 因此,若在來源中具有 emailAddress 屬性,在目標中具有 userPrincipalName,將可使用 emailAddress 屬性的函式 (以某個常數值取代部分字元) 來進行比對。
- 不支援根據屬性組合進行比對:大部分的應用程式都不支援根據兩個屬性進行查詢。 因此,無法根據屬性的組合進行比對。 您可以逐一評估單一屬性。
- 所有使用者都必須至少有一個比對屬性的值: 如果您定義一個比對屬性,則所有使用者在來源系統中都必須有該屬性的值。 例如,若將 userPrincipalName 定義為比對屬性,則所有使用者都必須具有 userPrincipalName。 如果您定義多個比對屬性 (例如,extensionAttribute1 和 mail),則並非所有使用者都必須具有相同的比對屬性。 某個使用者可能具有 extensionAttribute1,但沒有 mail;而另一個使用者則可能具有 mail,但沒有 extensionAttribute1。
- 目標應用程式必須支援比對屬性的篩選:應用程式開發人員可以在其使用者或群組 API 上篩選屬性子集。 在展示館中的應用程式,我們確保預設屬性映射是目標應用程式的 API 所支援的篩選屬性。 在變更目標應用程式的預設匹配屬性時,請確認非 Microsoft 的 API 文檔,以確保該屬性可以被過濾。
編輯群組屬性映射
特定應用程式 (例如 ServiceNow、Box 和 G Suite) 支援佈建群組和使用者物件的能力。 除了群組成員以外,群組物件也可包含群組屬性,例如顯示名稱和電子郵件別名。
佈建群組可以選擇性地啟用或停用,方法是在 [對應] 下選取群組對應,然後在 [屬性對應] 畫面中將您所需的選項設定為 [啟用]。
佈建為群組物件一部分的屬性,可依照與使用者物件相同的方式進行自訂,如前所述。
提示
佈建群組物件 (屬性和成員) 與將群組指派給應用程式是不同的概念。 您可以將群組指派給應用程式,但只能佈建群組中所包含的使用者物件。 要在指派中使用群組,並不需要設定整個群組的物件。
編輯支援的屬性清單
系統會預先設定支援指定應用程式的使用者屬性。 大部分應用程式的使用者管理 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 圖形 API預設屬性 支援自訂目錄擴充功能)。 欲了解更多關於建立擴充屬性的資訊,請參閱
Syncing extension attributes for Microsoft Entra Application Provisioning 以及 Microsoft Entra ID 供應的已知問題Known issues for provisioning in Microsoft Entra ID - 支援跨網域身分識別系統 (SCIM) 2.0 的應用程式
- Microsoft Entra ID 支援將 XPATH 和 JSONPath 元資料寫回至 Workday 或 SuccessFactors。 Microsoft Entra ID 不支援預設架構中未包含的新 Workday 或 SuccessFactor 屬性
注意
對於已自訂應用程式和系統模式,且對自訂屬性定義有深入了解的管理員,或者在 Microsoft Entra 管理中心介面中沒有自動顯示原始屬性的情況下,建議只有這些管理員編輯支援屬性的列表。 有時,這會需要熟悉應用程式或系統所提供的 API 和開發人員工具。 預設會鎖定支援屬性清單的編輯功能,但客戶可以瀏覽至下列 URL 來啟用此功能:https://portal.azure.com/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true 。 接著,您可以導覽至您的應用程式來檢視屬性清單。
注意
當 Microsoft Entra ID 中的目錄擴充屬性沒有自動出現在屬性映射下拉選單時,你可以手動將它加入「Microsoft Entra 屬性清單」。 在手動為你的配置應用程式新增 Microsoft Entra 目錄擴充屬性時,請注意目錄擴充功能屬性名稱會區分大小寫。 例如:如果您有名為 extension_53c9e2c0exxxxxxxxxxxxxxxx_acmeCostCenter 的目錄擴充屬性,請務必以目錄中定義的相同格式輸入。 不支援佈建多重值目錄擴充屬性。
要編輯所支援屬性的清單時,系統會提供下列屬性:
- 名稱 - 屬性的系統名稱,如目標物件的結構描述所定義。
-
類型:屬性所儲存的資料類型 (如目標物件的結構描述所定義),可以是下列其中一種類型。
- 二進位 - 屬性包含二進位資料。
- 布林值 - 屬性包含 True 或 False 值。
- 日期時間 - 屬性包含日期字串。
- 整數 - 屬性包含整數。
- 參考 - 屬性包含對目標應用程式中的另一個資料表所儲存的值進行參考的識別碼。
- 字串 - 屬性包含文字字串。
- 主鍵? - 屬性是否定義為目標物件結構描述中的主索引鍵欄位。
- 是必要的嗎? - 屬性是否必須填入目標應用程式或系統中。
- 多個值? - 屬性是否支援多個值。
- 大小寫完全相符? - 是否以區分大小寫的方式評估屬性值。
- API 運算式 - 請勿使用,除非特定佈建連接器(例如 Workday)的文件中另有指示。
-
參考的物件屬性 - 如果這是參考類型屬性,則此功能表可讓您在目標應用程式中選取包含屬性相關值的資料表和屬性。 例如,若有名為 "Department" 的屬性,而且其儲存值參照個別 "Departments" 資料表中的物件,則您將會選取
Departments.Name。 該應用程式支援的參考表和主要 ID 欄位是預先設定好的,無法使用 Microsoft Entra 系統管理中心 編輯。 不過,你可以用 Microsoft 圖形 API 來編輯。
將自訂延伸模組屬性佈建至符合 SCIM 規範的應用程式
SCIM 要求建議 (RFC) 會定義核心使用者和群組結構描述,同時也允許擴充結構描述,以符合您應用程式的需求。 若要將自訂屬性新增至 SCIM 應用程式:
請瀏覽至 Entra ID 的 企業應用程式。
選取您的應用程式,然後選取 [佈建]。
在 [對應] 底下,選取要新增自訂屬性的物件 (使用者或群組)。
在頁面底部,選取 [顯示進階選項]。
選取 [編輯 AppName 的屬性清單]。
注意
如果應用程式名稱的屬性清單編輯選項沒有出現,請使用網址
https://portal.azure.com/?Microsoft_AAD_Connect_Provisioning_forceSchemaEditorEnabled=true以開啟架構編輯器。在屬性清單的底部,將自訂屬性的相關資訊輸入到提供的欄位中。 然後,選取 [新增屬性]。
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/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}
}
將角色佈建至 SCIM 應用程式
使用範例中的步驟,以將使用者的應用程式角色佈建至您的應用程式。 描述僅適用於自訂 SCIM 應用程式。 若為畫廊應用程式(例如 Salesforce 和 ServiceNow),請使用預先定義的角色對應。 項目符號說明如何將 AppRoleAssignments 屬性轉換為您應用程式預期的格式。
- 在 Microsoft Entra ID 中將 appRoleAssignment 映射到應用程式中的角色,需要使用 expression 來轉換該屬性。 appRoleAssignment 屬性不應直接對應至角色屬性,除非使用運算式進行角色詳細資料的剖析。
注意
從企業應用程式佈建角色時,SCIM 標準會以不同的方式定義企業使用者角色屬性。 欲了解更多資訊,請參閱
SingleAppRoleAssignment
使用時機:使用 SingleAppRoleAssignment 運算式為使用者佈建單一角色,並指定主要角色。
如何設定:使用所述步驟,以導覽至 [屬性對應] 頁面,並使用 SingleAppRoleAssignment 運算式對應至 roles 屬性。 有三個角色屬性可供選擇 (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)
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"Operations": [
{
"op": "Add",
"path": "roles",
"value": [
{
"value": "{\"id\":\"06b07648-ecfe-589f-9d2f-6325724a46ee\",\"value\":\"25\",\"displayName\":\"Role1234\"}"
}
]
}
]
}
PATCH 和 POST 中的要求格式不同。 若要確保 POST 和 PATCH 以相同格式傳送,您可以使用這裡所述的功能旗標。
AppRoleAssignmentsComplex
使用時機:使用 AppRoleAssignmentsComplex 運算式為使用者佈建多個角色。
如何設定:如所述來編輯所支援屬性的清單,以包括角色的新屬性:
然後,使用 AppRoleAssignmentsComplex 運算式對應至自訂角色屬性,如圖所示:
考量的事項
- 所有角色都被設定為 primary = false。
- SCIM 角色中不需要
id屬性。 請改用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)
{
"schemas": [
"urn:ietf:params:scim:api:messages:2.0:PatchOp"
],
"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 取代功能。 對於支援多個角色的 SCIM 應用程式,這確保在 Microsoft Entra ID 中移除的角色也會在目標應用程式中被移除。 替換功能也會移除使用者未反映在 Entra ID 中的任何額外角色
AppRoleAssignmentsComplex 和 AssertiveAppRoleAssignmentsComplex 之間的區別在於補丁調用的模式和對目標系統的影響。 前者只會執行 PATCH 新增操作,因此不會移除目標上的任何現有角色。 後者會進行 PATCH 替換操作,如果目標系統中的角色尚未在 Entra ID 上指派給使用者,則會將其移除。
如何設定:如所述來編輯所支援屬性的清單,以包括角色的新屬性:
然後,使用 AssertiveAppRoleAssignmentsComplex 運算式對應至自訂角色屬性,如圖中所示:
考量的事項
- 所有角色都會佈建為 primary = false。
- SCIM 角色中不需要
id屬性。 請改用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 和 emails) 是多重值屬性,您需要指定不同類型的電話號碼或電子郵件。 請使用表達式來處理多重值屬性。 它允許你指定屬性類型,並將其映射到對應的 Microsoft Entra 使用者屬性以獲取相應的值。
phoneNumbers[type eq "work"].valuephoneNumbers[type eq "mobile"].valuephoneNumbers[type eq "fax"].value
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"phoneNumbers": [
{
"value": "555-555-5555",
"type": "work"
},
{
"value": "555-555-5555",
"type": "mobile"
},
{
"value": "555-555-5555",
"type": "fax"
}
]
}
還原預設屬性和屬性對應
如果您要重新開始,並將現有的對應重設為其預設狀態,您可以選取 [還原預設對應] 核取方塊,並儲存設定。 這樣做會讓所有映射和範圍過濾器設定得就像該應用程式從應用程式庫新增到 Microsoft Entra 租戶一樣。
選取此選項,會在佈建服務執行時強制重新同步所有使用者。
重要
強烈建議先將 [佈建狀態] 設為 [關閉],再叫用此選項。
您應該知道的事情
- Microsoft Entra ID 提供了高效的同步流程實作。 在初始化環境中,同步處理期間只會處理需要更新的物件。
- 更新屬性對應設定會影響同步處理周期的效能。 更新屬性對應組態需要重新評估所有受控物件。
- 建議的一個最佳做法是將您屬性對應的連續更改次數減至最少。
- 目前不支援新增要佈建至應用程式的相片屬性,因為您無法指定同步處理相片的格式。 您可以在 User Voice 上要求此功能。
- 該屬性
IsSoftDeleted通常是應用程式預設映射的一部分,在以下四種情況之一中可能為 true:- 由於使用者已被取消應用程式分配,因此不在適用範圍內。
- 由於未滿足範圍設定條件,使用者未在範圍內。
- 使用者在 Microsoft Entra ID 中被軟刪除。
- 該屬性
AccountEnabled對用戶設置為 false。 請嘗試將IsSoftDeleted屬性保留在屬性對應中。
- Microsoft Entra 的配置服務不支援配置空值。
- 其主鍵 (通常是
ID) 不應該包括為屬性對應中的目標屬性。 - 角色屬性通常需要使用運算式來對應,而不是直接對應。 若想了解更多角色映射的相關資訊,請參閱將角色佈建至 SCIM 應用程式。
- 雖然您可以從對應中停用群組,但不支援停用使用者。