Inrupt WebsiteSupport Center

Access Control Policy (ACP)

ESS uses Access Control Policy (ACP) to manage access to Pod resources. 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)](acp.md#acp-matcher)) evaluates to true, AND
< allOf | anyOf | noneOf > ([Matcher(s)](acp.md#acp-matcher)) evaluates to true, AND
…

Then< allow ( [AccessMode(s)](acp.md#acp-access-modes) ) | deny ( [AccessMode(s)](acp.md#acp-access-modes) ) | allow ( [AccessMode(s)](acp.md#acp-access-modes) ) AND deny ( [AccessMode(s)](acp.md#acp-access-modes) ) >

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)](acp.md#acp-matcher)) evaluate to true, AND
< allOf | anyOf | noneOf > ([Matcher(s)](acp.md#acp-matcher)) 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.

See also Authorization and Clients

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

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)](acp.md#acp-access-modes) ) | deny ( [AccessMode(s)](acp.md#acp-access-modes) ) |allow ( [AccessMode(s)](acp.md#acp-access-modes) ) AND deny ( [AccessMode(s)](acp.md#acp-access-modes) ) >

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 allows 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 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, 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.

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 the default ACP policies for the Pod Owner and for Access Grant enablement:

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 configuration 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 .

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.

  • Initial Access Grant Enablement policies allow the use of Access Grants that grant read/write/append access to the Pod resources. New in Version 2.2

          If allOf(VC Matcher) evaluates to true, Then allow (Read and Write and Append).

    Specifically, ESS creates:

Policy 3 for the Pod Root:If a presented VC matches the specified type, allow its use for Read, Write, and Append access.

Policy 4 for the Pod Root’s Initial Member Policies:If a presented VC matches the specified type, allow its use for Read, Write, and Append access. See alsoINRUPT_AUTHORIZATION_DEFAULT_ACR_ACCESS_GRANTS_ALLOWED_MODES.

Important

The policies only enable the use of Access Grants for the allowed access modes. To determine the access for an agent using an access grant, ESS uses the intersection of:

  • The allowed access specified by the policy, and

  • The granted access specified in the Access Grant (for the resource specified in the Access Grant).

Note A Pod’s initial Policies are set when the Pod is provisioned. As such, updates to the various INRUPT_AUTHORIZATION_DEFAULT_ACR_* options do not affect existing Pods.

That is, once a Pod’s initial policies have been created, changes to the various INRUPT_AUTHORIZATION_DEFAULT_ACR_* options are not reflected in that Pod’s policies.

Examples

Create Policy to Match Agents and Clients

The following example sets up an app-friends-policy that allow Read and Write access to any Agent that satisfies the match-app-friends Matcher conditions; namely, Agents whose WebID matches one of the specified WebIDs and is using an application whose Client Identifier matches the specified Client IDs. When verifying against a policy that specifies a Client Application Matcher, the user must be logged in. A Policy that specifies a Client Application Matcher but no Agent Matcher does not match any agent.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2, asUrl } from "@inrupt/solid-client";


// ... Various logic, including login logic, omitted for brevity.
// ...


async function setupPolicyToMatchAgentsAndClients(resourceURL) {

  const agentsToMatch = [ "https://id.example.com/chattycarl", "https://id.example.com/busybee" ];
  const clientIDsToMatch = [ "https://myapp.example.net/appid" ];

  try {
    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
      resourceURL,            // Resource whose ACR to set up
      { fetch: fetch }       // fetch from the authenticated session
    );

    // 2. Initialize a new Matcher.
    let appFriendsMatcher = acp_ess_2.createResourceMatcherFor(
      resourceWithAcr,
      "match-app-friends"
    );

    // 3. For the Matcher, specify the Agent(s) to match.
    agentsToMatch.forEach(agent => {
      appFriendsMatcher = acp_ess_2.addAgent(appFriendsMatcher, agent);
    })

    // 4. For the Matcher, specify the Client ID(s) to match.
    clientIDsToMatch.forEach(clientID => {
      appFriendsMatcher = acp_ess_2.addClient(appFriendsMatcher, clientID);
    })

    // 5. Add the Matcher definition to the Resource's ACR.
    resourceWithAcr = acp_ess_2.setResourceMatcher(
      resourceWithAcr,
      appFriendsMatcher
    );

    // 6. Create a Policy for the Matcher.
    let appFriendsPolicy = acp_ess_2.createResourcePolicyFor(
      resourceWithAcr,
      "app-friends-policy",
    );

    // 7. Add the appFriendsMatcher to the Policy as an allOf() expression.
    // Since using allOf() with a single Matcher, could also use anyOf() expression

    appFriendsPolicy = acp_ess_2.addAllOfMatcherUrl(
      appFriendsPolicy,
      appFriendsMatcher
    );

    // 8. Specify the access modes (e.g., allow Read and Write).
    appFriendsPolicy = acp_ess_2.setAllowModes(appFriendsPolicy,
      { read: true, write: true }
    );

    // 9. Apply the Policy to the resource.
    resourceWithAcr = acp_ess_2.addPolicyUrl(
      resourceWithAcr,
      asUrl(appFriendsPolicy)
    );

    // 10. Add the Policy definition to the resource's ACR. 
    resourceWithAcr = acp_ess_2.setResourcePolicy(
      resourceWithAcr,
      appFriendsPolicy
    );

    // 11. Save the modified ACR for the resource.
    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
      resourceWithAcr,
      { fetch: fetch }          // fetch from the authenticated session
    );

  } catch (error) {
    console.error(error.message);
  }
}

Details

In particular, the example uses:

  1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset with its ACR.

    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
  resourceURL,            // Resource whose ACR to set up
  { fetch: fetch }       // fetch from the authenticated session
);

    To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

  2. acp_ess_2.createResourceMatcherFor to initialize the Matcher that will be used by the policy.

    let appFriendsMatcher = acp_ess_2.createResourceMatcherFor(
  resourceWithAcr,
  "match-app-friends"
);

    When saved, the Matcher URL will be {ACR URL}#match-app-friends.

  3. acp_ess_2.addAgent to specify the WebID of the agent(s) to match:

    agentsToMatch.forEach(agent => {
  appFriendsMatcher = acp_ess_2.addAgent(appFriendsMatcher, agent);
})

  4. acp_ess_2.addClient to specify the Client ID of the application(s) to match.

    clientIDsToMatch.forEach(clientID => {
  appFriendsMatcher = acp_ess_2.addClient(appFriendsMatcher, clientID);
})

  5. acp_ess_2.setResourceMatcher to store the new matcher definition to the ACR:

    resourceWithAcr = acp_ess_2.setResourceMatcher(
  resourceWithAcr,
  appFriendsMatcher
);

  6. acp_ess_2.createResourcePolicyFor to initialize the policy:

    let appFriendsPolicy = acp_ess_2.createResourcePolicyFor(
  resourceWithAcr,
  "app-friends-policy",
);

    When saved, the policy URL will be {ACR URL}#app-friends-policy.

  7. acp_ess_2.addAllOfMatcherUrl to add the matcher to the policy.

    // Since using allOf() with a single Matcher, could also use anyOf() expression

appFriendsPolicy = acp_ess_2.addAllOfMatcherUrl(
  appFriendsPolicy,
  appFriendsMatcher
);

  8. acp_ess_2.setAllowModes to specify that the policy allows Read and Write modes:

    appFriendsPolicy = acp_ess_2.setAllowModes(appFriendsPolicy,
  { read: true, write: true }
);

  9. acp_ess_2.addPolicyUrl to apply the new policy to the resource:

    resourceWithAcr = acp_ess_2.addPolicyUrl(
  resourceWithAcr,
  asUrl(appFriendsPolicy)
);

  10. acp_ess_2.setResourcePolicy to store the new policy definition to the ACR:

    resourceWithAcr = acp_ess_2.setResourcePolicy(
  resourceWithAcr,
  appFriendsPolicy
);

  11. acp_ess_2.saveAcrFor to save the modified ACR.

    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
  resourceWithAcr,
  { fetch: fetch }          // fetch from the authenticated session
);

