Magnolia 5.7 reached extended end of life on May 31, 2022. Support for this branch is limited, see End-of-life policy. Please note that to cover the extra maintenance effort, this EEoL period is a paid extension in the life of the branch. Customers who opt for the extended maintenance will need a new license key to run future versions of Magnolia 5.7. If you have any questions or to subscribe to the extended maintenance, please get in touch with your local contact at Magnolia.
There are three levels of control when REST requests are issued:
- Web access
- JCR access
- Command-level access
Permissions to issue REST requests are controlled using Magnolia's standard role-based security mechanism.
Security strategy
REST endpoints are a powerful tool but can also make your site very vulnerable. Make sure you understand how to implement a strong security strategy to safeguard your system.
Web access security
Web access 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.
Web permissions are granted as web access lists per role. They grant 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
andDELETE
for a given URI.
Web access is checked for every endpoint.
JCR access security
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. Grant JCR access lists per role.
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 that reads or writes JCR data.
JCR access security can be bypassed for the delivery
endpoint for testing purposes.
Role-based security for commands
Command level security access only applies to the commands endpoint.
Role-based access to specific commands are configured in the rest-services
module:
/modules/rest-services/rest-endpoints/commands/enabledCommands/
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.
Security for endpoints - summary
Endpoints always require URI access, they may also require JCR access or a specific role defined at a command level.
When you request a REST URL, URI security is checked first:
- If the URI security check fails, the request is redirected to the login page by default.
- If the the URI security check is passed, the request is delegated to the endpoint in question.
If the endpoint concerns JCR access, JCR access security is checked too:
- If the user is not granted access to the requested node, the endpoint responds with an HTTP error.
- If JCR security access is granted, the endpoint responds with an HTTP response code 200 and a response body if appropriate.
If the endpoint triggers commands, the command definition grants access via specifically defined roles defined per command:
HTTP method | Web access security required | JCR access security | Specific role based security | |
---|---|---|---|---|
delivery | GET | /.rest/delivery/* | Read-only access for the delivery API path | - |
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 |
REST roles
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 thebackup
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.
Custom REST roles
Magnolia recommends you create custom REST roles granting specific access for specific use cases.
The custom roles you create depend on your individual project requirements. In general, we recommend you:
- First deny everything, then specifically grant only what is required.
- Avoid granting write permissions on JCR workspaces for anonymous users.
- Create different roles for each use case.
4 Comments
Marty Glaubitz
What about other Request Methods such as OPTIONS? I found that seems to be no way to get an OPTIONS request through the security chain. And no OPTIONS Request = no CORS
Christoph Meier
Hi
What exactly do you want to do? Cross-origin resource sharing?
You could do this with a filter, see Filters#AddingHTTPheaders
Marty Glaubitz
Christoph Meier i want to controll the entire process in my custom REST Endpoint. The problem is that the REST Security system only allows to differentiate between GET, PUT, POST & DELETE. But in order to controll the CORS headers, i must be able to receive requests with the OPTIONS method as well. Putting the CORS headers into every response is no viable option for me...
As i said the only hard limitation here is that the REST Security doesn't allow OPTIONS requests, otherwise this would be working perfectly fine.
Christoph Meier
This should be easy avoidable with a bypass rule on the filter.
However ... I recommend you to discuss the topic in the the google discussion group(s), see
https://groups.google.com/a/magnolia-cms.com/forum/#!forum/user-list
https://groups.google.com/a/magnolia-cms.com/forum/#!forum/dev-list
There you will have a bigger audience of more experienced people.