Delegation
Last updated
Version 2.1 (current version)
Last updated
This page must be considered part of the iSHARE Framework
This page is considered normative and is therefore compliant with RFC 2119.
Authorization
String.
OAuth 2.0 authorization based on bearer token. MUST contain “Bearer “ + access token value. How to retrieve the access token can be found at Access Token Endpoint section.
Content-Type
String.
Defines request body content type. MUST be equal to application/json.
The body of the request MUST contain a JSON with the following structure.
delegationRequest
Object. Root level.
The request for delegation evidence.
policyIssuer
String. Contained in delegationRequest.
Identifier of the delegator (the delegating entity, usually the Entitled Party).
target
Object. Contained in delegationRequest.
MUST for the root level contain an accessSubject. No other elements are allowed.
accessSubject
String. Contained in target.
Identifier of the delegate, also known as the entity that receives the delegated rights (usually the Service Consumer).
policySets
Array of Objects. Contained in delegationRequest.
Container for one or more objects containing policy elements with an indication for further delegation. Note that policySet elements within one delegationRequest MUST not restrict each other, but rather offer a mechanism to express additional rights. They will be evaluated by the Authorization Registry in a permit-override manner, allowing a Permit if only one of the policySet elements evaluates to Permit.
policies
Array of Objects. Contained in policySets.
Used to express the actual rights for which evidence is being requested. Note that policies within one policySets object MUST not restrict each other, but rather offer a mechanism to express additional rights. They will be evaluated in a permit-override manner, allowing a Permit if only one of the policy elements evaluates to Permit.
target
Object. Contained in policies.
Describes the target, in terms of resource and action, this request applies to. It is also the scope that is permitted through the default rule.
resource
Object. Contained in target.
Contains type, identifiers and attributes.
type
String. Contained in resource.
String which describes the type of the resource for which delegation evidence is requested.
identifiers
Array of Strings. Contained in resource.
Array of strings containing one or more resource identifiers for which the delegation evidence is requested. Use of wildcards (for example "*") is allowed.
attributes
Array of Strings. Contained in resource.
Array of attributes of the resources for which the delegation evidence is requested. Use of wildcards (for example "*") is allowed.
actions
Array of Strings. Contained in target.
Array of actions for which delegation evidence is requested.
rules
Array of Objects. Contained in policies.
effect
String. Contained in rules.
Value must be equal to Permit or Deny.
delegation_path
Array of Strings. Root level. Optional.
Container for one or more iSHARE identifiers values for a situation where multiple delegation policies need to be linked together.
previous_steps
Array of Strings. Root level. Optional.
Container for one or more pieces of evidence such that the client has legitimate reason to request delegation evidence. For example:
Client_assertion
Delegation_evidence in a delegation chain
Other evidence or information as determined by the data space (could also be verified post-transaction), specification beyond the scope of this framework
Privacy considerations: to prevent unallowed access to delegation evidence, a data space or participant can decide to require evidence or information in the previous_steps attribute, depending on the nature of the data that is being shared.
The response contains a delegation_evidence_token, containing an iSHARE JWT. The decoded delegation_evidence_token JWT payload is structured as follows.
delegationEvidence
Object. Root level.
The root of any delegation evidence.
notBefore
Integer. Contained in delegationEvidence.
Unix timestamp in UTC indicating the start of validity period of this delegation evidence. SHOULD equal the time of issuing of the evidence unless historic evidence is requested.
notOnOrAfter
Integer. Contained in delegationEvidence.
Unix timestamp in UTC indicating the end of validity period of this delegation evidence. It is up to the issuer off the evidence to set this time. Note that a reasonable amount of time SHOULD be allowed for processing of longer delegation paths. Also note that evidence cannot be revoked, so setting very long validity periods SHOULD be avoided.
policyIssuer
String. Contained in delegationEvidence.
Identifier of the delegator, also know as the delegating entity (usually the Entitled Party).
target
Object. Contained in delegationEvidence.
MUST for the root level contain an accessSubject. No other elements are allowed. It makes the entire delegation evidence applicable only to this accessSubject.
accessSubject
Object. Contained in target.
iSHARE identifier of the delegate, also known as the entity that receives the delegated rights (usually the Service Consumer). It should be either iSHARE identifier for M2M cases or human pseudonym for H2M cases.
policySets
Array of Objects. Contained in delegationEvidence.
Container for one or more objects containing policy elements with an indication for further delegation. Note that policySet elements within one delegationEvidence MUST not restrict each other, but rather offer a mechanism to express additional rights. They MUST be evaluated in a permit-override manner, allowing a Permit if only one of the policySet elements evaluates to Permit.
maxDelegationDepth
Integer. Contained in policySets. Optional.
Optional element that, if present, indicates that further delegation of the rights, conveyed in the policy elements that are part of this PolicySet, is allowed. The value indicates the delegation steps that are allowed after this step in order to evaluate the entire delegation path to Permit.
target
Object. Contained in policySets.
Contains environment.
environment
Object. Contained in target.
Contains licenses.
licenses
Array of Strings. Contained in environment.
Array which describes which iSHARE licenses apply to this policySet.
policies
Array of Objects. Contained in policySets.
Used to express the actual rights for which evidence is being provided. Note that policies within one policySets object MUST not restrict each other, but rather offer a mechanism to express additional rights. They will be evaluated in a permit-override manner, allowing a Permit if only one of the policy elements evaluates to Permit.
target
Object. Contained in policies.
Describes the target, in terms of resource and action, this request applies to. It is also the scope that is permitted through the default rule.
resource
Object. Contained in target.
Contains type, identifiers and attributes.
type
String. Contained in resource.
String which describes the type of resource to which the rules apply.
identifiers
Array of Strings. Contained in resource.
Array of strings containing one or more resource identifiers to which the rules apply.
attributes
Array of Strings. Contained in resource.
Array of attributes of the resources to which the rules apply.
actions
Array of Strings. Contained in target.
Array of actions that apply to this policy.
environment
Object. Contained in target.
Optional field that contains serviceProviders.
serviceProviders
Array of Strings. Contained in environment. Optional.
Array which lists the party identifier of Service Providers which are allowed to provide services to the accessSubject as described within this policy.
rules
Array of Objects. Contained in policies.
effect
String. Contained in rules.
Value must be equal to Permit or Deny.
The response contains an encoded JWT:
After decoding, the example content of the JWT looks like this:
Used to obtain delegation evidence from an Authorization Registry. The response is a signed JSON Web Token. Please refer to the models ‘jwt_header’ and ‘jwt_payload_delegation_evidence_token’ which indicate what the decoded response will look like.
/delegation