Make a Resource Public: Create Public Policy for a Resource

The following example uses the ACP-specific APIs to set up a public-policy that allows Read access to the public (i.e., everyone) for a resource.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2 } from "@inrupt/solid-client";

// ... Various logic, including login logic, omitted for brevity.
// ...

async function setupPublicReadPolicyForResource(resourceURL) {
  try {
    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
      resourceURL,              // Resource for which to set up the policies
      { fetch: fetch }          // fetch from the authenticated session
    );

    // 2. Create a Matcher for the Resource.
    let resourcePublicMatcher = acp_ess_2.createResourceMatcherFor(
      resourceWithAcr,
      "match-public"  // Matcher URL will be {ACR URL}#match-public
    );

    // 3. Specify that the matcher matches the Public (i.e., everyone).
    resourcePublicMatcher = acp_ess_2.setPublic(resourcePublicMatcher);

    // 4. Add Matcher to the Resource's ACR.
    resourceWithAcr = acp_ess_2.setResourceMatcher(
      resourceWithAcr,
      resourcePublicMatcher,
    );

    // 5. Create the Policy for the Resource.
    let resourcePolicy = acp_ess_2.createResourcePolicyFor(
      resourceWithAcr,
      "public-policy",  // Policy URL will be {ACR URL}#public-policy
    );

    // 6. Add the Public Matcher to the Policy as an allOf() expression.
    resourcePolicy = acp_ess_2.addAllOfMatcherUrl(
      resourcePolicy,
      resourcePublicMatcher
    );

    // 7. Specify the access modes for the Policy.
    resourcePolicy = acp_ess_2.setAllowModes(
      resourcePolicy,
      { read: true, append: false, write: false },
    );

    // 8. Apply the Policy to the Resource.
    resourceWithAcr = acp_ess_2.addPolicyUrl(
       resourceWithAcr,
       asUrl(resourcePolicy)
     );

    // 9. Add the Policy definition to the Resource's ACR. 
    resourceWithAcr = acp_ess_2.setResourcePolicy(
       resourceWithAcr,
       resourcePolicy,
    );

    // 10. Save the ACR for the Resource.
    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
      resourceWithAcr,
      { fetch: fetch }          // fetch from the authenticated session
    );
  } catch (error) {
    console.error(error.message);
  }
}

