Ctrl+K
Ctrl+K

WebID Service#

Starting in version 2.0, ESS introduces a separate service to host and manage WebIDs and the corresponding Profile Documents.

WebID and Profile Document#

According to the WebID draft specification, a WebID is a URL that identifies an agent.

Starting in version 2.0,

  • ESS’ WebID service creates WebIDs of the form:

    https://id.{ESS DOMAIN}/{username}

  • The WebID profile document is no longer hosted in the user’s Pod. [1]

Prior to version 2.0, ESS issued WebIDs of the form https://{ESS Domain}/{username}/profile/card#me, which were hosted in the user’s Pod.

WebID Profile Document#

The WebID URL dereferences to the agent’s WebID profile, where the profile is a document that describes the agent.

The ESS WebID service ensures that the WebID Profile document is a valid RDF document. An RDF document is a document whose contents consists of statements that have the following form (also known as a triple):

<subject> <predicate> <object> .

The WebID profile document is a publicly accessible document. [1]

WebID Profile Document Constraints#

ESS enforces the following constraints on the RDF data model in the WebID Profile:

  • The document must contain the following solid:oidcIssuer triple :

    <WebID URL> solid:oidcIssuer <defaultIssuer URL> .

    where

    • <WebID URL> is the agent’s WebID

    • <defaultIssuer URL> is the configured INRUPT_WEBID_ISSUER value.

  • For all solid:oidcIssuer triples,

    • The subject must be the agent’s WebID URL.

    • The object must be a valid HTTP(S) URL.

  • If an rdf:type triple is present in the WebID Profile Document, its value must be one of:

    • foaf:Agent

    • foaf:Group

    • foaf:Person

    • foaf:Organization

    where foaf: is the namespace prefix for http://xmlns.com/foaf/0.1/.

    For example,

    <WebID URL> a foaf:Agent.

  • For any foaf:isPrimaryTopicOf triples, the object must be an HTTP(S) URL.

  • For any pim:storage triples, the object must be an HTTP(S) URL.

ESS allows any other RDF triples, without constraints, in the WebID profile.

WebID Profile Document Endpoints#

The WebID service provides various endpoints for managing (get, create, replace, add storage info, delete) the WebID profile document.

Authentication and Authorization Requirements#

The operations to create and modify the WebID profile (create, replace, update with storage info, delete) have authentication and authorization requirements:

  • Agents must be authenticated.

  • The agent’s ID token must be issued by an approved issuer. See INRUPT_JWT_ISSUER_ALLOW_LIST for details.

  • Agents can only use approved applications to create and modify their WebID profile. See INRUPT_WEBID_ALLOWED_CLIENT_IDS for details.

  • Agents can only create and modify their own WebID. Specifically, the WebID service checks that the webid claim in the agent’s ID token matches the specified https://id.{ESS DOMAIN}/{username} endpoint.

Fetch a Profile Document#

A client can retrieve the profile associated with a WebID by issuing a GET request to the WebID:

Method:

GET

Endpoint:

https://id.{ESS DOMAIN}/{username}

Accept:

text/turtle

Body:

N/A

Content-Type:

N/A

Tip

Per the WebID draft specification, an HTTP request on the WebID can return a redirect status (303) along with the profile document URL in the Location header.

As such, a client may need to handle the HTTP redirection according to its needs (e.g., follow the redirect automatically or error).

Alternatively, if the profile document URL is the WebID with a file extension (e.g., .ttl, .jsonld), you can issue a GET request directly to the profile document URL.

Upon successful fetch, the response includes a status of 200 OK (including when the client automatically follows the redirect) and the profile document in its body.

Create a Profile Document#

Important

The operation has authentication and authorization requirements. See Authentication and Authorization Requirements.

To create a WebID profile document if one does not already exist for the WebID, issue a POST request to the WebID:

Method:

POST

Endpoint:

https://id.{ESS DOMAIN}/{username}

Body:

N/A

Content-Type:

N/A

Note

If the WebID profile document already exists, the POST request returns a 400 Bad Request error.

Upon successful creation of a WebID profile document, the response includes a status of 201 Created. The newly created WebID profile document has the following content:

@prefix foaf: <http://xmlns.com/foaf/0.1/>.
@prefix solid: <http://www.w3.org/ns/solid/terms#>.
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#>.

<https://id.{ESS DOMAIN}/{username}> a foaf:Agent;
    solid:oidcIssuer <{WEBID_ISSUER}/>.

Where the {WEBID_ISSUER} is the configured INRUPT_WEBID_ISSUER value.

Replace a Profile Document#

Important

The operation has authentication and authorization requirements. See Authentication and Authorization Requirements.

To replace an existing WebID profile document, issue a PUT request with a valid replacement profile document to the WebID:

Method:

PUT

Endpoint:

https://id.{ESS DOMAIN}/{username}

Body:

A profile document that conform to the WebID service’s constraints.

If the document does not conform to the service constraints, a 400 Bad Request error is returned.

