Access Grant Service

ESS supports an authorization mechanism based on Access Requests and Grants . With Access Requests and Grants:

An agent sends an Access Request to the resource owner . This request includes the specific access modes (e.g. Read , Write , Append ), the resources to access, etc. See Access Request Shape.
The resource owner approves or denies the Access Request.

For an approved request, ESS creates an Access Grant with an approved status.
For a denied request, ESS creates an Access Grant with a denied status.

If the requesting agent receives an approved Access Grant, the requesting agent can exchange the Access Grant for an access token in order to access the resource. See UMA tokens.

Important

An Access Request for a Container, by default, also applies to the Container’s descendants, unless explicitly specified otherwise in the request (See inherit: false).
An Access Grant for a Container, by default, also applies to the Container’s descendants, unless explicitly specified otherwise in the grant (See inherit: false).

Access Grant Service

ESS provides an Access Grant Service that serializes Access Requests and Grants as Verifiable Credentials (VCs) and provides various Access Grants endpoints that follow the draft VC API.

ESS Access Grant Service Endpoints

By default, the ESS Access Grant Service runs from the following root URL:

https://vc.<ESS Domain>

To change the root URL, see INRUPT_VC_ISSUER .

The ESS Access Grant Service consists of the following endpoints:

Endpoint

Description

/issue

Issues Access Requests and Grants that are serialized as VCs.

/verify

Verifies Access Requests and Grants that are serialized as VCs.

/status

Updates the status of an Access Grant.

/query

Query for Access Requests and Grants using filters.

/derive

Query for Access Requests and Grants VCs and derive a Verifiable Presentation that contains the matching Access Requests and Grants VCs.

Endpoint Access Control

Access Tokens

ESS Access Grant Service endpoints ( /issue , /status , /query , and /derive ) require the user to be authenticated. To identify the user, the endpoints support the use of the following tokens:

See also:

Client Allow Lists

Note The Access Grant Service replaces the INRUPT_VC_CLIENT_ID_ALLOW_LIST configuration with required configurations that specify allow lists by the specific Access Credential Type. These configuration must be set for the Access Grant Service to start.

To restrict client access to the /issue and /status endpoints, see:

INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSREQUEST (Defaults to Any .)
INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSGRANT (Default is unset .)

To set these configurations, use the ESS-provided overlay inputs/ file ess-verifiable-credentials-client-type-allow-list.env . If keeping default values for these configurations, you only need to set INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSGRANT in the ess-verifiable-credentials-client-type-allow-list.env file.

Access Grant Service Discovery

ESS provides a Access Grant service metadata resource at the following /.well-known/vc-configuration URI:

https://vc.<ESS Domain>/.well-known/vc-configuration

The endpoint returns a JSON-LD document that includes the locations for the Access Grant Service endpoints:

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://vc.<ESS Domain>/credentials/v1"
  ],
  "derivationService": "https://vc.<ESS Domain>/derive",
  "issuerService": "https://vc.<ESS Domain>/issue",
  "queryService": "https://vc.<ESS Domain>/query",
  "statusService": "https://vc.<ESS Domain>/status",
  "supportedSignatureTypes": [
    "Ed25519Signature2020"
  ],
  "verifierService": "https://vc.<ESS Domain>/verify"
}

Access Grant Service Configuration

As part of the installation process, Inrupt provides base Kustomize overlays and associated files that require deployment-specific configuration inputs.

The following configuration options are available for the service and may be set as part of updating the inputs for your deployment. The Inrupt-provided base Kustomize overlays may be using updated configuration values that differ from the default values.

Required

INRUPT_VC_ISSUER

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

Specifies the root URL of the Access Grant service.

QUARKUS_DATASOURCE_JDBC_URL

Required if using a PostgreSQL database for persistence

The JDBC connection string for the PostgreSQL database.

QUARKUS_DATASOURCE_PASSWORD

Required if using a PostgreSQL database for persistence

The password for the JDBC connector

QUARKUS_DATASOURCE_USERNAME

Required if using a PostgreSQL database for persistence

The username for the JDBC connector

QUARKUS_MONGODB_CONNECTION_STRING

Required if using MongoDB for persistence

The connection string for the MongoDB database

INRUPT_KAFKA_AUDITV1EVENTSENCRYPTED_CIPHER_PASSWORD

