在標識元令牌、存取令牌和 SAML 令牌中設定和管理選擇性宣告

發行項
2025/01/27

Microsoft Entra 所傳回權杖的大小較小，以確保要求這些權杖的用戶端達到最佳效能。因此，權杖中預設不再有數個宣告，而且必須依據個別應用程式明確提出要求才會提供。

針對您的應用程式，您可以透過 Microsoft Entra 系統管理中心的應用程式 UI 或資訊清單來設定選擇性宣告。

必要條件

具有有效訂用帳戶的 Azure 帳戶。免費建立帳戶。
完成快速入門：註冊應用程式

在應用程式中設定選擇性宣告

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

繼續進行應用程式 UI
繼續進行資訊清單

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

在 [管理] 底下，選取 [資訊清單]。網頁式資訊清單編輯器隨即開啟，讓您編輯資訊清單。或者，您也可以選取 [下載] 並在本機編輯資訊清單，然後使用 [上傳] 以將其重新套用到您的應用程式。如果檔案未包含 optionalClaims 屬性，即可予以新增。

下列應用程式資訊清單項目會將 auth_time、ipaddr 和 upn 選擇性宣告新增至識別碼權杖、存取權杖和 SAML 權杖。

JSON

"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，名稱屬性中的值即為來自使用者物件的延伸模組屬性。
`essential`	Edm.Boolean	如果值為 true，就必須要有用戶端指定的宣告，才能確保使用者所要求之特定工作的授權體驗順暢。預設值為 false。
`additionalProperties`	集合 (Edm.String)	宣告的其他屬性。如果屬性存在於此集合中，它就會修改名稱屬性中所指定之選擇性宣告的行為。

設定目錄擴充的選擇性宣告

除了標準的選擇性宣告集之外，您也可以設定權杖來包含 Microsoft Graph 擴充。如需詳細資訊，請參閱使用延伸模組將自訂資料新增至資源。

重要

系統一律使用資源 (而非用戶端) 的資訊清單來產生存取權杖。在 ...scope=https://graph.microsoft.com/user.read... 要求中，資源是 Microsoft Graph API。使用 Microsoft Graph API 資訊清單 (而不是用戶端的資訊清單) 來建立存取權杖。即使變更應用程式的資訊清單，也絕不會導致 Microsoft Graph 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" (此選項只會包含指派給應用程式的群組)
例如：

JSON
```
"groupMembershipClaims": "SecurityGroup"
```
預設會在群組宣告值中發出群組物件識別碼。若要將宣告值修改為包含內部部署群組屬性，或將宣告類型變更為角色，請使用 optionalClaims 設定，如下所示：

設定群組名稱設定的選擇性宣告。

若要權杖中的群組在選擇性宣告區段中包含內部部署群組屬性，請指定應該套用選擇性宣告的權杖類型。您也會指定所要求選擇性宣告的名稱，以及所需的任何其他屬性。

可以列出多個權杖類型：

idToken，代表 OIDC 識別碼權杖
accessToken 適用於 OAuth 存取權杖
Saml2Token 適用於 SAML 權杖。

Saml2Token 類型適用於 SAML1.1 和 SAML2.0 格式權杖。

針對每個相關的權杖類型，將群組宣告修改為使用資訊清單中的 optionalClaims 區段。 optionalClaims 結構描述如下所示：

JSON

{
    "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_name`、`emit_as_roles` 和 `cloud_displayname`。

在 additionalProperties 中，只需要 sam_account_name、dns_domain_and_sam_account_name、netbios_domain_and_sam_account_name 中的其中一個。如果出現多個，則會使用第一個，其他都忽略。您也可以新增 cloud_displayname 以發出雲端群組的顯示名稱。此選項只有在 groupMembershipClaims 設定為 ApplicationGroup 時才會運作。

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

如果使用 emit_as_roles ，則任何設定為使用者（或資源應用程式）的應用程式角色都不會在角色宣告中。

下列範例顯示群組宣告的資訊清單設定：

在 OAuth 存取權杖中，以 dnsDomainName\sAMAccountName 格式發出 groups 作為群組名稱。

JSON

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

在 SAML 和 OIDC 識別碼權杖中，以 netbiosDomain\sAMAccountName 格式發出要傳回的群組名稱作為角色宣告。

JSON

"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 格式發出群組名稱，並為指派至應用程式的群組，發出 SAML 和 OIDC 識別碼權杖中雲端群組的 cloud_display 名稱。

JSON

"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>_<homedomain>#EXT#@<resourcedomain>) 包含同盟使用者的 UPN。
其他用戶端針對此應用程式所要求的存取權杖會包括 auth_time 宣告。
SAML 權杖包含 skypeId 目錄結構描述延伸模組 (在此範例中，此應用程式的應用程式識別碼為 ab603c56068041afb2f6832e2a17e237)。 SAML 權杖會將 Skype ID 公開為 extension_ab603c56068041afb2f6832e2a17e237_skypeId。

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

選取您想要設定選擇性宣告的應用程式。
在 [管理] 底下，選取 [權杖設定]。
選取 [新增選擇性宣告]、選取 [識別碼] 權杖類型、從宣告清單中選取 [upn]，然後選取 [新增]。
選取 [新增選擇性宣告]、選取 [存取] 權杖類型、從宣告清單中選取 [auth_time]，然後選取 [新增]。
從 [權杖設定] 概觀畫面中，選取 [upn] 旁的鉛筆圖示，選取 [外部驗證] 切換，然後選取 [儲存]。
依序選取 [新增選擇性宣告] 和 [SAML] 權杖類型，並從宣告清單中選取 [extn.skypeID] (只在您已建立稱為 skypeID 的 Microsoft Entra 使用者物件時才適用)，然後選取 [新增]。

在資訊清單中設定宣告：

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

您可以使用此編輯器直接編輯資訊清單。資訊清單遵循 Application 實體的結構描述，而且資訊清單儲存時會自動格式化。新元素會新增至 optionalClaims 屬性。

JSON

"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
        }
    ]
}

資訊清單更新完成後，請選取 [儲存] 以儲存資訊清單。

限制

應用程式可以發出最多10個擴充屬性作為選擇性宣告。

共用方式為

在標識元令牌、存取令牌和 SAML 令牌中設定和管理選擇性宣告

必要條件

在應用程式中設定選擇性宣告

設定目錄擴充的選擇性宣告

目錄擴充格式

設定群組選擇性宣告

選擇性宣告範例

限制

意見反應

其他資源

共用方式為

在標識元令牌、存取令牌和 SAML 令牌中設定和管理選擇性宣告

必要條件

在應用程式中設定選擇性宣告

設定目錄擴充的選擇性宣告

目錄擴充格式

設定群組選擇性宣告

選擇性宣告範例

限制

相關內容

意見反應

其他資源