Ctrl+K
Archived docs. ESS 2.0 has reached end of life.

/derive Endpoint#

New in version 2.0.

Starting in version 2.0, ESS supports an authorization mechanism based on access requests and grants.

ESS serializes the access requests and grants as Verifiable Credentials (VCs) and provides an endpoint that queries access requests/grants VCs and returns the matching VCs in a Verifiable Presentation.

/derive Endpoint#

The ESS Access Grant service provides an endpoint with the following URL:

https://vc.<ESS DOMAIN>/derive

Note

Access to the /derive endpoint requires users to be authenticated.

To query for/derive access requests/grants, clients can send a derivation request to the endpoint:

Method:

POST

Content-Type

application/json

Endpoint:

https://vc.<ESS DOMAIN>/derive

Payload:

Derivation request object. See Input: Verifiable Credential for details.

Behavior#

The ESS’ /derive endpoint implements the derive credential portion of the VC API specification [1] with the following exceptions:

  • ESS’ /derive endpoint returns a Verifiable Presentation instead of a VC.

  • ESS’ /derive endpoint, by default, excludes both expired VCs (i.e., VCs with expirationDate in the past) and future VCs (i.e., VCs with issuanceDate in the future). To override, see options.

The endpoint queries the user-associated access requests/grants (regardless of revocation status) to return a Verifiable Presentation that contains the matching access requests/grants VCs. User-associated access requests/grants are:

  • Access Requests made by the user; i.e., the credentialSubject.id of the VC(s) is the user’s WebID,

  • Access Requests made to the user; i.e., the user’s WebID matches the property credentialSubject.hasConsent.isConsentForDataSubject, and

  • Access Grants issued to the user; i.e., the user’s WebID matches any of the following fields:

    • "credentialSubject.providedConsent.isProvidedTo"

    • "credentialSubject.providedConsent.isProvidedToPerson"

    • "credentialSubject.providedConsent.isProvidedToController"

Input: Verifiable Credential#

The endpoint accepts a JSON document of the form:

{
  "verifiableCredential": <VC to filter/query by>,
  "options": {
    "include": "ExpiredVerifiableCredential"
  }
}

verifiableCredential

Specify a filter access request/grant VC. The filter VC acts similarly to a “search-by-example” model and can be minimal (i.e., can be missing fields or have empty values such as an empty array, an empty document) or comprehensive. However, if any of the following field paths appear in the filter VC and are non-empty, ESS Access Grant services uses these non-empty field paths to filter access requests/grants VCs:

options

Optional. Specify the "include": "ExpiredVerifiableCredential" option to include expired VCs and future VCs in the returned VP.

"options": {
  "include": "ExpiredVerifiableCredential"
}

Omit to exclude the expired and future VCs.

If you specify a different option or value (such as "include": "ExpiredVerifiableCredentials" with an s), the endpoint ignores the option and excludes the expired and future VCs.

Output: Verifiable Presentation#

