WebID Document Best Practices
This guide provides advice and best practices for creating and maintaining WebID Documents.
It will cover the following:
Basic makeup of a WebID Document for use in a managed ecosystem
How it is used in Solid Identity
Considerations for architects on protecting WebID Documents on behalf of users in managed ecosystems.
What is a WebID?
A WebID is a URI that uniquely identifies an entity in a Solid ecosystem.
A WebID Document is an RDF document dereferenced from the WebID URI. This WebID Document allows Solid applications and services to discover services used or trusted by the entity that controls the WebId, such as their trusted Identity Providers, Solid Pods, and potentially some public personal information.
The WebID Document is an RDF public document and should be expressed in Turtle format, although other formats may be available.
WebID Document Content
The authority governing the Solid ecosystem should have control over and define the content of the WebID Document.
A WebID Document will likely contain three pieces of information:
A list of trusted OIDC issuers used to assert their identity for access to Solid servers and apps.
Any Solid Pods associated with that particular WebID.
Optionally, the profile could include a list of extended WebID Documents. These extended profiles are stored in Pods and could be publicly accessible or protected by access control.
Example of the minimum requirement for a WebID Document
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix schema: <http://schema.org/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix person: <http://localhost:8080/data/person/> .
<https://id.inrupt.com/dave> a foaf:Agent ;
<http://www.w3.org/ns/pim/space#storage> <https://storage.inrupt.com/bb79f34c-3e25-4b9d-9b68-0193e5491111/> ;
<http://www.w3.org/ns/solid/terms#oidcIssuer> <https://login.inrupt.com> ;
foaf:isPrimaryTopicOf <https://storage.inrupt.com/bb79f34c-3e25-4b9d-9b68-0193e5491111/profile> .
OIDC Issuer
<http://www.w3.org/ns/solid/terms#oidcIssuer> <https://login.inrupt.com> ;
The WebID Document must contain at least one Solid OIDC identity provider. Without this, the entity cannot use any Solid services that require authentication.
As part of the authentication flow, Solid Applications and Solid Servers will ensure the issuer providing the identity token is present in the WebID Document. If it is not present, the session will terminate. Only trusted IDPs must be added to the WebID Document.
The WebID Document can list multiple Identity Providers, which means more than one Solid OIDC provider can assert the same identity for a given entity or user. Assuming that all Identity Providers are onboarded, trusted, and are known providers of the WebID service, the user or application can choose which IDP to use.
Solid Pod Storage
The WebID Document is the primary mechanism to discover Solid Pods so that applications and services can write or fetch data. In most deployments, the user will have one Pod but also may have many. If multiple Pods are present, the WebID Document must contain some metadata to aid in selecting a Pod. A common way to achieve this is by using rdfs:label as a description property to provide human-readable labels written by the operator. For instance, if users utilize a health app, they could choose the "Health Wallet" rather than a "Finance Wallet."
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .
@prefix schema: <http://schema.org/> .
@prefix foaf: <http://xmlns.com/foaf/0.1/> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
@prefix person: <http://localhost:8080/data/person/> .
<https://id.inrupt.com/LindaSmith> a foaf:Person ;
<http://www.w3.org/ns/pim/space#storage> <https://storage.inrupt.com/bb79f34c-3e25-4b9d-9b68-0193e5491111/>, <https://storage.inrupt.com/bb79f34c-3e25-4b9d-9b68-0193e5491112/> ;
<http://www.w3.org/ns/solid/terms#oidcIssuer> <https://login.inrupt.com> ;
foaf:isPrimaryTopicOf <https://storage.inrupt.com/bb79f34c-3e25-4b9d-9b68-0193e5491111/profile> .
<https://storage.inrupt.com/bb79f34c-3e25-4b9d-9b68-0193e5491111/> a <http://www.w3.org/ns/pim/space#ControlledStorage> ;
rdfs:label "National Health Service Solid Wallet Storage"@en .
<https://storage.inrupt.com/bb79f34c-3e25-4b9d-9b68-0193e5493912/> a <http://www.w3.org/ns/pim/space#ControlledStorage> ;
rdfs:label "Ward Bank Solid Wallet Storage"@en .
Personal Information
The WebID Document associated with a WebID may contain personal details about the user identified by the WebID. Users have the option to share their personal information in the WebID Document. For personal information that is better kept private (such as phone number or private address), ESS can create a Extended-Profile-Document in the user's Wallet which can be placed under access control.
Vocabulary
To promote application interoperability, we recommend a set of vocabularies to use in the WebID Document. As mentioned above, three main concepts are referenced in a WebID Document:
The type of entity
The identity providers for the users to authenticate
The list of Solid Pods that belong to that particular WebID.
The entities that hold WebID Documents can be classified as an agent, a person, or an organization using the FOAF vocabulary.
To describe the different Identity Providers, we use the Solid term vocabulary and specifically utilize the property oidcIssuer. The Workspace Ontology is the recommended vocabulary for expressing Solid Wallet Storage, with pim:storage being the associated property. Finally, the WebID Service administrator can decide the term for a specific property (predicate) for a possible extended profile(s).
WebID Document Edits
Adding untrusted OIDC Issuers or unauthorized non-user-controlled Wallet Storage to the WebID Document could constitute a security threat.
As it is unlikely that regular users will understand this significance, the governing body overseeing the managed Solid ecosystem must enforce strict controls over how modifications are made to the WebID Document. Secure tooling or applications must be created to wrap up the WebID service.
Considering the severe risks involved, regular users must be only granted permission to edit their WebID Document under extremely controlled circumstances. A WebID editor application built by the governing body should be responsible for validating and approving any potential changes. The validation process should ensure that the agent making the changes is allowed to do so and that the changes themselves are in line with the ecosystem’s security policies.
As mentioned in the document, multiple OIDC issuers can be listed in a single WebID Document.
Whilst ESS has additional guards to ensure untrusted Issuers cannot be used to authenticate users in the form of service allow lists, this should not be used as the only line of defense. Allow lists can become large and cumbersome in complex deployments.
If the Issuer Allow List grows significantly, one potential solution could be OIDC Federation, which would allow multiple federations and various Identity Providers. This specification is still in its early stages, but it would instruct establishing trust among a group of IdPs.
Last updated