Access Control Policy (ACP)#

ESS uses Access Control Policy (ACP) to manage access to Pod resources. [1] With ACP, Pod owners can define Policies that determine access for their Pod’s resources.

Policies#

Policies determine access for Pod resources. A policy statement consists of:

Matcher statements that specify conditions that must be satisfied for the Policy to take effect.
Access mode statements that specify which access modes are allowed and/or denied to the agent(s) satisfying the Matcher statements.

If

< allOf | anyOf > (Matcher(s)) evaluates to true, AND

< allOf | anyOf | noneOf > (Matcher(s)) evaluates to true, AND

…

Then
<allow (AccessMode(s)) | deny (AccessMode(s)) | allow (AccessMode(s)) AND deny (AccessMode(s)) >

Important

The noneOf() expression excludes matches from the allOf and anyOf expressions; i.e., you can use the noneOf expression to refine the allOf and anyOf matches.

Because the noneOf() expression acts as a secondary/supplementary filter to the allOf and anyOf expressions, a policy statement with only a noneOf(<matchers>) condition cannot be satisfied.

Matcher Statements#

< allOf | anyOf > (Matcher(s)) evaluate to true, AND

< allOf | anyOf | noneOf > (Matcher(s)) evaluates to true, AND

…

Matchers#

Matchers specify the conditions under which the Access Policy applies.

ESS supports the following types of Matchers:

Agent Matchers

To match agents by specific WebID(s).

To match any authenticated agent.

To match any agent.

Client Matchers

To match by specific Client ID(s).

To match any client application.

Note

To use Client Application Matchers, the Policy must also specify an Agent Matcher.

Verifiable Credentials Matchers

To match by Verifiable Credential(s) type; e.g., match VC type http://www.w3.org/ns/solid/vc#SolidAccessGrant.

Can be used to enable the use of access grants. For details, see access grants.

`allOf`, `anyOf`, `noneOf` Operators#

A policy specifies its matchers in allOf(), anyOf(), and noneOf() operator expressions.

`allOf(<matchers>)`	Evaluates to true if all of its listed matchers evaluate to true.
`anyOf(<matchers>)`	Evaluates to true if any of its listed matchers evaluate to true.
`noneOf(<matchers>)`	Evaluates to true if none of its listed matchers evaluate to true.

Important

The noneOf() expression excludes matches from the allOf and anyOf expressions; i.e., you can use the noneOf expression to refine the allOf and anyOf matches.

Because the noneOf() expression acts as a secondary/supplementary filter to the allOf and anyOf expressions, a policy statement with only a noneOf(<matchers>) condition cannot be satisfied.

Access Mode Statements#

<allow (AccessMode(s)) | deny (AccessMode(s)) | allow (AccessMode(s)) AND deny (AccessMode(s)) >

Access Modes#

Access Modes describe the permissions that can be granted or denied. The available modes are:

Access Mode	Description
`Read`	Permission to view/retrieve a resource. See also CRUD Operations and Access Modes.
`Write`	Permission to create a resource, update the content of a resource, and delete a resource: Tip To create a resource, you must have Write access on both the resource and the resource’s container. To delete a resource, you must have Write access on both the resource and the resource’s container. See also CRUD Operations and Access Modes.
`Append`	Permission to add content to a resource: If a resource is a container (analogous to a folder in a file system), the `Append` permission on the resource allows agents to add new resources (container, RDF resource, non-RDF resource) to the container. If a resource is an RDF resource, the `Append` permission on a resource allow agents to add statements to the resource. See also CRUD Operations and Access Modes.

Access Mode

Description

Read

Permission to view/retrieve a resource.

Write

Permission to create a resource, update the content of a resource, and delete a resource:

Tip

To create a resource, you must have Write access on both the resource and the resource’s container.
To delete a resource, you must have Write access on both the resource and the resource’s container.

Append

Permission to add content to a resource:

If a resource is a container (analogous to a folder in a file system), the Append permission on the resource allows agents to add new resources (container, RDF resource, non-RDF resource) to the container.
If a resource is an RDF resource, the Append permission on a resource allow agents to add statements to the resource.

`allow`, `deny` Expressions#

A policy statement specifies its access modes in allow(Access Modes) or deny(Access Modes) expressions:

The allow expression specifies the access modes to be granted.
The deny expression specifies the access modes to be denied.

An agent is granted an access mode for a resource if:

The agent satisfies a policy that allows the access mode for the resource, and
The agent does not satisfy any policy that denies that access mode for the resource.

For example:

If a resource only has a single policy that allows Read and Write for an agent, the the agent is granted Read and Write for the resource.
If a resource has:
- A policy that allows Read and Write for an agent, and
- A policy that denies Write for the same agent,
Then, the agent is granted Read access for the resource.