Details

In particular, the example uses:

  1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset (the SolidDataset can be a Container) with its ACR.

    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
  resourceURL,              // Resource for which to set up the policies
  { fetch: fetch }          // fetch from the authenticated session
);

    To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

  2. acp_ess_2.createResourceMatcherFor to initialize the Matcher that will be used by the policy.

    let resourcePublicMatcher = acp_ess_2.createResourceMatcherFor(
  resourceWithAcr,
  "match-public"  // Matcher URL will be {ACR URL}#match-public
);

    When saved, the Matcher URL will be {ACR URL}#match-public.

  3. acp_ess_2.setPublic to specify that the matcher is a Public matcher; i.e., matches everyone.

    resourcePublicMatcher = acp_ess_2.setPublic(resourcePublicMatcher);

  4. acp_ess_2.setResourceMatcher to store the matcher definition to the ACR:

    resourceWithAcr = acp_ess_2.setResourceMatcher(
  resourceWithAcr,
  resourcePublicMatcher,
);

  5. acp_ess_2.createResourcePolicyFor to initialize the policy for the Resource:

    let resourcePolicy = acp_ess_2.createResourcePolicyFor(
  resourceWithAcr,
  "public-policy",  // Policy URL will be {ACR URL}#public-policy
);

    When saved, the policy URL will be {ACR URL}#public-policy.

  6. acp_ess_2.addAllOfMatcherUrl to add the matcher to the policy.

    resourcePolicy = acp_ess_2.addAllOfMatcherUrl(
  resourcePolicy,
  resourcePublicMatcher
);

  7. acp_ess_2.setAllowModes to specify the access modes for the policy:

    resourcePolicy = acp_ess_2.setAllowModes(
  resourcePolicy,
  { read: true, append: false, write: false },
);

  8. acp_ess_2.addPolicyUrl to apply the new policy to the resource:

    resourceWithAcr = acp_ess_2.addPolicyUrl(
   resourceWithAcr,
   asUrl(resourcePolicy)
 );

  9. acp_ess_2.setResourcePolicy to store the new policy definition to the ACR:

    resourceWithAcr = acp_ess_2.setResourcePolicy(
   resourceWithAcr,
   resourcePolicy,
);

  10. acp_ess_2.saveAcrFor to save the modified ACR.

    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
  resourceWithAcr,
  { fetch: fetch }          // fetch from the authenticated session
);