The strong cipher key to use when running auditing with encrypted messages.

INRUPT_KAFKA_AUDITV1EVENTSPRODUCERENCRYPTED_CIPHER_PASSWORD

The strong cipher key to use when running auditing with encrypted messages over the auditv1eventsproducerencrypted topic.

KAFKA_BOOTSTRAP_SERVERS

Default : localhost:9092.

Comma-delimited list of Kafka broker servers for use by ESS services, including this service.

Setting KAFKA_BOOTSTRAP_SERVERS configures ESS to use the same Kafka instance(s) for all its Kafka message channels (e.g., solidresource and auditv1out message channels). The Access Grant service uses the auditv1out message channel.

Note Inrupt-provided overlays default to using KAFKA_BOOTSTRAP_SERVERS.

To use a different Kafka instance for the auditv1out channel, use specific message channel configuration.

UMA Configuration

INRUPT_AUTHZ_AS_URI

The URI of the UMA Authorization Server.

The value must match:

INRUPT_JWT_AUTHORIZATION_SERVER_ISSUER configuration for the service, and
INRUPT_UMA_ISSUER configuration for UMA Service

INRUPT_JWT_AUTHORIZATION_SERVER_ISSUER

The URI of the UMA token issuer.

The value must match INRUPT_AUTHZ_AS_URI

INRUPT_JWT_AUTHORIZATION_SERVER_JWKS

The JWKS endpoint of the INRUPT_JWT_AUTHORIZATION_SERVER_ISSUER

OIDC Configuration

INRUPT_JWT_ALLOWED_SIGNATURE_ALGORITHMS

Default : ES256, RS256.

A comma-separated list that specifies the allowed encryption algorithms used to sign ID tokens.

INRUPT_JWT_ISSUER_ALLOW_LIST

A comma-separated list of trusted issuers of Solid-OIDC tokens.

If unset, the service accepts Solid-OIDC tokens from all issuers with the exception of those in the INRUPT_JWT_ISSUER_DENY_LIST.
If set, the service accepts only the Solid-OIDC tokens from the issuers in the list with the following exception:
- If an issuer is in both INRUPT_JWT_ISSUER_ALLOW_LIST and INRUPT_JWT_ISSUER_DENY_LIST , the INRUPT_JWT_ISSUER_DENY_LIST supersedes the INRUPT_JWT_ISSUER_ALLOW_LIST and the issuer is not accepted by ESS.

Tip Ensure that ESS UMA service’ INRUPT_JWT_ISSUER_ALLOW_LIST is consistent with the INRUPT_JWT_ISSUER_ALLOW_LIST value set for this service.

INRUPT_JWT_ISSUER_DENY_LIST

A comma-separated list of disallowed issuers of Solid-OIDC tokens.

If unset, the service accepts Solid-OIDC tokens from all issuers unless INRUPT_JWT_ISSUER_ALLOW_LIST is set, in which case, the service only accepts tokens from those in the INRUPT_JWT_ISSUER_ALLOW_LIST .
If set, the service disallows the Solid-OIDC tokens from the issuers in the list. If INRUPT_JWT_ISSUER_ALLOW_LIST is also set, issuers not in the INRUPT_JWT_ISSUER_ALLOW_LIST are also disallowed.

Tip Ensure that ESS UMA service’ INRUPT_JWT_ISSUER_ALLOW_LIST is consistent with the INRUPT_JWT_ISSUER_ALLOW_LIST value set for this service.

Allow List Configuration

INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSGRANT

Determines which applications can access the /issue Endpoint and the /status Endpoint for Access Grants; i.e., can be used to issue and revoke Access Requests.

The value can be either:

A comma-delimited list of the applications (specifically, their Client IDs) that are allowed access.
One of the following reserved keywords (case-insensitive):
- Any to allow all applications.
- None to disallow all applications.

See Client Allow Lists

INRUPT_VC_CLIENT_ID_ALLOW_LIST_SOLIDACCESSREQUEST

Default : Any

Determines which applications can access the /issue Endpoint and the /status Endpoint for Access Grants; i.e., can be used to issue and revoke Access Requests.

The value can be either:

A comma-delimited list of the applications (specifically, their Client IDs ) that are allowed access.
One of the following reserved keywords (case-insensitive):
- Any to allow all applications.
- None to disallow all applications.

See Client Allow Lists

