Azure Entra ID应用注册：无法向Access Token添加自定义声明

我创建了一个Azure Entra ID应用注册，希望向JWT Access Token中添加自定义声明。按照官方指引操作后，通过Postman请求令牌并在jwt.io中验证，发现令牌里并未包含新增的自定义声明。尝试过通过Azure门户添加自定义声明，也调整了User.Read、openid、profile等作用域，但结果没有变化。

以下是我的应用清单：

{"id": "cfdb05a2-357b-4e52-8f68-7a4a48a45256","acceptMappedClaims": null,"accessTokenAcceptedVersion": 2,"addIns": [],"allowPublicClient": true,"appId": "19eccd56-b192-450d-820c-77a353d1fd7c","appRoles": [],"oauth2AllowUrlPathMatching": false,"createdDateTime": "2024-04-22T14:31:19Z","description": null,"certification": null,"disabledByMicrosoftStatus": null,"groupMembershipClaims": "None","identifierUris": ["api://19eccd56-b192-450d-820c-77a353d1fd7c"],"informationalUrls": {"termsOfService": null,"support": null,"privacy": null,"marketing": null},"keyCredentials": [],"knownClientApplications": [],"logoUrl": null,"logoutUrl": null,"name": "TEST_APP_SAML","notes": null,"oauth2AllowIdTokenImplicitFlow": true,"oauth2AllowImplicitFlow": true,"oauth2Permissions": [],"oauth2RequirePostResponse": false,"optionalClaims": {"idToken": [{"name": "tenant_region_scope","source": null,"essential": false,"additionalProperties": []},{"name": "verified_primary_email","source": null,"essential": false,"additionalProperties": []},{"name": "verified_secondary_email","source": null,"essential": false,"additionalProperties": []},{"name": "vnet","source": null,"essential": false,"additionalProperties": []},{"name": "ctry","source": null,"essential": false,"additionalProperties": []},{"name": "tenant_ctry","source": null,"essential": false,"additionalProperties": []},{"name": "xms_pdl","source": null,"essential": false,"additionalProperties": []},{"name": "xms_pl","source": null,"essential": false,"additionalProperties": []},{"name": "xms_tpl","source": null,"essential": false,"additionalProperties": []},{"name": "ztdid","source": null,"essential": false,"additionalProperties": []},{"name": "upn","source": null,"essential": false,"additionalProperties": ["include_externally_authenticated_upn"]},{"name": "xms_cc","source": null,"essential": false,"additionalProperties": []}],"accessToken": [{"name": "ctry","source": null,"essential": false,"additionalProperties": []},{"name": "tenant_ctry","source": null,"essential": false,"additionalProperties": []},{"name": "ztdid","source": null,"essential": false,"additionalProperties": []},{"name": "upn","source": null,"essential": false,"additionalProperties": ["include_externally_authenticated_upn"]},{"name": "login_hint","source": null,"essential": false,"additionalProperties": []}],"saml2Token": []},"orgRestrictions": [],"parentalControlSettings": {"countriesBlockedForMinors": [],"legalAgeGroupRule": "Allow"},"passwordCredentials": [],"preAuthorizedApplications": [],"publisherDomain": "andreasweier85gmail.onmicrosoft.com","replyUrlsWithType": [{"url": "https://jwt.ms","type": "InstalledClient"},{"url": "https://login.microsoftonline.com/common/oauth2/nativeclient","type": "InstalledClient"}],"requiredResourceAccess": [{"resourceAppId": "00000003-0000-0000-c000-000000000000","resourceAccess": [{"id": "14dad69e-099b-42c9-810b-d002981feec1","type": "Scope"},{"id": "e1fe6dd8-ba31-4d61-89e7-88639da4683d","type": "Scope"}]},{"resourceAppId": "00eda80b-051a-46ab-940f-2bbdc3dabeec","resourceAccess": [{"id": "4d2e19f0-3525-4517-9e7d-48f0411b4395","type": "Scope"}]}],"samlMetadataUrl": null,"signInUrl": null,"signInAudience": "AzureADMultipleOrgs","tags": ["apiConsumer","singlePageApp"],"tokenEncryptionKeyId": null}

排查与解决步骤 #

• 确认Access Token的受众匹配应用标识符URI
  如果请求的Access Token受众（aud字段）是Microsoft Graph（值为00000003-0000-0000-c000-000000000000），那么应用清单里的optionalClaims.accessToken配置不会生效——这些自定义声明仅针对你的应用自身API（即aud为api://19eccd56-b192-450d-820c-77a353d1fd7c）的令牌生效。必须请求你的应用的API权限，而非Microsoft Graph权限。

• 设置acceptMappedClaims为true
  当前应用清单中acceptMappedClaims为null，需将其修改为true。该属性是应用接收映射自定义声明的必要条件，修改后保存应用清单。

• 使用正确的作用域请求令牌
  请求Access Token时，必须使用你的应用标识符URI作为作用域前缀，例如api://19eccd56-b192-450d-820c-77a353d1fd7c/.default，不能仅使用User.Read、openid等Microsoft Graph作用域。只有请求应用自身的作用域，才会触发自定义声明的注入。

• 检查用户/租户属性是否存在有效值
  部分自定义声明（如ctry、tenant_ctry）依赖于用户或租户的对应属性是否已配置。如果用户的国家/地区属性为空，这些声明不会出现在令牌中。可在Azure Entra ID的用户配置页面检查相关属性值。

• 清除缓存并重新获取令牌
  Azure Entra ID会缓存令牌，修改配置后需等待几分钟，或在请求时添加prompt=login参数强制重新登录，确保获取最新配置下的令牌。

内容的提问来源于stack exchange，提问作者Andreas Weier