設定選擇性宣告
Microsoft Entra 傳回的令牌會保持較小,以確保要求這些令牌的客戶端達到最佳效能。 因此,根據預設,令牌中不再存在數個宣告,而且必須依個別應用程式特別要求。
您可以透過 Microsoft Entra 系統管理中心的應用程式 UI 或指令清單,為您的應用程式設定選擇性宣告:
- 以至少 雲端應用程式系統管理員 的身分登入 Microsoft Entra 系統管理中心。
- 流覽至 [身分>識別應用程式> 應用程式註冊]。
- 選擇您要根據案例和所需結果設定選擇性宣告的應用程式。
- 在 [管理] 底下,選取 [令牌組態]。
- 選取 [ 新增選擇性宣告]。
- 選取您想要設定的令牌類型,例如 Access。
- 選取要新增的選擇性宣告。
- 選取 [新增]。
設定目錄延伸模組選擇性宣告
除了標準選擇性宣告集之外,您也可以設定令牌以包含 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_name
emit_as_roles
和cloud_displayname
。在 中
additionalProperties
,只需要其中dns_domain_and_sam_account_name
sam_account_name
netbios_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 身分識別平台 中的令牌和宣告。
意見反映
https://aka.ms/ContentUserFeedback。
即將推出:我們會在 2024 年淘汰 GitHub 問題,並以全新的意見反應系統取代並作為內容意見反應的渠道。 如需更多資訊,請參閱:提交及檢視以下的意見反映: