From c73ef50e48fdf8a1646ca8a77be5c6ffeb5e9562 Mon Sep 17 00:00:00 2001 From: Joachim Van Herwegen Date: Tue, 23 Aug 2022 09:45:33 +0200 Subject: [PATCH] docs: Document ACP-related changes --- RELEASE_NOTES.md | 16 +++++++++++++- .../features/protocol/authorization.md | 22 ++++++++++++------- 2 files changed, 29 insertions(+), 9 deletions(-) diff --git a/RELEASE_NOTES.md b/RELEASE_NOTES.md index 3c2abfe7e..7b6c0a18b 100644 --- a/RELEASE_NOTES.md +++ b/RELEASE_NOTES.md @@ -4,7 +4,8 @@ ### New features -- ... +- The server can be configured to use [ACP](https://solidproject.org/TR/acp) instead of WebACL. + `config/file-acp.json` is an example of a configuration that uses this authorization scheme instead. ### Data migration @@ -28,6 +29,13 @@ The following changes are relevant for v5 custom configs that replaced certain f - `/app/main/general/templates.json` was added to configure a generic template engine handler. - `/app/main/default.json` now imports the above config file. - All files configuring template engines. +- Several minor changes due to support ACP. + - `ldp/authorization/*` +- Resource generation was changed to there is 1 reusable resource generator. + - `init/initializers/*` + - `setup/handlers/setup.json` + - `identity/access/initializers/*` + - `identity/pod/*` ### Interface changes @@ -36,6 +44,12 @@ These changes are relevant if you wrote custom modules for the server that depen - `AgentGroupAccessChecker` no longer accepts any input parameters. - The functions in `Vocabularies.ts` were renamed, the typings have been made more precise and several utility types were added. +- Several changes to support ACP. + - `WebAclAuxiliaryReader` was renamed to `AuthAuxiliaryReader`. + - `OwnerPermissionReader` input parameter `aclStrategy` was renamed to `authStrategy`. + - `TemplatedResourcesGenerator` has been renamed to `BaseResourcesGenerator` and has a different interface now. +- `CredentialSet` was replaced by a single `Credentials` interface. + This impacts all authentication and authorization related classes. ## v5.0.0 diff --git a/documentation/markdown/architecture/features/protocol/authorization.md b/documentation/markdown/architecture/features/protocol/authorization.md index f47220923..d7b1a3f13 100644 --- a/documentation/markdown/architecture/features/protocol/authorization.md +++ b/documentation/markdown/architecture/features/protocol/authorization.md @@ -52,11 +52,10 @@ flowchart TD Both of the WebID extractors make use of the [`access-token-verifier`](https://github.com/CommunitySolidServer/access-token-verifier) library to parse incoming tokens based on the [Solid-OIDC specification](https://solid.github.io/solid-oidc/). -Besides those there are always the public credentials, which everyone has. All these credentials then get combined into a single union object. -If successful, a `CredentialsExtractor` will return a key/value map -linking the type of credentials to their specific values. +If successful, a `CredentialsExtractor` will return an object containing all the information extracted, +such as the WebID of the agent, or the issuer of the token. There are also debug configuration options available that can be used to simulate credentials. These can be enabled as different options through the `config/ldp/authentication` imports. @@ -106,13 +105,13 @@ In both cases it will parse the bodies to determine what the impact would be of ## Permission reading -`PermissionReaders` take the input of the above to determine which permissions are available for which credentials. +`PermissionReader`s take the input of the above to determine which permissions are available. The modes from the previous step are not yet needed, but can be used as optimization as we only need to know if we have permission on those modes. Each reader returns all the information it can find based on the resources and modes it receives. -In the default configuration the following readers are combined when WebACL is enabled as authorization method. +In most of the default configuration the following readers are combined when WebACL is enabled as authorization method. In case authorization is disabled by changing the authorization import to `config/ldp/authorization/allow-all.json`, -this diagram is just a class that always returns all permissions. +the diagram would be a single class that always returns all permissions. ```mermaid flowchart TD @@ -126,7 +125,7 @@ flowchart TD WrappedWebAclReader("WrappedWebAclReader
ParentContainerReader") end - WrappedWebAclReader --> WebAclAuxiliaryReader("WebAclAuxiliaryReader
WebAclAuxiliaryReader") + WrappedWebAclReader --> WebAclAuxiliaryReader("WebAclAuxiliaryReader
AuthAuxiliaryReader") WebAclAuxiliaryReader --> WebAclReader("WebAclReader
WebAclReader") ``` @@ -152,13 +151,20 @@ while deleting a resource requires `write` permissions there. In case the target is an ACL resource, `control` permissions need to be checked, no matter what mode was generated by the `ModesExtractor`. -The `WebAclAuxiliaryReader` makes sure this conversion happens. +The `AuthAuxiliaryReader` makes sure this conversion happens. Finally, the `WebAclReader` implements the [efffective ACL resource algorithm](https://solidproject.org/TR/2021/wac-20210711#effective-acl-resource) and returns the permissions it finds in that resource. In case no ACL resource is found this indicates a configuration error and no permissions will be granted. +### ACP + +It is also possible to use ACP as authorization method instead of WebACL. +In that case the diagram is very similar, +except the `AuthAuxiliaryReader` is configured for Access Control Resources, +and it points to a `AcpReader` instead. + ## Authorization All the results of the previous steps then get combined in the `PermissionBasedAuthorizer` to either allow or reject a request.