REST module security

Permissions to issue REST requests are controlled using Magnolia's standard role-based security mechanism.

Do, re mi ..

<START: note from chm>

URI access security

URI security is checkecked by the URISecurityFilter. The filter checks whether the role(s) of the requesting user allow to request the given path by the given method.

URI permissions are granted by ACLs. An ACL grants access to a path for get or get&post.

get => grants the HTTP method GET for a given URI.

get&post => grants the HTTP methods GET, PUT, POST and DELETE for a given URI.

URI access is checked for every endpoint.

JCR access security

JCR acces security is a feature of the JCR standard (defined by JCR JSR-170 and JSR-283). JCR access is granted per workspace on path level - it can grant the permision to read or to read&write.

When using endpoints dealing with JCR repositories - nodes and properties to read and write - delivery to read only - the given user must have an appropriate role which provides JCR permissions for the given method.

JCR access security is checked on every endpoint dealing which reads or writes JCR data. (Exception: It can be bypassed for the delivery endpoint for testing reasons.)

Specific role based security applied to commands

... requires further, nice hopefully well understandable bla bla ... :-|.

Summary

When requesting a REST URL - first URI security is checked. If URI security check fails, the request is redirected to the login page per default. If the URI security is granted, the requested is delegated to the responsible endpoint.

If the endpoint concerns with JCR access - JCR access security is checked too. If the user is not granted access to the requested node, the endpoint returns with the the HTTP response code 401, 403, 404 or 500 depending on the case (to be checked or to be shortened). When JCR security access is granted, the endpoint returns with the HTTP response code 200 and may or may not return an response body.

If the endpoint triggers commands - the command definition grants access via specifically defined roles defined per command ... (oder so ähnlich ...).

<EOF: note from chm>

REST roles

The REST module installs four default roles with the following permissions:

rest-admin

Web access

Configured access

rest-editor

Web access

rest-anonymous

Web access

rest-backup

Web access

Configured access

The superuser account has the rest-admin role by default so you can use superuser to test your requests. However, for production use you should create a custom REST role. The anonymous role is specifically denied access to the REST endpoints.

Custom REST roles

Magnolia recommends you create custom REST roles granting specific access for specific use cases.TODO:

DOCU-1199 - Getting issue details... STATUS

To be further specified into

• rest roles used on the public instance - mainly to grant to anonymous user
• rest roles for the author context for specific apps and whatnot ...

Enabling commands (optional)

Commands are custom actions executed at pre-defined trigger points. Magnolia uses commands to activate content, send email, flush the cache, take backups, import and export data, and to do many other tasks. Commands can perform duties within the system or connect to external resources.

To enable the use of commands through REST:

1. Open the security app and grant the rest-admin role a permission to issue requests to the commands endpoint.  Permission to the endpoint is denied by default. Add a new rule.
   
2. Whitelist any commands you want to expose to REST. The white list is managed in /modules/rest-services/rest-endpoints/commands/enabledCommands.

Properties: