为企业应用程序定制在 JSON Web Token (JWT) 中发布的声明

Microsoft 标识平台支持在 Microsoft Entra 应用程序库中的大多数预集成应用程序和自定义应用程序上进行单一登录 (SSO)。 当用户使用 OIDC 协议通过 Microsoft 标识平台向应用程序进行身份验证时，系统会将令牌发送到该应用程序。 应用程序会验证并使用令牌登录用户，而不会提示输入用户名和密码。

OIDC 和 OAuth 应用程序使用的这些 JSON Web 令牌 (JWT) 包含名为声明的有关用户的信息片段。 “声明”是标识提供者在为某个用户颁发的令牌中陈述的有关该用户的信息。 在 OIDC 响应中，“声明”数据通常包含在标识提供者以 JWT 形式颁发的 ID 令牌中。

查看或编辑声明

可选的 JWT 声明可以在原始应用程序注册中配置，但也可以在企业应用程序中配置。 要查看或编辑 JWT 中颁发给应用程序的声明，请执行以下操作：

1. 至少以云应用程序管理员身份登录到 Microsoft Entra 管理中心。
2. 浏览到“标识”>“应用程序”>“企业应用程序”>“所有应用程序”。
3. 选择应用程序，在左侧菜单中选择“单一登录”，然后在“属性和声明”部分中选择“编辑”。

由于各种原因，应用程序可能需要声明自定义。 例如，当应用程序需要一组不同的声明 URI 或声明值时。 使用“属性和声明”部分，可以添加或移除应用程序的声明。 还可以根据用例创建特定于应用程序的自定义声明。

以下步骤介绍了如何分配常数值：

1. 选择要修改的声明。
2. 在“源属性”中按组织输入不带引号的常量值，然后选择“保存”。

属性概述显示常量值。

特定声明转换

可以使用以下特殊声明转换函数。

添加特定于应用程序的声明

要添加特定于应用程序的声明：

1. 在“用户属性和声明”中，选择“添加新声明”打开“管理用户声明”网页。
2. 输入声明的“名称”。 该值不需要严格遵循 URI 模式。 如果需要 URI 模式，可以将其放入命名空间字段。
3. 选择声明可检索其值的源。 可以从“源属性”下拉列表中选择一个用户属性，或者在用户属性作为声明发出之前对其应用转换。

声明转换

对用户属性应用转换：

1. 在管理声明中，选择转换作为声明源，以打开管理转换页。
2. 从“转换”下拉列表中选择函数。 根据选择的函数，提供参数和常量值以在转换中进行计算。
3. 将源视为多值指示转换是应用于所有值还是仅应用于第一个值。 默认情况下，多值声明中的第一个元素将应用转换。 勾选此框时，可确保将其应用于所有值。 此复选框仅对多值属性启用。 例如 user.proxyaddresses。
4. 若要应用多个转换，请选择“添加转换”。 对一个声明最多可以应用两个转换。 例如，可以先提取 user.mail 的电子邮件前缀。 然后，将字符串设为大写。

可以使用以下功能转换声明。

如果需要其他转换，请在“SaaS 应用程序”类别下的 Microsoft Entra ID 反馈论坛中发布你的想法。

基于正则表达式的声明转换

下图显示了第一级转换的示例：

下表提供了有关第一级转换的信息。 表中列出的操作对应于上图中的标签。 选择“编辑”以打开声明转换边栏选项卡。

下图显示了第二级转换的示例：

下表提供了有关第二级转换的信息。 表中列出的操作对应于上图中的标签。

下图显示了测试转换的示例：

下表提供了有关转换的信息。 表中列出的操作对应于上图中的标签。

RegexReplace() 转换也可用于组声明转换。

转换验证

选择添加或运行测试后出现以下情况时，消息将提供详细信息：

• 使用了具有重复用户属性的输入参数。
• 找到了未使用的输入参数。 定义的输入参数在替换模式文本中应具有相应的用法。
• 提供的测试正则表达式输入与提供的正则表达式不匹配。
• 找不到替换模式中组的源。

发出基于条件的声明

能够根据用户类型和用户所属的组来指定声明的源。

用户类型可以是：

• 任何 - 允许所有用户访问应用程序。
• 成员：本机租户的成员
• 所有来宾：从具有或没有 Microsoft Entra ID 的外部组织中移来的用户。
• Microsoft Entra 来宾：属于使用 Microsoft Entra ID 的另一个组织的来宾用户。
• 外部来宾：来宾用户属于没有 Microsoft Entra ID 的外部组织。

