feat: Support purpose claim

joachimvh · joachimvh · commit 350a1dad7f40 · 2026-07-27T11:27:56.000+02:00
diff --git a/documentation/getting-started.md b/documentation/getting-started.md
@@ -41,6 +41,7 @@ so some information might change depending on which version and branch you're us
       - [Publicly accessible resources](#publicly-accessible-resources)
     + [Exchange ticket](#exchange-ticket)
       - [Authentication methods](#authentication-methods)
+        - [Additional claims](#additional-claims)
       - [Customizing OIDC verification](#customizing-oidc-verification)
     + [Generate token](#generate-token)
       - [Enabling optional token features](#enabling-optional-token-features)
@@ -325,6 +326,20 @@ The `claim_token_format` explains to the AS how the `claim_token` should be inte
 In this case, this is a custom format designed for this server,
 where the token is a URL-encoded WebID.
 
+It is also possible to provide multiple claims by using an array for `claim_token`:
+```json
+{
+  "grant_type": "urn:ietf:params:oauth:grant-type:uma-ticket",
+  "ticket": "TICKET_ID",
+  "claim_token": [
+    { "claim_token": "eyJhbGciOiJSUzI1NiIsInR5cCI...", "claim_token_format": "http://openid.net/specs/openid-connect-core-1_0.html#IDToken" },
+    { "claim_token": "https://w3id.org/dpv#ScientificResearch", "claim_token_format": "http://www.w3.org/ns/odrl/2/purpose" }
+  ]
+}
+```
+When multiple claims are provided, each claim must include both a `claim_token` and `claim_token_format`.
+The AS will verify all provided claims and use them collectively to determine authorization.
+
 #### Authentication methods
 
 The above claim token format indicates that the claim token should be interpreted as a valid WebID.
@@ -335,13 +350,23 @@ In that case the body is expected to be an OIDC ID token.
 Both Solid and standard OIDC tokens are supported.
 In case of standard tokens, the value of the `sub` field will be used to match the assignee in the policies.
 
+Multiple authentication methods can be combined in a single request by providing multiple claims as shown above.
+This allows the AS to verify multiple credentials simultaneously and combine their claims.
+
 The values that are extracted from the OIDC token are expected to be IRIs.
 In case the `sub` or `azp`, which is discussed below, values are not IRIs,
 the server wil internally convert them by URL encoding the value, and prepending them with `http://example.com/id/`.
 This means that your policies should reference the converted ID.
 For example, if your `sub` value is `my id`, your policy needs to target `http://example.com/id/my%20id`.
 This base URL will be updated in the future once we have settled on a fixed value.
 
+##### Additional claims
+
+Besides claims that identify the user and client, additional claims can also be provided containing additional information.
+Currently, the only additional claim that is supported is the `purpose` claim.
+This can be provided with a `claim_token_format` of `http://www.w3.org/ns/odrl/2/purpose`,
+and with the `claim_token` being the IRI of the purpose.
+
 #### Customizing OIDC verification
 
 Several configuration options can be added to further restrict authentication when using OIDC tokens,
diff --git a/packages/uma/config/credentials/verifiers/default.json b/packages/uma/config/credentials/verifiers/default.json
@@ -13,6 +13,13 @@
       "@id": "urn:uma:default:TypedVerifier",
       "@type": "TypedVerifier",
       "verifiers": [
+        {
+          "TypedVerifier:_verifiers_key": "http://www.w3.org/ns/odrl/2/purpose",
+          "TypedVerifier:_verifiers_value": {
+            "@id": "urn:uma:default:KeyValueVerifier",
+            "@type": "KeyValueVerifier"
+          }
+        },
         {
           "TypedVerifier:_verifiers_key": "urn:solidlab:uma:claims:formats:webid",
           "TypedVerifier:_verifiers_value": {
diff --git a/packages/uma/src/credentials/verify/KeyValueVerifier.ts b/packages/uma/src/credentials/verify/KeyValueVerifier.ts
@@ -0,0 +1,16 @@
+import { ClaimSet } from '../ClaimSet';
+import { Credential } from '../Credential';
+import { Verifier } from './Verifier';
+
+/**
+ * A verifier that assigns the credential token value as claims value, with the format being used as claims key.
+ */
+export class KeyValueVerifier implements Verifier {
+  public constructor() {}
+
+  public async verify(credential: Credential): Promise<ClaimSet> {
+    return {
+      [credential.format]: credential.token
+    }
+  }
+}
diff --git a/packages/uma/src/index.ts b/packages/uma/src/index.ts
@@ -16,6 +16,7 @@ export * from './credentials/verify/OidcVerifier';
 export * from './credentials/verify/JwtVerifier';
 export * from './credentials/verify/IriVerifier';
 export * from './credentials/verify/RefreshTokenVerifier';
+export * from './credentials/verify/KeyValueVerifier';
 
 // Dialog
 export * from './dialog/AggregatorNegotiator';
diff --git a/packages/uma/src/policies/authorizers/OdrlAuthorizer.ts b/packages/uma/src/policies/authorizers/OdrlAuthorizer.ts
@@ -2,7 +2,7 @@ import { RDF } from '@solid/community-server';
 import { getLoggerFor } from 'global-logger-factory';
 import { DataFactory, Quad, Store } from 'n3';
 import { EyelingReasoner, ODRL, ODRLEngineMultipleSteps, ODRLEvaluator } from 'odrl-evaluator';
-import { CLIENTID, WEBID } from '../../credentials/Claims';
+import { CLIENTID, PURPOSE, WEBID } from '../../credentials/Claims';
 import { ClaimSet } from '../../credentials/ClaimSet';
 import { basicPolicy } from '../../ucp/policy/ODRL';
 import { PrioritizeProhibitionStrategy } from '../../ucp/policy/PrioritizeProhibitionStrategy';
@@ -14,6 +14,11 @@ import { Authorizer } from './Authorizer';
 
 const { quad, namedNode, literal, blankNode } = DataFactory
 
+const claimOperandMap: Record<string, string> = {
+    [CLIENTID]: ODRL.deliveryChannel,
+    [PURPOSE]: ODRL.purpose,
+} as const;
+
 /**
  * Permission evaluation is performed as follows:
  *
@@ -70,15 +75,22 @@ export class OdrlAuthorizer implements Authorizer {
         );
 
         const subject = typeof claims[WEBID] === 'string' ? claims[WEBID] : 'urn:solidlab:uma:id:anonymous';
-        const clientQuads: Quad[] = [];
-        const clientSubject = blankNode();
-        if (typeof claims[CLIENTID] === 'string') {
-            clientQuads.push(
-                quad(clientSubject, RDF.terms.type, ODRL.terms.Constraint),
-                quad(clientSubject, ODRL.terms.leftOperand, ODRL.terms.deliveryChannel),
-                quad(clientSubject, ODRL.terms.operator, ODRL.terms.eq),
-                quad(clientSubject, ODRL.terms.rightOperand, namedNode(claims[CLIENTID])),
-            );
+        const claimContextConstraints: { subject: ReturnType<typeof blankNode>; quads: Quad[] }[] = [];
+        for (const [ claimKey, leftOperand ] of Object.entries(claimOperandMap)) {
+            const claimValue = claims[claimKey];
+            if (typeof claimValue !== 'string') {
+                continue;
+            }
+            const claimSubject = blankNode();
+            claimContextConstraints.push({
+                subject: claimSubject,
+                quads: [
+                    quad(claimSubject, RDF.terms.type, ODRL.terms.Constraint),
+                    quad(claimSubject, ODRL.terms.leftOperand, namedNode(leftOperand)),
+                    quad(claimSubject, ODRL.terms.operator, ODRL.terms.eq),
+                    quad(claimSubject, ODRL.terms.rightOperand, namedNode(claimValue)),
+                ],
+            });
         }
 
         for (const { resource_id, resource_scopes } of query) {
@@ -101,14 +113,13 @@ export class OdrlAuthorizer implements Authorizer {
                 }
                 const request = basicPolicy(requestPolicy);
                 const requestStore = request.representation
-                // Adding context triples for the client identifier, if there is one
-                if (clientQuads.length > 0) {
+                for (const contextConstraint of claimContextConstraints) {
                     requestStore.addQuad(quad(
                         namedNode(request.ruleIRIs[0]),
                         namedNode('https://w3id.org/force/sotw#context'),
-                        clientSubject,
+                        contextConstraint.subject,
                     ));
-                    requestStore.addQuads(clientQuads);
+                    requestStore.addQuads(contextConstraint.quads);
                 }
 
                 // evaluate policies
diff --git a/packages/uma/src/policies/authorizers/SimpleOdrlAuthorizer.ts b/packages/uma/src/policies/authorizers/SimpleOdrlAuthorizer.ts
@@ -2,7 +2,7 @@ import { NamedNode } from '@rdfjs/types';
 import { getLoggerFor } from 'global-logger-factory';
 import { DataFactory as DF, Quad_Subject, Store } from 'n3';
 import { ODRL } from 'odrl-evaluator';
-import { CLIENTID, WEBID } from '../../credentials/Claims';
+import { CLIENTID, PURPOSE, WEBID } from '../../credentials/Claims';
 import { ClaimSet } from '../../credentials/ClaimSet';
 import { ReadOnlyStore, UCRulesStorage } from '../../ucp/storage/UCRulesStorage';
 import { Permission } from '../../views/Permission';
@@ -27,6 +27,11 @@ const dateComparators: NodeJS.Dict<(a: Date, b: Date) => boolean> = {
   [ODRL.gteq]: (a: Date, b: Date) => a >= b,
 };
 
+const claimOperandMap: Record<string, string> = {
+    [ODRL.deliveryChannel]: CLIENTID,
+    [ODRL.purpose]: PURPOSE
+} as const;
+
 /**
  * A simple authorizer that can handle basic ODRL policies with direct permissions and prohibitions,
  * without any complex constraints or inheritance.
@@ -151,7 +156,7 @@ export class SimpleOdrlAuthorizer implements Authorizer {
    * Determines if all constraints for the given rule are valid.
    * Returns true if all constraints are valid, false if any constraint is not valid,
    * and undefined if any constraint is too complex to evaluate.
-   * Only supports deliveryChannel (for client ID) and dateTime constraints.
+   * Only supports deliveryChannel (for client ID), purpose, and dateTime constraints.
    */
   protected validateConstraints(rule: Quad_Subject, policies: ReadOnlyStore, claims: ClaimSet): boolean | undefined {
     const constraints = policies.getObjects(rule, ODRL.terms.constraint, null).map(constraint => ({
@@ -165,15 +170,7 @@ export class SimpleOdrlAuthorizer implements Authorizer {
     }
     for (const constraint of constraints) {
       // Return undefined if any of these are too complex or unknown
-      if (constraint.leftOperand.equals(ODRL.terms.deliveryChannel)) {
-        if (!constraint.operator.equals(ODRL.terms.eq)) {
-          return false;
-        }
-        const clientId = claims[CLIENTID];
-        if (typeof clientId !== 'string' || constraint.rightOperand.value !== clientId) {
-          return false;
-        }
-      } else if (constraint.leftOperand.equals(ODRL.terms.dateTime)) {
+      if (constraint.leftOperand.equals(ODRL.terms.dateTime)) {
         const comparisonDate = new Date(constraint.rightOperand.value);
         const comparator = dateComparators[constraint.operator.value];
         if (!comparator) {
@@ -182,6 +179,15 @@ export class SimpleOdrlAuthorizer implements Authorizer {
         if (!comparator(new Date(), comparisonDate)) {
           return false;
         }
+      } else if (claimOperandMap[constraint.leftOperand.value]) {
+        const claimKey = claimOperandMap[constraint.leftOperand.value];
+        if (!constraint.operator.equals(ODRL.terms.eq)) {
+          return false;
+        }
+        const claimValue = claims[claimKey];
+        if (typeof claimValue !== 'string' || constraint.rightOperand.value !== claimValue) {
+          return false;
+        }
       } else {
         // Unsupported constraint
         return;
diff --git a/packages/uma/test/unit/policies/authorizers/OdrlAuthorizer.test.ts b/packages/uma/test/unit/policies/authorizers/OdrlAuthorizer.test.ts
@@ -3,7 +3,7 @@ import { RDF, XSD } from '@solid/community-server';
 import { DataFactory as DF, Parser, Store } from 'n3';
 import { ODRL, ODRLEvaluator } from 'odrl-evaluator';
 import { Mocked } from 'vitest';
-import { CLIENTID } from '../../../../src/credentials/Claims';
+import { CLIENTID, PURPOSE } from '../../../../src/credentials/Claims';
 import { OdrlAuthorizer } from '../../../../src/policies/authorizers/OdrlAuthorizer';
 import { basicPolicy } from '../../../../src/ucp/policy/ODRL';
 import { UCRulesStorage } from '../../../../src/ucp/storage/UCRulesStorage';
@@ -123,6 +123,30 @@ describe('OdrlAuthorizer', (): void => {
     ]);
   });
 
+  it('adds purpose claim context using odrl:purpose', async(): Promise<void> => {
+    const claims = { [PURPOSE]: 'https://w3id.org/dpv#ScientificResearch' };
+    const query: Permission[] = [{ resource_id: 'rid', resource_scopes: [ 'urn:example:css:modes:read' ] }];
+
+    await expect(authorizer.permissions(claims, query)).resolves.toEqual([{ resource_id: 'rid', resource_scopes: [] }]);
+
+    expect(evaluate).toHaveBeenCalledTimes(1);
+    const generatedRequest = evaluate.mock.calls[0][1];
+    const purposeConstraintQuad = generatedRequest.find((quad) =>
+      quad.predicate.equals(ODRL.terms.leftOperand) && quad.object.equals(ODRL.terms.purpose));
+
+    expect(purposeConstraintQuad).toBeDefined();
+    const purposeConstraintSubject = purposeConstraintQuad!.subject;
+    const purposeConstraintQuads = generatedRequest.filter((quad) =>
+      quad.subject.equals(purposeConstraintSubject));
+
+    expect(purposeConstraintQuads).toEqualRdfQuadArray([
+      DF.quad(purposeConstraintSubject, RDF.terms.type, ODRL.terms.Constraint),
+      DF.quad(purposeConstraintSubject, ODRL.terms.leftOperand, ODRL.terms.purpose),
+      DF.quad(purposeConstraintSubject, ODRL.terms.operator, ODRL.terms.eq),
+      DF.quad(purposeConstraintSubject, ODRL.terms.rightOperand, DF.namedNode('https://w3id.org/dpv#ScientificResearch')),
+    ]);
+  });
+
   it('extracts the allowed scopes from the resulting report.', async(): Promise<void> => {
     const query: Permission[] = [{ resource_id: 'rid', resource_scopes: [ 'urn:example:css:modes:read' ] }];
 
diff --git a/packages/uma/test/unit/policies/authorizers/SimpleOdrlAuthorizer.test.ts b/packages/uma/test/unit/policies/authorizers/SimpleOdrlAuthorizer.test.ts
@@ -7,7 +7,7 @@ import { Authorizer } from '../../../../src/policies/authorizers/Authorizer';
 import { SimpleOdrlAuthorizer } from '../../../../src/policies/authorizers/SimpleOdrlAuthorizer';
 import { UCRulesStorage } from '../../../../src/ucp/storage/UCRulesStorage';
 import { Permission } from '../../../../src/views/Permission';
-import { WEBID, CLIENTID } from '../../../../src/credentials/Claims';
+import { WEBID, CLIENTID, PURPOSE } from '../../../../src/credentials/Claims';
 
 describe('SimpleOdrlAuthorizer', () => {
   const resource = 'res';
@@ -166,6 +166,38 @@ describe('SimpleOdrlAuthorizer', () => {
     expect(fallback.permissions).not.toHaveBeenCalled();
   });
 
+  it('returns permission if purpose constraint is satisfied', async () => {
+    const rule = addRule({});
+    addConstraint({
+      rule,
+      leftOperand: ODRL.terms.purpose,
+      operator: ODRL.terms.eq,
+      rightOperand: 'https://w3id.org/dpv#ScientificResearch',
+    });
+    const claims = { [PURPOSE]: 'https://w3id.org/dpv#ScientificResearch' };
+
+    const result = await authorizer.permissions(claims, query);
+
+    expect(result).toEqual([{ resource_id: resource, resource_scopes: [scope] }]);
+    expect(fallback.permissions).not.toHaveBeenCalled();
+  });
+
+  it('returns empty if claim constraint is not satisfied', async () => {
+    const rule = addRule({});
+    addConstraint({
+      rule,
+      leftOperand: ODRL.terms.purpose,
+      operator: ODRL.terms.eq,
+      rightOperand: 'http://example.com/purpose-a',
+    });
+    const claims = { [PURPOSE]: 'http://example.com/purpose-b' };
+
+    const result = await authorizer.permissions(claims, query);
+
+    expect(result).toEqual([]);
+    expect(fallback.permissions).not.toHaveBeenCalled();
+  });
+
   it('delegates to fallback if constraint is too complex', async () => {
     const rule = addRule({});
     store.addQuad(rule, ODRL.terms.constraint, DF.namedNode('constraint3'));
diff --git a/test/integration/Base.test.ts b/test/integration/Base.test.ts
@@ -4,7 +4,7 @@ import { Parser, Writer } from 'n3';
 import { readFile } from 'node:fs/promises';
 import * as path from 'node:path';
 import { getDefaultCssVariables, getPorts, instantiateFromConfig } from '../util/ServerUtil';
-import { generateCredentials } from '../util/UmaUtil';
+import { generateCredentials, noTokenFetch, findTokenEndpoint, attemptTokenRequest, getToken } from '../util/UmaUtil';
 
 const [ cssPort, umaPort ] = getPorts('Base');
 
@@ -101,6 +101,7 @@ describe('A server setup', (): void => {
   });
 
   describe('using ODRL authorization', (): void => {
+    const owner = 'https://pod.woutslabbinck.com/profile/card#me';
     const newResource = `http://localhost:${cssPort}/alice/resource.txt`;
     const newResource2 = `http://localhost:${cssPort}/alice/private/resource.txt`;
     let wwwAuthenticateHeader: string;
@@ -238,8 +239,51 @@ describe('A server setup', (): void => {
       expect(response.status).toBe(401);
     });
 
+    it('supports purpose claims.', async(): Promise<void> => {
+      const assignee = 'https://purpose.pod.example/profile/card#me';
+      const purpose = 'https://w3id.org/dpv#ScientificResearch';
+
+      const policy = `
+        @prefix ex: <http://example.org/>.
+        @prefix odrl: <http://www.w3.org/ns/odrl/2/> .
+
+        ex:purposePolicy a odrl:Agreement ;
+          odrl:uid ex:purposePolicy ;
+          odrl:permission ex:purposePermission .
+        ex:purposePermission a odrl:Permission ;
+          odrl:action odrl:read ;
+          odrl:target <${newResource}> ;
+          odrl:assignee <${assignee}> ;
+          odrl:assigner <${owner}> ;
+          odrl:constraint ex:purposeConstraint .
+        ex:purposeConstraint a odrl:Constraint ;
+          odrl:leftOperand odrl:purpose ;
+          odrl:operator odrl:eq ;
+          odrl:rightOperand <${purpose}> .
+      `;
+
+      const policyResponse = await fetch(`http://localhost:${umaPort}/uma/policies`, {
+        method: 'POST',
+        headers: { authorization: `WebID ${encodeURIComponent(owner)}`, 'content-type': 'text/turtle' },
+        body: policy,
+      });
+      expect(policyResponse.status).toBe(201);
+
+      // First request without purpose should be denied
+      const { as_uri, ticket } = await noTokenFetch(newResource);
+      const endpoint = await findTokenEndpoint(as_uri);
+      const deniedResponse = await attemptTokenRequest(ticket, endpoint, assignee);
+      expect(deniedResponse.status).toBe(403);
+
+      // Request new ticket and get token with both WebID and purpose claims
+      const { ticket: newTicket } = await noTokenFetch(newResource);
+      const tokenWithClaims = await getToken(newTicket, endpoint, assignee, undefined, [
+        { claim_token: purpose, claim_token_format: 'http://www.w3.org/ns/odrl/2/purpose' }
+      ]);
+      expect(typeof tokenWithClaims.access_token).toBe('string');
+    });
+
     it('the resource can be made publicly accessible by having an anonymous assignee.', async(): Promise<void> => {
-      const owner = 'https://pod.woutslabbinck.com/profile/card#me';
       const url = `http://localhost:${umaPort}/uma/policies`;
 
       const policy = `
@@ -276,7 +320,6 @@ describe('A server setup', (): void => {
     });
 
     it('the resource can be made publicly accessible by being a Set without assignee.', async(): Promise<void> => {
-      const owner = 'https://pod.woutslabbinck.com/profile/card#me';
       const url = `http://localhost:${umaPort}/uma/policies`;
 
       const policy = `
diff --git a/test/util/UmaUtil.ts b/test/util/UmaUtil.ts