Optional Configuration

INRUPT_JSONLD_CACHE_HOURS

Default : 6.

The number of hours to cache remote JSON-LD context documents.

See also:

INRUPT_JSONLD_CACHE_SIZE

Default : 100.

The maximum number of entries in the internal cache of remote JSON-LD context documents.

See also:

INRUPT_JSONLD_CONTEXT_ALLOW_LIST

Default : https://vc.{ESS DOMAIN}/credentials/v1.

A comma-delimited list of trusted JSON-LD context URIs allowed to be dereferenced. The list is in addition to the following contexts (i.e., you do not need to include the following contexts):

https://www.w3.org/2018/credentials/v1.
https://schema.inrupt.com/credentials/v2.jsonld.
https://schema.inrupt.com/credentials/v2.jsonld.
https://w3id.org/security/data-integrity/v1.
https://w3id.org/vc-revocation-list-2020/v1.
https://w3id.org/vc/status-list/2021/v1.
https://w3id.org/security/suites/ed25519-2020/v1.
http://www.w3.org/ns/odrl.jsonld.

Recommended If possible, set this configuration value to that of the UMA Service . Mismatched values may result in the failure to parse access request/grant VCs.

Warning Do not set to an empty list (i.e., do not unset this configuration). If empty, any context URI (with the exception of those URIs in INRUPT_JSONLD_CONTEXT_DENY_LIST ) is allowed, including untrusted and malicious contexts.

See also:

INRUPT_JSONLD_CONTEXT_DENY_LIST

A deny-list of JSON-LD context URIs. URIs listed in this configuration are prevented from being dereferenced.

See also:

INRUPT_JSONLD_HTTP_MAX_REDIRECTS

Default : 10.

The maximum number of redirects allowed when fetching JSON-LD context documents.

See also:

INRUPT_JSONLD_HTTP_TIMEOUT

Default_ : 10.

The timeout in seconds for fetching a remote JSON-LD context document.

See also:

INRUPT_VC_ISSUER_DESCRIPTION

A description of the access request/grant issuer.

INRUPT_VC_ISSUER_NAME

A display name for the access request/grant issuer.

INRUPT_VC_ISSUER_TOS

A URL for a Terms of Service (TOS) document.

INRUPT_VC_MONGODB_DATABASE

Default : vc

The name of the MongoDB database.

QUARKUS_LOG_LEVEL

Default : INFO.

Logging level.

INRUPT_VC_MAX_DURATION

Default : P365D

A maximum duration (i.e., expiration time) for the issued Access Requests/Grants. Specify the value in a format supported by Java Duration.parse() method, such as PT2H (2 hours) or P180D (180 days).

If the value is set, the Access Grant Service calculates an expiration date using this value. Then,

If the credential payload sent to the /issue endpoint also specifies an expiration date, the issuer uses the earlier of the two dates.
If the credential payload sent to the /issue endpoint does not specify an expiration date, the Access Grant Service uses the calculated date as the expiration date.

If the value is unset, the Access Grant Service uses P365D (365 days) to calculate the expiration date.

If the credential payload sent to the /issue endpoint specifies an expiration date, the Access Grant Service uses the earlier of the two dates.
If the credential payload sent to the issuer endpoint does not specify an expiration date, the Access Grant Service uses the calculated date as the expiration date.

Tip

This value should be set in accordance with your specific business, industry, or regulatory policies that govern data access durations. For example, the default value of P365D is typical of a business process that requires data access to be revalidated on an annual basis.

/status Endpoint Configuration

INRUPT_VC_STATUS_LIST_ID_LENGTH

Default : 4.

This sets the size of the status list identifiers. A higher value adds a greater level of entropy to the status list allocations. For example, a value of 4 supports about 1.7 trillion entries.

This value can be changed at any time without adverse effects.

/query Endpoint Configuration

INRUPT_VC_QUERY_AGENT_PATHS

Default : /credentialSubject/providedConsent/isProvidedTo,/credentialSubject/providedConsent/isProvidedToPerson,/credentialSubject/providedConsent/isProvidedToController

A comma-separated list of paths that can be considered during query execution. The query runs against access requests and grants that have the agent’s WebID in any of the listed paths.

Available paths are:

/credentialSubject/providedConsent/isProvidedTo
/credentialSubject/providedConsent/isProvidedToPerson
/credentialSubject/providedConsent/isProvidedToController