用户类型在以下场景中很有用：来宾和员工访问应用程序使用的声明源不同。 可做如下规定：如果用户是员工，则从 user.email 获取 NameID。 如果用户是来宾，则从 user.extensionattribute1 获取 NameID。

要添加声明条件：

1. 在管理声明中，展开”声明条件”。
2. 选择用户类型。
3. 选择用户所属的组。 在某个给定应用程序的所有声明中，最多可以选择 50 个独一无二的组。
4. 选择声明可检索其值的源。 可以从“源属性”下拉列表中选择一个用户属性，或者在用户属性作为声明发出之前对其应用转换。

添加条件的顺序很重要。 Microsoft Entra 首先使用源 Attribute 评估所有条件，然后使用源 Transformation 评估所有条件，以确定要在声明中发出哪个值。 Microsoft Entra ID 从上到下评估具有相同源的条件。 声明发出与声明中的表达式匹配的最后一个值。 转换（如 IsNotEmpty 和 Contains）的作用类似于限制。

例如，Britta Simon 是 Contoso 租户中的来宾用户。 Britta 属于另一个也使用 Microsoft Entra ID 的组织。 基于以下对 Fabrikam 应用程序的配置，如果 Britta 尝试登录到 Fabrikam，Microsoft 标识平台将评估条件。

首先，Microsoft 标识平台会验证 Britta 的用户类型是否为“所有来宾”。 由于类型为“所有来宾”，因此 Microsoft 标识平台会将声明的源分配到 user.extensionattribute1。 其次，Microsoft 标识平台会验证 Britta 的用户类型是否为“Microsoft Entra 来宾”。 由于类型为“所有来宾”，因此 Microsoft 标识平台会将声明的源分配到 user.mail。 最后，使用值 user.mail 为 Britta 发出声明。

作为另一个示例，请考虑当 Britta Simon 尝试登录时，使用以下配置会发生什么情况。 Microsoft Entra 首先使用源 Attribute 评估所有条件。 当 Britta 的用户类型为 user.mailMicrosoft Entra 来宾时，声明的源为 。 接下来，Microsoft Entra ID 会评估转换。 由于 Britta 是来宾，因此 user.extensionattribute1 是声明的新源。 由于 Britta 是 Microsoft Entra 来宾，因此 user.othermail 是声明的新源。 最后，使用值 user.othermail 为 Britta 发出声明。

作为最后一个示例，请考虑如果 Britta 未配置 user.othermail 或其为空，会发生什么情况。 在这两种情况下，声明回退到 user.extensionattribute1，忽略条件条目。

安全注意事项

接收令牌的应用程序依赖于这一声明，不能篡改。 当你通过声明自定义修改令牌内容时，这些假定可能不再正确。 应用程序必须明确承认令牌已被修改，以防自己被恶意行为者创建的自定义内容的影响。 采用以下方式之一防止不适当的自定义：

• 配置自定义签名密钥
• 更新应用程序清单，以接受映射的声明。

如果没有此项，Microsoft Entra ID 将返回 AADSTS50146 错误代码。

配置自定义签名密钥

对于多租户应用，应使用自定义签名密钥。 请勿在应用部件清单 (manifest) 中设置 acceptMappedClaims。 在 Azure 门户中设置应用时，你将在租户中获得一个应用注册对象和一个服务主体。 该应用使用 Azure 全局登录密钥，该密钥不能用来自定义令牌中的声明。 若要获取令牌中的自定义声明，请从证书创建自定义登录密钥，并将其添加到服务主体。 对于测试，可以使用自签名的证书。 配置自定义签名密钥后，应用程序代码需要验证令牌签名密钥。

向服务主体添加以下信息：

• 私钥（作为密钥凭据）
• 密码（作为密码凭据）
• 公钥（作为密钥凭据）

从证书的 PFX 文件导出中提取 base-64 编码的私钥和公钥。 确保用于“签名”的 keyCredential 的 keyId 与 passwordCredential 的 keyId 相匹配。 可通过获取证书指纹的哈希来生成 customkeyIdentifier。

请求

下面的示例显示了用于向服务主体添加自定义签名密钥的 HTTP PATCH 请求的格式。 为便于阅读，keyCredentials 属性中的“密钥”值已缩短。 该值是 base-64 编码的。 对于私钥，属性用法为“Sign”。 对于公钥，属性用法为“Verify”。

PATCH https://graph.microsoft.com/v1.0/servicePrincipals/aaaaaaaa-bbbb-cccc-1111-222222222222

