自定义访问令牌钩子

Customize the access token issued by Supabase Auth

自定义访问令牌钩子在发放令牌之前运行，允许你根据使用的身份验证方法添加额外的声明。

🌐 The custom access token hook runs before a token is issued and allows you to add additional claims based on the authentication method used.

返回的声明必须符合我们的规范。Supabase Auth 会在钩子运行后检查这些声明，如果不存在就会返回错误。

🌐 Claims returned must conform to our specification. Supabase Auth will check for these claims after the hook is run and return an error if they are not present.

这些是当前访问令牌上可用的字段：

🌐 These are the fields currently available on an access token:

必需的索赔：iss、aud、exp、iat、sub、role、aal、session_id、email、phone、is_anonymous

🌐 Required Claims: iss, aud, exp, iat, sub, role, aal, session_id, email, phone, is_anonymous

可选声明：jti、nbf、app_metadata、user_metadata、amr，

🌐 Optional Claims: jti, nbf, app_metadata, user_metadata, amr,

输入

字段	类型	描述
`user_id`	`string`	尝试登录的用户的唯一标识符
`claims`	`object`	包含在访问令牌中的声明
`authentication_method`	`string`	用于请求访问令牌的身份验证方法。可能的值包括：`oauth`、`password`、`otp`、`totp`、`recovery`、`invite`、`sso/saml`、`magiclink`、`email/signup`、`email_change`、`token_refresh`、`oauth_provider/authorization_code`、`anonymous`

1
{
2
  "user_id": "8ccaa7af-909f-44e7-84cb-67cdccb56be6",
3
  "claims": {
4
    "aud": "authenticated",
5
    "exp": 1715690221,
6
    "iat": 1715686621,
7
    "sub": "8ccaa7af-909f-44e7-84cb-67cdccb56be6",
8
    "email": "",
9
    "phone": "",
10
    "app_metadata": {},
11
    "user_metadata": {},
12
    "role": "authenticated",
13
    "aal": "aal1",
14
    "amr": [ { "method": "anonymous", "timestamp": 1715686621 } ],
15
    "session_id": "4b938a09-5372-4177-a314-cfa292099ea2",
16
    "is_anonymous": true,
17
    "client_id": "oauth-client-id-if-oauth-flow"
18
  },
19
  "authentication_method": "anonymous"
20
}

输出

只有在你的钩子处理输入没有错误时才返回这些。

🌐 Return these only if your hook processed the input without errors.

字段	类型	描述
`claims`	`object`	钩子运行后更新的声明。

有时候 JWT 的大小可能会成为问题，特别是如果你正在使用服务端渲染框架。JWT 可能变得过大的常见情况包括：

🌐 Sometimes the size of the JWT can be a problem especially if you're using a Server-Side Rendering framework. Common situations where the JWT can get too large include:

这个用户的名字、邮箱地址或电话号码特别长
默认的 JWT 从 OAuth 提供商那边带来的声明太多了
包含了一个大头像的链接

为了减小 JWT 的大小，你可以定义一个像下面这样的自定义访问令牌钩子，这将指示认证服务器只发放包含列出的声明的 JWT。查看上面的文档，了解必须存在且不能删除的 JWT 声明。

🌐 To lower the size of the JWT you can define a Custom Access Token hook like the one below which will instruct the Auth server to issue a JWT with only the listed claims. Check the documentation above on what JWT claims must be present and cannot be removed.

参考 Postgres JSON 函数来了解如何操作 jsonb 对象。

🌐 Refer to the Postgres JSON functions on how to manipulate jsonb objects.

1
create or replace function public.custom_access_token_hook(event jsonb)
2
returns jsonb
3
language plpgsql
4
as $$
5
  declare
6
    original_claims jsonb;
7
    new_claims jsonb;
8
    claim text;
9
  begin
10
    original_claims = event->'claims';
11
    new_claims = '{}'::jsonb;
12
13
    foreach claim in array array[
14
      -- add claims you want to keep here
15
      'iss',
16
      'aud',
17
      'exp',
18
      'iat',
19
      'sub',
20
      'role',
21
      'aal',
22
      'session_id',
23
      'email',
24
      'phone',
25
      'is_anonymous'
26
   ] loop
27
      if original_claims ? claim then
28
        -- original_claims contains one of the listed claims, set it on new_claims
29
        new_claims = jsonb_set(new_claims, array[claim], original_claims->claim);
30
      end if;
31
    end loop;
32
33
    return jsonb_build_object('claims', new_claims);
34
  end
35
$$;