INRUPT_VC_QUERY_PROPERTY_LIMIT

Default : 16.

The maximum number of properties in a /derive query.

/derive Endpoint Configuration

INRUPT_VC_QUERY_AGENT_PATHS

Default : /credentialSubject/providedConsent/isProvidedTo,/credentialSubject/providedConsent/isProvidedToPerson,/credentialSubject/providedConsent/isProvidedToController

A comma-separated list of paths that can be considered during query execution. The query runs against access requests and grants that have the agent’s WebID in any of the listed paths.

Available paths are:

/credentialSubject/providedConsent/isProvidedTo
/credentialSubject/providedConsent/isProvidedToPerson
/credentialSubject/providedConsent/isProvidedToController

INRUPT_VC_QUERY_PROPERTY_LIMIT

Default : 16.

The maximum number of properties in a /derive query.

Service Configuration Logging

ESS services log their startup configuration.

INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW

Default : inrupt,smallrye.jwt.encrypt.key.id,smallrye.jwt.encrypt.key.location

A comma-separated list of configuration property prefixes ( case-sensitive ) that determine which configurations are logged:

If the list is empty, NO configuration property is logged.
If a configuration property starts with a listed prefix ( case-sensitive ), the configuration property and its value are logged unless the configuration also matches a prefix in INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY (which acts as a filter on INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW list). As such, if the configuration matches prefix in both INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW and INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY , the INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY takes precedence and the configuration is not logged. For example, if inrupt. is an allow prefix, but inrupt.kafka. is a deny prefix, all configurations that start with inrupt.kafka. are excluded from the logs.

When specifying the prefixes, you can specify the prefixes using one of two formats:

using dot notation (e.g., inrupt.foobar. ), or
using the MicroProfile Config environmental variables conversion value (e.g., INRUPT_FOOBAR_ ).

Warning Use the same format for both INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW and INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY.

For example, if you change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW , change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY as well.

Tip

To avoid allowing more than desired configurations, specify as much of the prefix as possible. If the prefix specifies the complete prefix term, include the term delineator. For example:

If using dot-notation, if you want to match configuration properties of the form foobar.<xxxx>... , specify foobar. (including the dot . ) instead of, for example, foo or foobar .
If using converted form, if you want to match configuration properties of the form FOOBAR_<XXXX>... , specify FOOBAR_ (including the underscore _ ) instead of, for example, FOO or FOOBAR .

INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY

Default : inrupt.vc.sign.key-seed,inrupt.kafka

A comma-separated list of configuration name prefixes ( case-sensitive ) that determines which configurations (that would otherwise match the INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW ) are not logged. That is, INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY acts as a filter on INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW . For example:

If foobar. is an allowed prefix, to suppress foobar.private.<anything> , you can specify foobar.private. to the deny list.
If foobar. is not an allowed prefix, no property starting with foobar. is logged. As such, you do not need to specify foobar.private to the deny list.

When specifying the prefixes, you can specify the prefixes using one of two formats:

using dot notation (e.g., inrupt.foobar. ), or
using the MicroProfile Config environmental variables conversion value (e.g., INRUPT_FOOBAR_ ).

Warning Use the same format for both INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW and INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY.

For example, if you change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_ALLOW , change the format of INRUPT_LOGGING_CONFIGURATION_PREFIX_DENY as well.

Log Redaction

INRUPT_LOGGING_REDACTION_NAME_ACTION

Default : REPLACE

Type of the redaction to perform. Supported values are:

Action

Description

REPLACE

Default. Replaces the matching text with a specified replacement.

PLAIN

Leaves the matching field unprocessed. Only available if the redaction target is a field (i.e.,INRUPT_LOGGING_REDACTION_{NAME}_FIELD).

DROP

Suppresses the matching field. Only available if the redaction target is a field (i.e.,INRUPT_LOGGING_REDACTION_{NAME}_FIELD).

PRIORITIZE

Changes the log level of the matching message.

SHA256

Replaces the matching text with its hash.

If the action is REPLACE ( default ), see also INRUPT_LOGGING_REDACTION_{NAME}_REPLACEMENT .
If the action is to PRIORITIZE , see also INRUPT_LOGGING_REDACTION_{NAME}_LEVEL .