Content-type: servicePrincipals/json
Authorization: Bearer {token}

{
    "keyCredentials":[
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=", 
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "aaaaaaaa-0b0b-1c1c-2d2d-333333333333",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "X509CertAndPassword",
            "usage": "Sign",
            "key":"cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
            "displayName": "CN=contoso"
        },
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
            "endDateTime": "2021-04-22T22:10:13Z",
            "keyId": "bbbbbbbb-1c1c-2d2d-3e3e-444444444444",
            "startDateTime": "2020-04-22T21:50:13Z",
            "type": "AsymmetricX509Cert",
            "usage": "Verify",
            "key": "cD2eF3gH4iJ5kL6mN7-oP8qR9sT==",
            "displayName": "CN=contoso"
        }

    ],
    "passwordCredentials": [
        {
            "customKeyIdentifier": "aB1cD2eF3gH4iJ5kL6-mN7oP8qR=",
            "keyId": "cccccccc-2d2d-3e3e-4f4f-555555555555",
            "endDateTime": "2022-01-27T19:40:33Z",
            "startDateTime": "2020-04-20T19:40:33Z",
            "secretText": "mypassword"
        }
    ]
}

使用 PowerShell 配置自定义签名密钥

使用 PowerShell 实例化 MSAL 公共客户端应用程序，并使用授权代码授予流获取 Microsoft Graph 的委托权限访问令牌。 使用访问令牌调用 Microsoft Graph，并为服务主体配置自定义签名密钥。 配置自定义签名密钥后，应用程序代码需要验证令牌签名密钥。

若要运行此脚本，你需要：

• 应用程序服务主体的对象 ID，位于 Azure 门户中企业应用程序内应用程序条目的“概述”边栏选项卡中。
• 应用注册，用于登录应用和获取用于调用 Microsoft Graph 的访问令牌。 在 Azure 门户的应用注册中应用程序条目的“概述”边栏选项卡中获取此应用的应用程序（客户端）ID。 应用注册应具有以下配置：
  • “移动和桌面应用程序”平台配置中列出的“http://localhost"”的重定向 URI。
  • 在“API 权限”中，Microsoft Graph 委托权限 Application.ReadWrite.All 和 User.Read（确保对这些权限授予管理员同意）。
• 登录以获取 Microsoft Graph 访问令牌的用户。 用户应是以下 Microsoft Entra 管理角色之一（更新服务主体所必需）：
  • 云应用管理员
  • 应用程序管理员
• 要配置为应用程序的自定义签名密钥的证书。 可以创建自签名证书，也可以从你信任的证书颁发机构获取一个证书。 脚本中使用了以下证书组件：
  • 公钥（通常为 .cer 文件）
  • PKCS#12 格式的私钥（.pfx 文件）
  • 私钥的密码（.pfx 文件）

##########################################################
# Replace the variables below with the appropriate values 

$fqdn="yourDomainHere" # This is used for the 'issued to' and 'issued by' field of the certificate
$pwd="password" # password for exporting the certificate private key
$tenantId   = "aaaabbbb-0000-cccc-1111-dddd2222eeee" # Replace with your Tenant ID
$appObjId = "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb" # Replace with the Object ID of the App Registration

##########################################################

# Create a self-signed cert

$cert = New-SelfSignedCertificate -certstorelocation cert:\currentuser\my -DnsName $fqdn
$pwdSecure = ConvertTo-SecureString -String $pwd -Force -AsPlainText
$path = 'cert:\currentuser\my\' + $cert.Thumbprint
$location="C:\\temp" # path to folder where both the pfx and cer file will be written to
$cerFile = $location + "\\" + $fqdn + ".cer"
$pfxFile = $location + "\\" + $fqdn + ".pfx"
 
# Export the public and private keys
Export-PfxCertificate -cert $path -FilePath $pfxFile -Password $pwdSecure
Export-Certificate -cert $path -FilePath $cerFile

$pfxpath = $pfxFile # path to pfx file
$cerpath = $cerFile # path to cer file
$password = $pwd  # password for the pfx file
 
# Check PowerShell version (minimum 5.1) (.Net) or PowerShell Core (.Net Core) and read the certificate file accordingly
 
if ($PSVersionTable.PSVersion.Major -gt 5)
    { 
        $core = $true
    }
