同步處理 Microsoft Entra 應用程式佈建的擴充屬性

發行項
04/10/2024

將使用者帳戶從 Microsoft Entra ID 佈建到 SaaS 應用程式或內部部署應用程式時，Microsoft Entra ID 必須包含建立使用者配置檔所需的所有數據（屬性）。自定義使用者布建的屬性對應時，您可能會發現您想要對應的屬性不會出現在 Microsoft Entra ID 的 [來源屬性 ] 清單中。本文說明如何新增遺漏的屬性。

判斷需要新增延伸模組的位置

新增應用程式所需的遺漏屬性將會在內部部署的 Active Directory 或 Microsoft Entra 標識符中開始，視用戶帳戶所在的位置及其帶入 Microsoft Entra ID 的方式而定。

首先，識別 Microsoft Entra 租使用者中的哪些使用者需要應用程式存取權，因此將會在布建至應用程式的範圍內。

接下來，判斷屬性的來源，以及這些使用者如何帶入 Microsoft Entra ID 的拓撲。

屬性的來源	拓撲	所需的步驟
HR 系統	HR 系統的背景工作角色會以使用者身分佈建到 Microsoft Entra ID 中。	在 Microsoft Entra ID 中建立擴充屬性。更新 HR 輸入對應，以從 HR 系統填入 Microsoft Entra ID 使用者的擴充屬性。
HR 系統	HR 系統的背景工作角色會以使用者身分佈建到 Windows Server AD 中。 Microsoft Entra 連線雲端同步處理會將它們同步處理到 Microsoft Entra 識別符。	如有必要，請擴充 AD 架構。使用雲端同步在 Microsoft Entra ID 中建立擴充屬性。更新 HR 輸入對應，以從 HR 系統填入 AD 用戶的擴充屬性。
HR 系統	HR 系統的背景工作角色會以使用者身分佈建到 Windows Server AD 中。 Microsoft Entra 連線將它們同步處理至 Microsoft Entra 識別符。	如有必要，請擴充 AD 架構。使用 Microsoft Entra 連線，在 Microsoft Entra 識別碼中建立擴充屬性。更新 HR 輸入對應，以從 HR 系統填入 AD 用戶的擴充屬性。

如果您的組織用戶已經在內部部署的 Active Directory 中，或是在 Active Directory 中建立使用者，則必須將使用者從 Active Directory 同步至 Microsoft Entra ID。您可以使用 Microsoft Entra 連線或 Microsoft Entra 連線雲端同步來同步使用者和屬性。

請洽詢內部部署的 Active Directory 網域系統管理員，這些屬性是否為AD DS架構User物件類別的一部分，如果不是，請在這些使用者擁有帳戶的網域中擴充 Active Directory 網域服務架構。
設定 Microsoft Entra 連線或 Microsoft Entra 連線雲端同步，以將使用者與其擴充屬性從 Active Directory 同步處理至 Microsoft Entra ID。這兩個解決方案都會自動將特定屬性同步處理至 Microsoft Entra ID，但並非所有屬性。此外，某些預設同步處理的屬性（例如 sAMAccountName）可能不會使用圖形 API 公開。在這些情況下，您可以使用 Microsoft Entra 連線目錄擴充功能，將屬性同步處理至 Microsoft Entra 識別符，或使用 Microsoft Entra 連線雲端同步處理。如此一來，圖形 API 和 Microsoft Entra 布建服務就會看到屬性。
如果內部部署的 Active Directory 中的使用者還沒有必要的屬性，您必須更新 Active Directory 中的使用者。透過從 Workday、SAP SuccessFactors 讀取屬性，或使用輸入 HR API 使用不同的 HR 系統，即可完成此更新。
等候 Microsoft Entra 連線或 Microsoft Entra 連線雲端同步處理，將您在 Active Directory 架構中所做的更新和 Active Directory 使用者同步處理到 Microsoft Entra ID。

或者，如果不需要存取應用程式的使用者都源自內部部署的 Active Directory，則必須先使用 PowerShell 或 Microsoft Entra ID 中的 Microsoft Graph 建立架構延伸模組，再設定布建至您的應用程式。

下列各節概述如何為僅限雲端使用者的租使用者，以及具有 Active Directory 使用者的租使用者建立擴充屬性。

在僅限雲端使用者的租使用者中建立擴充屬性

