如何排查PostgREST API中JWT认证导致的401错误

我是PostgreSQL新手，在使用无代码PostgREST API搭配JWT认证的项目中遭遇401未授权错误，陷入困境。登录成功后仍持续收到401错误，数据库日志显示ERROR: permission denied for view...，但admin-api服务仅输出请求详情无错误信息，请求协助排查原因。

Docker配置 #

运行两个Docker服务，compose文件启动正常，admin-api已连接数据库：

db:
    image: postgis/postgis:12-master
    ports:
      - '55432:5432'
    environment:
      POSTGRES_DB: #db_name
      POSTGRES_USER: #admin_user
      POSTGRES_PASSWORD: #admin_pass
    volumes:
      - type: bind
        source: ./db-schema
        target: /db-schema
        read_only: true
    command: >
        postgres -c custom.jwt_secret= #jwt_key_definition

  admin-api:
    image: postgrest/postgrest:v7.0.1
    ports:
      - "3000:3000"
    environment:
      PGRST_DB_URI: #db_uri
      PGRST_DB_SCHEMA: api
      PGRST_DB_ANON_ROLE: anonymous
      PGRST_LOG_LEVEL: "debug"
      PGRST_ROLE_CLAIM_KEY: '.role'
      PGRST_JWT_SECRET: #same_jwt_key_definition_as_above
    depends_on:
      - db

SQL配置 #

用SQL文件定义数据库schema，包含admin_users表，并为db_user角色授予视图权限。通过自定义sign_jwt函数处理登录并生成JWT，经jwt.io验证，生成的token签名有效且role声明正确：

create role db_user nologin;

grant anonymous to admin_user;
grant db_user to admin_user;

grant usage on schema api to anonymous;
grant usage on schema api to db_user;


CREATE OR REPLACE FUNCTION api.authenticate(
  IN username text,
  IN password text
)
RETURNS json
LANGUAGE plpgsql
SECURITY DEFINER
AS $$
DECLARE
  _user public.admin_users;
  jwt_token text;
BEGIN
  -- Add parameter validation
  IF username IS NULL OR password IS NULL THEN
    RETURN json_build_object('error', 'Email and password are required');
  END IF;

  SELECT * INTO _user
  FROM public.admin_users
  WHERE public.admin_users.email = username
  AND public.admin_users.password_hash = crypt(password, public.admin_users.password_hash);
  
  IF _user.id IS NULL THEN
    RETURN json_build_object('error', 'Invalid email or password');
  END IF;

  -- Prepare payload for JWT
  jwt_token := sign_jwt(
    jsonb_build_object(
      'user_id', _user.id,
      'role', _user.role,
      'exp', extract(epoch from (now() + interval '7 days'))::integer  -- Token expiration time
    ),
    current_setting('custom.jwt_secret',true)  -- Use from the environment
  );
  RAISE INFO 'JWT Token: %', jwt_token;

  -- Return the JWT token along with a success message
  RETURN json_build_object('message', 'Authentication successful', 'token', jwt_token);

END;
$$;

-- Grant execute permission to anonymous
GRANT EXECUTE ON FUNCTION api.authenticate(text, text) TO anonymous;

react-admin前端配置 #

前端使用react-admin搭配ra-data-postgrest包，登录函数获取到"Authentication successful"响应并将token存入authData.token，通过httpClient函数将token添加到请求头：

// HTTP client that adds JWT auth header
export const httpClient = (url: string, options: any = {}) => {
  const authData = JSON.parse(localStorage.getItem('auth') || '{}');
  console.log("Auth Data for httpClient:", authData);

  if (!authData || !authData.token) {
    return fetchUtils.fetchJson(url, options);
  }

  options.user = {
        authenticated: true,
        token: `${authData.token}`,
    };

  if (!options.headers) {
    options.headers = new Headers({ 'Content-Type': 'application/json' });
  }

  options.headers.set('Authorization', `Bearer ${authData.token}`);
  console.log("Request Headers:", Object.fromEntries(options.headers));

  return fetchUtils.fetchJson(url, options);
};

1. 补全角色的视图/表访问权限 #

数据库日志提示权限不足，说明JWT对应的角色仅拥有schema的usage权限，缺少具体视图/表的访问权限。执行以下SQL补全：

-- 给db_user授权目标视图的查询权限
GRANT SELECT ON api.目标视图名 TO db_user;
-- 如果操作表，需要对应增删改查权限
GRANT SELECT, INSERT, UPDATE, DELETE ON api.目标表名 TO db_user;
-- 若表有自增ID序列，需同步授权
GRANT USAGE, SELECT ON SEQUENCE api.目标表_id_seq TO db_user;

2. 验证JWT角色与数据库角色匹配 #

• 用jwt.io解析token，确认payload中role字段的值与数据库中定义的db_user完全一致（PostgreSQL角色名大小写敏感）。
• 检查api.authenticate函数中_user.role的实际取值，确保从admin_users表取出的角色是合法的数据库角色。

3. 修正JWT密钥配置 #

• 清理数据库启动命令中的注释，确保custom.jwt_secret设置正确：

  command: >
      postgres -c custom.jwt_secret=你的实际密钥
  

• 确认PostgREST的PGRST_JWT_SECRET与数据库的custom.jwt_secret完全一致，包括特殊字符、大小写。

4. 检查PostgREST角色切换日志 #

查看PostgREST的debug日志，确认请求时是否输出Switching role to "db_user"类的条目。如果没有，说明：

• JWT的role字段未被正确识别，检查PGRST_ROLE_CLAIM_KEY是否匹配JWT payload的字段路径（当前配置.role对应顶级role字段）。
• JWT签名无效，或token已过期。

5. 验证前端请求头 #

打开浏览器开发者工具的Network面板，查看请求的Authorization头：

• 确认头格式为Bearer 完整token，无空格或截断。
• 确认请求没有被跨域策略或前端中间件拦截导致头丢失。

6. 检查视图依赖权限 #

如果视图查询了其他schema的表，需给db_user授予这些底层表的对应权限，否则即使视图本身授权，仍会因底层表权限不足报错。

内容的提问来源于stack exchange，提问作者bt-nick