Authorization for Data Spaces

4.1. Channel security

As specified by [UMA-Fed], § 1.3, all interactions via the protection API must happen over an HTTP/1.1 channel (or higher) protected by TLS 1.3 (or higher), and in accordance with the recommendations formulated in [RFC9325].

Require key exhange algorithms based on ephemeral Diffie–Hellman ciphers (TLS_DHE and TLS_ECDHE) to ensure forward secrecy.

Require HTTP/2, which includes the requirements above, and patches some vulnerabilities in (m)TLS negotiation.

In the long-term, abstract from HTTP towards any SASL-aware application layer (cf. draft-vanrein-httpauth-sasl-06) . Conversely, enable HTTP-delivered OAuth tokens to be presented to SASL resource servers with rfc7628.

In the long-term, add support for DTLS & QUIC.

4.2. Message security

Messages from the resource server to the authorization server must be protected with a protection API access token, as defined in [UMA-Fed], § 1.3.

This is a deviation from the Level 0 specification, to realign with classic UMA.

Messages from the authorization server to the resource server should be protected with a HTTP Message Signature [RFC9421] using one of the keys present in the JWK Set refered to in the authorization server’s metadata.

decide on minimal headers/components to sign

4.3. Application security

The authorization server preferably interacts with resource owners and other agents through a (web) application, providing them with a graphical user interface. Since this broadens the attack surface for malicious actors, the authorization server must protect the security of its applications adequately by modern standards.

In particular, web applications for interaction with the requesting party, e.g., during claims gathering (cf. claims interaction endpoint), or with the resource owner, e.g., for policy management, must implement Cross Origin and Content Security policies, and SHOULD take into account the sources bundled in [CRE-636-347].

Moreover, in interactive flows that make use of redirection of the user agent (browser), e.g., claims gathering at the claims interaction endpoint, the authorization server should allow requests to include a state parameter, and clients should employ this parameter to track the valid state of the interaction. The value of the state parameter should be unguessable and opaque to any agent but the client itself, and [SHOULD NOT] include (unencrypted) sensitive information. If such a state parameter is used, clients must check the value after the authorization server redirects back to them, and must invalidate any message containing an invalid state parameter.

make accepting state param a must for AS: the authorization server must include it unaltered in the redirection to the client

4.4. Linking an RS to an AS

The resource owner links a resource server to their authorization server by providing the former with the root URI of the latter, i.e., the authorization server’s issuer value (cf. § 3.2 Authorization server metadata). How this information is provided, is out of the scope of this specification.

Presuming most ASs will come with some kind of native app, a QR-based flow would be handy. We could specify how, after scanning an RS’s QR code, the AS (app) would contact that RS on a Well-Known URI to initiate contact, either through a redirect URI or by specifying a code to be checked/entered.

As soon as resource server and authorization server are known to each other, the former can request a protection API access token from the latter. This must happen via an [OAuth20] flow that both servers support. In most cases, this should include interaction of the resource owner, e.g., via the authorization code flow using redirects of the resource owner’s user-agent, but other [OAuth20] flows may be employed.

To prevent the resource owner from having to confirm the authorization every time a token expires, the authorization server should inlcude a refresh token in each successful token response.

5.1. Creating an asset

In order to protect resources with A4DS, the resource server needs to register them at the authorization server. [UMA-Fed], § 3, specifies how to manage these resource descriptions using CRUD operations within the namespace of the resource registration endpoint.

New resources are registered through a registration request, which is a `POST` request to the resource registration endpoint, with an application/json body containing a resource description object. The A4DS profile also allows the request to contain a JSON array of one or more resource description objects.

Each resource description object consists of the following fields:

resource_scopes, of type sequence<ScopeDescription>

required. An array of scope descriptions or scope identifiers, representing the scopes available for the resource.

Scope descriptions are JSON objects containing the following fields:

_id, of type string

recommended. A URI identifying the scope.
Within the context of a registration request, this field is required.

name, of type string

optional. A human-readable string naming the scope.

description, of type string

optional. A human-readable string describing the scope at length.

icon_uri, of type string

optional. A URI for a graphic icon representing the scope.

dictionary ScopeDescription {
  string _id;
  string name;
  string description;
  string icon_uri;
};

