設定選擇性宣告

發行項
06/14/2024

Microsoft Entra 傳回的令牌會保持較小，以確保要求這些令牌的客戶端達到最佳效能。因此，根據預設，令牌中不再存在數個宣告，而且必須依個別應用程式特別要求。

您可以透過 Microsoft Entra 系統管理中心的應用程式 UI 或指令清單，為您的應用程式設定選擇性宣告：

以至少雲端應用程式系統管理員的身分登入 Microsoft Entra 系統管理中心。
流覽至 [身分>識別應用程式> 應用程式註冊]。
選擇您要根據案例和所需結果設定選擇性宣告的應用程式。

繼續進行應用程式UI
繼續進行指令清單

在 [管理] 底下，選取 [令牌組態]。
選取 [ 新增選擇性宣告]。
選取您想要設定的令牌類型，例如 Access。
選取要新增的選擇性宣告。
選取 [新增]。

在 [管理] 底下，選取 [指令清單]。 Web 型指令清單編輯器隨即開啟，可讓您編輯指令清單。您可以選擇性地選取 [ 下載並編輯本機指令清單]，然後使用 [上傳 ] 將它重新套用至您的應用程式。如果檔案不包含 optionalClaims 屬性，您可以新增它。

下列應用程式指令清單專案會將 auth_time、 ipaddr和 upn 選擇性宣告新增至標識碼、存取和 SAML 令牌。

"optionalClaims": {
    "idToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "accessToken": [
        {
            "name": "ipaddr",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "upn",
            "essential": false
        },
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": false
        }
    ]
}

完成後，請選取儲存。現在，指定的選擇性宣告會包含在應用程式的令牌中。

物件 optionalClaims 會宣告應用程式要求的選擇性宣告。應用程式可以設定在標識碼令牌、存取令牌和 SAML 2 令牌中傳回的選擇性宣告。應用程式可以設定一組不同的選擇性宣告，以在每個令牌類型中傳回。

名稱	類型	描述
`idToken`	集合	JWT 識別碼令牌中傳回的選擇性宣告。
`accessToken`	集合	JWT 存取令牌中傳回的選擇性宣告。
`saml2Token`	集合	SAML 令牌中傳回的選擇性宣告。

如果特定宣告支援，您也可以使用 additionalProperties 字段來修改選擇性宣告的行為。

名稱	類型	描述
`name`	Edm.String	選擇性宣告的名稱。
`source`	Edm.String	宣告的來源（目錄物件）。延伸模組屬性中有預先定義的宣告和用戶定義宣告。如果來源值為 null，則宣告是預先定義的選擇性宣告。如果來源值是user，name屬性中的值就是用戶對象的擴充屬性。
`essential`	Edm.Boolean	如果值為 true，用戶端所指定的宣告是必要的，以確保使用者要求之特定工作的順利授權體驗。預設值為 false。
`additionalProperties`	集合（Edm.String）	宣告的其他屬性。如果這個集合中有屬性，它會修改 name 屬性中指定的選擇性宣告行為。

設定目錄延伸模組選擇性宣告

除了標準選擇性宣告集之外，您也可以設定令牌以包含 Microsoft Graph 延伸模組。如需詳細資訊，請參閱使用延伸模組將自定義數據新增至資源。

重要

存取令牌一律會使用資源的指令清單產生，而不是用戶端。在要求 ...scope=https://graph.microsoft.com/user.read...中，資源是Microsoft圖形 API。存取令牌是使用 Microsoft Graph API 指令清單來建立，而不是用戶端的指令清單。變更應用程式的指令清單永遠不會讓Microsoft圖形 API 的令牌看起來不同。若要驗證變更 accessToken 是否有效，請為您的應用程式要求令牌，而不是另一個應用程式。

選擇性宣告支援擴充屬性和目錄延伸模組。這項功能適用於附加應用程式可以使用的更多用戶資訊。例如，用戶已設定的其他標識碼或重要組態選項。如果您的應用程式指令清單要求自定義擴充功能和 MSA 使用者登入您的應用程式，則不會傳回這些延伸模組。

目錄延伸模組格式設定

使用應用程式指令清單設定目錄延伸模組選擇性宣告時，請使用擴充功能的完整名稱（格式為： extension_<appid>_<attributename>。 <appid>是要求宣告之應用程式的 appId（或用戶端識別碼）的移除版本。

