/derive
Endpoint#
New in version 2.0.
Starting in version 2.0, ESS supports an authorization mechanism based on access requests and grants. In 2.0, the access requests and grants are serialized as a Verifiable Credentials (VCs).
To support access requests and grants, ESS provides an endpoint that derives VCs through query and return the matching VCs in a Verifiable Presentation.
/derive
Endpoint#
The ESS VC 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 VCs, clients can send a derivation request to the endpoint:
Method: |
|
---|---|
Content-Type |
|
Endpoint: |
|
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 withexpirationDate
in the past) and future VCs (i.e., VCs withissuanceDate
in the future). To override, see options.
The endpoint queries the user-associated VCs (regardless of revocation status) to return a Verifiable Presentation that contains the matching VCs. User-associated VCs are:
VCs that have been issued to the user; i.e., the
credentialSubject.id
of the VC(s) is the user’s WebID,VCs that have been requested of the user; i.e., the user’s WebID matches the property
credentialSubject.hasConsent.isConsentForDataSubject
, andVCs that have been granted 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"
}
}
|
Specify a filter 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 VC services uses these non-empty field paths to filter VCs: |
|
Optional. Specify the "options": {
"include": "ExpiredVerifiableCredential"
}
Omit to exclude the expired and future VCs. If you specify a different option or value (such as |
Output: Verifiable Presentation#
The /derive
endpoint returns a Verifiable Presentation containing
the matching VCs:
{
"@context": [
"https://www.w3.org/2018/credentials/v1"
],
"holder": "https://vc.<ESS Domain>",
"type": "VerifiablePresentation",
"verifiableCredential": [
{ // Matching VC },
{ // Matching VC },
...
]
}
Filter Paths#
id
#
"id": <value>
If the id
field is present in the filter VC, the ESS VC service
considers the field for filtering user-associated VCs.
credentialSubject
#
If the credentialSubject
field is present in the filter VC and is
not empty (i.e., it is not an empty document and contains at
least one non-empty field path),
the ESS VC 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 VC service only considers non-empty credentialSubject
field
path(s) to filter user-associated VCs. 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 VC, the ESS VC service
considers the field for filtering user-associated VCs.
type
#
"type": <value(s)>
If the type
field is present in the filter VC, the ESS VC service
considers the field for filtering user-associated 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 VC 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 VC payloads return user-associated VCs (both active and revoked) that that match the filter field paths. Because the payload does not specify the options: {“include”: “ExpiredVerifiableCredential” }, expired and future VCs are excluded from the results.
Example 1#
The filter VC queries for user-associated VCs where owliverowner
grants Read
access to
requestingrabbit
. The filter VC 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 VC matches all user-associated VCs 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, ANDcredentialSubject.providedConsent.hasStatus
matches the value"https://w3id.org/GConsent#ConsentStatusExplicitlyGiven"
, ANDcredentialSubject.providedConsent.hasStatus
matches the value"https://id.<ESS DOMAIN>/requestingrabbit"
, ANDcredentialSubject.id
matches the value"https://id.<ESS DOMAIN>/owliverowner"
, ANDtype
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 VC queries for user-associated VCs that grants Write
access to the specified
resource. The filter VC 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 VC matches all user-associated VCs 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, ANDcredentialSubject.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 VC service performs a match only on non-empty id, credentialSubject, issuer, type field paths. Otherwise, the service returns all VCs associated with the user.
For example, when the following payloads are posted to the /derive
endpoint:
The filter VC is an empty document; i.e., the filter VC does not contain any of the fields used for matching:
{ "verifiableCredential": { } }
This would match all the VCs (access request VCs and access grant VCs) associated with the user.
The filter VC 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 the VCs (access request VCs and access grant VCs) associated with the user.
The VC filter 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 VCs associated with the user.
- 1
The VC API specification is in Draft status. Features based on draft specifications are subject to change.