Pod Services#

Changed in version 2.0.

Starting in ESS 2.0, Pod provisioning and storage is handled by a separate Pod Provisioning Service and Pod Storage Service.

Pod Provisioning Service#

ESS’ Pod provisioning service manages the creation of Pods, using the following URL format:

https://storage.{ESS Domain}/{Unique Pod Identifier}/

Prior to version 2.0, ESS Pods used URLs of the form https://{ESS Domain}/{username}/.

Default Resource (Extended Profile)#

When creating a Pod, ESS creates an extended profile resource. The extended profile resource is separate from the public WebID profile. The extended profile resource, unlike the public WebID profile, is hosted in the user’s Pod, and by default, is private. Users can grant or deny access to their extended profile like any other resource in their Pod.

Initial ACP Policies#

When a Pod is created, like any other Pod resource, an Access Control Resource is also created for the Pod Root. The ACR is initialized with default ACP policies; the default policies depend on whether INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST is set or unset:

If INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST is set (when creating the policy),

Policy 1 for the Pod Root:

If the agent matches the Pod owner’s WebID, and the client application matches a Solid-OIDC Client ID listed (when creating the policy) in INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST , allow Read and Write.

Policy 2 for the Pod Root’s Default Member Policies:

If the agent matches the Pod owner’s WebID and the client application matches a Solid-OIDC Client ID listed (when creating the policy) in INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST, allow Read and Write access.

For more information on default member policies, see Default Member Policies.

Note

INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST only affects new ACRs. As such, any change to the list after the ACR has been initialized has no effect on existing policies.

Provisioning Endpoint#

The ESS Pod provisioning service provides an endpoint that client applications can use to create new Pods.

Important

Access to this endpoint requires users to be authenticated.

The following configurations, if set, may affect the behavior of this endpoint:

To create a new Pod (and the extended profile resource), a client will issue an authenticated POST request to the endpoint.

Method:

POST

Endpoint:

https://provision.{ESS domain}/

Body:

N/A

Content-Type:

N/A

Upon successful creation (status 201), the endpoint returns a Location header with the location of the new Pod. In addition, the response contains a JSON payload with information about the newly created Pod:

{
   "@context":{
      "id":"@id",
      "storage":{
         "@type":"@id",
         "@id":"http://www.w3.org/ns/pim/space#storage"
      },
      "profile":{
         "@type":"@id",
         "@id":"http://xmlns.com/foaf/0.1/isPrimaryTopicOf"
      }
   },
   "id":"{WebID}",
   "profile":"https://storage.{ESS Domain}/{Pod Identifier}/profile",
   "storage":"https://storage.{ESS Domain}/{Pod Identifier}/"
}

@context

Contains the following context for Pod information fields:

{
   "id":"@id",
   "storage":{
      "@type":"@id",
      "@id":"http://www.w3.org/ns/pim/space#storage"
   },
   "profile":{
      "@type":"@id",
      "@id":"http://xmlns.com/foaf/0.1/isPrimaryTopicOf"
   }
}

id

The WebID of the authenticated user for whom the Pod has been created.

profile

The URL of an extended profile resource stored on the Pod. The URL has the form https://storage.{ESS Domain}/{Pod Identifier}/profile.

Note

The extended profile resource is separate from the public WebID Profile Document. As with any resource in a user’s Pod, the extended profile resource is private by default.

storage

The URL root of the newly created Pod. The URL has the form https://storage.{ESS Domain}/{Pod Identifier}.

This payload can be used to update the WebID Profile with the Pod information.

Pod Storage Service#

ESS’ Pod storage service hosts the Pods created by the Pod provisioning service and is responsible for reading and writing the resources stored in the Pod.

The Pod URL has the following pattern:

https://storage.{ESS Domain}/{Unique Pod Identifier}/

Prior to version 2.0, ESS Pods had the URL of the form https://{ESS Domain}/{username}/

Pod Resources#

