Aggregator Specification

Living Document,

Previous Versions:
Issue Tracking:
GitHub
Inline In Spec
Editor:
(Ghent University - imec)

CC0 To the extent possible under law, the editors have waived all copyright and related or neighboring rights to this work. In addition, as of 6 December 2025, the editors have made this specification available under the Open Web Foundation Agreement Version 1.0, which is available at https://www.openwebfoundation.org/the-agreements/the-owf-1-0-agreements-granted-claims/owfa-1-0. Parts of this work may be from another specification document. If so, those parts are instead covered by the license of that specification document.

Abstract

This document has the specification of the aggregator.

1. Introduction

The introduction for the Aggregator specification will be expanded in future revisions.

2. Definitions

NOTE: that this is different from the Authorization Server (AS) that issues UMA RPT tokens. The IDP Servers are used to provide identity to users. The Authorization Servers checks this identity and issues RPT tokens for resource servers.

3. Public Metadata

4. Aggregator Maintenance

This section describes how aggregators are managed on the Aggregator Server level.

4.1. Aggregator Creation

This section describes how clients can create an Aggregator.

TODO where to add versioning info?

TODO where to use DPOP tokens?

TODO Authorization on the aggregator creation endpoint is defined by the implementation.


   
    
    
  1. 
     
    client needs to login into an application (IPD_client_token)
    
    
  2. 
     
    client goes to aggregator creation endpoint (with IPD_client_token)
    
     
      
      
    • 
       
      registration_type="PKCE" (Determines the flow e.g. "create", "PKCE", "device", "client_credentials")
      
      
    • 
       
      action="create" (Deterrmines the action e.g. "create", "login", "delete")
      
       
      NOTE: do we want to support update (maybe to update the IDP or the AS_URL)?
      
      
    • 
       
      
        authorization_server= 
         (the UMA authorization server of the aggregator should use)
       
      
      
    • 
       
      
        account_id=
         (OPTIONAL: in case of login or delete)
       
      
     
    
    
  3. 
     
    The aggregator returns:
    
     
      
      
    • 
       
      
        client_id=
         (to be used in step 3 as client_id)
       
      
      
    • 
       
      
        code_challenge=
         (to be used in step 3)
       
      
      
    • 
       
      code_challenge_method=S256 (to denote that SHA256 is used as the code challenge method)
      
      
    • 
       
      
        OPTIONAL: state=
         (to be used in step 3 if the IDP requires state)
       
      
       
       TODO How do we know if the IDP requires state?
      
       
       TODO How does the aggregator register with the AS?
      
     
    
    
  4. 
     
    client goes to the authorization endpoint with:
    
     
      
      
    • 
       
      response_type = "code" (Others MAY NOT be supported by the IDP Server)
      
      
    • 
       
      client_id = (from from step 2, in case of SOLID this is a resource hosted by the aggregator)
      
      
    • 
       
      
        redirect_uri=
         (returns to the client)
       
      
      
    • 
       
      scope=openid webid offline_access (As per [SOLID OIDC] openid is a scope that is needed to verify Alice’s identity, webid is required by the Solid OIDC specification to denote a WebID login, offline_access: Is required to get a refresh token.)
      
      
    • 
       
      
        code_challenge=
         (from step 2)
       
      
      
    • 
       
      code_challenge_method=S256 (to denote that SHA256 is used as the code challenge method)
      
      
    • 
       
      
        OPTIONAL: state=
         (from step 2, if provided)
       
      
     
    
    
  5. 
     
    IDP Server authenticates the user (e.g. via username/password)
    
    
  6. 
     
    IDP Server gets user consent for the requested scopes and client_id
    
    
  7. 
     
    IDP Server redirects to redirect_uri with authorization code
    
    
  8. 
     
    client sends the authorization code to the aggregator creation endpoint with:
    
     
      
      
    • 
       
      registration_type="PKCE" (Determines the flow e.g. "create", "PKCE", "device", "client_credentials")
      
      
    • 
       
      action="create" (Deterrmines the action e.g. "create", "login", "delete")
      
      
    • 
       
      
        code=
         (from step 6)
       
      
      
    • 
       
      
        redirect_uri=
         (same as step 3)
       
      
      
    • 
       
      
        OPTIONAL: state=
         (from step 3, if provided)
       
      
     
    
    
  9. 
     
    Aggregator checks if the redirect_uri is the same as client_id of client application (from client authorization token in step 2)
    
    
  10. 
     
    aggregator creation endpoint redeems the authorization code (IDP_aggregator_token) at the token endpoint with:
    
     
      
      
    • 
       
      grant_type=authorization_code
      
      
    • 
       
      
        code=
         (from step 6) (the IDP checks if the code was already used and unexpired)
       
      
      
    • 
       
      
        redirect_uri=
         (same as step 3) (the IDP checks if this matches the original redirect_uri)
       
      
      
    • 
       
      
        client_id=
         (from step 2) (the IDP checks if this matches the original client_id)
       
      
      
    • 
       
      
        code_verifier=
         (from step 2) (the IDP checks if this matches the original code_challenge)
       
      
      
    • 
       
      
        state=
         (from step 3, if provided) (the IDP checks if this matches the original state)
       
      
     
    
    
  11. 
     
    IDP Server returns:
    
     
      
      
    • 
       
      IDP_aggregator_token (access token to access resources on behalf of the user)
      
      
    • 
       
      refresh_token (to get a new IDP_aggregator_token when the current one expires)
      
     
    
    
  12. 
     
    aggregator creation endpoint creates an aggregator account for the user with the IDP_aggregator_token and returns the aggregator account details
    
   

   
