Magnolia 5.6 reached end of life on June 25, 2020. This branch is no longer supported, see End-of-life policy.
Page History
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.
URI access security
.
| Table of Contents |
|---|
Security strategy
| Multiexcerpt | ||
|---|---|---|
| ||
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 URI security is checked by the
| Javadoc resource link | ||||
|---|---|---|---|---|
|
URI Web permissions are granted by Access Control Lists (ACL). An ACL grants as web access lists per role. They grant access to a path for Get or Get & Post.
- Get – Grants the HTTP method
GETfor a given URI. - Get & Post – Grants the HTTP methods
GET,PUT,POSTandDELETEfor a given URI.
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 dealing which that reads or writes JCR data.Exception: It
| Info |
|---|
JCR access security can be bypassed for the |
...
Role-based security
...
... requires further, nice hopefully well understandable bla bla ... :-|.
Summary
| Info |
|---|
Depending on the endpoint, its access requires always URI access, may require JCR access or may require a specific role defined defined on command level. |
...
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/
| Include Page | ||||
|---|---|---|---|---|
|
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 with 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 thebackupcommand from a running Magnolia instance.
| Multiexcerpt include | ||||||
|---|---|---|---|---|---|---|
|
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 | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|
To be further specified into
|
Enabling commands (optional)
...
| Note |
|---|
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:
- Open the security app and grant the
rest-adminrole a permission to issue requests to thecommandsendpoint. Permission to the endpoint is denied by default. Add a new rule.
- Whitelist any commands you want to expose to REST. The white list is managed in
/modules/rest-services/rest-endpoints/commands/enabledCommands.
...
| enableHeadingAttributes | false |
|---|---|
| enableSorting | false |
| class | m5-configuration-tree |
| enableHighlighting | false |
...
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
...
| Mgnl f |
|---|
...
| Mgnl f |
|---|
...
| Mgnl f |
|---|
...
| Mgnl n |
|---|
...
| Mgnl n |
|---|
...
| Mgnl n |
|---|
...
| Mgnl n |
|---|
...
| Mgnl n |
|---|
...
| Mgnl p |
|---|
...
rest
...
| Mgnl p |
|---|
...
website
...
| Mgnl p |
|---|
...
activate
...
| Mgnl n |
|---|
Properties:
...
required
Enabled commands node.
...
<command>
...
required
Arbitrary name for the command. Use any name you like.
...
access
...
required
Access node.
...
roles
...
required
Roles node.
...
<role>
...
required
Role name. Grants the role permission to execute the command . Add the default rest role. The property name is arbitrary but the value must be a valid role name.
...
catalogName
...
required
Catalog where the command resides.
...
commandName
required
...
- .
Overview
Content Tools