在 Azure Active Directory B2C 自定义策略中定义 ID 令牌提示技术配置文件

重要

自 2025 年 5 月 1 日起，Azure AD B2C 将不再可供新客户购买。在我们的常见问题解答中了解详细信息。

Azure AD B2C 允许信赖方应用程序作为 OAuth2 授权请求的一部分发送入站 JWT。 JWT 可由信赖方应用程序或标识提供者颁发，并且可以传递有关用户或授权请求的提示。 Azure AD B2C 验证签名、颁发者名称和令牌受众，并从入站令牌中提取声明。

用例

可以使用此解决方案将数据发送到封装在单个 JWT 中的 Azure AD B2C。 Signup with email invitation 系统管理员可向其发送已签名邀请的解决方案基于id_token_hint。只有有权访问邀请电子邮件的用户才能在目录中创建帐户。

令牌签名方法

使用id_token_hint，令牌颁发者（信赖方应用或标识提供者）组成令牌，然后使用签名密钥对其进行签名，以证明令牌来自受信任的源。签名密钥可以是对称密钥或非对称密钥。对称加密或私钥加密使用共享机密对签名进行签名和验证。非对称加密或公钥加密是使用私钥和公钥的加密系统。私钥仅对令牌颁发者知道，用于对令牌进行签名。公钥与 Azure AD B2C 策略共享，以验证令牌的签名。

令牌格式

id_token_hint必须是有效的 JWT。下表列出了必需声明。其他声明是可选的。

名字	索赔	示例值	DESCRIPTION
观众	`aud`	`00001111-aaaa-2222-bbbb-3333cccc4444`	标识令牌的目标接收方。访问群体是由令牌颁发者定义的任意字符串。 Azure AD B2C 验证此值，如果令牌不匹配，则拒绝令牌。
发行人	`iss`	`https://localhost`	标识安全令牌服务（令牌颁发者）。颁发者是由令牌颁发者定义的任意 URI。 Azure AD B2C 验证此值，如果令牌不匹配，则拒绝令牌。
过期时间	`exp`	`1600087315`	令牌失效的时间，以纪元时间表示。 Azure AD B2C 验证此值，并在令牌过期时拒绝令牌。
生效时间	`nbf`	`1599482515`	令牌生效的时间，以纪元时间表示。这一次通常与颁发令牌的时间相同。 Azure AD B2C 验证此值，如果令牌生存期无效，则拒绝令牌。

以下令牌是有效 ID 令牌的示例：

{
  "alg": "HS256",
  "typ": "JWT"
}.{
  "displayName": " John Smith",
  "userId": "john.s@contoso.com",
  "nbf": 1599482515,
  "exp": 1600087315,
  "iss": "https://localhost",
  "aud": "00001111-aaaa-2222-bbbb-3333cccc4444"
}

协议

“Protocol”元素的“Name”属性必须设置为。例如， IdTokenHint_ExtractClaims 技术配置文件的协议为 None：

<TechnicalProfile Id="IdTokenHint_ExtractClaims">
  <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
  <Protocol Name="None" />
  ...

从包含类型为 <a0/> 的业务流程步骤调用技术配置文件。

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

输出声明

OutputClaims 元素包含要从 JWT 中提取的声明列表。可能需要将策略中定义的声明的名称映射到 JWT 中定义的名称。还可以包含 JWT 不返回的声明，只要设置 DefaultValue 属性。

元数据

使用对称密钥时，以下元数据相关。

特征	必选	DESCRIPTION
发行人	是的	标识安全令牌服务（令牌颁发者）。此值必须与 JWT 声明中的声明相同 `iss` 。
IdTokenAudience	是的	标识令牌的目标接收方。必须与 JWT 声明中的声明相同 `aud` 。

使用非对称密钥时，以下元数据相关。

特征	必选	DESCRIPTION
元数据	是的	指向令牌颁发者配置文档的 URL，也称为 OpenID 已知配置终结点。
发行人	否	标识安全令牌服务（令牌颁发者）。此值可用于覆盖元数据中配置的值，并且必须与 JWT 声明中的声明相同 `iss` 。
IdTokenAudience	否	标识令牌的目标接收方。必须与 JWT 声明中的声明相同 `aud` 。

