为 JWT 访问令牌或 ID 令牌添加自定义字段¶

JWT（JSON Web Token）是一种在各方之间以 JSON 对象形式安全传输信息的常见方法。由于信息经过了数字签名，因此可以被验证和信任。使用 Authany，您可以很方便地为 JWT 访问令牌或 ID 令牌添加自定义字段。

本操作指南将带您了解如何使用 Authany 和 JavaScript Hooks，添加诸如 用户资料 等属性之类的自定义字段到 JWT 访问令牌/ID 令牌的 payload 中。

下面是 JWT 访问令牌默认包含的字段示例，以及对这些值的说明。

说明

您也可以在 Authany 管理台的用户资料上添加自定义属性。

前提条件¶

Authany 账号： 您需要一个 Authany 账号才能跟随本指南操作。如果还没有账号，可以在 Authany 官网免费创建一个。
已注册的应用： 您需要在 Authany 中拥有一个已注册的应用（客户端）。

修改访问令牌¶

为您的应用启用访问令牌¶

请确保在管理台的应用设置中已启用 Issue JWT as access token 选项。

登录您的 Authany 账号。
进入 Applications 标签页，选择已有的应用。
在 App Configuration 面板中，找到「Access token」部分。
打开 Issue JWT as access token 开关。

创建新的事件 Hook¶

借助 Hook，Authany 让您可以灵活地为身份验证流程添加自定义逻辑。您可以创建一个 Hook，在即将发生的事件时触发。例如，oidc.jwt.pre_create 事件会在签发 JWT 访问令牌之前发生，可以用它向令牌中添加额外信息。

进入 Authany 管理台的 Advanced->Hooks 部分。
新增一个 Blocking Event。
将 Block Hook 的 Type 选择为 TypeScript，并将 Event 选项设置为 oidc.jwt.pre_create。您将从零开始编写一个新的 TypeScript 函数。

在 Config 选项下点击 Edit Script。
将以下内容复制粘贴到编辑器中：

import { EventOIDCJWTPreCreate, EventOIDCJWTPreCreateHookResponse } from "https://deno.land/x/authgear_deno_hook@v2.0.0/mod.ts";

export default async function(e: EventOIDCJWTPreCreate): Promise<EventOIDCJWTPreCreateHookResponse> {
  return {
    mutations:{
      jwt: {
        payload:{
          ...e.payload.jwt.payload,
          standard_attributes: e.payload.user.standard_attributes,
          custom_attributes: e.payload.user.custom_attributes
        }
      }
    },
    is_allowed: true
  };
}

点击 Finish Editing。
从导航栏返回 Hooks 页面，点击页面顶部的 Save 按钮。

在上面的代码中，我们导入了所需的模块，例如 EventOIDCJWTPreCreateHookResponse 和 EventOIDCJWTPreCreate，它们是 Authany Deno hook TypeScript 库中的类型。我们通过添加用户的标准属性（e.payload.user.standard_attributes）和自定义属性（e.payload.user.custom_attributes）来修改 JWT payload。

验证 JWT 令牌中的自定义字段¶

有两种方式可以测试：

您可以在应用服务器端使用 JWT 解码器解码 JWT 令牌，并检查其中的 payload。
如果您创建的应用类型是 OIDC Client Application，需要按照下面的步骤操作。展开查看说明。

使用 OIDC Client Application 验证 JWT 令牌中的自定义字段

本节说明如何使用 **OpenID App** 的端点获取访问令牌，并检查新添加的自定义属性是否已出现在 JWT 访问令牌中。 **前提条件** * 请确保您在 Authany 管理台中已注册了类型为 **OIDC Client Application** 的应用。 **步骤 1：获取必要的参数** 打开您的 **OpenID Auth App** 配置，找到 **Client ID**、**Client Secret**，并查看 **Authorization** 和 **Token** 端点。接下来的步骤中会用到它们。 ![](../assets/image-10-1.png) ![](../assets/image-6-1.png) **步骤 2：构造授权端点 URL** 该端点的 URL 通常由授权服务器提供，其中包含指定所请求的 `scope`、`client_id` 和 response\_type 的参数。下面是授权端点 URL 的示例：