If no “allow access” policy is satisfied for a resource, then that resource is inaccessible to the agent. That is, an unsatisfied “deny access” policy does not confer access. For example,

If a resource has defined only a single policy that denies Read and the policy is unsatisfied by an agent, that agent still does not have any access to that resource.

CRUD Operations and Access Modes#

This section summarizes the relationship between Create/Read/Update/Delete (CRUD) operations and the access modes.

To create a resource, the user requires either an Append or Write access.

Note

The creation operation creates the resource (be it container, RDF resource, non-RDF resource) and updates the content of the parent container with the new resource’s metadata.

Resource	Description
Container	Either `Append` or `Write` access on the parent container (under which the new container is to be created) allows agents to create a new container. For example, to create `https://storage..../parentcontainer/newContainer/`, either an `Append` or a `Write` access on `https://storage..../parentcontainer/` allows agents to create `https://storage..../parentcontainer/newContainer/`.
RDF resource	Either `Append` or `Write` access on the parent container (under which the new resource is to be created) allows agents to create a RDF resource. For example, to create `https://storage..../parentcontainer/newResource/`, either an `Append` or a `Write` access on `https://storage..../parentcontainer/` allows agents to create `https://storage..../parentcontainer/newResource`.
Non-RDF resource	Either `Append` or `Write` access on the parent container (under which the new resource is to be created) allows agents to create a new non-RDF resource. For example, to create `https://storage..../parentcontainer/foo.jpg`, an `Append` or `Write` access on `https://storage..../parentcontainer/` allows agents to create `https://storage..../parentcontainer/foo.jpg`.

Resource

Description

Container

Either Append or Write access on the parent container (under which the new container is to be created) allows agents to create a new container.

For example, to create https://storage..../parentcontainer/newContainer/, either an Append or a Write access on https://storage..../parentcontainer/ allows agents to create https://storage..../parentcontainer/newContainer/.

RDF resource

Either Append or Write access on the parent container (under which the new resource is to be created) allows agents to create a RDF resource.

For example, to create https://storage..../parentcontainer/newResource/, either an Append or a Write access on https://storage..../parentcontainer/ allows agents to create https://storage..../parentcontainer/newResource.

Non-RDF resource

Either Append or Write access on the parent container (under which the new resource is to be created) allows agents to create a new non-RDF resource.

For example, to create https://storage..../parentcontainer/foo.jpg, an Append or Write access on https://storage..../parentcontainer/ allows agents to create https://storage..../parentcontainer/foo.jpg.

For read operations, the user requires Read access.

Resource	Description
Container	`Read` access on the target container (analogous to a folder in a file system) allow agents to read/retrieve the container as a resource (not the resource(s) under the container). That is, Read access only affects read operation on the container itself. Reading a container (which stores metadata about the resources contained within the container) allows a client to discover what resources are contained inside the container and their resource type (i.e., analogous to an `ls` on a folder in a file system).
RDF resource	`Read` access on the RDF resource allows agents to read/retrieve the resource (regardless of the access on the parent container). For example, if a resource has as its URL `https://storage..../container/ResourceToRead`, to read/retrieve this resource: The user must have `Read` access on `https://storage..../container/ResourceToRead`. The user’s access on `https://storage..../container/` is immaterial.
Non-RDF resource	`Read` access on a non-RDF resource allows agents to read/retrieve the resource (regardless of Read access on the container). For example, if a non-RDF resource has as its URL `https://storage..../container/foo.jpg`, to read/retrieve this resource: The user must have `Read` access on `https://storage..../container/foo.jpg`. The user’s access on `https://storage..../container/` is immaterial.

Resource

Description

Container

Read access on the target container (analogous to a folder in a file system) allow agents to read/retrieve the container as a resource (not the resource(s) under the container). That is, Read access only affects read operation on the container itself.

Reading a container (which stores metadata about the resources contained within the container) allows a client to discover what resources are contained inside the container and their resource type (i.e., analogous to an ls on a folder in a file system).

RDF resource

Read access on the RDF resource allows agents to read/retrieve the resource (regardless of the access on the parent container).

For example, if a resource has as its URL https://storage..../container/ResourceToRead, to read/retrieve this resource:

The user must have Read access on https://storage..../container/ResourceToRead.
The user’s access on https://storage..../container/ is immaterial.

Non-RDF resource

Read access on a non-RDF resource allows agents to read/retrieve the resource (regardless of Read access on the container).

For example, if a non-RDF resource has as its URL https://storage..../container/foo.jpg, to read/retrieve this resource:

The user must have Read access on https://storage..../container/foo.jpg.
The user’s access on https://storage..../container/ is immaterial.