scope identifier (_id) URIs can also be added directly as a string to the resource_scopes array. In that case, the resource server must make sure the resource description is publicly accessible at that URI.

The resource server should not register scope identifiers that are not URIs. In case such identifiers are present in the resource_scopes array, the authorization server should interpret them as a scope without scope description, uniquely identified by the comination of its string value and the identifier of the resource server.

For example, the following resource_scopes array expresses that the resource being registered can be read from and written to.

"resource_scopes": [
  {
    "_id": "https://example.org/modes/read",
    "name": "read",
    "description": "read the resource",
    "icon_uri": "http://example.org/icons/magnifiying_glass"
  },
 "https://example.org/modes/write"
]

A request of the form GET https://example.org/modes/write HTTP/1.1 could then return the following.

HTTP/1.1 200 OK
Content-Type: application/json
...
{
  "_id": "https://example.org/modes/write",
  "name": "write",
  "description": "write to the resource",
  "icon_uri": "http://example.org/icons/pen"
}

resource_relations, of type string

optional. A JSON object representing the structural relations the resource has towards other resources that are already registered.

Keys of the object represent relations from the resource being registered to the already existing resources. Values are strings, or arrays of strings, which must be valid identifiers of already registered resources.

Although the authorization server should not interpret the keys of the resource_relations object, and the resource server is thus free to mint its own inverse relations for relations that are conventionally expressed in the other direction – from the existing resource to the resource being registered – the resource server may alternatively express such relations by nesting them in a @reverse object.

For example, the following resource_relations object describe the resource being registered as derived from resources A and B, and contained in resource C – i.e., reading in reverse, resource C contains the the resource being registered.

"resource_relations": {
 "urn:example:relation:derivedFrom": [
  "urn:example:assets:A",
  "urn:example:assets:B"
 ],
 "@reverse": {
  "urn:example:relation:contains": "urn:example:assets:C",
 }
}

resource_defaults, of type string

optional. A JSON object representing the possible relations that future resources might have towards the newly registered resource, as well as the default/inherited scopes the newly registered resource can infer onto those future resources.

Keys of the object represent relations from potential future resources to the resource being registered – this is the opposite of the direction in resource_relations. Values are objects interpreted as blueprints for future resources having the corresponding relation to the newly registered resource.

Just like with resource_relations, the authorization server should not interpret the keys of the registered resource_defaults object, and the resource server may express inverse relations – from the resource being registered to potential future resources – by nesting them in a @reverse object.

Currently, the blueprints support the following fields:

resource_scopes, of type string

optional. An array of scope identifiers or scope descriptions, similar to the top-level resource_scopes field, representing the minimal set of scopes available for future resources that have the corresponding relation to the newly registered resource.

dictionary DefaultDescription {
  string resource_scopes;
};

go into inheritance of these scopes from the newly registered resource in future resources!

Note that the resource_defaults object defines the complete set of relations that can be declared from future resources to the resource being registered. If at some point other relations need to be declared, the resource server should therefore update the resource registration in which the resource_defaults are defined. Moreover, to allow a relation to be declared towards the resource being registered, without specifying any bleuprint defaults for it, the resource server should add the relation to the resource_defaults with an empty object as corresponding value.

For example:

"resource_defaults": {
  "urn:example:relation:rel_with_no_defaults": {},
  "urn:example:relation:rel_from_readable_resources": {
    "scope": [ "https://example.org/modes/read" ]
  },
  "@reverse": {  
    "urn:example:relation:inverse_rel": {
      "scope": [
        "https://example.org/modes/read", 
        "https://example.org/modes/write" 
      ]
    }
  }
}

type

recommended. A string identifying the semantics of the resource. The A4DS profile adds the restriction that this value should be a URI.

name

recommended. A human-readable string naming the resource.

description

recommended. A human-readable string describing the resource at length.

icon_uri

recommended. A URI for a graphic icon representing the resource.

dictionary ResourceDescription {
  sequence<ScopeDescription> resource_scopes;
  string resource_relations;
  string resource_defaults;
  string type;
  string name;
  string description;
  string icon_uri;
};

A full registration request could then look as follows:

