feat(backend): validate JWT issuer (iss) claim when an issuer option is provided (#8772)

Co-authored-by: Dominic Couture <dominic@clerk.dev>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
Co-authored-by: wobsoriano <sorianorobertc@gmail.com>

Author: 4 people

.changeset/backend-issuer-validation.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Added an optional `issuer` option to `verifyJwt()`, `verifyToken()`, and `authenticateRequest()` to validate the JWT `iss` claim against a string or list of allowed strings. For `verifyToken()` and `authenticateRequest()`, this applies only to session tokens. Omitting `issuer` preserves existing behavior.

packages/backend/src/errors.ts

@@ -15,6 +15,7 @@ export const TokenVerificationErrorReason = {
   TokenInvalid: 'token-invalid',
   TokenInvalidAlgorithm: 'token-invalid-algorithm',
   TokenInvalidAuthorizedParties: 'token-invalid-authorized-parties',
+  TokenInvalidIssuer: 'token-invalid-issuer',
   TokenInvalidSignature: 'token-invalid-signature',
   TokenNotActiveYet: 'token-not-active-yet',
   TokenIatInTheFuture: 'token-iat-in-the-future',

packages/backend/src/jwt/__tests__/assertions.test.ts

@@ -8,6 +8,7 @@ import {
   assertHeaderAlgorithm,
   assertHeaderType,
   assertIssuedAtClaim,
+  assertIssuerClaim,
   assertOAuthAudienceClaim,
   assertSubClaim,
 } from '../assertions';
@@ -264,6 +265,43 @@ describe('assertAuthorizedPartiesClaim(azp?, authorizedParties?)', () => {
   });
 });
 
