认证

自定义访问令牌钩子

自定义由 Supabase Auth 颁发的访问令牌

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

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

以下是当前访问令牌中可用的字段：

必需声明：iss, aud, exp, iat, sub, role, aal, session_id 可选声明：jti, nbf, app_metadata, user_metadata, amr, email, phone

输入参数

字段类型描述
user_idstring尝试登录用户的唯一标识符
claimsobject包含在访问令牌中的声明信息
authentication_methodstring用于请求访问令牌的认证方法。可能的值包括：oauth, password, otp, totp, recovery, invite, sso/saml, magiclink, email/signup, email_change, token_refresh, anonymous
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{  "user_id": "8ccaa7af-909f-44e7-84cb-67cdccb56be6",  "claims": {    "aud": "authenticated",    "exp": 1715690221,    "iat": 1715686621,    "sub": "8ccaa7af-909f-44e7-84cb-67cdccb56be6",    "email": "",    "phone": "",    "app_metadata": {},    "user_metadata": {},    "role": "authenticated",    "aal": "aal1",    "amr": [ { "method": "anonymous", "timestamp": 1715686621 } ],    "session_id": "4b938a09-5372-4177-a314-cfa292099ea2",    "is_anonymous": true  },  "authentication_method": "anonymous"}

输出

仅当您的钩子成功处理输入且没有错误时返回这些内容。

字段类型描述
claimsobject钩子运行后更新后的声明(claims)对象。

在某些情况下，JWT的大小可能会成为问题，特别是当您使用服务端渲染框架时。导致JWT过大的常见情况包括：

  • 用户有特别长的姓名、电子邮件地址或电话号码
  • 默认JWT包含来自OAuth提供商的过多声明
  • 包含过大的头像URL

为了减小JWT的大小，您可以定义如下所示的Custom Access Token钩子，它将指示Auth服务器仅签发包含列出声明的JWT。请查阅上方文档了解哪些JWT声明必须存在且不能被移除。

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
create or replace function public.custom_access_token_hook(event jsonb)returns jsonblanguage plpgsqlas $$  declare    original_claims jsonb;    new_claims jsonb;    claim text;  begin    original_claims = event->'claims';    new_claims = '{}'::jsonb;    foreach claim in array array[      -- 在此添加您想保留的声明      'iss',      'aud',      'exp',      'iat',      'sub',      'role',      'aal',      'session_id'   ] loop      if original_claims ? claim then        -- 如果original_claims包含列出的声明之一，将其设置到new_claims中        new_claims = jsonb_set(new_claims, array[claim], original_claims->claim);      end if;    end loop;    return jsonb_build_object('claims', new_claims);  end$$;