您可以使用 Microsoft Graph 和 PowerShell 來擴充 Microsoft Entra 識別符中使用者的用戶架構。如果您有需要該屬性的使用者，且沒有任何使用者源自或從內部部署的 Active Directory 同步處理，則這是必要的。（如果您有 Active Directory，請繼續閱讀下一節中關於如何使用 Microsoft Entra 連線目錄擴充功能將屬性同步處理至 Microsoft Entra ID。

建立架構延伸模組之後，當您下次流覽 Microsoft Entra 系統管理中心的布建頁面時，就會自動探索這些延伸模組屬性，在大部分情況下。

當您有超過 1,000 個服務主體時，您可能會在來源屬性清單中發現遺漏擴充功能。如果您建立的屬性未自動出現，請確認屬性已建立，並手動新增至您的架構。若要確認已建立它，請使用 Microsoft Graph 和 Graph 總管。若要手動將它新增至您的架構，請參閱編輯支援的屬性清單。

使用 Microsoft Graph 建立僅限雲端用戶的擴充屬性

您可以使用 Microsoft Graph 擴充 Microsoft Entra 使用者的架構。

首先，列出租使用者中的應用程式，以取得您正在處理之應用程式的標識碼。若要深入瞭解，請參閱列出 extensionProperties。

GET https://graph.microsoft.com/v1.0/applications

接下來，建立擴充屬性。將下方的 ID 屬性取代為 在上一個步驟中擷取的標識碼 。您必須使用 「ID」 屬性，而不是「appId」。若要深入瞭解，請參閱 [建立擴充功能Property]/graph/api/application-post-extensionproperty）。

POST https://graph.microsoft.com/v1.0/applications/{id}/extensionProperties
Content-type: application/json

{
    "name": "extensionName",
    "dataType": "string",
    "targetObjects": [
      "User"
    ]
}

先前的要求已建立格式 extension_appID_extensionName為的擴充屬性。您現在可以使用此擴充屬性來更新使用者。若要深入瞭解，請參閱更新使用者。

PATCH https://graph.microsoft.com/v1.0/users/{id}
Content-type: application/json

{
  "extension_inputAppId_extensionName": "extensionValue"
}

最後，確認用戶的屬性。若要深入瞭解，請參閱取得使用者。 Graph v1.0 預設不會傳回任何使用者的目錄擴充屬性，除非要求中指定屬性做為要傳回的屬性之一。

GET https://graph.microsoft.com/v1.0/users/{id}?$select=displayName,extension_inputAppId_extensionName

使用 PowerShell 建立僅限雲端用戶的擴充屬性

您可以使用 PowerShell 建立自訂擴充功能。

注意

自 2024 年 3 月 30 日起，Azure AD 和 MSOnline PowerShell 模組已被取代。若要深入瞭解，請閱讀淘汰更新。在此日期之後，這些模組的支援僅限於 Microsoft Graph PowerShell SDK 和安全性修正的移轉協助。已淘汰的模組將繼續在 2025 年 3 月 30 日運作。

建議您移轉至 Microsoft Graph PowerShell ，以與 Microsoft Entra ID （先前稱為 Azure AD）互動。如需常見的移轉問題，請參閱移轉常見問題。 注意： MSOnline 1.0.x 版可能會在 2024 年 6 月 30 日之後發生中斷。

#Connect to your Azure AD tenant
Connect-AzureAD

#Create an application (you can instead use an existing application if you would like)
$App = New-AzureADApplication -DisplayName “test app name” -IdentifierUris https://testapp

#Create a service principal
New-AzureADServicePrincipal -AppId $App.AppId

#Create an extension property
New-AzureADApplicationExtensionProperty -ObjectId $App.ObjectId -Name “TestAttributeName” -DataType “String” -TargetObjects “User”

您可以選擇性地測試是否可以在僅限雲端用戶上設定擴充屬性。

#List users in your tenant to determine the objectid for your user
Get-AzureADUser

#Set a value for the extension property on the user. Replace the objectid with the ID of the user and the extension name with the value from the previous step
Set-AzureADUserExtension -objectid 0ccf8df6-62f1-4175-9e55-73da9e742690 -ExtensionName “extension_6552753978624005a48638a778921fan3_TestAttributeName”

#Verify that the attribute was added correctly.
Get-AzureADUser -ObjectId 0ccf8df6-62f1-4175-9e55-73da9e742690 | Select -ExpandProperty ExtensionProperty

