Access Control Policy (ACP)

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

Policies

Policies determine access for Pod resources. A policy 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 matching:

Agents	To match agents by specific WebID(s). To match any authenticated agent. To match any agent.
Clients	To match by specific Client ID(s). To match any client application. Note To use Client Matchers, the Policy must also specify an Agent Matcher. See also Authorization and Clients.
Verifiable Credentials	To match by Verifiable Credential(s) type; e.g., match VC type http://www.w3.org/ns/solid/vc#SolidAccessGrant. Tip To enable the use of ESS issued access grants (which are serialized as VCs), a policy with a VC Matcher is required. 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 as well as to subscribe to notifications for the 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.

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 required access modes.

CreateReadUpdateDelete

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.

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.

Member Policies

If a resource is a Container, you can also specify Member Policies in the Container’s ACR. Member Policies will be inherited by the Container’s children/descendants.

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. [2]

[2]

In version 2.0, ESS also uses the values in INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST as part of the initial ACP policies that determine the read/write/append access to the Pod and its resource.

Starting in 2.1, ESS uses the values in INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST if set. If unset, ESS uses the values in INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST (same as it did in version 2.0).

For details, see Initial ACP Policies.

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 initial policies give the Pod Owner read and write access to the Pod. These policies also specify a client matcher as well if the Authorization service’s configuration for the initial client allow list is set:

• INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST or if that is unset,

• INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST.

Disambiguation

Both Authorization Service and Pod Storage Service have a INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST setting.

Only the Authorization Service setting affects which clients are allowed. The Pod Storage Service is for Discovery purposes only.

A Pod’s Initial Policies are set when the Pod is provisioned. As such, updates to the operator-controlled allow lists do not affect existing Pods.

Allow List is SetAllow List is Not Set

Note

Starting in 2.1, ESS uses the values in its Authorization service’s INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST (at the time of Pod creation) to create the client matcher for the initial ACP policies. If the setting is unset, ESS uses the values in its Authorization service’s INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST (at the time of Pod creation).

Using the value of the Pod owner’s WebID and an initial client allow list, ESS creates the initial policies of the form:

If allOf(AgentMatcher and ClientMatcher) evaluates to true, Then allow (Read and Write).

Specifically, ESS creates:

Policy 1 for the Pod Root:

If the agent matches the Pod owner’s WebID, and if the client application’s Client ID has a match in the initial client allow list, allow Read and Write access.

Policy 2 for the Pod Root’s Initial Member Policies:

If the agent matches the Pod owner’s WebID, and if the client application’s Client ID has a match in the initial client allow list, allow Read and Write access.

For more information on a Container’s Member Policies, see Member Policies.

Note

After a Pod’s initial policies have been created, changes to INRUPT_AUTHORIZATION_DEFAULT_ACR_CLIENT_ID_ALLOW_LIST (or INRUPT_AUTHORIZATION_CLIENT_ID_ALLOW_LIST) do not impact the Pod’s policies.

[3]

• ESS’ ACP is based on an earlier version of the Access Control Policy (ACP) Specification.

• Inrupt does not provide support for ESS servers running Web Access Control (WAC) in Production.