View Policies and Matchers for a Resource

The following example uses the ACP-specific APIs to view the ACP policies for a resource.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2, solidDatasetAsTurtle } from "@inrupt/solid-client";

// ... Various logic, including login logic, omitted for brevity.

async function viewResourceACR(resourceURL) {

  try {
    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    const resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
      resourceURL,
      { fetch: fetch }            // fetch from the authenticated session
    );

    // 2a. Get the Access Control Resource (ACR)
    const myACR = await getSolidDataset(
      acp_ess_2.getLinkedAcrUrl(resourceWithAcr),
      { fetch: fetch }
    );
    
    // 2b. Output (formatted as Turtle) its policies and matchers details.
    console.log(solidDatasetAsTurtle(myACR));

    // 3a. Get all policies from the ACR to process policies.
    const myResourcePolicies = acp_ess_2.getResourcePolicyAll(resourceWithAcr);

    // Loop through each policy for processing.
    myResourcePolicies.forEach(policy => {
      //... 
    });

    // 3b. Get a specific policy from the ACR.
    const specificPolicy = acp_ess_2.getResourcePolicy(
      resourceWithAcr,
      "specify-the-name-of-policy-to-get"
    );

    // 4a. Get all matchers from the ACR to process matchers.
    const myResourceMatchers = acp_ess_2.getResourceMatcherAll(resourceWithAcr)

    // Loop through each matcher for processing.
    myResourceMatchers.forEach(matcher => {
      // ... 
    });

    // 4b. Get a specific matcher from the ACR.
    const specificMatcher = acp_ess_2.getResourceMatcher(
      resourceWithAcr,
      "specify-the-name-of-matcher-to-get"
    );


  } catch (error) {
      console.error(error.message);
  }
}

Details

In particular, the example uses:

  1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset (the SolidDataset can be a Container) with its ACR.

    const resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
  resourceURL,
  { fetch: fetch }            // fetch from the authenticated session
);

    To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

  2. getSolidDataset with getLinkedAcrUrl to retrieve the ACR.

    const myACR = await getSolidDataset(
  acp_ess_2.getLinkedAcrUrl(resourceWithAcr),
  { fetch: fetch }
);

    Once you retrieve the ACR as a SolidDataset, you can use solidDatasetAsTurtle to format ACR as Turtle.

    console.log(solidDatasetAsTurtle(myACR));

  3. acp_ess_2.getResourcePolicyAll to get the policies from the resource’s ACR.

    const myResourcePolicies = acp_ess_2.getResourcePolicyAll(resourceWithAcr);

// Loop through each policy for processing.
myResourcePolicies.forEach(policy => {
  //... 
});

    To view a specific policy, you can use acp_ess_2.getResourcePolicy:

    const specificPolicy = acp_ess_2.getResourcePolicy(
  resourceWithAcr,
  "specify-the-name-of-policy-to-get"
);

  4. acp_ess_2.getResourceMatcherAll to get all matchers from the resource’s ACR.

    const myResourceMatchers = acp_ess_2.getResourceMatcherAll(resourceWithAcr)

