Delegation Policy

The Delegation Policy Request endpoint is an API endpoint that can be used to request the creation of a delegation policy.

The POST request to /delegationPolicy is an OPTIONAL endpoint. For more information on OPTIONAL specifications, see functional requirements per role.

Request creation of a delegation policy

post

The Delegation policy request endpoint is an API endpoint that receives policy creation requests. The POST body accepts a JWT token: the Policy Creation Request Token.

Authorizations

BearerAuth

AuthorizationstringRequired

OAuth 2.0 authorization based on bearer token. MUST contain “Bearer “ + access token value. Must be provided if restricted endpoints are needed.

Body

application/json

delegationPolicyRequestTokenstring · application/jwtRequired

Responses

200

OK: The requested policy is created.

No content

401

Unauthorized: When Authorization header is either missing, invalid or token has already expired.

403

Forbidden: This error message is return when a policy creation request could not be processed after rules evaluation. The requested policy does not comply with the rules as set by the Entitled Party.

500

Server Error: When the Authorization Registry was unable to process the request

post

/delegationPolicy

HTTPcURLJavaScriptPython

POST /delegationPolicy HTTP/1.1
Host: isharetest.net
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 39

{
  "delegationPolicyRequestToken": "text"
}

No content

Request

Headers

• Authorization String. (Required) OAuth 2.0 authorisation based on a bearer token. MUST contain “Bearer “ + access token value. How to retrieve the access token can be found in the Access Token Endpoint section.

• Content-Type String. Defines the request body content type. MUST be equal to application/json.

Parameters

The body of the request contains iSHARE Compliant JWT delegationPolicyRequestToken. Besides the default attributes (iss, sub, aud, etc.), it contains the following attributes. The model of the delegation PolicyRequestToken is available on the iSHARE OpenAPI documentation. For convenience, the model is also described below.

• delegationPolicyRequest Object. Root level. (Required) Contains information about the delegation policy that is requested to create.

  • notBefore Integer. Contained in delegationPolicyRequest. (Required) Unix timestamp indicating the start of the validity period of the requested delegation policy.

  • notOnOrAfter Integer. Contained in delegationPolicyRequest. Unix timestamp indicating the end of the validity period of the requested delegation policy.

  • policyRequestor String. Contained in delegationPolicyRequest. (Required) Identifier of the party to which the right is delegated.

  • policyIssuer String. Contained in delegationPolicyRequest. (Required) Identifier of the delegator, also known as the delegating entity.

  • target Object. Contained in delegationPolicyRequest. (Required) MUST for the root level contain an accessSubject. No other elements are allowed. It makes the entire requested delegation policy applicable only to this accessSubject.

    • accessSubject Object. Contained in target. (Required) The identifier of the delegate, also known as the entity that receives the delegated rights. It should be a party identifier for M2M cases or a human pseudonym for H2M cases. This would usually hold the same value as policyRequestor.

  • policySets Array of Objects. Contained in delegationPolicyRequest. (Required) A container for one or more objects containing policy elements with an indication for further delegation. Note that policySet elements within one delegationPolicyRequest MUST not restrict each other, but rather offer a mechanism to express additional rights. They will be evaluated by the Authorisation Registry in a permit-override manner, allowing a Permit if only one of the policySet elements evaluates to Permit.

    • maxDelegationDepth Integer. Contained in policySets. Optional. An 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. Optional.

      Contains environment.

      • environment

        Object. Contained in target. Optional.

        Contains licenses.

        • licenses

          Array of Strings and Objects. Contained in environment.

          An array which describes which iSHARE licenses apply to this policy set. Please refer to theLicenses model for more information about structuring this array.

    • policies

      Array of Objects. Contained in policySets. (Required)

      Used to express the actual rights for which evidence is being provided. Note that policies within one policySet 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. (Required) Describes the target, in terms of resource and action, this request applies. It is also the scope that is permitted through the default rule.

        • resource Object. Contained in target. (Required) Contains type, identifiers and attributes.

          • type String. Contained in resource. (Required) String which describes the type of resource to which the rules apply.

          • identifiers Array of Strings. Contained in resource. Optional. Optional array of strings containing one or more resource identifiers.

          • attributes Array of Strings. Contained in resource. Optional. An optional array of attributes of the resources the delegated rights apply to.

        • actions Array of Strings. Contained in target. (Required) An array of actions that apply to this policy.

        • context Object. Contained in target. Optional. Object containing context information that must be evaluated by the Authorisation Registry before providing Delegation Evidence.

          • conditions Object. Contained in context. Optional. Optional conditions which must be evaluated by the Authorisation Registry. For guidance on how to interoperably define conditions, refer to the page about delegation evidence conditions. The condition structure is the same as the structure when conditions are part of the rules that are provided to the Service Provider/Consumer (Type 2: evaluate conditions by the Service Provider). When Delegation Evidence is requested by the Service Provider/Consumer (Type 1: conditions evaluated by an Authorisation Registry), it is expected that the context contains key/value pairs on which these conditions must be applied. The following keywords in conditions are reserved:

            • serviceProviders: reserved keyword for a condition that contains a list of party identifiers of Service Providers, which are allowed to provide services to the accessSubject.

      • rules Array of Objects. Contained in policies. (Required)

        • effect String. Contained in rules. (Required) Value must be equal to Permit or Deny.

        • conditions Object. Contained in rules. Optional. Optional conditions which must be evaluated by the Service Provider before the rule applies. The conditions must be provided as-is to the Service Provider. For guidance on how to interoperably define conditions, refer to the page about delegation evidence conditions (Type 2: evaluate conditions by the Service Provider). The following keywords in conditions are reserved:

          • serviceProviders: reserved keyword for a condition that contains a list of party identifiers of Service Providers, which are allowed to provide services to the accessSubject.

Response

HTTP status codes

• 200 OK

  When the creation of the delegation policy was successful, an OK result should be returned.