Add configurable JWT claim paths for OIDC flexibility

Adds environment variables to configure JWT claim paths, allowing
deployments to use custom namespaces and claim names that match their
OIDC provider's token structure:

- JWT_CLAIMS_NAMESPACE: The namespace key in the JWT (default: https://hasura.io/jwt/claims)
- JWT_CLAIMS_USER_ID: Claim name for user ID (default: x-hasura-user-id)
- JWT_CLAIMS_ALLOWED_ROLES: Claim name for allowed roles (default: x-hasura-allowed-roles)
- JWT_CLAIMS_DEFAULT_ROLE: Claim name for default role (default: x-hasura-default-role)

This matches the claim path configurability in Aerie UI, enabling
consistent configuration across both applications when using custom
OIDC providers like Keycloak.

Co-Authored-By: Pranav Subramanian <pranav@example.com>

Author: 2 people

.env.template

@@ -9,3 +9,11 @@ HASURA_API_URL=http://localhost:8080
 # JWT configuration. For OIDC/JWKS, include jwk_url, issuer, and audience:
 # HASURA_GRAPHQL_JWT_SECRET='{ "jwk_url": "https://your-oidc-provider/.well-known/jwks", "issuer": "https://your-oidc-provider", "audience": "your-client-id" }'
 HASURA_GRAPHQL_JWT_SECRET=
+
+# JWT claim paths - customize where user ID, roles, etc. are read from in the JWT.
+# Defaults follow Hasura's JWT claims namespace convention.
+# These should match your OIDC provider's token mapper configuration.
+# JWT_CLAIMS_NAMESPACE=https://hasura.io/jwt/claims
+# JWT_CLAIMS_USER_ID=x-hasura-user-id
+# JWT_CLAIMS_ALLOWED_ROLES=x-hasura-allowed-roles
+# JWT_CLAIMS_DEFAULT_ROLE=x-hasura-default-role

src/env.ts

@@ -2,6 +2,18 @@ import type { Algorithm } from 'jsonwebtoken';
 import { GroupRoleMapping } from './types/auth';
 import { StringValue } from 'ms';
 
+/**
+ * JWT claim path configuration.
+ * Allows customization of where user ID, roles, and other claims are read from in the JWT.
+ * Defaults follow Hasura's JWT claims namespace convention.
+ */
+export type JwtClaimsConfig = {
+  namespace: string;
+  userId: string;
+  allowedRoles: string;
+  defaultRole: string;
+};
+
 export type Env = {
   ALLOWED_ROLES: string[];
   ALLOWED_ROLES_NO_AUTH: string[];
@@ -17,6 +29,7 @@ export type Env = {
   HASURA_API_URL: string;
   HASURA_GRAPHQL_JWT_SECRET: string;
   JWT_ALGORITHMS: Algorithm[];
+  JWT_CLAIMS: JwtClaimsConfig;
   JWT_EXPIRATION: StringValue;
   LOG_FILE: string;
   LOG_LEVEL: string;
@@ -30,6 +43,13 @@ export type Env = {
   VERSION: string;
 };
 
+export const defaultJwtClaims: JwtClaimsConfig = {
+  namespace: 'https://hasura.io/jwt/claims',
+  userId: 'x-hasura-user-id',
+  allowedRoles: 'x-hasura-allowed-roles',
+  defaultRole: 'x-hasura-default-role',
+};
+
 export const defaultEnv: Env = {
   AERIE_DB_HOST: 'localhost',
   AERIE_DB_PORT: '5432',
@@ -49,6 +69,7 @@ export const defaultEnv: Env = {
   HASURA_API_URL: 'http://hasura:8080',
   HASURA_GRAPHQL_JWT_SECRET: '',
   JWT_ALGORITHMS: ['RS256'],
+  JWT_CLAIMS: defaultJwtClaims,
   JWT_EXPIRATION: '36h' as StringValue,
   LOG_FILE: 'console',
   LOG_LEVEL: 'info',
@@ -121,6 +142,12 @@ export function getEnv(): Env {
   const HASURA_GRAPHQL_JWT_SECRET = env['HASURA_GRAPHQL_JWT_SECRET'] ?? defaultEnv.HASURA_GRAPHQL_JWT_SECRET;
   const HASURA_API_URL = env['HASURA_API_URL'] ?? defaultEnv.HASURA_API_URL;
   const JWT_ALGORITHMS = parseArray(env['JWT_ALGORITHMS'], defaultEnv.JWT_ALGORITHMS);
+  const JWT_CLAIMS: JwtClaimsConfig = {
+    namespace: env['JWT_CLAIMS_NAMESPACE'] ?? defaultJwtClaims.namespace,
+    userId: env['JWT_CLAIMS_USER_ID'] ?? defaultJwtClaims.userId,
+    allowedRoles: env['JWT_CLAIMS_ALLOWED_ROLES'] ?? defaultJwtClaims.allowedRoles,
+    defaultRole: env['JWT_CLAIMS_DEFAULT_ROLE'] ?? defaultJwtClaims.defaultRole,
+  };
   const JWT_EXPIRATION = (env['JWT_EXPIRATION'] as StringValue) ?? defaultEnv.JWT_EXPIRATION;
   const LOG_FILE = env['LOG_FILE'] ?? defaultEnv.LOG_FILE;
   const LOG_LEVEL = env['LOG_LEVEL'] ?? defaultEnv.LOG_LEVEL;
@@ -152,6 +179,7 @@ export function getEnv(): Env {
     HASURA_API_URL,
     HASURA_GRAPHQL_JWT_SECRET,
     JWT_ALGORITHMS,
+    JWT_CLAIMS,
     JWT_EXPIRATION,
     LOG_FILE,
     LOG_LEVEL,

src/main.ts

@@ -1,23 +1,23 @@
+import cookieParser from 'cookie-parser';
 import cors from 'cors';
 import express from 'express';
 import helmet from 'helmet';
 import { getEnv } from './env.js';
 import getLogger from './logger.js';
 import initApiPlaygroundRoutes from './packages/api-playground/api-playground.js';
+import { CAMAuthAdapter } from './packages/auth/adapters/CAMAuthAdapter.js';
+import { NoAuthAdapter } from './packages/auth/adapters/NoAuthAdapter.js';
+import { validateGroupRoleMappings } from './packages/auth/functions.js';
 import initAuthRoutes from './packages/auth/routes.js';
-import initExpansionRoutes from './packages/expansion/expansion.js';
 import { DbMerlin } from './packages/db/db.js';
+import initExpansionRoutes from './packages/expansion/expansion.js';
+import initExternalSourceRoutes from './packages/external-source/external-source.js';
 import initFileRoutes from './packages/files/files.js';
 import initHasuraRoutes from './packages/hasura/hasura-events.js';
 import initHealthRoutes from './packages/health/health.js';
 import initPlanRoutes from './packages/plan/plan.js';
 import initSwaggerRoutes from './packages/swagger/swagger.js';
-import initExternalSourceRoutes from './packages/external-source/external-source.js';
-import cookieParser from 'cookie-parser';
 import { AuthAdapter } from './types/auth.js';
-import { NoAuthAdapter } from './packages/auth/adapters/NoAuthAdapter.js';
-import { CAMAuthAdapter } from './packages/auth/adapters/CAMAuthAdapter.js';
-import { validateGroupRoleMappings } from './packages/auth/functions.js';
 
 async function main(): Promise<void> {
   const logger = getLogger('main');

src/packages/auth/functions.ts

@@ -211,15 +211,15 @@ export function generateJwt(
   expiry: StringValue = getEnv().JWT_EXPIRATION,
 ): string | null {
   try {
-    const { HASURA_GRAPHQL_JWT_SECRET } = getEnv();
+    const { HASURA_GRAPHQL_JWT_SECRET, JWT_CLAIMS } = getEnv();
     const { key, type }: JwtSecret = JSON.parse(HASURA_GRAPHQL_JWT_SECRET);
     if (key) {
       const options: jwt.SignOptions = { algorithm: type as Algorithm, expiresIn: expiry };
       const payload: JwtPayload = {
-        'https://hasura.io/jwt/claims': {
-          'x-hasura-allowed-roles': allowedRoles,
-          'x-hasura-default-role': defaultRole,
-          'x-hasura-user-id': username,
+        [JWT_CLAIMS.namespace]: {
+          [JWT_CLAIMS.allowedRoles]: allowedRoles,
+          [JWT_CLAIMS.defaultRole]: defaultRole,
+          [JWT_CLAIMS.userId]: username,
         },
         username,
       };

src/packages/auth/middleware.ts

@@ -1,4 +1,5 @@
 import type { NextFunction, Request, Response } from 'express';
+import { getEnv } from '../../env.js';
 import { decodeJwt, session } from './functions.js';
 
 export const auth = async (req: Request, res: Response, next: NextFunction) => {
@@ -24,8 +25,15 @@ export const adminOnlyAuth = async (req: Request, res: Response, next: NextFunct
       return;
     }
 
-    const defaultRole = jwtPayload['https://hasura.io/jwt/claims']['x-hasura-default-role'] as string;
-    const allowedRoles = jwtPayload['https://hasura.io/jwt/claims']['x-hasura-allowed-roles'] as string[];
+    const { JWT_CLAIMS } = getEnv();
+    const namespace = jwtPayload[JWT_CLAIMS.namespace] as Record<string, string | string[]>;
+    if (!namespace) {
+      res.status(401).send({ message: `JWT missing claims namespace: ${JWT_CLAIMS.namespace}` });
+      return;
+    }
+
+    const defaultRole = namespace[JWT_CLAIMS.defaultRole] as string;
+    const allowedRoles = namespace[JWT_CLAIMS.allowedRoles] as string[];
 
     const { headers } = req;
     const { 'x-hasura-role': role } = headers;

src/types/auth.ts

@@ -7,8 +7,10 @@ export type JwtDecode = {
   jwtPayload: JwtPayload | null;
 };
 
+// JWT payload with configurable claims namespace
+// The namespace key is dynamic (configured via JWT_CLAIMS_NAMESPACE)
 export type JwtPayload = {
-  'https://hasura.io/jwt/claims': Record<string, string | string[]>;
+  [namespace: string]: Record<string, string | string[]> | string;
   username: string;
 };
 

test/jwt.test.ts

@@ -301,3 +301,91 @@ describe('decodeJwt with HS256 static key', () => {
     expect(result.jwtErrorMessage).toContain('invalid signature');
   });
 });
+
+describe('configurable JWT claim paths', () => {
+  beforeEach(() => {
+    vi.stubEnv('JWT_ALGORITHMS', JSON.stringify(['RS256']));
+    vi.stubEnv(
+      'HASURA_GRAPHQL_JWT_SECRET',
+      JSON.stringify({
+        type: 'RS256',
+        key: publicKey,
+      }),
+    );
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  test('reads claims from default Hasura namespace', async () => {
+    // Default namespace: https://hasura.io/jwt/claims
+    const payload = {
+      'https://hasura.io/jwt/claims': {
+        'x-hasura-allowed-roles': ['admin', 'user'],
+        'x-hasura-default-role': 'admin',
+        'x-hasura-user-id': 'user-123',
+      },
+      username: 'user-123',
+    };
+    const token = signToken(payload);
+
+    const result = await decodeJwt(`Bearer ${token}`);
+
+    expect(result.jwtErrorMessage).toBe('');
+    expect(result.jwtPayload).not.toBeNull();
+    const namespace = result.jwtPayload?.['https://hasura.io/jwt/claims'] as Record<string, unknown>;
+    expect(namespace['x-hasura-user-id']).toBe('user-123');
+    expect(namespace['x-hasura-allowed-roles']).toEqual(['admin', 'user']);
+    expect(namespace['x-hasura-default-role']).toBe('admin');
+  });
+
+  test('reads claims from custom namespace when configured', async () => {
+    // Custom namespace
+    vi.stubEnv('JWT_CLAIMS_NAMESPACE', 'custom/claims');
+    vi.stubEnv('JWT_CLAIMS_USER_ID', 'sub');
+    vi.stubEnv('JWT_CLAIMS_ALLOWED_ROLES', 'roles');
+    vi.stubEnv('JWT_CLAIMS_DEFAULT_ROLE', 'primary_role');
+
+    const payload = {
+      'custom/claims': {
+        sub: 'custom-user-456',
+        roles: ['editor', 'viewer'],
+        primary_role: 'editor',
+      },
+      username: 'custom-user-456',
+    };
+    const token = signToken(payload);
+
+    const result = await decodeJwt(`Bearer ${token}`);
+
+    expect(result.jwtErrorMessage).toBe('');
+    expect(result.jwtPayload).not.toBeNull();
+    const namespace = result.jwtPayload?.['custom/claims'] as Record<string, unknown>;
+    expect(namespace['sub']).toBe('custom-user-456');
+    expect(namespace['roles']).toEqual(['editor', 'viewer']);
+    expect(namespace['primary_role']).toBe('editor');
+  });
+
+  test('supports Keycloak-style claim paths', async () => {
+    // Keycloak typically uses realm_access.roles or resource_access
+    vi.stubEnv('JWT_CLAIMS_NAMESPACE', 'realm_access');
+    vi.stubEnv('JWT_CLAIMS_ALLOWED_ROLES', 'roles');
+
+    const payload = {
+      realm_access: {
+        roles: ['aerie_admin', 'aerie_user'],
+      },
+      preferred_username: 'keycloak-user',
+      username: 'keycloak-user',
+    };
+    const token = signToken(payload);
+
+    const result = await decodeJwt(`Bearer ${token}`);
+
+    expect(result.jwtErrorMessage).toBe('');
+    expect(result.jwtPayload).not.toBeNull();
+    const namespace = result.jwtPayload?.['realm_access'] as Record<string, unknown>;
+    expect(namespace['roles']).toEqual(['aerie_admin', 'aerie_user']);
+  });
+});