else
    { 
        $core = $false
    }
 
    #  this is for PowerShell Core
    $Secure_String_Pwd = ConvertTo-SecureString $password -AsPlainText -Force
 
    # reading certificate files and creating Certificate Object
    if ($core)
    {
        $pfx_cert = get-content $pfxpath -AsByteStream -Raw
        $cer_cert = get-content $cerpath -AsByteStream -Raw
        $cert = Get-PfxCertificate -FilePath $pfxpath -Password $Secure_String_Pwd
    }
    else
    {
        $pfx_cert = get-content $pfxpath -Encoding Byte
        $cer_cert = get-content $cerpath -Encoding Byte
        # calling Get-PfxCertificate in PowerShell 5.1 prompts for password - using alternative method
        $cert = [System.Security.Cryptography.X509Certificates.X509Certificate2]::new($pfxpath, $password)
    }

 
    # base 64 encode the private key and public key
    $base64pfx = [System.Convert]::ToBase64String($pfx_cert)
    $base64cer = [System.Convert]::ToBase64String($cer_cert)
 
    # getting id for the keyCredential object
    $guid1 = New-Guid
    $guid2 = New-Guid
 
    # get the custom key identifier from the certificate thumbprint:
    $hasher = [System.Security.Cryptography.HashAlgorithm]::Create('sha256')
    $hash = $hasher.ComputeHash([System.Text.Encoding]::UTF8.GetBytes($cert.Thumbprint))
    $customKeyIdentifier = [System.Convert]::ToBase64String($hash)
 
    # get end date and start date for our keycredentials
    $endDateTime = ($cert.NotAfter).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
    $startDateTime = ($cert.NotBefore).ToUniversalTime().ToString( "yyyy-MM-ddTHH:mm:ssZ" )
 
    # building our json payload
    $object = [ordered]@{    
    keyCredentials = @(       
         [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid1
            startDateTime = $startDateTime 
            type = "AsymmetricX509Cert"
            usage = "Sign"
            key = $base64pfx
            displayName = "CN=$fqdn" 
        },
        [ordered]@{            
            customKeyIdentifier = $customKeyIdentifier
            endDateTime = $endDateTime
            keyId = $guid2
            startDateTime = $startDateTime 
            type = "AsymmetricX509Cert"
            usage = "Verify"
            key = $base64cer
            displayName = "CN=$fqdn"   
        }
        )  
    passwordCredentials = @(
        [ordered]@{
            customKeyIdentifier = $customKeyIdentifier
            displayName = "CN=$fqdn"
            keyId = $guid1           
            endDateTime = $endDateTime
            startDateTime = $startDateTime
            secretText = $password
            hint = $null
        }
    )
    }
 
Connect-MgGraph -tenantId $tenantId -Scopes Application.ReadWrite.All
$graphuri = "https://graph.microsoft.com/v1.0/applications/$appObjId"
Invoke-MgGraphRequest -Method PATCH -Uri $graphuri -Body $object

    $json = $object | ConvertTo-Json -Depth 99
    Write-Host "JSON Payload:"
    Write-Output $json

验证令牌签名密钥

启用了声明映射的应用必须通过将 appid={client_id} 追加到其 OpenID Connect 元数据请求来验证令牌签名密钥。 以下示例显示应使用的 OpenID Connect 元数据文档格式：

https://login.microsoftonline.com/{tenant}/v2.0/.well-known/openid-configuration?appid={client-id}

更新应用程序清单

对于单租户应用，可以在应用程序清单中将 acceptMappedClaims 属性设置为 true。 如 apiApplication 资源类型中所述。 设置该属性允许应用程序使用声明映射，而无需指定自定义的签名密钥。

请求令牌的受众需要使用经过验证的 Microsoft Entra 租户域名，这意味着应设置 Application ID URI（在应用程序清单中由 identifierUris 表示），例如将其设置为 https://contoso.com/my-api 或（仅使用默认租户名）https://contoso.onmicrosoft.com/my-api。

如果未使用经过验证的域，Microsoft Entra ID 将返回 AADSTS501461 错误代码以及消息“AcceptMappedClaims 仅支持与应用程序 GUID 匹配的令牌受众或经过验证的租户域中的受众。 请更改资源标识符，或使用特定于应用程序的签名密钥。”

高级声明选项

配置 OIDC 应用程序的高级声明选项，以公开与 SAML 令牌相同的声明。 还适用于打算对 SAML2.0 和 OIDC 响应令牌使用相同声明的应用程序。

通过选中管理声明边栏选项卡中的高级声明选项下的框来配置高级声明选项。

相关内容

• Microsoft Entra ID 中使用的声明和令牌。