+describe('assertIssuerClaim(iss, issuer?)', () => {
+  const iss = 'https://clerk.example.com';
+
+  it('does not throw if no issuer is provided (opt-in)', () => {
+    expect(() => assertIssuerClaim(iss)).not.toThrow();
+    expect(() => assertIssuerClaim(iss, undefined)).not.toThrow();
+    expect(() => assertIssuerClaim(undefined)).not.toThrow();
+    expect(() => assertIssuerClaim(iss, '')).not.toThrow();
+    expect(() => assertIssuerClaim(iss, [])).not.toThrow();
+  });
+
+  it('does not throw if iss exactly matches the issuer string', () => {
+    expect(() => assertIssuerClaim(iss, iss)).not.toThrow();
+  });
+
+  it('does not throw if iss is included in the issuer list', () => {
+    expect(() => assertIssuerClaim(iss, ['https://clerk.other.com', iss])).not.toThrow();
+  });
+
+  it('throws if iss does not match the issuer string', () => {
+    expect(() => assertIssuerClaim(iss, 'https://clerk.evil.com')).toThrow(
+      `Invalid JWT issuer claim (iss) "https://clerk.example.com".`,
+    );
+  });
+
+  it('throws if iss is not included in the issuer list', () => {
+    expect(() => assertIssuerClaim(iss, ['https://clerk.evil.com', 'https://clerk.other.com'])).toThrow(
+      `Invalid JWT issuer claim (iss) "https://clerk.example.com".`,
+    );
+  });
+
+  it('throws if iss is missing or not a string when an issuer is required', () => {
+    expect(() => assertIssuerClaim(undefined, iss)).toThrow(`Invalid JWT issuer claim (iss) undefined.`);
+    expect(() => assertIssuerClaim(42, iss)).toThrow(`Invalid JWT issuer claim (iss) 42.`);
+  });
+});
+
 describe('assertExpirationClaim(exp, clockSkewInMs)', () => {
   beforeEach(() => {
     vi.useFakeTimers();

packages/backend/src/jwt/__tests__/verifyJwt.test.ts

@@ -119,16 +119,44 @@ describe('verifyJwt(jwt, options)', () => {
     expect(data).toEqual(mockJwtPayload);
   });
 
-  it('returns the valid JWT payload if valid key & issuer method & azp is given', async () => {
+  it('returns the valid JWT payload if valid key & issuer list & azp is given', async () => {
     const inputVerifyJwtOptions = {
       key: mockJwks.keys[0],
-      issuer: (iss: string) => iss.startsWith('https://clerk'),
+      issuer: ['https://clerk.other-app.com', mockJwtPayload.iss],
       authorizedParties: ['https://accounts.inspired.puma-74.lcl.dev'],
     };
     const { data } = await verifyJwt(mockJwt, inputVerifyJwtOptions);
     expect(data).toEqual(mockJwtPayload);
   });
 
+  it('returns an error if the issuer string does not match the iss claim', async () => {
+    const { errors: [error] = [] } = await verifyJwt(mockJwt, {
+      key: mockJwks.keys[0],
+      issuer: 'https://clerk.another-app.com',
+      authorizedParties: ['https://accounts.inspired.puma-74.lcl.dev'],
+    });
+    expect(error?.reason).toBe('token-invalid-issuer');
+    expect(error?.message).toContain('Invalid JWT issuer claim (iss)');
+  });
+
+  it('returns an error if no issuer in the list matches the iss claim', async () => {
+    const { errors: [error] = [] } = await verifyJwt(mockJwt, {
+      key: mockJwks.keys[0],
+      issuer: ['https://clerk.another-app.com', 'https://clerk.other-app.com'],
+      authorizedParties: ['https://accounts.inspired.puma-74.lcl.dev'],
+    });
+    expect(error?.reason).toBe('token-invalid-issuer');
+  });
+
+  it('does not validate the iss claim when no issuer is provided', async () => {
+    const { data, errors } = await verifyJwt(mockJwt, {
+      key: mockJwks.keys[0],
+      authorizedParties: ['https://accounts.inspired.puma-74.lcl.dev'],
+    });
+    expect(errors).toBeUndefined();
+    expect(data).toEqual(mockJwtPayload);
+  });
+
   it('returns the valid JWT payload if valid key & issuer & list of azp (with empty string) is given', async () => {
     const inputVerifyJwtOptions = {
       key: mockJwks.keys[0],

packages/backend/src/jwt/assertions.ts

@@ -1,8 +1,6 @@
 import { TokenVerificationError, TokenVerificationErrorAction, TokenVerificationErrorReason } from '../errors';
 import { algs } from './algorithms';
 
-export type IssuerResolver = string | ((iss: string) => boolean);
-
 const isArrayString = (s: unknown): s is string[] => {
   return Array.isArray(s) && s.length > 0 && s.every(a => typeof a === 'string');
 };
@@ -126,6 +124,21 @@ export const assertAuthorizedPartiesClaim = (azp?: string, authorizedParties?: s
   }
 };
 
+export const assertIssuerClaim = (iss: unknown, issuer?: string | string[]) => {
+  const issuerList = [issuer].flat().filter(i => !!i);
+  if (issuerList.length === 0) {
+    return;
+  }
+
+  if (typeof iss !== 'string' || !issuerList.includes(iss)) {
+    throw new TokenVerificationError({
+      action: TokenVerificationErrorAction.EnsureClerkJWT,
+      reason: TokenVerificationErrorReason.TokenInvalidIssuer,
+      message: `Invalid JWT issuer claim (iss) ${JSON.stringify(iss)}. Expected "${issuerList}".`,
+    });
+  }
+};
+
 export const assertExpirationClaim = (exp: number, clockSkewInMs: number) => {
   if (typeof exp !== 'number') {
     throw new TokenVerificationError({

packages/backend/src/jwt/verifyJwt.ts

@@ -12,6 +12,7 @@ import {
   assertHeaderAlgorithm,
   assertHeaderType,
   assertIssuedAtClaim,
+  assertIssuerClaim,
   assertSubClaim,
 } from './assertions';
 import { importKey } from './cryptoKeys';
@@ -131,6 +132,7 @@ export type VerifyJwtOptions = {
    * @default 5000
    */
   clockSkewInMs?: number;
+  issuer?: string | string[];
   /**
    * @internal
    */
@@ -146,7 +148,7 @@ export async function verifyJwt(
   token: string,
   options: VerifyJwtOptions,
 ): Promise<JwtReturnType<JwtPayload, TokenVerificationError>> {
-  const { audience, authorizedParties, clockSkewInMs, key, headerType } = options;
+  const { audience, authorizedParties, clockSkewInMs, issuer, key, headerType } = options;
   const clockSkew =
     typeof clockSkewInMs === 'number' && Number.isFinite(clockSkewInMs) ? clockSkewInMs : DEFAULT_CLOCK_SKEW_IN_MS;
 
@@ -194,11 +196,12 @@ export async function verifyJwt(
 
   // Payload verifications (only after signature is confirmed valid)
   try {
-    const { azp, sub, aud, iat, exp, nbf } = payload;
+    const { azp, sub, aud, iss, iat, exp, nbf } = payload;
 
     assertSubClaim(sub);
     assertAudienceClaim(aud, audience);
     assertAuthorizedPartiesClaim(azp, authorizedParties);
+    assertIssuerClaim(iss, issuer);
     assertExpirationClaim(exp, clockSkew);
     assertActivationClaim(nbf, clockSkew);
     assertIssuedAtClaim(iat, clockSkew);

packages/backend/src/jwt/verifyMachineJwt.ts

@@ -72,8 +72,9 @@ async function resolveKeyAndVerifyJwt(
     }
 
     const { data: payload, errors: verifyErrors } = await verifyJwt(token, {
-      ...options,
       key,
+      audience: options.audience,
+      clockSkewInMs: options.clockSkewInMs,
       ...(headerType ? { headerType } : {}),
     });
 

packages/backend/src/tokens/__tests__/verify.test.ts

@@ -86,6 +86,28 @@ describe('tokens.verify(token, options)', () => {
     expect(result.errors).toBeUndefined();
   });
 
+  it('rejects the token when the provided issuer option does not match the iss claim', async () => {
+    server.use(
+      http.get(
+        'https://api.clerk.test/v1/jwks',
+        validateHeaders(() => {
+          return HttpResponse.json(mockJwks);
+        }),
+      ),
+    );
+
+    const { data, errors } = await verifyToken(mockJwt, {
+      apiUrl: 'https://api.clerk.test',
+      secretKey: 'a-valid-key',
+      authorizedParties: ['https://accounts.inspired.puma-74.lcl.dev'],
+      issuer: 'https://clerk.another-app.com',
+      skipJwksCache: true,
+    });
+
+    expect(data).toBeUndefined();
+    expect(errors?.[0].reason).toBe('token-invalid-issuer');
+  });
+
   it('verifies the token by fetching the JWKs from Backend API when secretKey is provided', async () => {
     server.use(
       http.get(
@@ -866,6 +888,45 @@ describe('tokens.verifyMachineAuthToken(token, options)', () => {
       expect(result.errors).toBeUndefined();
     });
 
+    it('rejects an M2M JWT whose aud does not include the configured audience', async () => {
+      server.use(http.get('https://api.clerk.test/v1/jwks', () => HttpResponse.json(mockJwks)));
+      const token = await createSignedM2MJwt();
+
+      const result = await verifyMachineAuthToken(token, {
+        apiUrl: 'https://api.clerk.test',
+        secretKey: 'a-valid-key',
+        audience: 'mch_3xxxxx',
+      });
+
+      expect(result.tokenType).toBe('m2m_token');
+      expect(result.data).toBeUndefined();
+      expect(result.errors?.[0].code).toBe('token-verification-failed');
+      expect(result.errors?.[0].message).toContain('Invalid JWT audience claim array (aud)');
+    });
+
+    it('ignores a session-token issuer option when verifying an M2M JWT', async () => {
+      server.use(
+        http.get(
+          'https://api.clerk.test/v1/jwks',
+          validateHeaders(() => {
+            return HttpResponse.json(mockJwks);
+          }),
+        ),
+      );
+
+      const m2mJwt = await createSignedM2MJwt();
+
+      const result = await verifyMachineAuthToken(m2mJwt, {
+        apiUrl: 'https://api.clerk.test',
+        secretKey: 'a-valid-key',
+        issuer: 'https://clerk.inspired.puma-74.lcl.dev',
+      });
+
+      expect(result.tokenType).toBe('m2m_token');
+      expect(result.errors).toBeUndefined();
+      expect(result.data).toBeDefined();
+    });
+
     it('rejects M2M JWT with alg: none', async () => {
       server.use(
         http.get(