The /derive endpoint returns a Verifiable Presentation containing the matching access requests/grants VCs:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1"
  ],
  "holder": "https://vc.<ESS Domain>",
  "type": "VerifiablePresentation",
  "verifiableCredential": [
    { // Matching access request/grant VC },
    { // Matching access request/grant VC },
    ...
  ]
}

Filter Paths#

id#

"id": <value>

If the id field is present in the filter access requests/grants VC, the ESS Access Grant service considers the field for filtering user-associated access requests/grants.

credentialSubject#

If the credentialSubject field is present in the filter access requests/grants VC, and is not empty (i.e., it is not an empty document and contains at least one non-empty field path), the ESS Access Grant service considers the non-empty credentialSubject field path(s) to filter user-associated VCs.

For Access Request VCs#

Since credentialSubject.hasConsent only appears in access request VCs, a non-empty credentialSubject.hasConsent field path can be used to query access request VCs.

"credentialSubject": {
  "hasConsent": {
    "mode": <value or array of values>
    "hasStatus": <value>,
    "isConsentForDataSubject": <value>,
    "forPersonalData": <value or array of values>
  },
  "id": <value>
}

Note

For credentialSubject.hasConsent.mode and credentialSubject.hasConsent.forPersonalData fields that can be a single URL string or an array of URL strings,

  • A single URL string is equivalent to an array with a single element.

  • To filter by an array, matching VCs must include all elements in the provided array. However, the matching VCs can have additional elements in the array; that is, the matching VCs are not restricted to just the elements specified in the filter array.

That is:

  • <field>: "foo" condition would match:

    • <field>: "foo"

    • <field>: [ "foo" ]

    • <field>: [ "foo", "other string" ]

  • <field>: [ "foo" ] condition would match:

    • <field>: "foo"

    • <field>: [ "foo" ]

    • <field>: [ "foo", "other string" ]

For Access Grant VCs#

Since credentialSubject.providedConsent only appears in access grant VCs, a non-empty credentialSubject.providedConsent field path can be used to query access grant VCs.

"credentialSubject": {
  "providedConsent": {
    "mode":  <value(s)>,
    "hasStatus": <value>,
    "isProvidedToPerson": <value>,
    "forPersonalData": <value(s)>
  },
  "id": <value>
}

Note

For credentialSubject.providedConsent.mode and credentialSubject.providedConsent.forPersonalData fields that can be a single URL string or an array of URL strings,

  • A single URL string is equivalent to an array with a single element.

  • To filter by an array, matching VCs must include all elements in their array. However, the matching VCs can have additional elements in the array; that is, the matching VCs are not restricted to just the elements specified in the filter array.

That is:

  • <field>: "foo" (or <field>: ["foo"]) condition would match:

    • <field>: "foo"

    • <field>: [ "foo" ]

    • <field>: [ "foo", "other string" ]

  • <field>: [ "foo",  "bar" ] condition would match:

    • <field>: [ "foo", "bar" ]

    • <field>: [ "foo", "bar", "something else" ]

Empty credentialSubject#

ESS Access Grant service only considers non-empty credentialSubject field path(s) to filter user-associated access requests/grants. Empty credentialSubject field path(s) are not considered as part of the filter. Examples of empty credentialSubject field paths are:

"credentialSubject": {

}

"credentialSubject": {
   "hasConsent": {}
}

"credentialSubject": {
   "hasConsent": {
      "mode": [],
      "forPersonalData": []
   }
}

"credentialSubject": {
   "providedConsent": { }
}

"credentialSubject": {
   "providedConsent": {
       "mode": []
   }
}

issuer#

"issuer": <value>

If the issuer field is present in the filter access request/grant VC, the ESS Access Grant service considers the field for filtering user-associated access requests/grants VCs.

type#

"type": <value(s)>

If the type field is present in the filter access request/grant VC, the ESS Access Grant service considers the field for filtering user-associated access requests/grants VCs.

Note

If the type value is a non-empty array, matching VCs must include all elements in that array. The matching VCs can have additional elements in the array; that is, the matching VCs are not restricted to just the elements specified in the filter array.

Examples#

ESS Access Grant service performs a match on non-empty id, credentialSubject, issuer, and type field paths present in the filter VCs.

Note

In the following examples, the filters return user-associated access requests/grants (both active and revoked) that match the filter field paths. Because the payload does not specify the options: {“include”: “ExpiredVerifiableCredential” }, expired and future access requests/grants are excluded from the results.

Example 1#

The filter queries for user-associated access requests/grants where owliverowner grants Read access to requestingrabbit. The filter’s verifiableCredential field contains the following non-empty fields for matching:

  • credentialSubject.providedConsent.mode

  • credentialSubject.providedConsent.hasStatus

  • credentialSubject.providedConsent.isProvidedToPerson

  • credentialSubject.id

  • type

When the following payload is posted to the /derive endpoint,

{
   "verifiableCredential": {
      "credentialSubject": {
         "providedConsent": {
            "mode": ["http://www.w3.org/ns/auth/acl#Read" ],
            "hasStatus": "https://w3id.org/GConsent#ConsentStatusExplicitlyGiven",
            "isProvidedToPerson": "https://id.<ESS DOMAIN>/requestingrabbit"
          },
          "id": "https://id.<ESS DOMAIN>/owliverowner"
      },
      "type": [
          "VerifiableCredential",
          "SolidAccessGrant"
      ]
   }
}

The filter matches all user-associated access requests/grants where:

  • credentialSubject.providedConsent.mode matches the value "http://www.w3.org/ns/auth/acl#Read" or contains the value "http://www.w3.org/ns/auth/acl#Read" as an array element, AND

  • credentialSubject.providedConsent.hasStatus matches the value "https://w3id.org/GConsent#ConsentStatusExplicitlyGiven", AND

  • credentialSubject.providedConsent.hasStatus matches the value "https://id.<ESS DOMAIN>/requestingrabbit", AND

  • credentialSubject.id matches the value "https://id.<ESS DOMAIN>/owliverowner", AND

  • type contains the values "VerifiableCredential" and "SolidAccessGrant" as array elements.

Upon completion, the endpoint returns a Verifiable Presentation with the matching VCs.

Example 2#

The following filter queries for user-associated access grants that grants Write access to the specified resource. The filter’s verifiableCredential field contains the following non-empty fields for matching:

  • credentialSubject.providedConsent.mode

  • credentialSubject.providedConsent.forPersonalData

When the following payload is posted to the /derive endpoint,

{
  "verifiableCredential": {
    "credentialSubject": {
      "providedConsent": {
        "mode": "http://www.w3.org/ns/auth/acl#Write",
        "forPersonalData": [
          "https://storage.<ESS Domain>/<Pod Identifier>/getting-started/readingList/myList"
        ]
      }
    }
  }
}

The filter matches all user-associated access grants where:

  • credentialSubject.providedConsent.mode matches the value "http://www.w3.org/ns/auth/acl#Write" or contains the value "http://www.w3.org/ns/auth/acl#Write" as an array element, AND

  • credentialSubject.providedConsent.forPersonalData matches the value "https://storage.<ESS Domain>/<Pod Identifier>/getting-started/readingList/myList" or contains the value as an array element.

Upon completion, the endpoint returns a Verifiable Presentation with the matching VCs.

Empty Filter Paths#

ESS Access Grant service performs a match only on non-empty id, credentialSubject, issuer, type field paths. Otherwise, the service returns all access requests/grants associated with the user.

For example, when the following payloads are posted to the /derive endpoint:

  • The filter’s verifiableCredential field is an empty document; i.e., the filter VC does not contain any of the fields used for matching:

    {
  "verifiableCredential": { }
}

    This would match all access request VCs and access grant VCs associated with the user.

  • The filter’s verifiableCredential field contains empty values for the query field “credentialSubject.hasConsent” and no other matching fields (i.e., id, type, credentialSubject.id fields). As such, the filter VC does not have any non-empty matching filter paths

    {
  "verifiableCredential": {
     "credentialSubject": {
       "hasConsent": { }
     }
  }
}

    This would match all access request VCs and access grant VCs associated with the user.

  • The filter’s verifiableCredential field contains empty values for the query field “credentialSubject.providedConsent” and no other matching fields (i.e., id, type, credentialSubject.id):

    {
  "verifiableCredential": {
     "@context": [
       "https://www.w3.org/2018/credentials/v1",
       "https://w3id.org/security/suites/ed25519-2020/v1",
       "https://w3id.org/vc-revocation-list-2020/v1",
       "https://vc.<ESS DOMAIN>/credentials/v1"
     ],
     "credentialStatus": {
       "id": "https://vc./status/VfaR#98",
       "revocationListCredential": "https://vc.<ESS DOMAIN>/status/VfaR",
       "revocationListIndex": "98",
       "type": "RevocationList2020Status"
     },
     "credentialSubject": {
       "providedConsent": { }
     },
     "type": [ ]
  }
}

Upon completion, the endpoint returns a Verifiable Presentation with the matching VCs; in this case, all access request VCs and access grant VCs associated with the user.

On this page