// Loop through each matcher for processing.
myResourceMatchers.forEach(matcher => {
  // ... 
});

    To view a specific matcher, you can use acp_ess_2.getResourceMatcher:

    const specificMatcher = acp_ess_2.getResourceMatcher(
  resourceWithAcr,
  "specify-the-name-of-matcher-to-get"
);

Delete Existing Policy for a Resource

The following example deletes an existing Policy for a resource.

Tip

To view existing Policies for a resource, see View Policies and Matchers for a Resource.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2 } from "@inrupt/solid-client";

// ... Various logic, including login logic, omitted for brevity.

async function deletePolicyForResource(resourceURL, policyName) {

  try {

    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
      resourceURL,           // Resource whose policy you want to delete
      { fetch: fetch }       // fetch from the authenticated session
    );

    // 2. Remove the Policy definition from the ACR
    resourceWithAcr = acp_ess_2.removeResourcePolicy(resourceWithAcr, policyName);

    // 3. Save the ACR for the Resource.
    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
      resourceWithAcr,
      { fetch: fetch }          // fetch from the authenticated session
    );

  } catch (error) {
    console.error(error.message);
  }
}

Details

In particular, the example uses:

  1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset (the SolidDataset can be a Container) with its ACR.

    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
  resourceURL,           // Resource whose policy you want to delete
  { fetch: fetch }       // fetch from the authenticated session
);

    To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

  2. acp_ess_2.removeResourcePolicy to delete the Policy definition from the ACR:

    resourceWithAcr = acp_ess_2.removeResourcePolicy(resourceWithAcr, policyName);

    acp_ess_2.removeResourcePolicy can also accept the Policy URL or the Policy itself instead of the Policy name.

  3. acp_ess_2.saveAcrFor to save the modified ACR.

    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
  resourceWithAcr,
  { fetch: fetch }          // fetch from the authenticated session
);

Modify Existing Matcher for a Resource

The following example continues from an earlier example. Specifically, the example modifies the match-app-friends created in Create Policy to Match Agents and Clients to remove one of the Agents from the match list.

Tip

To view existing Matchers for a resource, see View Policies and Matchers for a Resource.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2 } from "@inrupt/solid-client";

// ... Various logic, including login logic, omitted for brevity.

async function removeAgentFromMatcher(resourceURL) {

  try {

    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
        resourceURL,           // Resource whose Matcher you want to modify
        { fetch: fetch }       // fetch from the authenticated session
    );

    // 2. Get the Matcher to modify.
    let matcherToModify = acp_ess_2.getResourceMatcher(
        resourceWithAcr,
        "match-app-friends" // Name of the Matcher created in an earlier example.
    );

    // 3. Modify the Matcher; e.g., remove an Agent from the Matcher.

    const agentToRemove="https://id.example.com/chattycarl";
    matcherToModify = acp_ess_2.removeAgent(matcherToModify, agentToRemove);

    // 4. Store the modified Matcher definition to the resource's ACR.
    resourceWithAcr = acp_ess_2.setResourceMatcher(
        resourceWithAcr,
        matcherToModify
    );

    // 5. Save the modified ACR for the resource.
    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
        resourceWithAcr,
        { fetch: fetch }          // fetch from the authenticated session
    );

  } catch (error) {
    console.error(error.message);
  }
}

Details

