feat: Make sub in access tokens an optional feature

Author: joachimvh

documentation/getting-started.md

@@ -43,7 +43,9 @@ so some information might change depending on which version and branch you're us
       - [Authentication methods](#authentication-methods)
       - [Customizing OIDC verification](#customizing-oidc-verification)
     + [Generate token](#generate-token)
+      - [Enabling optional token features](#enabling-optional-token-features)
       - [Partial permission tokens](#partial-permission-tokens)
+      - [Include `sub` claim in access token](#include-sub-claim-in-access-token)
     + [Use token](#use-token)
   * [Policies](#policies)
     + [Client application identification](#client-application-identification)
@@ -381,37 +383,47 @@ How these policies work will be covered later on.
 If successful, the server will return a 200 response with a JSON body containing, among others,
 an `access_token` field containing the access token, and a `token_type` field describing the token type.
 
-The generated access token will also contain a `sub` claim.
-This value indicates the identity from the original identification input that was provided during token exchange.
-
 If the claims are insufficient, a 403 response will be given instead.
 
-#### Partial permission tokens
-
-It is possible to set up the server so it also returns tokens
-if only some of the requested permissions are granted,
-instead of returning a 403 response.
-This can be useful for setups where the RS requires only one of the requested permissions to perform a request.
-The disadvantage is that the client might receive a token
-that does not have all permissions to perform the intended action.
+#### Enabling optional token features
 
-To enable this, start the UMA server with both `default.json` and `enable-partial.json`.
+Some token-related features are optional and can be enabled by adding extra configuration files
+when starting the UMA server, in addition to `default.json`.
 
 From the repository root:
 ```bash
-yarn start:uma -- -c ./config/default.json -c ./config/enable-partial.json
+yarn start:uma -- -c ./config/default.json -c ./config/<feature-config>.json
 ```
 
 From `packages/uma`:
 ```bash
-yarn start -c ./config/default.json -c ./config/enable-partial.json
+yarn start -c ./config/default.json -c ./config/<feature-config>.json
 ```
 
+#### Partial permission tokens
+
+It is possible to set up the server so it also returns tokens
+if only some of the requested permissions are granted,
+instead of returning a 403 response.
+This can be useful for setups where the RS requires only one of the requested permissions to perform a request.
+The disadvantage is that the client might receive a token
+that does not have all permissions to perform the intended action.
+
+To enable this, use `enable-partial.json` as the feature config.
+
 With this enabled:
 - If at least one requested permission can be authorized, the AS returns `200` with an access token.
 - If not all requested permissions are granted, that response body includes `partial: true`.
 - If no requested permission can be authorized, the AS returns `403`.
 
+#### Include `sub` claim in access token
+
+By default, generated access tokens do not include a `sub` claim.
+To include it, use `enable-sub.json` as the feature config.
+
+With this enabled:
+- Generated access tokens include `sub`, set to the identity extracted during token exchange.
+
 ### Use token
 
 When receiving the access token, the client can perform the same request as it did in the first step,

packages/uma/config/enable-sub.json

@@ -0,0 +1,12 @@
+{
+  "@context": [
+    "https://linkedsoftwaredependencies.org/bundles/npm/@solidlab/uma/^0.0.0/components/context.jsonld"
+  ],
+  "@graph": [
+    {
+      "@id": "urn:uma:default:TokenFactory",
+      "@type": "JwtTokenFactory",
+      "addSub": true
+    }
+  ]
+}

packages/uma/src/tokens/JwtTokenFactory.ts

@@ -26,12 +26,14 @@ export class JwtTokenFactory extends TokenFactory {
    * @param issuer - server URL to assign to the issuer field
    * @param tokenStore - stores the link between JWT and access token
    * @param params - additional parameters for the generated JWT
+   * @param addSub - if true, adds a sub claim to the JWT if available in the input token
    */
   constructor(
     protected readonly keyGen: JwkGenerator,
     protected readonly issuer: string,
     protected readonly tokenStore: KeyValueStorage<string, AccessToken>,
     protected readonly params: JwtTokenParams = { expirationTime: '30m', aud: 'solid' },
+    protected readonly addSub = false,
   ) {
     super();
   }
@@ -52,7 +54,7 @@ export class JwtTokenFactory extends TokenFactory {
       .setExpirationTime(this.params.expirationTime)
       .setJti(randomUUID());
 
-    if (token.sub) {
+    if (this.addSub && token.sub) {
       signJwt = signJwt.setSubject(token.sub);
     }
 

packages/uma/test/unit/tokens/JwtTokenFactory.test.ts

@@ -1,5 +1,5 @@
 import { AlgJwk, JwkGenerator, KeyValueStorage } from '@solid/community-server';
-import { exportJWK, generateKeyPair, GenerateKeyPairResult, jwtVerify, KeyLike, SignJWT } from 'jose';
+import { exportJWK, generateKeyPair, GenerateKeyPairResult, jwtVerify, SignJWT } from 'jose';
 import { beforeAll, Mocked } from 'vitest';
 import { AccessToken } from '../../../src/tokens/AccessToken';
 import { JwtTokenFactory } from '../../../src/tokens/JwtTokenFactory';
@@ -63,7 +63,6 @@ describe('JwtTokenFactory', (): void => {
     expect(parsed.payload).toEqual({
       permissions: token.permissions,
       contract: token.contract,
-      sub: token.sub,
       iat: Math.floor(now.getTime()/1000),
       iss: issuer,
       aud: 'solid',
@@ -116,4 +115,21 @@ describe('JwtTokenFactory', (): void => {
     await expect(factory.deserialize(jwt)).rejects
       .toThrow('Invalid Access Token provided, error while parsing: value is not an array');
   });
+
+  it('includes the sub claim when addSub is true.', async(): Promise<void> => {
+    const factoryWithSub = new JwtTokenFactory(keyGen, issuer, tokenStore, undefined, true);
+    const result = await factoryWithSub.serialize(token);
+    const parsed = await jwtVerify(result.token, keys.publicKey);
+    expect(parsed.payload.sub).toBe(token.sub);
+    expect(parsed.payload).toEqual({
+      permissions: token.permissions,
+      contract: token.contract,
+      sub: token.sub,
+      iat: Math.floor(now.getTime()/1000),
+      iss: issuer,
+      aud: 'solid',
+      exp: Math.floor(now.getTime()/1000) + 30 * 60,
+      jti: '1-2-3-4-5',
+    });
+  });
 });

test/integration/Oidc.test.ts

@@ -26,7 +26,10 @@ describe('A server supporting OIDC tokens', (): void => {
 
     umaApp = await instantiateFromConfig(
       'urn:uma:default:App',
-      path.join(__dirname, '../../packages/uma/config/default.json'),
+      [
+        path.join(__dirname, '../../packages/uma/config/default.json'),
+        path.join(__dirname, '../../packages/uma/config/enable-sub.json')
+      ],
       {
         'urn:uma:variables:port': umaPort,
         'urn:uma:variables:baseUrl': `http://localhost:${umaPort}/uma`,