Backlinks
Agents, groups, and authorizations
LinkedDataHub access control is based on the W3C ACL ontology.
Access modes¶
There are three access modes (classes of operation) that map to HTTP methods:
| Mode | Permits | HTTP method |
|---|---|---|
| Read | Read the contents, including querying them. | GET |
| Write | Overwrite the contents, including deleting or modifying them. | PUT, PATCH, DELETE |
| Append | Add information without removing or replacing any. | POST |
acl:Control grants nothing: authorizations are documents in the administration dataspace,
so changing them takes acl:Write there.
Agents¶
An agent is a person or a piece of software, identified by a WebID, that can be authorized to have certain modes of access to certain dataspaces.
Groups¶
A group is a named group of agents to which an authorization can
be given. It is a subclass of the foaf:Group
class.
There are several default groups:
- Owners
- Writers
- Readers
By default, only members of the owners group have access to the administration dataspace: its built-in Full control authorization grants them read, append and write access to the administration root and everything below it. See Authorizations.
Note that an agent being a member of one of the above groups does not automatically provide it with an authorization. A valid authorization for the whole group has to be present.
Authorizations¶
An authorization explicitly grants access for an agent or a group
of agents to a specific document (acl:accessTo), to every document below a container (acl:default),
or to the resources of a class (acl:accessToClass). Grants only add access:
no authorization overrides another.
An authorization counts only in its own document, the one whose foaf:primaryTopic it is, and a group's members count
only in the group's own document.
To use the administration dataspace, an agent needs access to its documents like to any others. By default the owners group has it.
The default authorizations for groups and their respective access modes:
| Group | Read access | Write/append access | Administration dataspace |
|---|---|---|---|
| Owners | Read | Write | Read, Append, Write |
| Append | |||
| Writers | Read | Write | — |
| Append | |||
| Readers | Read | — | — |
An authorization is a plain RDF resource. Granting the writers group full access to the Northwind orders container:
@prefix acl: <http://www.w3.org/ns/auth/acl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
<#this> a acl:Authorization ;
rdfs:label "Order management" ;
acl:agentGroup <https://admin.localhost:4443/acl/groups/writers/#this> ;
acl:mode acl:Read, acl:Append, acl:Write ;
acl:accessTo <https://localhost:4443/orders/> .ldh admin create authorization \ --label "Order management" \ --agent-group "https://admin.localhost:4443/acl/groups/writers/#this" \ --to "https://localhost:4443/orders/" \ --read --append --write
An authorization can also reach every document below a container with acl:default. Granting the readers group read access to
the orders container and every order in it:
@prefix acl: <http://www.w3.org/ns/auth/acl#> .
@prefix rdfs: <http://www.w3.org/2000/01/rdf-schema#> .
<#this> a acl:Authorization ;
rdfs:label "Order read access" ;
acl:agentGroup <https://admin.localhost:4443/acl/groups/readers/#this> ;
acl:mode acl:Read ;
acl:accessTo <https://localhost:4443/orders/> ;
acl:default <https://localhost:4443/orders/> .ldh admin create authorization \ --label "Order read access" \ --agent-group "https://admin.localhost:4443/acl/groups/readers/#this" \ --to "https://localhost:4443/orders/" \ --default "https://localhost:4443/orders/" \ --read
A document is below a container when its own sioc:has_parent or sioc:has_container leads there. acl:default does
not cover the container itself, hence the acl:accessTo alongside it.
acl:accessToClass grants access to the resources of a class, such as nfo:FileDataObject for file uploads. It refuses the
document classes (def:Root, dh:Container, dh:Item) and the classes above them: documents are granted through the
hierarchy.
A public-access authorization allows access for non-authenticated agents — the Publish stage of the
tutorial shows the one ldh admin make-public creates, granting acl:Read to the foaf:Agent class
on the root and every document below it.
Document owners¶
The agent that creates a document is its owner (acl:owner), and stays so for the life of the document. The built-in
Owner access authorization grants read, append and write access to the lacl:OwnerAgent class, which matches
the owners of the requested document, on the end-user root and every document below
it.
The owner's and secretary's authorizations are stored under stable URIs (acl/authorizations/owner-webid/ and acl/authorizations/secretary-webid/), so reloading the admin dataset does not create duplicates.
Access requests¶
If access is denied due to missing authorization, the agent can ask for it by issuing a request to the dataspace's owners. The request indicates the request URI and access mode in question. The owners can then accept the request by creating an authorization with the provided information (possibly extending the requested access to a group of agents or a class of resources), or simply ignore it.
A request is data too — asking for write access to a Northwind order:
@prefix lacl: <https://w3id.org/atomgraph/linkeddatahub/admin/acl#> .
@prefix acl: <http://www.w3.org/ns/auth/acl#> .
<#this> a lacl:AuthorizationRequest ;
lacl:requestAgent <https://localhost:4443/agents/jane/#this> ;
lacl:requestMode acl:Write ;
lacl:requestAccessTo <https://localhost:4443/orders/10248/> .Management¶
| Action | CLI command |
|---|---|
| Create group | ldh admin create group |
| Create authorization | ldh admin create authorization |
| Add agent to group | ldh admin add agent |
| Make a document public | ldh admin make-public |
To request access to someone else's dataspace, see the Request access guide. To open your data to the public, follow the Publish stage of the tutorial.