In particular, the example uses:

  1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset (the SolidDataset can be a Container) with its ACR.

    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
    resourceURL,           // Resource whose Matcher you want to modify
    { fetch: fetch }       // fetch from the authenticated session
);

    To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

  2. acp_ess_2.getResourceMatcher to get the Matcher from the resource’s ACR.

    let matcherToModify = acp_ess_2.getResourceMatcher(
    resourceWithAcr,
    "match-app-friends" // Name of the Matcher created in an earlier example.
);

    The match-app-friends was created in an earlier example, Create Policy to Match Agents and Clients.

    Tip

    To view existing Matchers for a resource, see View Policies and Matchers for a Resource.

  3. acp_ess_2.removeAgent to remove an Agent’s WebID from the list of the Matcher’s WebIDs to match.

    policyToModify = acp_ess_2.setAllowModes(policyToModify,
  { write: false }
);

  4. acp_ess_2.setResourceMatcher to update the Matcher definition in the ACR:

    resourceWithAcr = acp_ess_2.setResourcePolicy(
  resourceWithAcr,
  policyToModify
);

  5. acp_ess_2.saveAcrFor to save the modified ACR.

    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
  resourceWithAcr,
  { fetch: fetch }          // fetch from the authenticated session
);

Modify Existing Policy for a Resource

The following example continues from an earlier example. Specifically, the example modifies the app-friends-policy created in Create Policy to Match Agents and Client.

Tip

To view existing Policies for a resource, see View Policies and Matchers for a Resource.

import { handleIncomingRedirect, login, fetch, getDefaultSession } from '@inrupt/solid-client-authn-browser';
import { acp_ess_2 } from "@inrupt/solid-client";

// ... Various logic, including login logic, omitted for brevity.

async function modifyAppFriendsPolicy(resourceURL) {

  try {

    // 1. Fetch the SolidDataset with its Access Control Resource (ACR).
    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
      resourceURL,           // Resource whose Policy you want to modify
      { fetch: fetch }       // fetch from the authenticated session
    );

    // 2. Get the Policy to modify. 
    let policyToModify = acp_ess_2.getResourcePolicy(
      resourceWithAcr,
      "app-friends-policy" // Name of the Policy created in an earlier example.
    );

    // 3. Change the Write access mode to false (from true). Other access modes remain unchanged.
    policyToModify = acp_ess_2.setAllowModes(policyToModify,
      { write: false }
    );

    // 4. Store the modified Policy definition to the resource's ACR. 
    resourceWithAcr = acp_ess_2.setResourcePolicy(
      resourceWithAcr,
      policyToModify
    );

    // 5. Save the modified ACR for the resource.
    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
      resourceWithAcr,
      { fetch: fetch }          // fetch from the authenticated session
    );

  } catch (error) {
    console.error(error.message);
  }
}

Details

In particular, the example uses:

  1. acp_ess_2.getSolidDatasetWithAcr to retrieve the SolidDataset (the SolidDataset can be a Container) with its ACR.

    let resourceWithAcr = await acp_ess_2.getSolidDatasetWithAcr(
  resourceURL,           // Resource whose Policy you want to modify
  { fetch: fetch }       // fetch from the authenticated session
);

    To specify policies for files with other structures (such as .pdf or .jpeg files), use acp_ess_2.getFileWithAcr instead.

  2. acp_ess_2.getResourcePolicy to get the Policy from the resource’s ACR. The app-friends-policy was created in an earlier example, Create Policy to Match Agents and Clients.

    let policyToModify = acp_ess_2.getResourcePolicy(
  resourceWithAcr,
  "app-friends-policy" // Name of the Policy created in an earlier example.
);

    Tip

    To view existing Policies for a resource, see View Policies and Matchers for a Resource.

  3. acp_ess_2.setAllowModes to update the Write access mode for the Policy. The other Access Modes for this Policy remain unchanged.

    policyToModify = acp_ess_2.setAllowModes(policyToModify,
  { write: false }
);

    For additional Policy functions, see the API documentation.

  4. acp_ess_2.setResourcePolicy to update the Policy definition in the ACR:

    resourceWithAcr = acp_ess_2.setResourcePolicy(
  resourceWithAcr,
  policyToModify
);

  5. acp_ess_2.saveAcrFor to save the modified ACR.

    const updatedResourceWithAcr = await acp_ess_2.saveAcrFor(
  resourceWithAcr,
  { fetch: fetch }          // fetch from the authenticated session
);
PreviousAuthorization/Access ControlNextIdentity-Based Access Policies

Last updated