Merge pull request #13595 from DavidZemon/feature/allow-more-jwt-claims

feat: Allow passing additional JWT claims to `TokenIssuer`

plugins/auth-backend/api-report.md

@@ -706,7 +706,7 @@ export type TokenParams = {
   claims: {
     sub: string;
     ent?: string[];
-  };
+  } & Record<string, JsonValue>;
 };
 
 // @public (undocumented)

plugins/auth-backend/src/identity/TokenFactory.test.ts

@@ -48,7 +48,12 @@ describe('TokenFactory', () => {
 
     await expect(factory.listPublicKeys()).resolves.toEqual({ keys: [] });
     const token = await factory.issueToken({
-      claims: { sub: entityRef, ent: [entityRef] },
+      claims: {
+        sub: entityRef,
+        ent: [entityRef],
+        'x-fancy-claim': 'my special claim',
+        aud: 'this value will be overridden',
+      },
     });
 
     const { keys } = await factory.listPublicKeys();
@@ -60,6 +65,7 @@ describe('TokenFactory', () => {
       aud: 'backstage',
       sub: entityRef,
       ent: [entityRef],
+      'x-fancy-claim': 'my special claim',
       iat: expect.any(Number),
       exp: expect.any(Number),
     });

plugins/auth-backend/src/identity/TokenFactory.ts

@@ -77,8 +77,7 @@ export class TokenFactory implements TokenIssuer {
     const key = await this.getKey();
 
     const iss = this.issuer;
-    const sub = params.claims.sub;
-    const ent = params.claims.ent;
+    const { sub, ent, ...additionalClaims } = params.claims;
     const aud = 'backstage';
     const iat = Math.floor(Date.now() / MS_IN_S);
     const exp = iat + this.keyDurationSeconds;
@@ -98,7 +97,7 @@ export class TokenFactory implements TokenIssuer {
       throw new AuthenticationError('No algorithm was provided in the key');
     }
 
-    return new SignJWT({ iss, sub, ent, aud, iat, exp })
+    return new SignJWT({ ...additionalClaims, iss, sub, ent, aud, iat, exp })
       .setProtectedHeader({ alg: key.alg, kid: key.kid })
       .setIssuer(iss)
       .setAudience(aud)

plugins/auth-backend/src/identity/types.ts

@@ -14,6 +14,8 @@
  * limitations under the License.
  */
 
+import { JsonValue } from '@backstage/types';
+
 /** Represents any form of serializable JWK */
 export interface AnyJWK extends Record<string, string> {
   use: 'sig';
@@ -28,13 +30,20 @@ export interface AnyJWK extends Record<string, string> {
  * @public
  */
 export type TokenParams = {
-  /** The claims that will be embedded within the token */
+  /**
+   * The claims that will be embedded within the token. At a minimum, this should include
+   * the subject claim, `sub`. It is common to also list entity ownership relations in the
+   * `ent` list. Additional claims may also be added at the developer's discretion except
+   * for the following list, which will be overwritten by the TokenIssuer: `iss`, `aud`,
+   * `iat`, and `exp`. The Backstage team also maintains the right add new claims in the future
+   * without listing the change as a "breaking change".
+   */
   claims: {
     /** The token subject, i.e. User ID */
     sub: string;
     /** A list of entity references that the user claims ownership through */
     ent?: string[];
-  };
+  } & Record<string, JsonValue>;
 };
 
 /**