ESS Pods supports storing different types of Solid Resources, including:

  • a Container

    Analogous to folders in a file system. A Container can contain other Containers as well as RDF and non-RDF resources. Container URLs always end with a slash /.

  • a Resource Description Framework (RDF) resource.

    A file whose contents consists of statements (also known as triples) that describe some “subject” by its relationships:

    <subject> <predicate> <object>
    

    The predicate describes the relationship between the subject and the object.

    For more information, see RDF Data Model.

  • a non-RDF Resource

    Any non-RDF binary or text file, such as .pdf , .jpeg, etc.

ESS supports the Solid Protocol specification. As such, navigating, creating, deleting and editing Solid Resources within a Pod is directly supported via the standard HTTP interfaces.

Discovery#

ESS provides Pod storage service (and related) metadata at the following .well-known/solid URI:

https://storage.{ESS Domain}/.well-known/solid

Its Response.body returns Resource Description Framework (RDF) statements. Depending on your configuration, the response can include information about:

@prefix solid: <http://www.w3.org/ns/solid/terms#> .

[ a                          solid:DiscoveryDocument ;
  <http://www.w3.org/ns/auth/acl#trustedApp>
          <https://podbrowser.inrupt.com/api/app> ;
  solid:maxPodsPerOwner      10 ;
  solid:notificationGateway  <https://notification.{ESS DOMAIN}.com/> ;
  solid:provision            <https://provision.{ESS DOMAIN}.com/> ;
  solid:validatesRdfSources  true
] .

Pod Services 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.

Pod Provision Options#

INRUPT_STORAGE_MAX_PODS_PER_OWNER#

Default: 10

For Pod Provision Service Only

The maximum number of Pods owned by a specific WebID.

Important

The INRUPT_STORAGE_MAX_PODS_PER_OWNER value must equal value must equal Authorization Service’s INRUPT_AUTHORIZATION_MAX_POD_COUNT value. When changing the INRUPT_STORAGE_MAX_PODS_PER_OWNER value, ensure you also update INRUPT_AUTHORIZATION_MAX_POD_COUNT to the same value.

Shared Options (Pod Provision and Pod Storage Options)#

Pod Storage Options#

INRUPT_STORAGE_HTTP_BASE_URL#

The base URL of the storage service. This is mainly for use by supporting services like Pod Provisioning service.

Important

The value requires a trailing slash /; e.g., https://storage.{ESS_DOMAIN}/.

INRUPT_STORAGE_HTTP_CACHE_CONTROL_MAX_AGE#

Default: 0

The max-age directive value on the Cache-Control header.

For more information of Cache-Control directives, see https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control.

INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST#

Default: https://permissions.{ESS_DOMAIN}/app/id,https://podbrowser.inrupt.com/api/app

Comma-delimited list of applications that are displayed in /.well-known/solid as trusted applications. Trusted applications can perform read and write operations on the Access Control Resources. To specify applications, use their Solid-OIDC Client IDs.

The list should reflect the values set in the Authorization Service‘s INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST since the authorization server’s configuration actually determines what clients are the trusted applications. That is, the Pod service’s configuration is for display/discoverability purposes only.

Solid-OIDC Issuer Configuration Options#

INRUPT_JWT_ISSUER_ALLOW_LIST#

A comma-separated list of trusted Solid-OIDC issuers (i.e., identity providers).

See also INRUPT_JWT_ISSUER_DENY_LIST.

INRUPT_JWT_ISSUER_DENY_LIST#

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

INRUPT_JWT_ALLOWED_SIGNATURE_ALGORITHMS#

Default: ES256, RS256

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

UMA Configuration#

INRUPT_AUTHZ_AS_URI#

The URI of the UMA Authorization Server.

INRUPT_AUTHZ_UMA_ANONYMOUS_ENABLED#

Default: false

A boolean flag that determines whether to support anonymous (i.e., unauthenticated) access to resources that have been granted public access.

INRUPT_AUTHZ_UMA_OIDC_ENABLED#

Default: false

A boolean flag that determines whether the Pod server supports OIDC access tokens. When set to false, clients will need access tokens from the associated UMA server.

SMALLRYE_JWT_ENCRYPT_KEY_LOCATION#

The location of the JWK key used to encrypt the ticket for the UMA Service. This should be configured to the SMALLRYE_JWT_SIGN_KEY_LOCATION on the UMA Service.

SMALLRYE_JWT_ENCRYPT_KEY_ID#

