RFC034
| Document property | Value |
|---|---|
Issue reference | #9+ |
Document status [draft/final] | Draft |
Background and rationale
Currently iSHARE certified Authorization Registries (see functional requirements or general information):
Can hold information on delegations to other entities by Entitled Parties;
Has a process in place allowing for the registration, update and revocation of delegations;
Can check, on the basis of this information, whether a legal entity is authorized to take delivery of a service;
Can confirm whether this is the case to the Service Provider.
There is no prescribed API endpoint to request creating, updating and deleting delegations. An Authorization Registry provider is free to design the process for registration, update and revocation of delegations.
Proposed change
In this change the term "Delegation Policy" is used interchangeably with "Delegation" to describe the delegation in which an Entitled Party stores a delegation to a Service Consumer. For more information see https://dev.ishareworks.org/introduction/getting-started.html#additional-authorization.
Purpose
This RFC aims to stimulate the registration of fine grained authorizations by creating the possibility for machine-to-machine request delegations and automatically approve them based on a ruleset provided by an entitled party.
Description and principles
As an Entitled Party I want to delegate the right to request (to create) delegation policies to a party.
Principles:
The party to which the right is delegated is called the “Delegation Policy Requestor”.
The general delegation used to delegate the right to create and manage delegations is called “meta-delegation”.
The “Delegation Policy Requestor” can request delegations using an API offered by the Authorization Registry.
The “Delegation Policy Requestor” can only request and manage delegations at the Authorization Registry at which the meta-delegation is stored (i.e. the Authorization Registry of the Entitled Party).
The requests are automatically (dis)approved based on a ruleset that is defined by the Entitled Party.
A wildcard (“*”) ruleset, essentially allowing the “Delegation Policy Requestor” to request and manage all of the Entitled Party’s delegations, is not allowed.
Authorization Registries should follow principles on overlapping policies (see Meta Delegations specification).
Note that it remains possible to create, update and delete delegations by the Entitled Party itself, making this change fully backwards compatible.
Example use cases
By implementing the changes in this RFC multiple scenarios will benefit from this. These are best explained using examples. This first example use case describes a situation where an entitled party uses a service provided by a third party. Instead of defining fine-grained delegations for this third party, the entitled party registers a generic delegation at his Authorization Registry, setting the boundaries (rules) for delegations that are provisioned from a software solutation (for instance an eCMR) that already contains fine grained delegations. The delegations are proactively provisioned from the 3rd party software/service provider, after which the service can be consumed based on these delegations.
In this example we use the following entities (all of them are iSHARE participants):
[Banana & co]: the Entitled Party[eCMR]: the 3rd party software/service provider used by the Entitled Party[Authorization Registry]: the Authorization registry[Warehouse 13]: a Service Provider[ABC Trucking]: a Service Consumer (acting as a Delegation Policy Requestor)
The Entitled Party (
Banana & co) creates a meta-delegation at Authorization Registry (using an interface provided by the Authorization Registry), including a ruleset that determines the scope of delegations that can be created based on the meta-delegation. The rules could for instance contain a list of containers, or a timeframe (all containers in the coming month) and the Service Provider (Warehouse 13) where the data is stored.The Entitled Party (
Banana & co) requests the 3rd party software/service provider (eCMR) to provision the Authorization Registry with delegation policies.The 3rd party software/service provider (
eCMR) requests the creation of fine-grained delegations-policies at the Authorization Registry, based on the meta-delegation and the existing knowledge of fine-grained within the 3rd party software/service provider.The Authorization Registry evaluates the request for creation of the delegation policies with the ruleset in the meta-delegation. If the required delegation falls within the ruleset of the meta-delegation, the delegation is created.
This step is outside the scope of iSHARE. The Entitled Party requests a service from a party (
Banana & co) (requires ABC Trucking to pick up a container). The party (ABC Trucking) requires data that belongs to the Entitled Party (Banana & co) from a Service Provider (Warehouse 13) and will therefore act as a Service Consumer. It needs a delegation in order to access this data at the Service Provider (Warehouse 13) where the data is stored.The Service Consumer (
ABC Trucking) requests delegation evidence from the Authorization Registry. The delegation evidence is provided based on the fine grained delegation policies that are stored in the Authorization Registry.With the delegation evidence the Service Consumer (
ABC Trucking) can request data from the Service Provider (Warehouse 13).This step is outside the scope of iSHARE. The requested service from the Service Consumer (
ABC Trucking) is delivered to the Entitled Party (Banana & co).
Other examples for using the proposed changes in this RFC are:
An entitled party could delegate the management of delegation-policies to the Service Consumer. The Service Consumer requests the creation of a delegation policy based on the meta-delegation just before accessing a service provided by the Service Provider.
A party could request a delegation from the Entitled Party by requesting this delegation at the Authorization Registry. The Authorization Registry informs the Entitled Party that a certain delegation is requested, after which the Entitled Party can approve this. This is depicted in the diagram below.
Impact on the ecosystem
The following table lists the impact of this RFC on the formal iSHARE roles (excluding the Scheme Owner role).
| Formal role | Technical impact | Business / legal / functional / operational impact |
|---|---|---|
Service Consumer | Possibly, when it wants to request policy creation | Possibly, when it wants to request policy creation |
Service Provider | No | No |
Entitled party | No | Yes, create meta-delegation, allow fine grained authorizations to be automatically managed |
Authorization Registry1 | Yes, provide a way to manage meta-delegations and provide API for delegation policy request | Yes, provide operational and functional process to support this as well define the legal boundaries on policies created based on rule sets |
Identity Provider | No | No |
Identity Broker | No | No |
Data Space Administrator | No | No |
Satellite | No | No |
1 This change is fully backwards compatible with current implementations of Authorization Registries. Current delegations are therefore not affected.
This RFC introduces a non-formal role of a party called “Delegation Policy Requestor”. Any party can fulfill this role, as long as this party is enrolled as a participant in the data space and can therefore be identified when registering the meta-delegation.
| Non-formal role | Technical impact | Business / legal / functional / operational impact |
|---|---|---|
Delegation Policy Requestor | Yes, implement AR delegation policy request API | Yes, support Entitled Party in providing fine grained authorizations |
Impact iSHARE Foundation (Scheme Owner)
iSHARE Trust Framework
The RFC will require changes in the iSHARE Trust Framework (as published here). The following changes are foreseen:
A new basic data license will be defined, which forms the legal basis for requesting delegations. First draft:
This license may not be sufficient in all cases and participants are expected to add more definitions of licenses to be included in the licenses list and this way contribute to iSHARE framework.
In the structure of delegation evidence under “Policy” the definition of “type” should indicate that the use of “ISHARE.DELEGATION” is reserved.
The functional description per role (paragraph Authorization Registry) must be amended.
Secondary use cases must be amended.
Since changes are required in the iSHARE Trust Framework this RFC requires a new version of the iSHARE Trust Framework to be drafted, discussed, approved and published.
Technical documentation
Changes in the technical documentation (https://dev.ishare.eu/) are required, specifically in the Delegations section. The following changes are foreseen:
The specifications under DELEGATION on https://dev.ishare.eu/ will be appended with a specification for the “Policy Creation Request Endpoint”. For the purpose of this RFC the API requirements are specified as OpenAPI 3 specifications and will form an integral part of the technical requirements to an iShare certified Authorization Registry. The proposed API specification is hosted on Swaggerhub here and including the definition of the JWT token here.
Under the DELEGATION section a page will be created holding requirements to the meta-delegation. A first version of the intended page is provided in Meta Delegations specification.
Conformance test tool
The conformance test tool must be amended with testing of the newly required API endpoint. This is a test that is relevant for testing Authorization Registries. Detailed test cases will be defined and shared before they are implemented in CTT.
Other documentation
Other documentation to be changed:
https://ishare.eu/about-ishare/roles/
https://ishare.eu/about-ishare/roles/roles-breakdown/
https://ishare.eu/about-ishare/authorization-registry/
In reference implementations of an Authorization Registry it would make sense to make a note about the new requirement.
Implementation
Release schedule
To be decided after discussion in the Change Advisory Board.
Communication
To be defined.
Last updated
