Status of this document
This section is non-normative.
This document is a draft for a technical specification published by the Knowledge on Web Scale (KNoWS) group of the Internet Technology and Data Science Lab (IDLab), an imec-affiliated research group at Ghent University (UGent).
It is a working document, that has NOT been publically reviewed, but represents active research at its time of publication. As such, document may be subject to changes, and other documents may supersede it at any time.
The specification proposed in this document is being drafted in multiple stages.
-
Level 0, specified in this current draft, describes the interfaces and protocols of the final prototype implementation presented in the white paper From Resource Control to Digital Trust with User-Managed Access [UMA-Trust]. It lays the groundwork for the general flow of the protocol.
-
Level 1 will build on Level 0, to address some minor shortcomings discussed in the white paper, and optimise alignment with existing standards.
-
Level 2 and higher will build on Level 1, to cover the more extensive questions left open in the white paper.
Comments regarding this document are welcome, via the GitHub issue tracker, but the editors do NOT guarantee that this feedback will be processed, or when.
1. Introduction
This section is non-normative.
User-Managed Access (UMA) is a pair of complementary extensions to The OAuth 2.0 Authorization Framework [OAuth20], published by the Kantara Initiative. It comprises the following specifications:
-
User-Managed Access (UMA) 2.0 Grant for OAuth 2.0 Authorization, which defines a new authorization grant that enables party-to-party authorization and asynchronous policy configuration [UMA-Grant].
-
Federated Authorization for User-Managed Access (UMA) 2.0, which adds a protection API enabling the federation of resource servers and authorization servers, enabling improved automation, central monitoring and a more granular control over resources and scopes [UMA-Fed].
This document introduces a profile for the combined UMA specifications, called Authorization for Data Spaces (A4DS, read as 'affords').
...
2. Definitions
...
3. Authorization server metadata
To inform other parties (e.g. resource servers and clients) about its API endpoints and capabilities, the authorization server MUST declare this metadata in a discovery document that is publically readable on the well-known URI [RFC8615] formed by appending the string /.well-known/uma2-configuration to the root URI of the authorization server. The document MUST be in [JSON] and adhere to [RFC8414], as specified by [UMA-Grant], § 2, and [UMA-Fed], § 2. The following metadata parameters are or special concern to this UMA extension profile:
uma_profiles_supported-
REQUIRED. UMA profiles and extensions supported by this authorization server, as specified by [UMA-Grant], § 2. The metadata value MUST be a [JSON] array containing the URI
...
issuer-
REQUIRED. The authorization server’s issuer identifier, as specified by [RFC8414], § 2.
jwks_uri-
REQUIRED. The URL at which the authorization server serves its JWK Set [JWK] document, which contains the public key(s) used to validate signatures from the authorization server, as specified by [RFC8414], § 2.
resource_registration_endpoint-
REQUIRED. The URI at which the resource server registers resources to put them under protection of the authorization server, as specified by [UMA-Fed], § 2, and extended in § 4.2.1 Resource registration.
permission_endpoint-
REQUIRED. The URI at which the resource server requests permissions on the client’s behalf, as specified by [UMA-Fed], § 2, and extended in § 4.3 Requesting a Ticket.
token_endpoint-
REQUIRED. The URL at which the client requests an access token from the authorization server, as defined in [OAuth20].
introspection_endpoint-
REQUIRED. The URL at which the resource server can retrieve meta information about a token, including whether this token is currently active, as defined in [RFC7662], § 2.
4. The federated protection API
The authorization server MUST provide a protection API, as defined by [UMA-Fed], to govern its interactions with one or more resource servers. This API consists of three endpoints, listed in the authorization server's metadata: resource registration endpoint, resource registration endpoint, and introspection endpoint.
4.1. Security
4.1.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), according to the recommendations formulated in [RFC9325].
4.1.2. Message security
To be securely identifiable, the resource server MUST declare a JSON Web Key Set [RFC7517] on the Well-Known URI /.well-known/jwks.json [RFC8615].
loosen required url (since ref in discovery anyway)
In contrast to [UMA-Fed], § 1.3, messages from the resource server to the authorization server MUST NOT be protected with a protection API access token (PAT), but MUST be protected with a HTTP Message Signature [RFC9421] using one of the keys present in the aforementioned JWK Set.
discuss use of token (classic UMA)
discuss other key-based approaches (e.g. mTLS)
4.1.3. Linking an RS to an AS
decide on protocol: how to get do mutual registration between AS and RS ?
4.2. Resource management
4.2.1. Resource registration
In order to make resources accessible via 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.
go into resource and scope descriptions
make user_access_policy_uri recommended ?
4.2.1.1. Initial resources
...
discuss (bulk) registration of initial resources
4.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 body consisting of a permission object or an array of one or more permission objects. Each permission object contains the resource_scopes requested for a specific resource_id. According to [UMA-Fed], § 4.2, a successful permission request results in a ticket parameter in an application 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
5. Accessing resources at the resource server
5.1. 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 § 4.3 Requesting a Ticket.
If the authorization server responds with status code
If the authorization server responds with status code 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 header of a 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 UnauthorizedWWW- 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
5.2. 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 as necessary (cf. [RFC7662]). If this is indeed the case, the resource server MUST 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.
6. Requesting access at the authorization server
6.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. This request is sent to the token_endpoint of the authorization server, as described by [UMA-Grant], § 3.3.1. Contrary to the UMA specification, the request can not limit the scope represented in the ticket (but it can achieve the same with the permission parameter described in the following section).
still allowing scope would not break anything
The body of the request is encoded as application, rather than application.
revert this decision, allowing both, to remain compatible with standard oauth/uma clients; e.g. by relying on Rich Authorization Requests and/or JWT-Secured Authorization Requests and/or Pushed Authorization Requests.
For example:
POST/ token HTTP/ 1.1 Host: as . example. comContent- 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..." }
6.2. Requesting access WITHOUT a permission ticket
For clients that know the resource(s) and scope(s) they need access to, the A4DS profile adds a shortcut that saves them the initial request to the resource server. Instead, those clients can address the authorization server directly, and include the resource(s) and scope(s) directly under the permissions parameter. A new ticket is then automatically generated on-the-fly. When present, the permissions parameter MUST contain a JSON array of objects with the following two fields:
-
resource_id: a string -
resource_scopes: an array of strings
NOTE: Keycloak employs a similar approach, but restricts the their permission 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. comContent- 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..." }
6.3. Receiving 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 OKContent- Type: application/ json... { "access_token" : "sbjsbhs(/SSJHBSUSSJHVhjsgvhsgvshgsv" , "token_type" : "Bearer" }
The client can then use this token to access the required resources at the resource server (cf § 5.2 Attempting access WITH a token).
6.4. Claim token formats
...
clarify claim token formats, and discuss advertising them with a parameter separate from uma profiles