https://<YOUR_AUTHGEAR_ENDPOINT>/oauth2/authorize?client_id={YOUR_CLIENT_ID}&response_type=code&scope=openid

将 `` 替换为您 Authany 服务器的域名，将 `YOUR_CLIENT_ID` 替换为您应用在 **OpenID App** 中的 Client ID。 **步骤 3：将用户重定向到授权端点** 接下来，您需要将用户重定向到授权端点。您可以直接把该 URL 放到浏览器中，并使用您想为其获取访问令牌的用户凭据登录。成功完成身份验证和授权同意后，Authany 会将用户重定向回您指定的重定向 URI，并在查询参数中带上一个**授权码**。下一步会用到这个授权码

**步骤 4：获取访问令牌** 您需要向 **OpenID App 的 Token 端点**发起请求，用上一步获取的授权码换取访问令牌。 * Token 端点的 URL 通常类似于 `https:///oauth2/token`。 * 包含诸如 `grant_type=authorization_code`、`code=AUTHORIZATION_CODE`、`client_id=YOUR_CLIENT_ID`、`client_secret=YOUR_CLIENT_SECRET`、`redirect_uri=YOUR_REDIRECT_URI` 之类的参数。 * 向 Token 端点发起 POST 请求以获取访问令牌。

curl --request POST \
  --url 'https://<YOUR_AUTHGEAR_ENDPOINT>/oauth2/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=authorization_code \
  --data code={YOUR_AUTHORIZATION_CODE} \
  --data redirect_uri={YOUR_REDIRECT_URI} \
  --data 'client_id={YOUR_CLIENT_ID}' \
  --data client_secret={YOUR_CLIENT_SECRET} \
  --data scope=openid

**步骤 5：验证访问令牌中的自定义属性** 最后，我们可以使用 [JWT Debugger 工具](https://authany.com/tools/jwt-jwe-debugger) 调试访问令牌，查看之前添加的自定义字段及其值是否已出现在 JWT payload 中。

\\

修改 ID 令牌¶

借助 Hook，Authany 让您可以灵活地为身份验证流程添加自定义逻辑。您可以创建一个 Hook，在即将发生的事件时触发。例如，oidc.id_token.pre_create 事件会在签发 JWT 访问令牌之前发生，可以用它向令牌中添加额外信息。

进入 Authany 管理台的 Advanced->Hooks 部分。
新增一个 Blocking Event。
将 Block Hook 的 Type 选择为 TypeScript，并将 Event 选项设置为 oidc.id_token.pre_create。您将从零开始编写一个新的 TypeScript 函数。

在 Config 选项下点击 Edit Script。
将以下内容复制粘贴到编辑器中：

import { EventOIDCIDTokenPreCreate, EventOIDCIDTokenPreCreateHookResponse } from "https://deno.land/x/authgear_deno_hook@v2.0.0/mod.ts";

export default async function(e: EventOIDCIDTokenPreCreate): Promise<EventOIDCIDTokenPreCreateHookResponse> {
  const customAttributes = e.payload?.user?.custom_attributes ?? null;
  return {
    is_allowed: true,
    mutations: {
      id_token: {
        payload: {
          ...e.payload.id_token.payload,
          custom_attributes: customAttributes
        }
      }
    }
  }
}

点击 Finish Editing。
从导航栏返回 Hooks 页面，点击页面顶部的 Save 按钮。

在上面的代码中，我们导入了所需的模块，例如 EventOIDCIDTokenPreCreateHookResponse 和 EventOIDCIDTokenPreCreate，它们是 Authany Deno hook TypeScript 库中的类型。我们通过添加用户的自定义属性（e.payload.user.custom_attributes）来修改 JWT payload。