为 ID 令牌提示创建可验证凭据

项目
11/13/2024

使用 idTokens 证明的规则定义会生成颁发流，它需要你在 Microsoft Authenticator 中对 OpenID Connect (OIDC) 标识提供者执行交互式登录。标识提供者返回的 ID 令牌中的声明可用于填充颁发的可验证凭据。规则定义中的声明映射部分指定使用哪些声明。

创建具有 idTokens 证明类型的自定义凭据

在 Azure 门户中选择“添加凭据”时，可以选择启动两个快速入门。选择“自定义凭据”，然后选择“下一步”。

创建自定义凭据的“颁发凭据”快速入门的屏幕截图。

在“创建新凭据”页上，输入显示和规则定义的 JSON 代码。在“凭据名称”框中，为凭据提供类型名称。要创建凭据，选择“创建”。

“创建新凭据”页的屏幕截图，其中显示了用于显示和规则文件的 JSON 示例。

示例 JSON 显示定义

无论证明类型如何，JSON 显示定义都几乎相同。只需根据可验证凭据所拥有的声明来调整标签。显示定义的预期 JSON 是显示集合的内部内容。 JSON 是一个集合，如果要支持多个区域设置，则添加多个条目，以逗号作为分隔符。

{
    "locale": "en-US",
    "card": {
      "title": "Verified Credential Expert",
      "issuedBy": "Microsoft",
      "backgroundColor": "#000000",
      "textColor": "#ffffff",
      "logo": {
        "uri": "https://didcustomerplayground.z13.web.core.windows.net/VerifiedCredentialExpert_icon.png",
        "description": "Verified Credential Expert Logo"
      },
      "description": "Use your verified credential to prove to anyone that you know all about verifiable credentials."
    },
    "consent": {
      "title": "Do you want to get your Verified Credential?",
      "instructions": "Sign in with your account to get your card."
    },
    "claims": [
      {
        "claim": "vc.credentialSubject.userName",
        "label": "User name",
        "type": "String"
      },
      {
        "claim": "vc.credentialSubject.displayName",
        "label": "Display name",
        "type": "String"
      },
      {
        "claim": "vc.credentialSubject.firstName",
        "label": "First name",
        "type": "String"
      },
      {
        "claim": "vc.credentialSubject.lastName",
        "label": "Last name",
        "type": "String"
      }
    ]
}

示例 JSON 规则定义

JSON 证明定义应包含 idTokens 名称、OIDC 配置详细信息（clientId、配置、redirectUri 和作用域）和声明映射部分。规则定义的预期 JSON 是规则属性的内部内容，它以证明属性开头。

以下示例中的声明映射要求配置令牌，如提供者 ID 令牌中的声明所述。

{
  "attestations": {
    "idTokens": [
      {
        "clientId": "00001111-aaaa-2222-bbbb-3333cccc4444",
        "configuration": "https://didplayground.b2clogin.com/didplayground.onmicrosoft.com/B2C_1_sisu/v2.0/.well-known/openid-configuration",
        "redirectUri": "vcclient://openid/",
        "scope": "openid profile email",
        "mapping": [
          {
            "outputClaim": "userName",
            "required": true,
            "inputClaim": "$.upn",
            "indexed": true
          },
          {
            "outputClaim": "displayName",
            "required": true,
            "inputClaim": "$.name",
            "indexed": false
          },
          {
            "outputClaim": "firstName",
            "required": true,
            "inputClaim": "$.given_name",
            "indexed": false
          },
          {
            "outputClaim": "lastName",
            "required": true,
            "inputClaim": "$.family_name",
            "indexed": false
          }
        ],
        "required": false
      }
    ]
  },
  "validityInterval": 2592000,
  "vc": {
    "type": [
      "VerifiedCredentialExpert"
    ]
  }
}

应用程序注册

clientId 属性是在 OIDC 标识提供者中注册的应用程序的应用程序 ID。对于 Microsoft Entra ID，请通过执行下列步骤创建应用程序：

在 Azure 门户中，转到 Microsoft Entra ID。
选择“应用注册”并选择“新建注册”，然后为应用命名。

如果只希望租户中的帐户能够登录，请选中“仅此目录中的帐户”复选框。
在“重定向 URI(可选)”中，选择“公共客户端/本机(移动和桌面)”，然后输入“vcclient://openid/”。

如果要查看 Microsoft Entra ID 令牌中包含的声明，请执行以下步骤：

在左窗格中选择“身份验证”>“添加平台”>“Web”。
输入 https://jwt.ms 作为“重定向 URI”，并选择“ID 令牌(用于隐式流和混合流)”。
选择“配置” 。

完成 ID 令牌测试后，请考虑删除 https://jwt.ms 以及对隐式流和混合流提供的支持。

对于 Microsoft Entra ID：可以测试应用注册，并且如果启用了对重定向到 https://jwt.ms 的支持，可以在浏览器中运行以下内容来获取 ID 令牌：

https://login.microsoftonline.com/<your-tenantId>/oauth2/v2.0/authorize?client_id=<your-appId>&nonce=defaultNonce&redirect_uri=https%3A%2F%2Fjwt.ms&scope=openid%20profile&response_type=id_token&prompt=login

在代码中将 your-tenantId 替换为租户 ID<>。若要获取额外的声明，需要将配置文件作为范围的一部分。

对于 Azure Active Directory B2C：应用注册过程是相同的，但 B2C 在 Azure 门户中具有通过“运行用户流”功能来测试 B2C 策略的内置支持。

标识提供者的 ID 令牌中的声明

声明必须存在于返回的标识提供者中，以便它们能够成功填充可验证凭据。

如果声明不存在，则颁发的可验证凭据中不会有值。如果声明在配置文件中具有 null 值，则大多数 OIDC 标识提供者不会在 ID 凭据中颁发声明。请确保在 ID 令牌定义中包含声明，并确保已在用户配置文件中输入声明的值。

对于 Microsoft Entra ID：若要将声明配置为包含在令牌中，请参阅向应用提供可选声明。配置是根据应用程序进行的，因此此配置适用的应用应具有在规则定义的客户端 ID 中指定的应用程序 ID。

要匹配显示和规则定义，应将应用程序的 optionalClaims JSON 设置为如下所示：

"optionalClaims": {
    "idToken": [
        {
            "name": "upn",
            "source": null,
            "essential": false,
            "additionalProperties": []
        },
        {
            "name": "family_name",
            "source": null,
            "essential": false,
            "additionalProperties": []
        },
        {
            "name": "given_name",
            "source": null,
            "essential": false,
            "additionalProperties": []
        },
        {
            "name": "preferred_username",
            "source": null,
            "essential": false,
            "additionalProperties": []
        }
    ],
    "accessToken": [],
    "saml2Token": []
},

对于 Azure Active Directory B2C：是否在 ID 令牌中配置其他声明取决于 B2C 策略是用户流还是自定义策略。有关用户流的信息，请参阅在 Azure Active Directory B2C 中设置注册和登录流。有关自定义策略的信息，请参阅向应用提供可选声明。

对于其他标识提供者，请参阅相关文档。

配置示例用于颁发和验证自定义凭据

要配置示例代码用于颁发和验证自定义凭据，需要：

租户的颁发者分散式标识符 (DID)
凭据类型
指向凭据的清单 URL

查找自定义凭据的此信息的最简单方法是转到 Azure 门户中的凭据。选择“颁发凭据”。然后便可以访问具有请求服务 API JSON 有效负载的文本框。将占位符值替换为环境的信息。颁发者的 DID 是 authority 值。

快速入门自定义凭据颁发的屏幕截图。

后续步骤

查看规则和显示定义参考。

通过