在 JWT 內，這些宣告會以下列名稱格式發出： extn.<attributename>。在 SAML 令牌中，這些宣告會以下列 URI 格式發出： http://schemas.microsoft.com/identity/claims/extn.<attributename>

設定群組選擇性宣告

提示

本文中的步驟可能會根據您從開始的入口網站稍有不同。

本節涵蓋選擇性宣告下的組態選項，以將群組宣告中使用的群組屬性從預設群組 objectID 變更為從內部部署 Windows Active Directory 同步處理的屬性。您可以透過 Azure 入口網站或應用程式指令清單來設定應用程式的群組選擇性宣告。群組選擇性宣告只會在 JWT 中針對用戶主體發出。服務主體不會包含在 JWT 中發出的群組選擇性宣告中。

重要

權杖中所發出的群組數目限制為 150 (適用於 SAML 判斷提示) 和 200 (適用於 JWT，包括巢狀群組)。如需群組限制和來自內部部署屬性之群組宣告的重要注意事項的詳細資訊，請參閱設定應用程式的群組宣告。

完成下列步驟，以使用 Azure 入口網站設定群組選擇性宣告：

選取您要設定選擇性宣告的應用程式。
在 [管理] 底下，選取 [令牌組態]。
選取 [ 新增群組宣告]。
選取要傳回的群組類型（安全組或目錄角色、所有群組和/或指派給應用程式的群組）：
- 指派給應用程式選項的群組只包含指派給應用程式的群組。 由於令牌中的群組數目限制，建議針對大型組織使用指派給應用程式選項的群組。若要變更指派給應用程式的群組，請從 [企業應用程式] 清單中選取應用程式 。選取 [使用者和群組]，然後選取 [新增使用者/群組]。從[使用者和群組] 選取您要新增至應用程式的群組。
- [ 所有群組] 選項包括 SecurityGroup、 DirectoryRole 和 DistributionList，但不包括 指派給應用程式的群組。
選擇性：選取特定的令牌類型屬性，以修改群組宣告值以包含內部部署群組屬性，或將宣告類型變更為角色。
選取 [儲存]。

完成下列步驟，以透過應用程式指令清單設定群組選擇性宣告：

選取您要設定選擇性宣告的應用程式。
在 [管理] 底下，選取 [指令清單]。
使用指令清單編輯器新增下列專案：

有效值為：
- “All” （此選項包括 SecurityGroup、DirectoryRole 和 DistributionList）
- “SecurityGroup”
- “DirectoryRole”
- “ApplicationGroup” （此選項僅包含指派給應用程式的群組）
例如：
```
"groupMembershipClaims": "SecurityGroup"
```
根據預設，群組對象標識碼會在群組宣告值中發出。若要修改宣告值以包含內部部署群組屬性，或將宣告類型變更為角色，請使用 optionalClaims 組態，如下所示：

設定組名組態選擇性宣告。

如果您想要令牌中的群組在選擇性宣告區段中包含內部部署群組屬性，請指定應套用哪些令牌類型選擇性宣告。您也可以指定要求的選擇性宣告名稱，以及所需的任何其他屬性。

可以列出多個權杖型態：

idToken 用於 OIDC 識別碼令牌
accessToken 適用於 OAuth 存取令牌
Saml2Token 適用於 SAML 令牌。

此 Saml2Token 類型同時適用於 SAML1.1 和 SAML2.0 格式令牌。

針對每個相關的令牌類型，修改群組宣告以使用 optionalClaims 指令清單中的區段。架構 optionalClaims 如下所示：

{
    "name": "groups",
    "source": null,
    "essential": false,
    "additionalProperties": []
}

選擇性宣告架構	值
`name`	必須是 `groups`
`source`	未使用。省略或指定 Null。
`essential`	未使用。省略或指定 false。
`additionalProperties`	其他屬性的清單。有效的選項為`sam_account_name`、`dns_domain_and_sam_account_name`、 `netbios_domain_and_sam_account_nameemit_as_roles` 和 `cloud_displayname`。

在中additionalProperties，只需要其中dns_domain_and_sam_account_namesam_account_namenetbios_domain_and_sam_account_name一個。如果有一個以上，則會使用第一個，並忽略任何其他專案。您也可以新增 cloud_displayname 以發出雲端群組的顯示名稱。只有在設定為 ApplicationGroup時才groupMembershipClaims適用此選項。

