Deze pagina’s zijn in het engels ten behoeve van mogelijk internationale ontwikkelaars

This endpoint MUST be implemented by the following roles:

Authorization Register

This endpoint MAY be implemented by the following roles:

Data Entitled party

Used to obtain delegation evidence from a data entitled party or authorisation register. Delegation evidence can be used in future data service requests to data service providers if delegation is enabled in their data service. In the DSGO delegation evidence expresses the delegation of rights from a data entitled party to a delegated data service consumer. For more information about delegation in the DSGO, see Delegaties.

Autorization registers MUST provide delegation evidence via the /delegation endpoint

If data entitled parties wish to provide delegation evidence, they MUST provide delegation evidence via the /delegation endpoint

Information about delegation is provided in delegationEvidence object. The delegationEvidence object is based on iSHARE v2.0, which in turn is inspired by the XACML 3.0 specifications, see Structure of delegation evidence.

delegationEvidence object

Parameters			Type	Description

Parameters			Type	Description
`notBefore`		Required	Integer	Timestamp indicating the start of the validity period of this delegation evidence, MUST be a UNIX timestamp, following the timestamp conventions. SHOULD equal the time of issuing of the evidence unless historic evidence is requested.
`notOnOrAfter`		Required	Integer	Timestamp indicating the end of the validity period of this delegation evidence, MUST be a UNIX timestamp, following the timestamp conventions. The issuer of the evidence (data entitled party or autorisation register) determines the 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`		Required	String	MUST contain a valid Organisation ID (an EORI or KvK number) of the delegator (data entitled party).
`target`		Required	Object	Object MUST contain an `accessSubject`. No other elements are allowed. It makes the entire delegation evidence applicable only to this `accessSubject`.
	`accessSubject`	Required	String in `target`	MUST contain a valid Organisation ID (an EORI or KvK number) oof the delegate (the data service consumer that receives the delegated rights).
`policySets`		Required	Array	MUST contain one or more `policySet` objects with an indication for further delegation. Note that multiple `policySet` objects 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` objects evaluates to `Permit`.

policySet Object

The second level objects in policySets each contain the parameters in the table below. Other parameters are not allowed. Note that XACML spec is heavily restricted, a.o. for the reason to prevent redundancy (and resulting possible conflicts) with the root policySet element.

Parameters				Type	Description

Parameters				Type	Description
`maxDelegationDepth`			Optional	Integer	Optional element which indicates whether further delegation of rights are allowed as part of this policySet, as conveyed in `policies`. MUST contain an integer value indicating the amount of delegation steps that are allowed after this step in order to evaluate the entire delegation path to `Permit`.
`target`			Required	Object	Object MUST contain an `environment` object. No other elements are allowed.
	`environment`		Required	Object in `target`	Object MUST contain a `licences`. No other elements are allowed.
		`licences`	Required	Array in `environment`	MUST be equal to one or more of the licence codes, prepended with a “`DSGO.`" prefix, which describes which DSGO licences apply to the object this `policySet` applies to.
`policies`			Required	Array	MUST contain one or more `policy` objects, used to express the actual rights being delegated. Note that `policies` within one `policySet` object 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 `policy` elements evaluates to `Permit`.

policy Object

A policy element contains the parameters in the table below.

Parameters				Type	Description

Parameters				Type	Description
`target`			Required	String	Object MUST contain a `resource` object, `actions` and `environment`, which describes the target, in terms of resource and action, this policy applies to. It is also the scope that is permitted through the default `rule`. Additional `rule` elements can be described to exclude resources and actions from the default `policy` rights
	`resource`		Required	Object in `target`	Object MUST contain the`type`, `identifiers` and `attributes`.
		`type`	Required	String in `resource`	MUST contain a string which describes the type of resource to which the rules apply.
		`identifiers`	Required	Array in `resource`	MUST contain an array of strings with one or more resource identifiers. Depending on the delegated rights, the identifier could be a data service `id`. Depending on the `type` an `identifier` SHOULD be an urn according to RFC 8141.
		`attributes`	Optional	Array in `resource`	Optional array describing the attributes of the resources the delegated rights apply to. If omitted defaults to all attributes. MUST contain an array of attributes of the resources the delegated rights apply to. Depending on the `type` an `attribute` SHOULD be an urn according to RFC 8141.
	`actions`		Required	Array in `target`	MUST contain an array describing the action for which the delegated rights apply.
	`environment`		Optional	Object in `target`	Object MUST contain a `serviceProviders`. No other elements are allowed.
		`serviceProviders`	Required	Array in `environment`	MUST contain an array of (one or more) valid Organisation ID, containing an EORI or KvK number, of the data service provider which are allowed to provide services to the `accessSubject` as described within this `policy`.