加密密钥

使用对称密钥时， CryptographicKeys 元素包含以下属性：

特征	必选	DESCRIPTION
客户端密钥	是的	用于验证 JWT 签名的加密密钥。

操作指南

使用对称密钥颁发令牌

步骤 1：创建共享密钥

创建可用于对令牌进行签名的密钥。例如，使用以下 PowerShell 代码生成密钥。

$bytes = New-Object Byte[] 32
$rand = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rand.GetBytes($bytes)
$rand.Dispose()
$newClientSecret = [System.Convert]::ToBase64String($bytes)
$newClientSecret

此代码创建类似于 VK62QTn0m1hMcn0DQ3RPYDAr6yIiSvYgdRwjZtU5QhI=..

步骤 2：将签名密钥添加到 Azure AD B2C

需要在 Azure AD B2C 策略密钥中创建令牌颁发者使用的相同密钥。

登录到 Azure 门户。
如果有权访问多个租户，请选择顶部菜单中的“设置”图标，切换到“目录 + 订阅”菜单中的 Azure AD B2C 租户。
在 Azure 门户中，搜索并选择 Azure AD B2C。
在概述页上，在策略下，选择 标识体验框架。
选择 策略密钥
选择 “手动”。
对于 Name，请使用 IdTokenHintKey。
前缀B2C_1A_可能会自动添加。
在 “机密 ”框中，输入之前生成的登录密钥。
对于 密钥用法，请使用加密。
选择创建。
确认已创建密钥 B2C_1A_IdTokenHintKey。

步骤 3：添加 ID 令牌提示技术配置文件

以下技术配置文件验证令牌并提取声明。

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <Item Key="IdTokenAudience">00001111-aaaa-2222-bbbb-3333cccc4444</Item>
        <Item Key="issuer">https://localhost</Item>
      </Metadata>
      <CryptographicKeys>
        <Key Id="client_secret" StorageReferenceId="B2C_1A_IdTokenHintKey" />
      </CryptographicKeys>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

步骤 4：准备策略

完成 “配置策略 ”步骤。

步骤 5：准备代码

GitHub 示例是一个 ASP.NET Web 应用程序和控制台应用，它生成使用对称密钥签名的 ID 令牌。

使用非对称密钥颁发令牌

使用非对称密钥，令牌使用 RSA 证书进行签名。此应用程序托管 Azure AD B2C 用来验证 ID 令牌签名的 OpenID Connect 元数据终结点和 JSON Web 密钥（JWKs）终结点。

令牌颁发者必须提供以下终结点：

/.well-known/openid-configuration - 一个已知配置终结点，其中包含有关令牌的相关信息，例如令牌颁发者名称和 JWK 终结点的链接。
/.well-known/keys - JSON Web 密钥（JWK）终结点，其中包含用于对密钥进行签名的公钥（使用证书的私钥部分）。

TokenMetadataController.cs 请参阅 .NET MVC 控制器示例。

步骤 1：准备自签名证书

如果还没有证书，可以使用自签名证书作为本作指南。在 Windows 上，可以使用 PowerShell 的 New-SelfSignedCertificate cmdlet 生成证书。

运行此 PowerShell 命令以生成自签名证书。 -Subject根据应用程序和 Azure AD B2C 租户名称修改参数。还可调整 -NotAfter 日期，为证书指定不同的过期日期。

