Manage Access to Data (ACP)¶
Access Control Policies (ACP) determine the access to Resources stored in Solid Pods. ACP is an alternative to Access Control Lists and is being proposed for inclusion in the Solid specifications.
Solid Server Support
Inrupt’s Enterprise Solid Server (ESS) provides support for ACP.
The other major Solid server implementation, Node Solid Server (powering widely-used Pod service providers
inrupt.net
andsolidcommunity.net
), does not provide support for ACP. Those servers use Web Access Control (WAC). WAC is not recommended for production use. For managing access to Pods on those servers, see Manage Access to Data (WAC) instead.
Access Control Resource (ACR)¶
Every Resource has an associated Access Control Resource (ACR). The Access Control Resource contains the Access Policy that applies to its associated Resource. If the Resource is a Container, its ACR can include Policies that applies to its children (i.e., Member Policies).
Access Policy¶
An Access Policy defines the agents’ access to a resource. Specifically, the Access Policy allows or denies the specified access modes to agents based on how they match the conditions in the listed access rules; i.e.,
If <all | any | none> of the access rules are true for an agent, < allow | deny > the specified access modes to a resource.
ACP Access Rules¶
Access Rules specify agent match conditions. Agent match conditions can be any of the following:
Agent is in a list of WebIDs.
Agent is the creator of the resource.
Agent has authenticated.
Agent can be anyone (i.e., Public).
Agent is a member of one of the listed groups.
A policy can specify that <all | any | none> of the access rules match an agent.
ACP Access Modes¶
Access Modes describe the type of permissions (i.e., access) to a resource. The following Access Modes are available:
Access Mode |
Description |
---|---|
Read |
View data. |
Append |
Add data. |
Write |
Add, update, and delete data. |
Accessing the APIs¶
The ACP-specific functions are exported as properties on the
acp_v2
export. That is, to use the function(s), you
import them with an import of acp_v2
.
For example, to use the getAcrPolicyUrlAll
, you import
acp_v2
:
import {
acp_v2
} from "@inrupt/solid-client";
// ...
const acrPolicyUrl = acp_v2.getAcrPolicyUrlAll(resource);
// ...
Managing Access Controls¶
The API provides the following WithAcr
functions to retrieve the
Access Control Resource (ACR) with the Resource:
getSolidDatasetWithAcr
, getFileWithAcr
, and
getResourceInfoWithAcr
.
To the retrieved Resource with ACR, you can use addPolicyUrl
function to make that Policy apply to the Resource, or use the
addMemberPolicyUrl
function to make the Policy apply to the Resource’s
children. For example:
import {
acp_v2
} from "@inrupt/solid-client";
const resourceWithAcr = await acp_v2.getSolidDatasetWithAcr(
"https://example.pod/resource",
);
let changedResourceWithAcr = acp_v2.addPolicyUrl(
resourceWithAcr,
"https://example.pod/policies#policy",
);
let changedResourceWithAcr = acp_v2.addMemberPolicyUrl(
changedResourceWithAcr,
"https://example.pod/policies#member-policy",
);
To access existing Policies that apply to a Resource or to its children,
use getPolicyUrlAll
and getMemberPolicyUrlAll
, respectively.
To remove existing Policies, use removePolicyUrl
and
removeMemberPolicyUrl
(for individual Policies) or
removePolicyUrlAll
and removeMemberPolicyUrlAll
(for all
currently applied Policies).
You can apply policies to the ACR itself using similar functions. Use
addAcrPolicyUrl
function to add the Policy to the Resource’s ACR or use the
addMemberAcrPolicyUrl
function to add the Policy to the ACR of the
Resource’s children. For example:
import {
acp_v2
} from "@inrupt/solid-client";
const resourceWithAcr = await acp_v2.getSolidDatasetWithAcr(
"https://example.pod/resource",
);
let changedResourceWithAcr = acp_v2.addAcrPolicyUrl(
resourceWithAcr,
"https://example.pod/policies#acr-policy",
);
let changedResourceWithAcr = acp_v2.addMemberAcrPolicyUrl(
changedResourceWithAcr,
"https://example.pod/policies#acr-member-policy",
);
To access existing Policies that apply to an ACR or to the Resource’s
children’s ACRs, use getAcrPolicyUrlAll
and getMemberAcrPolicyUrlAll
,
respectively.
To remove existing Policies, use removeAcrPolicyUrl
and
removeMemberAcrPolicyUrl
(for individual Policies) or
removeAcrPolicyUrlAll
and removeMemberAcrPolicyUrlAll
(for all
currently applied Policies).
Then, to save the Access Control Resource back to the Pod, you can use
saveAcrFor
as in the following example:
import {
acp_v2
} from "@inrupt/solid-client";
const resourceWithAcr = await acp_v2.getSolidDatasetWithAcr(
"https://example.pod/resource",
);
let changedResourceWithAcr = acp_v2.addAcrPolicyUrl(
resourceWithAcr,
"https://example.pod/policies#acr-policy",
);
changedResourceWithAcr = acp_v2.addMemberAcrPolicyUrl(
changedResourceWithAcr,
"https://example.pod/policies#acr-member-policy",
);
changedResourceWithAcr = acp_v2.addPolicyUrl(
changedResourceWithAcr,
"https://example.pod/policies#a-policy",
);
const updatedResourceWithAcr = await saveAcrFor(changedResourceWithAcr);
Managing Access Policies¶
To manage Access Policies, the following
functions are available: createPolicy
to create Access Policies,
getPolicy
and getPolicyAll
to retrieve Access Policies,
removePolicy
to remove Access Policy from a Resource, and
setPolicy
to add the Policy to a Resource.
Note
Access Controls require that a Policy has a full, known URL by which
it can be referred. You must specify this URL to createPolicy
when creating a Policy.
View Modes¶
To view what Modes (Read, Append, or Write) are allowed by a Policy, use
the getAllowModes
function. The function returns an object with the
boolean properties read
, append
and write
:
const policy = acp_v2.getPolicy(
solidDataset,
"https://example.pod/policies#a-policy",
);
const allowedModes = acp_v2.getAllowModes(policy);
// e.g. =>
// { read: true, append: false, write: false }
Similarly, you can use getDenyModes
to obtain a similar object
describing which Modes are denied by a Policy.
Modify Modes¶
To change which Modes a Policy allows, use the setAllowModes
function, passing it an object with boolean properties read
,
append
and write
:
const policy = acp_v2.createPolicy("https://example.pod/policies#a-policy");
const updatedPolicy = acp_v2.setAllowModes(
policy,
{ read: true, append: false, write: false },
);
Similarly, you can use setDenyModes
to change which Modes a Policy
denies.
Managing Access Rules¶
To manage Access Rules, the following
functions are available: createRule
to create Access Rules,
getRule
and getRuleAll
to retrieve Access Rules from a
Resource, removeRule
to remove Access Rule from a Resource, and
setRule
to add the Rule to a Resource.
Note
Access Controls require that a Rule has a full, known URL by which
it can be referred. You must specify this URL to createRule
when
creating a Rule.
Manage Rules for Specific Agents/Groups¶
To manage the Agents for a Rule (i.e., to whom the Rule applies), you
can use getAgentAll
, addAgent
, setAgent
, and
removeAgent
:
const rule = acp_v2.createRule("https://example.pod/rules#a-rule");
const changedRule = acp_v2.addAgent(
rule,
"https://other.pod/profile/card#me",
);
const addedAgents = acp_v2.getAgentAll(changedRule);
// => ["https://other.pod/profile/card#me"]
To manage the Groups for a Rule, you can use the Group
variants of
the functions, e.g., getGroupAll
, etc.
Manage Rules for Public, Any Authenticated User, or the Creator of a Resource¶
Additionally, to inspect whether a Rule applies to everybody, to any
authenticated user, or just the creator of a Resource, you can use the
hasPublic
function, the hasAuthenticated
function and the
hasCreator
function, respectively. To set whether a Rule
applies to everybody, any authenticated user, or the creator of a Resource,
use the corresponding setPublic
, setAuthenticated
and setCreator
functions:
const rule = acp_v2.getRule(
solidDataset,
"https://example.pod/rules#a-rule",
);
let changedRule = acp_v2.setPublic(rule, false);
changedRule = acp_v2.setAuthenticated(changedRule, true);
changedRule = acp_v2.setCreator(changedRule, false);
// `changedRule` does not include everybody,
// but it does include everybody who is authenticated.
Manage Required/Optional/Forbidden Rules¶
A policy can specify that <all | any | none> of the access rules match an agent.
To access rules that the policy specifies with the all condition,
use the required rule functions; e.g., getRequiredRuleUrlAll
,
addRequiredRuleUrl
, setRequiredRuleUrl
, and
removeRequiredRuleUrl
.
To access rules that the policy specifies with the any condition,
use the Optional
variants of the functions;
e.g., getOptionalRuleUrlAll
.
To access rules that the policy specifies with the none condition,
use the Forbidden
variants of the functions;
e.g., setForbiddenRuleUrl
.
const policy = acp_v2.policy(
solidDataset,
"https://example.pod/policies#a-policy",
);
// Replace existing required Rules by the Rule at
// https://example.pod/rules#a-rule
let changedPolicy = acp_v2.setRequiredRuleUrl(
policy,
"https://example.pod/rules#a-rule",
);
// Add the Rule at
// https://example.pod/rules#another-rule
// to the existing optional Rules:
let changedPolicy = acp_v2.addOptionalRuleUrl(
changedPolicy,
"https://example.pod/rules#another-rule",
);