`rules`			Required	Array	MUST contain one or more `rule` objects describing the obtained rights within the `resource`. The first `rule` is the default `rule` that applies to the `target` at `policy` level. Note that additional `rule` elements within one `policy` object are intended to restrict each the default `rule`. All `rule` elements in a `policy` MUST be evaluated in a `deny-override` manner, allowing a `Permit`only if all of the `rule` elements evaluate to `Permit`.

Default Rule

the default rule element contains the parameters in the table below.

Parameters		Type	Description

Parameters		Type	Description
`effect`	Required	String	MUST contain `Permit`

Additional rules

Additional rule elements contains the parameters in the table below.

Parameters				Type	Description

Parameters				Type	Description
`effect`			Required	String	MUST contain `Deny`
`target`			Required	Object	Object MUST contain a `resource` object, which describes the resource and action which this `rule` applies to. Additional `rule` elements are limitations of the default `rule` and `resource` scope.
	`resource`		Required	Object in `target`	Object MUST contain the `type`, `identifiers` and `attributes`.
		`type`	Optional*	String in `resource`	MUST contain a string which describes the type of resource to which the rules apply.
		`identifiers`	Optional*	Array in `resource`	MUST contain an array of strings with one or more resource identifiers. Depending on the `type` an `identifier` SHOULD be an urn according to RFC 8141.
		`attributes`	Optional*	Array in `resource`	Optional array describing the attributes of the resources the delegated rights apply to. If omitted defaults to all attributes. MUST contain an array of attributes of the resources the delegated rights apply to. Depending on the `type` an `attribute` SHOULD be a urn according to RFC 8141.
`actions`			Required	Array	Optional array of `actions`, the additional `rule` applies to the `actions` listed. MUST contain an array describing the specific action for which this `rule` applies. If no `actions` are listed then the default is to all actions defined within the `policy`.

* Note: Although not individually required, at least one of the parameters within the resource object MUST be specified to which the additional rules apply.

See below for an example delegationEvidence object (based on iSHARE v2.0, see link)

{
  "notBefore": 1541058939,
  "notOnOrAfter": 2147483647,
  "policyIssuer": "EU.EORI.NL000000005",
  "target": {
    "accessSubject": "EU.EORI.NL000000001"
  },
  "policySets": [
    {
      "maxDelegationDepth": 0,
      "target": {
        "environment": {
          "licenses": [
            "DSGO.0001"
          ]
        }
      },
      "policies": [
        {
          "target": {
            "resource": {
              "type": "GS1.CONTAINER",
              "identifiers": [
                "180621.CONTAINER-Z"
              ],
              "attributes": [
                "GS1.CONTAINER.ATTRIBUTE.ETA",
                "GS1.CONTAINER.ATTRIBUTE.WEIGHT"
              ]
            },
            "environment": {
              "dataServiceProviders": [
                "EU.EORI.NL000000003"
              ]
            },
            "actions": [
              "DSGO.READ",
              "DSGO.CREATE",
              "DSGO.UPDATE",
              "DSGO.DELETE"
            ]
          },
          "rules": [
            {
              "effect": "Permit"
            }
          ]
        }
      ]
    }
  ]
}

Endpoint

the /parties endpoint follows the generic technical requirements, as well as the requirements specified for specific methods. The figure below gives an overview of the HTTP methods that are supported by the /parties endpoint. These methods are further detailed and specified in the pages below: