Skip to main content

WebACL

This package allows you to handle rights through the WebACL standard.

Features#

  • View and modify rights of any resources
  • Automatically add rights when LDP resources, LDP containers or ActivityPub collections are created
  • Create ACL groups, manage members of these groups

Dependencies#

Sub-services#

Bots#

Install#

$ npm install @semapps/webacl --save

Usage#

const { WebAclService } = require('@semapps/webacl');
module.exports = {
mixins: [WebAclService],
settings: {
baseUrl: 'http://localhost:3000/',
superAdmins: ['http://localhost:3000/users/myself']
}
};

This service must be used with an instance of Fuseki which can handle WebAcl. We recommend to use the image semapps/jena-fuseki-webacl (see page on Docker Hub)

You will also need to add the WebAcl middleware to the broker settings.

// moleculer.config.js
const { WebAclMiddleware } = require('@semapps/webacl');
module.exports = {
middlewares: [
WebAclMiddleware
]
};

The WebAclMiddleware:

  • Protects the actions of the LDP service
  • Automatically updates ACL when LDP resources, LDP containers or ActivityPub collections are added or removed.

Secured and unsecured dataset#

It is important to know if your Fuseki dataset is secured with WebACL or not.

  • If you use a secured dataset without the WebACL service and middleware, you will get permission errors every time you try to access a container or resource, because Fuseki will not find the appropriate WebACL triples and will thus assume you do not have the permission to do the action.
  • If you use a unsecured data with the WebACL service and middleware, you will get the error Error when starting the webAcl service: the main dataset is not secure. see fuseki-admin.createDataset.

Here are some important notes:

  • To create a new secured dataset, you should use the FusekiAdmin service, and more specifically the fuseki-admin.createDataset action with the param secure: true. It will load the appropriate config.
  • If you create a new dataset through the Fuseki frontend, it will not be secured.
  • You should never use the DROP+ALL command on a secured dataset, as it will break all the internal config. Use CLEAR+ALL instead.
  • Removing a dataset through the Fuseki frontend will not remove the data and will create problems if you create a new dataset with the same name. So to correctly remove a dataset, you should do a rm -Rf on the two folders in the databases folders: datasetName and datasetNameAcl.

Caching#

If you wish to properly cache the WebAcl and improve performances, we recommend that you add a Cacher middleware before the WebACL middleware.

// moleculer.config.js
const { WebAclMiddleware, CacherMiddleware } = require('@semapps/webacl');
module.exports = {
middlewares: [
CacherMiddleware(...cacherConfig)
WebAclMiddleware,
]
};

See the Moleculer caching documentation to know what options can be passed.

Settings#

PropertyTypeDefaultDescription
baseUrlStringrequiredBase URL of the LDP server
superAdminsArrayArray of users' URIs you want to give superadmins rights (all permissions on all resources). This only works if you have a root LDP container.

Default permissions for new resources#

By default, new resources are created with these rights:

  • If the resource is created by an anonymous user:
    • acl:Read and acl:Write permissions are granted to all users
  • If the resource is created by an authenticated user:
    • acl:Read permission is granted to anonymous users
    • acl:Write and acl:Control permissions are granted to the creator
  • If the resource is created by the system (direct calls from other services):
    • acl:Read permission is granted to anonymous users
    • acl:Write permission is granted to authenticated users

If you wish to change these options, you can set the newResourcesPermissions parameter in LdpService's defaultContainerOptions, or to a particular container.

This newResourcesPermissions parameter can be:

  • An object in the form expected by the additionalRights parameters of the webacl.resource.addRights action (with keys "anon", "anyUser", "user", "group")
  • A function which receives the WebID of the creator (or "anon" if the user is not authenticated, or "system") and returns an object in the same shape

General notes#

  • The SemApps middleware will always connect to the SPARQL endpoint with a Basic Authorization header containing the admin user and its password.
  • If the middleware is doing a query on behalf of a SemApps user, it will send the WebID URI of this user in the HTTP header X-SemappsUser.
  • If no user is logged-in and the middleware is making a request as a public (anonymous) user, then the X-SemappsUser header will be sent with the value anon.
  • If to the contrary, the middleware is modifying the ACLs, it will send no header, or a header with the X-SemappsUser set to system.