POST /assets/ HTTP/1.1 Content-Type: application/json
Authorization: Bearer MHg3OUZEQkZBMjcx
...
{  
  "resource_scopes": [
    "read-public",
    "post-updates",
    "read-private",
    "http://www.example.com/scopes/all"
  ],
  "icon_uri": "http://www.example.com/icons/sharesocial.png",
  "name": "Tweedl Social Service",
  "type": "http://www.example.com/rsrcs/socialstream/140-compatible"
}

5.1.1. Interpreting a registration request

The complete semantics of registration requests, as specified above, is given by the following JSON-LD context. .

{
  "@context": {
    "@version": 1.1,
    "@protected": true,
    "xml": "http://www.w3.org/2001/XMLSchema#",
    "name": { "@type": "xml:string" },  
    "description": { "@type": "xml:string" },
    "icon_uri": { "@type": "@id" },
    "resource_relations": "@nest",
    "resource_defaults": { "@type": "@vocab" },
    "scope": { "@type": "@vocab" }
  }
}

resource servers should include this context explicitly in their registration requests. If they do not, authorization servers may implicitly assume it to be present anyway

5.1.2. Processing a registration request

Upon receiving a valid registration request, the authorization server should process each resource description it contains according to the algorithm presented in § 5.1.2.1 Processing a resource description.

dictionary RegistrationResponse {
  string _id;
  string user_access_policy_uri;
};

HTTP/1.1 201 Created
Content-Type: application/json
Location: /assets/asset1234
...
{
  "_id": "asset1234",
  "user_access_policy_uri": "http://as.example.com/rs/222/resource/KX3A-39WE/policy"
}

5.2. Inspecting an asset

GET /assets/ HTTP/1.1
Authorization: Bearer 204c69636b6c69
...

HTTP/1.1 200 OK
Content-Type: application/json
...
[  
  "KX3A-39WE",
  "9UQU-DUWW"
]

GET /assets/KX3A-39WE HTTP/1.1
Authorization: Bearer MHg3OUZEQkZBMjcx
...

5.3. Modifying an asset

DELETE /assets/9UQU-DUWW
Authorization: Bearer 204c69636b6c69
...

HTTP/1.1 204 No content
...

HTTP/1.1 205 Reset content
...
{  
  "user_access_policy_uri": "http://as.example.com/rs/222/resource/9UQU-DUWW/policy"
}

7.1. Attempting access with a token

When the client attempting to access resources presents the resource server with an access token, e.g., a Bearer token passed in the `Authorization` header of the request (cf. [RFC6750]), the resource server must determine whether the token is valid and covers the resources and scopes being accessed, as specified in [UMA-Grant], § 3.5 and [UMA-Fed], § 5, using token introspection if necessary (cf. [RFC7662]).

• If this is the case, the resource server should process the authorized request.

• If, on the contrary, the token is invalid, or does not cover the neccessary resources or scopes, the resource server must not give the client access, and must instead respond as if the request were unaccompanied by an access token (cf. infra).

7.2. Attempting access without a token

When the client attempting to access resources has no token authorizing the access, the resource server must request a permission ticket from the authorization server, as specified in [UMA-Grant], § 3.2, and described in § 7.3 Requesting a Ticket.

• If the authorization server responds with status code `200`, the resource server should let the attempted access succeed.

• If the authorization server responds with status code `201` and a ticket parameter, the resource server must not let the attempted access succeed. Instead, the resource server must pass this parameter to the client in the `WWW-Authenticate` header of a `401` response, with the scheme UMA, and the issuer URI of the authorization server as an additional parameter as_uri, as specified in [UMA-Grant], § 3.2.1 (see also [RFC9110], § 11.6.1).

For example:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: UMA
  as_uri="https://as.example.com",
  ticket="016f84e8-f9b9-11e0-bd6f-0021cc6004de"
...

look into particular use of realm parameter (vs scope) to limit protection space for user/ticket/type

7.3. Requesting a Ticket

When a client application makes an unauthorized attempt to access resources on an resource server – with an invalid access token, or none at all – the resource server can request a permission ticket from the relevant authorization server, and provide the ticket to the client as an indication of the scope of the attempted access, while pointing the client to the authorization server, as described in [UMA-Fed], § 4.