Relogin flow (for when the the aggregator needs a new token):
Same flow but in step 2 action="login"

   
NOTE: This does mean that the user can only have one aggregator account per aggregator server.

   
 TODO How to refresh the IDP_client_token? refresh tokens are not valid forever.

   
 TODO How to delete an aggregator => delete endpoint with authentication

   
5. Authentication and Authorization

   
The Aggregator relies on the Authorization for Data Spaces (A4DS) specification to authenticate clients and authorize access to resources. The Aggregator Service authenticates the Client using OIDC and obtains access tokens for upstream Resource Servers.

   
5.1. Client Flow

   
The Aggregator Service authenticates the Client with OIDC to obtain an access token for a Resource Server. The Aggregator Service relies on an OIDC access token linked to the Aggregator’s client identifier. The Aggregator SHOULD request the additional scope urn:knows:uma:scopes:derivation-creation from the Authorization Server of a Resource Server to enable the Aggregator functionality. The Authorization Server MUST return a derivation_resource_id together with the access token. The Aggregator MAY delete the derivation_resource_id when it is no longer needed. The Aggregator Service MUST update the resource registration at its Authorization Server to signal that it used this resource identifier to create derived resources.


{
  "resource_scopes": [ ... ],
  "resource_relations": {
    "prov:wasDerivedFrom": {
      "issuer": "https://as.example.org",
      "derivation_resource_id": "handle-id-1"
    }
  }
}


   
The Authorization Server MUST invalidate previous access tokens (for example by marking them inactive) if they are linked to a derived resource whose identifier has been consumed.

   
TODO: clarify whether polling for a new derivation_resource_id is necessary, or whether the Aggregator can request the Authorization Server for a normal scope referencing the identifier or supply the identifier as a hint when requesting with a ticket.

   
5.2. Resource Server Flow

   
When a Client requests access to a derived resource from the Aggregator Service, a normal UMA flow follows. During ticket creation, the Aggregator validates that the derivation_resource_id used to create the derived resource is still valid. If it is invalid, the Aggregator MUST recreate the Aggregator Service. The Aggregator Authorization Server MAY respond with a need_info error requesting access tokens for upstream resources. In that case, the Authorization Server MUST add the issuer, derivation_resource_id, and resource_scopes entries to the required_claims array. The issuer identifies the upstream Authorization Server. The derivation_resource_id contains the identifier (or identifiers) provided when the Aggregator Service requested an upstream access token. The resource_scopes list enumerates the scopes required to access the upstream resource and MUST include a derivation scope.


{
  "error": "need_info",
  "ticket": "tkt-A2",
  "required_claims": [
    {
      "claim_token_format": "urn:ietf:params:oauth:token-type:access_token",
      "details": {
        "issuer": "https://a.example.org",
        "derivation_resource_id": "handle-id-1",
        "resource_scopes": [ "urn:knows:uma:scopes:derivation-read" ]
      }
    }
  ]
}


   
The Client SHOULD then request access tokens from the Authorization Server of the upstream Resource Server with the required scopes, including the derivation scope.


{
  "grant_type": "urn:ietf:params:oauth:grant-type:uma-ticket",
  "permissions": [
    {
      "resource_id": "handle-id-1",
      "scopes": [ "urn:knows:uma:scopes:derivation-read" ]
    }
  ],
  "claim_token": "OIDC_token",
  "claim_token_format": "http://openid.net/specs/openid-connect-core-1_0.html#IDToken"
}


   
Finally, the Client retries the request to the Aggregator Service with the access tokens it received from the upstream Resource Servers.


{
  "grant_type": "urn:ietf:params:oauth:grant-type:uma-ticket",
  "ticket": "tkt-A2",
  "claim_tokens": [
    {
      "claim_token": "OIDC_token",
      "claim_token_format": "http://openid.net/specs/openid-connect-core-1_0.html#IDToken"
    },
    {
      "claim_token_format": "urn:ietf:params:oauth:token-type:access_token",
      "claim_token": "as-at-2"
    }
  ]
}


   
The Aggregator Authorization Server MUST verify the provided access tokens with the upstream Authorization Servers to confirm that the Client is authorized to access the upstream resources.

   
6. Creating an Aggregator Service

   
This section will describe how to create an Aggregator Service in more detail.

   
7. Using an Aggregator Service

   
Guidance for using an Aggregator Service will follow as the specification matures.

  

  

   

    Conformance

   

            Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology.
            The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL”
            in the normative parts of this document
            are to be interpreted as described in RFC 2119.
            However, for readability,
            these words do not appear in all uppercase letters in this specification.

        

   

            All of the text of this specification is normative
            except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

        

   

            Examples in this specification are introduced with the words “for example”
            or are set apart from the normative text with class="example", like this:

        

   

            This is an example of an informative example.
        

   

            Informative notes begin with the word “Note”
            and are set apart from the normative text with class="note", like this:

        

   

            Note, this is an informative note.

  


  
References

  
Normative References

  

   
[RFC2119]
   
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
  

  
Issues Index

  

   
 TODO where to add versioning info? ↵

   
 TODO where to use DPOP tokens? ↵

   
 TODO Authorization on the aggregator creation endpoint is defined by the implementation. ↵

   
 TODO How do we know if the IDP requires state? ↵

   
 TODO How does the aggregator register with the AS? ↵

   
 TODO How to refresh the IDP_client_token? refresh tokens are not valid forever. ↵

   
 TODO How to delete an aggregator => delete endpoint with authentication ↵