宣告中的目錄擴充屬性

目錄延伸屬性提供一種方式，將更多資料儲存在目錄物件上，例如使用者。 只有使用者物件上的延伸模組屬性可用來向應用程式發出宣告。 本文描述如何使用目錄延伸模組屬性，將使用者資料傳送至權杖宣告中的應用程式。

注意

Microsoft Graph 提供三個其他延伸模組機制來自訂 Graph 物件。 這些是延伸模組屬性 1-15、開放延伸模組和結構描述延伸模組。 如需詳細資料，請參閱 Microsoft Graph 文件。 使用開放和結構描述延伸模組儲存在 Microsoft Graph 物件上的資料，不會供權杖中的宣告作為來源使用。

目錄擴充屬性一律與租用戶中的應用程式相關聯。 目錄屬性的名稱會在其名稱中包含應用程式 appId。

目錄延伸模組屬性的識別碼格式為 extension_xxxxxxxxx_AttributeName。 其中 xxxxxxxxx 是定義延伸模組之應用程式的 appId，其中只有 0-9 和 A-Z 字元。

註冊和使用目錄延伸模組

以下列其中一種方式註冊目錄擴充屬性：

• 設定 Microsoft Entra Connect 建立這些屬性，並從內部部署將資料同步至屬性。 請參閱 Microsoft Entra Connect 同步：目錄擴充。
• 使用 Microsoft Graph 登錄、設定及讀取目錄延伸模組的值。 也可以使用 PowerShell Cmdlet。

從 Microsoft Entra Connect 發出具有資料宣告

使用 Microsoft Entra Connect 建立與同步的目錄延伸模組屬性，一律與 Microsoft Entra Connect 所用的應用程式識別碼建立關聯。 您可以將這些屬性設定為入口網站中企業應用程式設定中的宣告，以作為宣告的來源。 使用 AD Connect 建立目錄擴充屬性之後，就會顯示在 SAML SSO 宣告設定中。

使用 Graph 或 PowerShell 發出宣告

如果使用 Microsoft Graph 或 PowerShell 註冊目錄延伸模組屬性，則可以將應用程式設定為在使用者登入時接收該屬性中的資料。 應用程式可以設定為使用可在應用程式資訊清單中設定的選擇性宣告，在應用程式上註冊的目錄延伸模組中接收資料。

然後，租用戶應用程式可以註冊目錄擴充屬性以供自己使用。 將應用程式佈建到租用戶時，相關聯的目錄延伸模組會變成可供該租用戶中的使用者使用。 目錄延伸模組可用之後，可以使用 Microsoft Graph 來儲存和擷取資料。 目錄延伸模組也可以對應至 Microsoft 身分識別平台發出給應用程式的權杖中的宣告。

如果應用程式需要使用在其他應用程式上登錄的擴充屬性資料來傳送宣告，即必須使用宣告對應原則將擴充屬性對應至宣告。

管理目錄擴充屬性的常見模式是特別針對您需要的所有目錄擴充註冊應用程式。 當您使用此類型的應用程式時，所有擴充功能的名稱都具有相同的 appID。

例如，下列程式碼顯示宣告對應原則，從 OAuth/OIDC 權杖中的目錄擴充屬性發出單一宣告：

{
    "ClaimsMappingPolicy": {
        "Version": 1,
        "IncludeBasicClaimSet": "false",
        "ClaimsSchema": [{
                "Source": "User",
                "ExtensionID": "extension_xxxxxxx_test",
                "JWTClaimType": "http://schemas.contoso.com/identity/claims/exampleclaim"
            },
        ]
    }
}

其中 xxxxxxx 是註冊延伸模組所用應用程式的應用程式識別碼 (或用戶端識別碼)。

警告

當您為目錄擴充屬性定義宣告對應原則時，請使用 ExtensionID 屬性，而不是 ID 陣列主體內的 ClaimsSchema 屬性，如先前範例所示。

提示

在物件上設定目錄擴充屬性時，大小寫一致性相當重要。 在設定時，延伸模組屬性名稱不區分大小寫，但權杖服務從目錄讀取這些名稱時會區分大小寫。 如果在某個使用者物件上使用 "LegacyId" 名稱設定延伸模組屬性，又在另一個使用者物件上使用 "legacyid" 名稱，則當此屬性使用 "LegacyId" 名稱對應至宣告時，會成功擷取資料，並在第一位使用者的權杖中包含宣告，但第二位不包含。

下一步

• 了解如何為特定應用程式自訂在權杖中發出的宣告。