As specified in [UMA-Fed], § 4.1, the ticket is requested by sending a `POST` request to the permission_endpoint, with an application/json body containing a permission description object, or an array of such ojects.

Each permission description consists of the following fields.

resource_id, of type string

required. A string indicating the resource in question, as known to the authorization server. (Note that this identifier might differ from any related URI at the side of the resource server).

resource_scopes, of type string

required. An array of strings representing the scopes requested for the resource in question.

dictionary PermissionDescription {
  string resource_id;
  string resource_scopes;
};

Upon receiving a permission request, the authorization server must process it according to the following algorithm.

1. Create a new ticket, with an identifier that is unique within the context formed by the resource server and the authorization server itself.

2. For each permission description in the permission request:

   1. Check the validity of the resource identifier and scope identifiers.

      • If the resource identifier is invalid, the authorization server should send an error response to the resource server with error code invalid_resource_id (cf. [UMA-Fed], § 6).

      • If a scope identifier (_id) is invalid, the authorization server should send an error response to the resource server with error code invalid_scope (cf. [UMA-Fed], § 6).

   2. Add the details of the permission description to the newly created ticket.

According to [UMA-Fed], § 4.2, a successful permission request results in a `201` response containing the ticket parameter in an application/json body.

A4DS extends the possible responses of the authorization server to a permission request, to enable better integration with public resources. When the authorization server can detect within reasonable time that the resources in question are publically accessible, it should signal this to the resource server by sending a `200` response without a body instead. This way, the resource server can allow the client to access public resources without a round-trip to the authorization server, thus increasing performance and making public resources accessible for clients that are not aware of the UMA protocol.

8.1. Requesting access with a permission ticket

Having received a permission ticket from the resource server, the client can turn to the authorization server to request access for the resource(s) and scope(s) represented by the ticket. In addition to the common parameters listed above (cf. § 8 Requesting access at the authorization server), such a request must contain the following parameters.

ticket, of type string

required when presenting a ticket. The identifier of the permission ticket that the client received from the resource server.

For example:

POST /token HTTP/1.1
Host: as.example.com
Content-Type: application/json
...

{
  "grant_type": "urn:ietf:params:oauth:grant-type:uma-ticket",
  "ticket": "016f84e8-f9b9-11e0-bd6f-0021cc6004de",
  "claim_token_format": "http://openid.net/specs/openid-connect-core-1_0.html#IDToken",
  "claim_token": "eyj0..."
}

8.2. Requesting access without a permission ticket

For clients that know the resource(s) and scope(s) they want to access, the A4DS profile adds a shortcut that saves them the initial request to the resource server. Instead, those clients may address the authorization server directly, and include the resource(s) and scope(s) directly under the permissions parameter.

permissions, of type string

required when requesting permissions directly. The resource(s) and scope(s) the client requests access to. The format of this field is identical to that of the permission request described in § 7.3 Requesting a Ticket: a permission description object or an array of such objects.

NOTE: Keycloak employs a similar approach, but restricts the value of their permission parameter to a single string encoding of JSON data. Keycloak also allows such requests to target specific resource URIs, so their AS knows more than a standard UMA server.

For example:

POST /token HTTP/1.1
Host: as.example.com
Content-Type: application/json
...

{
  "permissions": {
    "resource_id": "KX3A-39WE",
    "resource_scopes": [ 
    "post-updates",
    "http://photoz.example.com/dev/scopes/print"
    ]
  },
  "claim_token_format": "http://openid.net/specs/openid-connect-core-1_0.html#IDToken",
  "claim_token": "eyj0..."
}

8.3. Requesting extra 'global scopes'

The UMA specification allows the traditional [OAuth20] scope parameter to be added to an access request, regardless of the scopes present in the ticket or in the permissions parameter. Each scope requested in this way applies to all resources to which the access request pertains. Clients can only request such 'global scopes' if they have been pre-registered for those scopes through a static or dynamic registration client registration mechanism.

scope, of type string

not recommended A string of space-separated scope identifiers, requesting extra scopes, for which the client has been pre-registered, that apply to all requested resources.

