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

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.

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.

Each Pod resource (Container, RDF resource, non-RDF resource) has an associated Access Control Resource (ACR). ACRs are hosted on the Authorization server.

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]

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:

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.

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.