The key id of the JWK key used to encrypt the ticket for the UMA Authorization Server. Required if using UMA.

Logging Configuration#

QUARKUS_LOG_LEVEL#

Default: INFO

Logging level.

Kafka Configuration#

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 Pod management services use the solidresource and auditv1out message channels.

Note

Inrupt-provided overlays default to using KAFKA_BOOTSTRAP_SERVERS.

To use a different Kafka instance for the solidresource and auditv1out channels, use MP_MESSAGING_OUTGOING_SOLIDRESOURCE_BOOTSTRAP_SERVERS and MP_MESSAGING_OUTGOING_AUDITV1OUT_BOOTSTRAP_SERVERS instead.

See also ESS’ Kafka Configuration.

MP_MESSAGING_OUTGOING_SOLIDRESOURCE_BOOTSTRAP_SERVERS#

Default: localhost:9092

Comma-delimited list of Kafka broker servers used for the outgoing resource notification messages.

These messages are sent over the solidresource message channel.

Note

To configure ESS to use the same Kafka instances for all its Kafka message channels, use KAFKA_BOOTSTRAP_SERVERS option instead. Inrupt-provided overlays default to using KAFKA_BOOTSTRAP_SERVERS.

MP_MESSAGING_OUTGOING_SOLIDRESOURCE_VALUE_SERIALIZER#

Default: org.apache.kafka.common.serialization.StringSerializer

The serializer used for the notification messages the service sends to Kafka.

Supported values are:

  • org.apache.kafka.common.serialization.StringSerializer

    When set to this value, notification messages sent to Kafka are unencrypted.

    Services that consume these messages (e.g., WebSocket Notification Service) will need to set their MP_MESSAGING_INCOMING_SOLIDRESOURCE_VALUE_DESERIALIZER to the corresponding deserializer value org.apache.kafka.common.serialization.StringDeserializer.

  • com.inrupt.components.kafka.encryption.EncryptMessageSerializer

    When set to this value, notification messages sent to Kafka are encrypted. Services that consume these encrypted messages (e.g., WebSocket Notification Service) will need to set their MP_MESSAGING_INCOMING_SOLIDRESOURCE_VALUE_DESERIALIZER configuration to the corresponding deserializer value com.inrupt.components.kafka.encryption.DecryptMessageDeserializer.

INRUPT_KAFKA_SOLIDRESOURCE_CIPHER_PASSWORD#

The symmetric key to use when encrypting messages (see MP_MESSAGING_OUTGOING_SOLIDRESOURCE_VALUE_SERIALIZER).

MP_MESSAGING_OUTGOING_AUDITV1OUT_BOOTSTRAP_SERVERS#

Default: localhost:9092

Comma-delimited list of Kafka broker servers used for the outgoing audit v1 messages.

These messages are sent over the auditv1out message channel.

Note

To configure ESS to use the same Kafka instances for all its Kafka message channels, use KAFKA_BOOTSTRAP_SERVERS option instead. Inrupt-provided overlays default to using KAFKA_BOOTSTRAP_SERVERS.

INRUPT_KAFKA_AUDITV1EVENTSENCRYPTED_CIPHER_PASSWORD#

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

AWS Options#

INRUPT_STORAGE_S3_BUCKET_NAME#

Default: inrupt.ess.storage

The name of the S3 bucket used for storage.

QUARKUS_S3_ENDPOINT_OVERRIDE#

Override S3 endpoint URL.

QUARKUS_S3_AWS_REGION#

An Amazon Web Services region that hosts the S3 Bucket.

QUARKUS_S3_AWS_CREDENTIALS_STATIC_PROVIDER_ACCESS_KEY_ID#

AWS Access key id.

QUARKUS_S3_AWS_CREDENTIALS_STATIC_PROVIDER_SECRET_ACCESS_KEY#

AWS Secret access key.

OpenTelemetry Options#

QUARKUS_OPENTELEMETRY_TRACER_EXPORTER_OTLP_ENABLED#

Default: false

The OpenTelemetry exporter can be enabled or disabled with this configuration.

QUARKUS_OPENTELEMETRY_TRACER_EXPORTER_OTLP_ENDPOINT#

The URL of the OpenTelemetry exporter.