教學課程:在 Microsoft Entra ID 中自訂 SaaS 應用程式的使用者佈建屬性對應
Microsoft Entra ID 支援將使用者佈建至 Salesforce、G Suite 等這類非 Microsoft SaaS 應用程式。 若為非 Microsoft SaaS 應用程式啟用使用者佈建,則 Microsoft Entra 系統管理中心會透過屬性對應來控制其屬性值。
開始之前,請確定您熟悉應用程式管理和「單一登入 (SSO)」概念。 查看以下連結:
在 Microsoft Entra 使用者物件與每個 SaaS 應用程式的使用者物件之間,有一組預先設定的屬性和屬性對應。 有些應用程式除了使用者以外,還會管理其他類型的物件,例如群組。
您可以根據您的業務需求自訂預設的屬性對應。 因此,您可以變更或刪除現有的屬性對應,或建立新的屬性對應。
注意
除了透過 Microsoft Entra 介面來設定屬性對應之外,您還可以檢閱、下載和編輯結構描述的 JSON 表示法。
編輯使用者屬性對應
提示
根據您開始使用的入口網站,本文中的步驟可能略有不同。
請依照下列步驟存取使用者佈建的對應功能:
以至少應用程式系統管理員的身分登入 Microsoft Entra 系統管理中心。
瀏覽至 [身分識別] > [應用程式] > [企業應用程式]。
此時會顯示所有已設定的應用程式清單,包括已從資源庫新增的應用程式。
選取任何應用程式以載入其 [應用程式管理] 窗格,您可以在其中檢視報表及管理應用程式設定。
選取 [佈建],以管理所選應用程式的使用者帳戶佈建設定。
展開 [對應] 以檢視和編輯在 Microsoft Entra ID 與目標應用程式之間流動的使用者屬性。 如果目標應用程式可支援,則此區段可讓您選擇性地設定群組和使用者帳戶的佈建。
選取 [對應] 設定,以開啟相關的 [屬性對應] 畫面。 SaaS 應用程式需要特定屬性對應才能正常運作。 若為必要的屬性,[刪除] 功能就無法使用。
在此螢幕擷取畫面中,您可以看到 Salesforce 中受控物件的 Username 屬性已填入所連結 Microsoft Entra 物件的 userPrincipalName 值。
注意
清除 [建立] 並不會影響現有使用者。 如果未選取 [建立],就無法建立新的使用者。
選取現有的 [屬性對應],以開啟 [編輯屬性] 畫面。 在此處,您可以編輯在 Microsoft Entra ID 與目標應用程式之間流動的使用者屬性。
了解屬性對應類型
透過屬性對應,您可以控制如何在非 Microsoft SaaS 應用程式中填入屬性。 支援四種不同的對應類型:
- 直接 – 使用 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 中撰寫屬性對應運算式的參照。 - 使用此屬性比對物件 – 是否應將此對應用來唯一識別來源與目標系統之間的使用者。 用於 Microsoft Entra ID 中的
userPrincipalName
或 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 Graph API 預設屬性和自訂目錄擴充)。 如需建立擴充的詳細資訊,請參閱同步處理擴充屬性以進行 Microsoft Entra 應用程式佈建和Microsoft Entra ID 中佈建的已知問題
- 支援跨網域身分識別系統 (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
的目錄擴充屬性,請務必以目錄中定義的相同格式輸入。 不支援佈建多重值目錄擴充屬性。
要編輯所支援屬性的清單時,系統會提供下列屬性:
- 名稱 - 屬性的系統名稱,如目標物件的結構描述所定義。
- 類型:屬性所儲存的資料類型 (如目標物件的結構描述所定義),可以是下列其中一種類型。
- 二進位 - 屬性包含二進位資料。
- 布林值 - 屬性包含 True 或 False 值。
- 日期時間 - 屬性包含日期字串。
- 整數 - 屬性包含整數。
- 參考 - 屬性包含對目標應用程式中的另一個資料表所儲存的值進行參考的識別碼。
- 字串 - 屬性包含文字字串。
- 主索引鍵? - 屬性是否定義為目標物件結構描述中的主索引鍵欄位。
- 是必要的嗎? - 屬性是否必須填入目標應用程式或系統中。
- 多重值? - 屬性是否支援多個值。
- 大小寫完全相符? - 是否以區分大小寫的方式評估屬性值。
- API 運算式 - 不使用,除非特定佈建連接器 (例如 Workday) 的文件另有指示。
- 參考的物件屬性 - 如果這是參考類型屬性,則此功能表可讓您在目標應用程式中選取包含屬性相關值的資料表和屬性。 例如,若有名為 "Department" 的屬性,而且其儲存值參照個別 "Departments" 資料表中的物件,則您將會選取
Departments.Name
。 給定應用程式所支援的參考資料表和主要識別碼欄位會預先進行設定,而且無法使用 Microsoft Entra 系統管理中心進行編輯。 不過,您可以使用 Microsoft Graph API 來對其進行編輯。
將自訂延伸模組屬性佈建至符合 SCIM 規範的應用程式
SCIM 要求建議 (RFC) 會定義核心使用者和群組結構描述,同時也允許擴充結構描述,以符合您應用程式的需求。 若要將自訂屬性新增至 SCIM 應用程式:
- 以至少應用程式系統管理員的身分登入 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/00aa00aa-bb11-cc22-dd33-44ee44ee44ee"
}
}
將角色佈建至 SCIM 應用程式
使用範例中的步驟,以將使用者的應用程式角色佈建至您的應用程式。 描述僅適用於自訂 SCIM 應用程式。 若為資源庫應用程式 (例如 Salesforce 和 ServiceNow),請使用預先定義的角色對應。 項目符號說明如何將 AppRoleAssignments 屬性轉換為您應用程式預期的格式。
- 將 Microsoft Entra ID 中的 appRoleAssignment 對應至應用程式中的角色,需要您使用運算式來轉換屬性。 appRoleAssignment 屬性「不應該直接對應」至角色屬性,而未使用運算式來剖析角色詳細資料。
注意
從企業應用程式佈建角色時,SCIM 標準會以不同的方式定義企業使用者角色屬性。 如需詳細資訊,請參閱在 Microsoft Entra ID 中開發和規劃 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)
"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)
"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"].value
phoneNumbers[type eq "mobile"]
.valuephoneNumbers[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 提供有效的同步處理程序實作。 在初始化環境中,同步處理期間只會處理需要更新的物件。
- 更新屬性對應會影響同步處理期間的效能。 更新屬性對應組態需要重新評估所有受控物件。
- 建議您最好不要經常變更屬性對應。
- 目前不支援新增要佈建至應用程式的相片屬性,因為您無法指定同步處理相片的格式。 您可以在 User Voice 上要求此功能。
IsSoftDeleted
屬性通常是應用程式預設對應的一部分。 在四個案例中的其中一個案例中,IsSoftdeleted
可以是 true:1) 使用者因未從應用程式取消指派而超出範圍。 2) 使用者因不符合範圍篩選而超出範圍。 3) 在 Microsoft Entra ID 中,會虛刪除使用者。4)AccountEnabled
屬性在使用者上設定為 false。 請嘗試將IsSoftDeleted
屬性保留在屬性對應中。- Microsoft Entra 佈建服務不支援佈建 Null 值。
- 其主索引鍵 (通常是
ID
) 不應該包括為屬性對應中的目標屬性。 - 角色屬性通常需要使用運算式來對應,而不是直接對應。 如需角色對應的詳細資訊,請參閱將角色佈建至 SCIM 應用程式。
- 雖然您可以從對應中停用群組,但不支援停用使用者。