For update operations, the user requires Append or Write access, depending on the specific update operation.

Resource	Description
Resource	Description
Container	To add resources to the Container, see the `Create` tab. To delete resources from the Container, see the `Delete` tab.
RDF resource	Either `Append` or `Write` access on an RDF resource allows agents to add content (statements) to the resource. `Write` access on an RDF resource allows agents to delete content (statements) from the resource. `Write` access on an RDF resource allows agents to modify existing content (statements) in the resource.
Non-RDF resource	`Write` access on the target resource allows agents to overwrite/replace the resource (regardless of the access on the parent container). For example, if the non-RDF resource has as its URL `https://storage..../container/foo.jpg`, to overwrite this resource: The user must have `Write` access on `https://storage..../container/foo.jpg`. The user’s access on `https://storage..../container/` is immaterial.

For delete operations, the user requires Write access.

Resource	Description
Container	`Write` access on both the parent container and the target container allows agents to delete the target container. For example, to delete `https://storage..../parentcontainer/containerToDelete/`, `Write` access on both `https://storage..../parentcontainer/` and `https://storage..../parentcontainer/containerToDelete/` allows agents to delete `https://storage..../parentcontainer/containerToDelete/`. Tip To delete a container, the container must be empty.
RDF resource	To delete an RDF resource , `Write` access on both the parent container and the target resource allows agents to delete the target resource. For example, to delete `https://storage..../parentcontainer/resourceToDelete/`, `Write` access on both `https://storage..../parentcontainer/` and `https://storage..../parentcontainer/resourceToDelete` allows agents to delete `https://storage..../parentcontainer/resourceToDelete`.
Non-RDF resource	To delete a non-RDF resource, `Write` access on both the parent container and the target resource allows agents to delete the target resource. For example, to delete `https://storage..../parentcontainer/foo.jpg`, `Write` access on both `https://storage..../parentcontainer/` and `https://storage..../parentcontainer/foo.jpg` allows agents to delete `https://storage..../parentcontainer/foo.jpg`.

Resource

Description

Container

Write access on both the parent container and the target container allows agents to delete the target container.

For example, to delete https://storage..../parentcontainer/containerToDelete/, Write access on both https://storage..../parentcontainer/ and https://storage..../parentcontainer/containerToDelete/ allows agents to delete https://storage..../parentcontainer/containerToDelete/.

Tip

To delete a container, the container must be empty.

RDF resource

To delete an RDF resource , Write access on both the parent container and the target resource allows agents to delete the target resource.

For example, to delete https://storage..../parentcontainer/resourceToDelete/, Write access on both https://storage..../parentcontainer/ and https://storage..../parentcontainer/resourceToDelete allows agents to delete https://storage..../parentcontainer/resourceToDelete.

Non-RDF resource

To delete a non-RDF resource, Write access on both the parent container and the target resource allows agents to delete the target resource.

For example, to delete https://storage..../parentcontainer/foo.jpg, Write access on both https://storage..../parentcontainer/ and https://storage..../parentcontainer/foo.jpg allows agents to delete https://storage..../parentcontainer/foo.jpg.

Access Control Resource#

Each Pod resource has an associated Access Control Resource (ACR) that contains the policies that determine access to the Pod resource.

The lifecycle of the ACR is bound to the lifecycle of the Pod resource; that is:

When creating a resource, ESS creates a corresponding ACR.
When deleting a resource, ESS deletes the corresponding ACR.

If a resource has no Policies that apply to it, the resource is inaccessible. However, the Pod owner can add new policies to provide access to the resource.

Default Member Policies#

If a resource is a Container, you can also specify Default Member Policies in the Container’s ACR. A Container’s Default Member Policies are used to initialize the ACRs of the Container’s children/descendents when they are created. As such, updates to a Container’s Default Member Policies do not affect existing children/descendents.

Access to ACRs#

ESS’ Authorization Service hosts the ACRs. The Authorization Service‘s INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST determines which clients can write policies to ACRs.

Note

Having read/write/append access to policies for a resource (i.e., write to the resource’s ACR) is distinct from having access to read/write/append the resource itself.

In addition, the option is used to create initial policies during Pod creation.

Initial ACP Policies#

When a Pod is created, an ACR is also created for the Pod Root, like any other Pod resource. 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.

Access Control Policy (ACP)#

Policies#

Matcher Statements#

Matchers#

allOf, anyOf, noneOf Operators#

Access Mode Statements#

Access Modes#

allow, deny Expressions#

CRUD Operations and Access Modes#

Access Control Resource#

Default Member Policies#

Access to ACRs#

Initial ACP Policies#

`allOf`, `anyOf`, `noneOf` Operators#

`allow`, `deny` Expressions#