New-SelfSignedCertificate `
    -KeyExportPolicy Exportable `
    -Subject "CN=yourappname.yourtenant.partner.onmschina.cn" `
    -KeyAlgorithm RSA `
    -KeyLength 2048 `
    -KeyUsage DigitalSignature `
    -NotAfter (Get-Date).AddMonths(12) `
    -CertStoreLocation "Cert:\CurrentUser\My"

步骤 2：添加 ID 令牌提示技术配置文件

以下技术配置文件验证令牌并提取声明。将元数据 URI 更改为令牌颁发者已知配置终结点。

<ClaimsProvider>
  <DisplayName>My ID Token Hint ClaimsProvider</DisplayName>
  <TechnicalProfiles>
    <TechnicalProfile Id="IdTokenHint_ExtractClaims">
      <DisplayName> My ID Token Hint TechnicalProfile</DisplayName>
      <Protocol Name="None" />
      <Metadata>
        <!-- Replace with your endpoint location -->
        <Item Key="METADATA">https://your-app.chinacloudsites.cn/.well-known/openid-configuration</Item>
        <Item Key="IdTokenAudience">your_optional_audience</Item>
        <!-- <Item Key="issuer">your_optional_token_issuer_override</Item> -->
      </Metadata>
      <OutputClaims>
        <OutputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
      </OutputClaims>
    </TechnicalProfile>
  </TechnicalProfiles>
</ClaimsProvider>

步骤 3：准备策略

完成 “配置策略 ”步骤。

步骤 4：准备代码

此 GitHub 示例 ASP.NET Web 应用程序生成 ID 令牌，并托管在 Azure AD B2C 中使用“id_token_hint”参数所需的元数据终结点。

配置您的策略

对于对称和非对称方法，技术 id_token_hint 配置文件是从包含类型 GetClaims 且需要指定信赖方策略的输入声明的业务流程步骤调用的。

将IdTokenHint_ExtractClaims技术配置文件添加到扩展策略。

将以下业务流程步骤作为第一项添加到用户旅程。

<OrchestrationStep Order="1" Type="GetClaims" CpimIssuerTechnicalProfileReferenceId="IdTokenHint_ExtractClaims" />

在信赖方策略中，重复在IdTokenHint_ExtractClaims技术配置文件中配置的相同输入声明。例如：

<RelyingParty>
  <DefaultUserJourney ReferenceId="SignUp" />
  <TechnicalProfile Id="PolicyProfile">
    <DisplayName>PolicyProfile</DisplayName>
    <Protocol Name="OpenIdConnect" />
    <InputClaims>
      <InputClaim ClaimTypeReferenceId="email" PartnerClaimType="userId" />
    </InputClaims>
    <OutputClaims>
      <OutputClaim ClaimTypeReferenceId="displayName" />
      <OutputClaim ClaimTypeReferenceId="givenName" />
      <OutputClaim ClaimTypeReferenceId="surname" />
      <OutputClaim ClaimTypeReferenceId="email" />
      <OutputClaim ClaimTypeReferenceId="objectId" PartnerClaimType="sub"/>
      <OutputClaim ClaimTypeReferenceId="identityProvider" />
    </OutputClaims>
    <SubjectNamingInfo ClaimType="sub" />
  </TechnicalProfile>
</RelyingParty>

根据业务需求，可能需要添加令牌验证，例如检查电子邮件地址的格式。为此，请添加调用声明转换技术配置文件的业务流程步骤。此外，添加自断言技术配置文件来显示错误消息。

创建令牌并签名

GitHub 示例演示如何创建此类令牌颁发 JWT，该 JWT 稍后作为查询字符串参数发送 id_token_hint 。下面是具有 id_token_hint 参数的授权请求示例

https://tenant-name.b2clogin.cn/tenant-name.partner.onmschina.cn/B2C_1A_signup_signin/oauth2/v2.0/authorize?client_id=11112222-bbbb-3333-cccc-4444dddd5555&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid&response_type=id_token&prompt=login&id_token_hint=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkaXNwbGF5TmFtZSI6IiBKb2huIFNtaXRoIiwidXNlcklkIjoiam9obi5zQGNvbnRvc28uY29tIiwibmJmIjoxNTk5NDgyNTE1LCJleHAiOjE2MDAwODczMTUsImlzcyI6Imh0dHBzOi8vbG9jYWxob3N0IiwiYXVkIjoiYTQ4OWZjNDQtM2NjMC00YTc4LTkyZjYtZTQxM2NkODUzZWFlIn0.nPmLXydI83PQCk5lRBYUZRu_aX58pL1khahHyQuupig

后续步骤

在 Azure AD B2C 社区 GitHub 存储库上通过邀请电子邮件解决方案检查注册。

Last updated on 2026-06-22