The A4DS profile discourages access requests for such global scopes. To request resource-specific scopes that are not included in a ticket from the resource server, it is preferable to use the permissions parameter specified in § 8.2 Requesting access without a permission ticket.

consider simply disallowing this, and letting 'scope' double as 'permissions', with permission descriptions without a resource id functioning as 'global scopes' (and similar without scope ids functioning as all scopes on one resource).

9.1. Claim descriptions

Metadata about a claim, that is relevant for processing it or presenting it to an agent, can be expressed in a claim description, containing the following parameters.

claim_token_format, of type string

optional. A string, or array of strings, indicating the (acceptable) token formats of a claim. The values should be URIs.

claim_type, of type string

optional. A string, or array of strings, indicating the (expected) semantic type/interpretation of a claim value. The values should be URIs.

issuer, of type string

optional. A string, or array of strings, indicating the (acceptable) authorities issuing the claim. The values should be URIs.

name, of type string

optional. A string that uniquely identifies the claim within context in which the claim description is used. The value should be a URI.

friendly_name, of type string

optional. A short human-readable string, which can be uses to display the claim in user interfaces.

dictionary ClaimDescription {
  string claim_token_format;
  string claim_type;
  string issuer;
  string name;
  string friendly_name;
};

NOTE: Parameters taking an array as value are to be interpreted as the union/disjunction of its elements, i.e., they are to be read as "one of ..."

9.2. Claim token formats

clarify claim token formats, and discuss advertising them with a parameter separate from uma profiles

9.3. Providing claims

UMA provides two mechanisms for requesting partys to provide claims to the authorization server:

• Claims pushing: ... (Section 3.3.1)

• Interactive claims gathering: ... (Section 3.3.2)

TODO

10.1. Completing the permission ticket

Upon receiving an access request, the authorization server should process it according to the following algorithm.

Go into the combination of permissions and scope (and possibly ticket).

1. If the access request contains a ticket parameter, the authorization server looks up the corresponding ticket in its knowledge base.

   • If the value of the ticket parameter is a valid ticket identifier, the corresponding ticket is used as target of the request.

   • If no ticket with the corresponding identifier is found, the authorization server should respond with error code invalid_grant (cf. [UMA-Fed], § 6).

2. If the access request contains a permissions parameter, the authorization server should create a new ticket, following the steps described in § 7.3 Requesting a Ticket. This ticket is then used as target of the request.

3. If the access request contains a scope parameter:

   1. Look up the metadata of the client, in particular the list of scopes for which it is pre-registered.

   2. Split the string value of the scope parameter on space characters.

   3. For each element of the split string:

      • If the string is a scope identifier (_id) present in the list of pre-registered scopes of the client: add the scope to the list of requested scopes for each of the permission descriptions in the target ticket.

        NOTE: the UMA algorithm keeps these separate, possibly allowing the extra scopes to vary between different messages in the authorization flow/negotiation... again, this seems to parallel the permissions object.

      • If not, the authorization server may disregard the element, or send an error response with error code invalid_scope (cf. [UMA-Fed], § 6).

10.2. Determining the policy decision

After having completed the information in the permission ticket, it is time for the authorization server to determine the authorization decision as a result of the resource owner’s policies, applied to the available information.

Just like UMA, the A4DS profile does not specify the mechanism by which this decision is to be made. On top of UMA, however, this specification adds an interface through which an authorization server may communicate with any interoperable policy engine, thereby clearly separating the domain of exchange and negotiation – between the client and the authorization server – from the domain of decision-making.

A4DS therefore defines a policy engine as any (implementation of an) algorithm that, given a complete permission ticket – including all requested permissions and all currently provided claims – can determine all active/operative policy conditions (and other relevant information, serving as state of the world), and evaluate their authorization status (i.e., compliance).

10.3. Granting an access token

When the authorization server concludes that the provided claims are sufficient to grant the client access to the requested resources, it responds with an access token and `Authorization` scheme, as specified in [UMA-Grant], § 3.3.5 (see also [RFC9110], § 11.6.2)).

For example:

HTTP/1.1 200 OK
Content-Type: application/json
... 

{ 
  "access_token": "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv",
  "token_type": "Bearer"
}

The client can then use this access token to access the required resources at the resource server (cf. § 7.1 Attempting access with a token).