Authorisation

This page must be considered part of the iSHARE Framework

This page is considered normative and is therefore compliant with RFC 2119.

Authorisation Registry discovery logic

The Service Provider or Service Consumer can discover the Authorisation Registry in the following order when its not already known.

1. The Entitled Party has registered an Authorisation Registry for the specific capability in its /capabilities endpoint;

2. The Entitled Party has registered the Authorisation Registry for the specific service provider in the Participant Registry;

3. The Entitled Party has registered an Authorisation Registry for a specific data space in the Participant Registry;

4. The Entitled Party's has set a default Authorisation Registry in the Participant Registry.

Machine to Machine (M2M) Authorisation

A core feature of iSHARE is enabling participants to manage authorisations, either on an organisational level or on a personal level. Read more on the background of iSHARE Authorisations in the iSHARE Scheme.

As defined by the iSHARE Framework, participants can request delegation evidence from either an Entitled Party or one of the Authorisation Registries. To receive this evidence, various rules need to be followed:

• An organisation can only request evidence for an Authorisation policy that concerns this organisation. The organisation is either the creator (issuer) of the policy, or is the subject to whom the policy applies.

• The only exception to the previous rule occurs when a Service Provider needs to gather delegation evidence for a client. The Service Provider needs to pass a valid client_assertion of this client to the Entitled Party / Authorisation Registry. This proves that this client is indeed at the gate of the Service Provider, and it is necessary to ask about his authorisations.

• Such a client_assertion should be passed through the previous_steps array in the delegation_mask. The delegation_mask is the body of the request to the /delegation endpoint of an Authorisation Registry. The recommendation is that the client_assertion is always necessary if a Service Provider is not listed as issuer or subject of the delegation. However, if there are valid reasons a dataspace may relax this requirement while keeping in mind the impact this can have on the privacy of the authorisations at the Authorisation Registry. Allowing anyone to fetch a delegation evidence without valid reasons may potentially allow a mischievous party to crawl through all authorisations. Appropriate measures must be taken to avoid such situations.

• iSHARE only specifies what the request and response data structure of delegation evidence looks like. iSHARE does not prescribe what the input and database storage for authorisation looks like. There is a standardised Delegation Policy creation endpoint, and Authorisation Registries may implement that.

The /policy endpoint of the Test Authorisation Registry is not standardised in iSHARE and is only an example of how authorisations can be stored at an AR.

Human to Machine (H2M) Authorisation

Besides authorisation on an organisational level, within iSHARE, it is also possible to authorise humans to act on behalf of another organisation. The generic OpenID Connect 1.0 flow does not take into account Authorisations of a human. However, in iSHARE, it is essential that authorisations of a user are combined with their identity details before a service can be offered.

As defined by the iSHARE Framework, authorisations of a human are registered at an Authorisation Registry, and can be retrieved via various means using the userinfo endpoint. For this purpose, there are some modifications to the OpenID Connect Flow. User identities are protected by sharing pseudonyms in order to comply with privacy requirements. Authorisation of a human is done by replacing the ‘accessSubject’ value on the root level in delegationEvidence with an iSHARE pseudonym of the human user.

In some cases, it is necessary to encrypt JWTs in order to prevent unsuspecting users or Identity Brokers from being able to read and infer data not meant for them.

Broadly, users’ interaction with the service provider can happen in 2 ways:

The service-specific approach

The user has the specific link to a specific service and is only interested in using that service. The service provider only needs to check if the human user is authorised to access this service.

The portal approach

The user uses a portal to access a service. The Service Provider needs to know the authorisations of the user in order to only show services available to the user.

Service Specific Approach

In the service-specific approach, the Service Provider will ask for a specific authorisation of the human user in the request parameter of the userinfo endpoint. This request closely follows the delegation mask specification. However, the value for the accessSubject On the root level of the delegationEvidence is replaced with the iSHARE pseudonym of the human user

Since the Identity Provider and Human Authorisation Registry are the same entity, the discovery is not needed. Else, follow the discovery logic as explained above.

Portal approach

In the portal approach, the Service Provider is allowed to do a wildcard request in the request parameter of the user info endpoint. This request closely follows the delegation mask specification. However, the value accessSubject on the root level of the delegation Evidence is replaced with the iSHARE pseudonym of the human user. The wildcard is allowed because the Service Provider needs to know all the authorisations of the human user to show them in the portal, before the human user can select the correct service. Since a human user would be representing only one company at a time, it is asked by the IDP to select the company they want to represent. When the user identity is common for different companies, it can represent.

Since the Identity Provider and Human Authorisation Registry are the same entity, the discovery is not needed. Else, follow the discovery logic as explained above.