Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
There are three levels of control when REST requests are issued:
Permissions to issue REST requests are controlled using Magnolia's standard role-based security mechanism.
URI security is checked by the URISecurityFilter. The filter checks whether the role(s) of the requesting user allow to the user to request a given path with given method.
URI permissions are granted by Access Lists (ACL). An ACL grants access to a path for Get or Get & Post.
GET
for a given URI.GET
, PUT
, POST
and DELETE
for a given URI.URI access is checked for every endpoint.
JCR access 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 Read-only or Read/Write permission.
When using endpoints dealing with JCR repositories (nodes
and properties
to read and write, delivery
to read only) the user must have an appropriate role that provides JCR permissions for the given method.
JCR access security is checked on every endpoint dealing which reads or writes JCR data.
JCR access security can be bypassed for the delivery
endpoint for testing purposes.
Command level security access is the lowest level of access you can configure by role for REST endpoints.
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.
Role-based access to specific commands can be configured in the rest-services
module: /modules/rest-services/rest-endpoints/commands/enabledCommands/
Endpoints always require URI access, they may also require JCR access or a specific role defined defined at a command level.
When you request a REST URL, URI security is checked first:
If the endpoint concerns JCR access, JCR access security is checked too:
If the endpoint triggers commands, the command definition grants access via specifically defined roles defined per command:
HTTP method | URI security required | JCR access security | Specific role based security | |
---|---|---|---|---|
delivery | GET | /.rest/delivery/v1/{workspace}/{path} | Read-only access for a path on a workspace | - |
nodes | GET | /.rest/nodes/v1/{workspace}/{path} | Read-only access for a path on a workspace | - |
PUT | /.rest/nodes/v1/{workspace}/{path} | Read/Write access for a path on a workspace | - | |
POST | /.rest/nodes/v1/{workspace}/{path} | Read/Write access for a path on a workspace | - | |
DELETE | /.rest/nodes/v1/{workspace}/{path} | Read/Write access for a path on a workspace | - | |
properties | GET | /.rest/nodes/v1/{workspace}/{path} | Read-only access for a path on a workspace | - |
PUT | /.rest/nodes/v1/{workspace}/{path} | Read/Write access for a path on a workspace | - | |
POST | /.rest/nodes/v1/{workspace}/{path} | Read/Write access for a path on a workspace | - | |
DELETE | /.rest/nodes/v1/{workspace}/{path} | Read/Write access for a path on a workspace | - | |
commands | POST | /.rest/commands/v2/{catalogName}/{command} | - | required |
The REST module installs four default roles with the following permissions:
rest-admin
– The REST administrator role grants GET/POST permissions to all Magnolia's REST APIs.rest-editor
– The REST editor role grants GET/POST permissions to REST services APIs (nodes, properties), for a limited set of workspaces.rest-anonymous
– The REST anonymous consumer role grants GET permissions to Magnolia's content delivery REST API.rest-backup
– The REST backup role grants permission to execute the backup
command from a running Magnolia instance.Web access Permission Path Get & Post Configured access Applies to Name Path Commands Delete Activate Web access Permission Path Deny Deny Deny Get & Post Deny Get & Post Get & Post Web access Permission Path Deny Get Web access Permission Path Get & Post Configured access Applies to Name Path Command Backuprest-admin
/.rest/*
/modules/rest-services/rest-endpoints/commands/enabledCommands/markAsDeleted/access/roles
/modules/rest-services/rest-endpoints/commands/enabledCommands/activate/access/roles
rest-editor
/.rest*
Get /.rest/delivery/*
/.rest/commands*
/.rest/nodes*
/.rest/nodes/v1/website*
/.rest/properties*
/.rest/properties/v1/website*
/.rest/cache/v1*
rest-anonymous
/.rest*
/.rest/delivery/*
rest-backup
/.rest/commands/v2/backup/backup
/modules/rest-services/rest-endpoints/commands/enabledCommands/backup/access/roles
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.
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 intoanonymous
user
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.
You can make sweeping changes with commands, such as bypassing approval and deleting the whole site. Commands are therefore subject to special security restrictions.
To enable the use of commands through REST:
rest-admin
role a permission to issue requests to the commands
endpoint. Permission to the endpoint is denied by default. Add a new rule./modules/rest-services/rest-endpoints/commands/enabledCommands
.Node name | Value |
---|---|
modules | |
rest-services | |
rest-endpoints | |
commands | |
enabledCommands | |
activate | |
access | |
roles | |
rest | rest |
catalogName | website |
commandName | activate |
markAsDeleted |
Properties:
enabledCommands | required Enabled commands node. |
| required Arbitrary name for the command. Use any name you like. |
| required Access node. |
| required Roles node. |
| required Role name. Grants the role permission to execute the command . Add the default |
| required Catalog where the command resides. |
| required Command definition name. |