Content-Type:

text/turtle

Upon successful update, the response includes a status of 204 No Content.

Add Pod Location to Profile Document#

Important

The operation has authentication and authorization requirements. See Authentication and Authorization Requirements.

To add a Pod Location to a WebID profile document, issue a POST request to the {WebID}/provision endpoint:

Method:

POST

Endpoint:

https://id.{ESS DOMAIN}/{username}/provision

Body:

A JSON document:

{
   "@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":"{extended Profile Resource stored on the Pod}",
   "storage":"{HTTP(S) Pod URL}"
}

See also Pod Provisioning service.

Content-Type:

application/json

Delete a Profile Document#

Important

The operation has authentication and authorization requirements. See Authentication and Authorization Requirements.

To delete a WebID profile document, issue a DELETE request to the WebID:

Method:

DELETE

Endpoint:

https://id.{ESS DOMAIN}/{username}

Body:

N/A

Content-Type:

N/A

Upon successful delete, the response includes a status of 204 No Content.

WebID 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#

These WebID service configuration options are set as part of updating the inputs for your deployment.

INRUPT_JWT_ISSUER_ALLOW_LIST#

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

Tip

Important

For the WebID service, you must set INRUPT_JWT_ISSUER_ALLOW_LIST to a non-empty list. If the list is empty, the WebID service throws an error.

The WebID service uses the INRUPT_JWT_ISSUER_ALLOW_LIST to check the issuer iss claim (from the agent’s ID token), accepting only the issuers in the list with the following exception:

All other issuers are rejected with a 401 Unauthorized error.

See also INRUPT_JWT_ISSUER_DENY_LIST.

INRUPT_PROVISION_HTTP_BASE_URL#

The base URL of the Pod Provisioning Service. This is used by the WebID Service to link to the Pod Provisioning Service.

Important

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

INRUPT_START_CLIENT_ID#

Default: https://start.{ESS_DOMAIN}/app/id

The Solid-OIDC Client ID of the start application. The default start app can handle:

  • User sign up/log in, and

  • Provisioning of the user’s WebID and Pod.

INRUPT_WEBID_ALLOWED_CLIENT_IDS#

Default: INRUPT_START_CLIENT_ID, INRUPT_WEBID_CLIENT_ID

Comma-delimited list of Solid-OIDC Client IDs. The list determines which clients are authorized to modify the WebID profile documents.

Specifically, the WebID service uses INRUPT_WEBID_ALLOWED_CLIENT_IDS to check the authorized party azp claim from the agent’s ID token.

INRUPT_WEBID_CLIENT_ID#

Default: https://id.{ESS_DOMAIN}/app/id

The URL of the WebID editor application.

INRUPT_WEBID_ISSUER#

Default: https://openid.{ESS DOMAIN}

The required issuer that must appear in the WebID profile documents. See WebID Profile Document Constraints.

Tip

Ensure this issuer is in the INRUPT_JWT_ISSUER_ALLOW_LIST.

See also INRUPT_OPENID_ISSUER.

QUARKUS_DATASOURCE_JDBC_URL#

The JDBC connection string for the persistence datasource. For example, jdbc:postgresql://HOSTNAME/DATABASE-NAME.

QUARKUS_DATASOURCE_PASSWORD#

The password for connecting to the persistence datasource.

QUARKUS_DATASOURCE_USERNAME#

The username for connecting to the persistence datasource.

Kafka Configuration#

Tip

See also ESS’ Kafka Configuration.

INRUPT_KAFKA_AUDITV1EVENTSENCRYPTED_CIPHER_PASSWORD#

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

KAFKA_BOOTSTRAP_SERVERS#

Default: localhost:9092

Comma-delimited list of Kafka broker servers for use by ESS services, iincluding 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). This 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.

See also ESS’ Kafka Configuration.

Optional#

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_DENY_LIST#

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

INRUPT_WEBID_CLIENT_CONTACTS#

A comma-delimited list of contacts (either email addresses or WebID URLs) for the client associated with the default Solid-OIDC Client ID. See INRUPT_WEBID_ALLOWED_CLIENT_IDS.

INRUPT_WEBID_CLIENT_LOGO_URI#

Default: https://{ESS DOMAIN}/logo.png

The application logo for the client associated with the default Solid-OIDC Client ID. See INRUPT_WEBID_ALLOWED_CLIENT_IDS.

INRUPT_WEBID_CLIENT_NAME#

Default: Inrupt WebID Manager

The name of the client associated with the default Solid-OIDC Client ID. See INRUPT_WEBID_ALLOWED_CLIENT_IDS.

INRUPT_WEBID_CLIENT_TOS_URI#

The URL for a terms of service document for the client associated with the default Solid-OIDC Client ID. See INRUPT_WEBID_ALLOWED_CLIENT_IDS.

QUARKUS_LOG_LEVEL#

Default: INFO

Logging level.

Additional Information#

See also https://quarkus.io/guides/all-config.

On this page