某些應用程式需要角色宣告中用戶的相關群組資訊。若要將宣告類型從群組宣告變更為角色宣告，請將新增 emit_as_roles 至 additionalProperties。群組值會在角色宣告中發出。

如果使用 emit_as_roles ，則設定使用者的任何應用程式角色不在角色宣告中。

下列範例顯示群組宣告的指令清單組態：

以 OAuth 存取令牌 dnsDomainName\sAMAccountName 的格式發出群組作為組名。

"optionalClaims": {
    "accessToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "dns_domain_and_sam_account_name"
            ]
        }
    ]
}

發出要以格式傳回 netbiosDomain\sAMAccountName 的組名作為 SAML 和 OIDC 識別碼令牌中的角色宣告。

"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "netbios_domain_and_sam_account_name",
                "emit_as_roles"
            ]
        }
    ]
}

針對內部部署同步群組發出組名， sam_account_name 並在 cloud_display SAML 和 OIDC 標識元令牌中針對指派給應用程式的群組發出組名。

"groupMembershipClaims": "ApplicationGroup",
"optionalClaims": {
    "saml2Token": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ],
    "idToken": [
        {
            "name": "groups",
            "additionalProperties": [
                "sam_account_name",
                "cloud_displayname"
            ]
        }
    ]
}

選擇性宣告範例

有多個選項可用來更新應用程式身分識別組態上的屬性，以啟用和設定選擇性宣告：

您可以使用 Azure 入口網站
您可以使用指令清單。
您也可以撰寫使用 Microsoft Graph API 更新應用程式的應用程式。 Microsoft Graph API 參考指南中的 OptionalClaims 類型可協助您設定選擇性宣告。

在下列範例中，會使用 Azure 入口網站和指令清單，將選擇性宣告新增至適用於您應用程式的存取、標識元和 SAML 令牌。不同的選擇性宣告會新增至應用程式可以接收的每個權杖類型：

標識元令牌包含完整窗體中同盟使用者的 UPN。<upn>_<homedomain>#EXT#@<resourcedomain>
其他用戶端要求此應用程式的存取令牌包含 auth_time 宣告。
SAML 令牌包含 skypeId 目錄架構延伸模組（在此範例中，此應用程式的應用程式識別碼為 ab603c56068041afb2f6832e2a17e237）。 SAML 令牌會將 Skype 識別子公開為 extension_ab603c56068041afb2f6832e2a17e237_skypeId。

在 Azure 入口網站中設定宣告：

選取您要設定選擇性宣告的應用程式。
在 [管理] 底下，選取 [令牌組態]。
選取 [新增選擇性宣告]、選取標識符令牌類型、從宣告清單中選取 upn，然後選取 [新增]。
選取 [新增選擇性宣告]、選取 [存取 令牌類型]、從宣告清單中選取 [auth_time ]，然後選取 [ 新增]。
從 [令牌設定概觀] 畫面中，選取 upn 旁的鉛筆圖示、選取 [外部驗證] 切換開關，然後選取 [儲存]。
選取 [新增選擇性宣告]、選取 SAML 令牌類型、從宣告清單中選取 extn.skypeID （僅適用於您已建立名為 skypeID 的 Microsoft Entra 使用者物件），然後選取 [ 新增]。

在指令清單中設定宣告：

選取您要設定選擇性宣告的應用程式。
在 [管理] 底下，選取 [指令清單] 以開啟內嵌指令清單編輯器。

您可以使用這個編輯器直接編輯指令清單。指令清單會遵循 Application 實體的架構，並在儲存後自動格式化指令清單。新元素會新增至 optionalClaims 屬性。

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "essential": false,
            "additionalProperties": [
                "include_externally_authenticated_upn"
            ]
        }
    ],
    "accessToken": [
        {
            "name": "auth_time",
            "essential": false
        }
    ],
    "saml2Token": [
        {
            "name": "extension_ab603c56068041afb2f6832e2a17e237_skypeId",
            "source": "user",
            "essential": true
        }
    ]
}

當您完成更新指令清單時，請選取 [ 儲存 ] 以儲存指令清單。

另請參閱

下一步

深入瞭解 Microsoft 身分識別平台中的令牌和宣告。

共用方式為