使用雲端同步建立擴充屬性

如果您有 Active Directory 中的使用者，且正在使用 Microsoft Entra 連線雲端同步處理，當您移至新增對應時，雲端同步會自動在內部部署的 Active Directory 中探索您的延伸模組。如果您使用 Microsoft Entra 連線同步處理，請繼續閱讀下一節使用 Microsoft Entra 連線建立擴充屬性。

使用下列步驟來自動探索這些屬性，並設定對應至 Microsoft Entra ID 的對應。

以至少混合式身分識別管理員 istrator 身分登入 Microsoft Entra 系統管理中心。
流覽至身分>識別混合式管理>Microsoft Entra 連線> Cloud 同步處理。
選取您想要新增擴充屬性和對應的組態。
在 [管理屬性] 下，選取 [按兩下以編輯對應]。
選取 [ 新增屬性對應]。系統會自動探索屬性。
新的屬性可在 [來源屬性] 下的下拉式清單中取得。
填入您想要的對應類型，然後選取 [ 套用]。

如需詳細資訊，請參閱 Microsoft Entra 連線雲端同步中的自定義屬性對應。

使用 Microsoft Entra 連線建立擴充屬性

如果存取應用程式的使用者源自內部部署的 Active Directory，則必須將屬性與 Active Directory 中的使用者同步處理至 Microsoft Entra ID。如果您使用 Microsoft Entra 連線，您必須先執行下列工作，才能設定布建至您的應用程式。

請洽詢內部部署的 Active Directory 網域系統管理員，這些屬性是否為AD DS架構User物件類別的一部分，如果不是，請在這些使用者擁有帳戶的網域中擴充 Active Directory 網域服務架構。
開啟 Microsoft Entra 連線精靈，選擇 [工作]，然後選擇 [自定義同步處理選項]。
以全域管理員 istrator 身分登入。
在 [選擇性功能] 頁面上，選取 [目錄擴充功能屬性同步]。
選取您想要擴充至 Microsoft Entra 識別碼的屬性。

注意

[可用屬性] 底下的搜尋會區分大小寫。
完成 Microsoft Entra 連線精靈，並允許執行完整的同步處理週期。當迴圈完成時，架構會擴充，且內部部署AD與 Microsoft Entra ID 之間會同步處理新的值。

注意

目前不支援從內部部署 AD 布建參考屬性的功能，例如 managedby 或 DN/DistinguishedName。您可以在 User Voice 上要求此功能。

填入並使用新屬性

在 Microsoft Entra 系統管理中心，當您編輯單一登錄的使用者屬性對應，或從 Microsoft Entra ID 佈建至應用程式時，Source 屬性列表現在會以格式<attributename> (extension_<appID>_<attributename>)包含新增的屬性，其中 appID 是租用戶中佔位符應用程式的標識符。選取屬性，並將其對應至目標應用程式以進行布建。

Microsoft Entra 連線精靈目錄延伸模組選取頁面

然後，您必須在啟用布建至應用程式之前，先將指派給應用程式的使用者填入必要的屬性。如果屬性不是源自 Active Directory，則有五種方式可大量填入使用者：

如果屬性源自 HR 系統，而且您要以 Active Directory 中的使用者身分從該 HR 系統布建背景工作角色，則請使用輸入 HR API 與 Active Directory 屬性，設定從 Workday、SAP SuccessFactors 或如果您使用不同 HR 系統的對應。然後，等候 Microsoft Entra 連線或 Microsoft Entra 連線雲端同步，將您在 Active Directory 架構中所做的更新和 Active Directory 使用者同步處理到 Microsoft Entra ID。
如果屬性源自 HR 系統，而且您不是使用 Active Directory，您可以透過輸入 API，設定從 Workday、SAP SuccessFactors 或其他項目的對應至 Microsoft Entra 使用者屬性。
如果屬性源自另一個內部部署系統，您可以設定 MICROSOFT Graph 的 MIM 連線 or 來建立或更新 Microsoft Entra 使用者。
如果屬性源自使用者本身，則您可以要求使用者在要求存取應用程式時提供屬性值，方法是在權利管理目錄中包含屬性需求。
針對所有其他情況，自定義應用程式可以透過 Microsoft Graph API 更新使用者。

下一步

定義布建範圍中的人員