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.
If INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST is not
set or empty (when creating the policy):
- Policy 1 for the Pod Root:
If the agent matches the Pod owner’s WebID, allow Read and Write access.
- Policy 2 for the Pod Root’s Default Member Policies:
If the agent matches the Pod owner’s WebID, 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: |
|
|---|---|
Endpoint: |
|
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}/"
}
|
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"
}
}
|
|
The WebID of the authenticated user for whom the Pod has been created. |
|
The URL of an extended profile resource stored on the Pod. The URL has the form
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. |
|
The URL root of the newly created Pod. The URL has the form
|
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:
List of application(s) that can perform read and write operations the Access Control Resources with the following caveat:
The list displays the value of
INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LISTconfigured on the Pod Storage Service. However, the actual configuration that determines the trusted applications is Authorization Service‘sINRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST.As such, if the two lists are not in sync, the displayed list may not accurately reflect the trusted apps.
Maximum number of Pods allowed per Agent.
Notification Gateway endpoint.
Provision service endpoint.
@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
] .
Access#
For access to the Pod resources, ESS’ Pod Storage service supports the use of the following tokens:
UMA Tokens#
To use UMA tokens:
Set the appropriate UMA Configuration.
Solid-OIDC Access Tokens#
To use Solid-OIDC tokens:
Set the appropriate Solid-OIDC Issuer Configuration Options.
Set the Pod Storage Service’s configuration
INRUPT_AUTHZ_UMA_OIDC_ENABLEDtotrue.
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:
10For Pod Provision Service Only
The maximum number of Pods owned by a specific WebID.
Important
The
INRUPT_STORAGE_MAX_PODS_PER_OWNERvalue must equal value must equal Authorization Service’sINRUPT_AUTHORIZATION_MAX_POD_COUNTvalue. When changing theINRUPT_STORAGE_MAX_PODS_PER_OWNERvalue, ensure you also updateINRUPT_AUTHORIZATION_MAX_POD_COUNTto the same value.
Additional Information#
See also https://quarkus.io/guides/all-config.