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.
Table of Contents |
---|
...
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. |
URI Web access security is checked by the
Javadoc resource link | ||||
---|---|---|---|---|
|
URI Web permissions are granted by Access Lists (ACL). An ACL grants as web access lists per role. They grant access to a path for Get or Get & Post.
GET
for a given URI.GET
, PUT
, POST
and DELETE
for a given URI.URI Web 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. 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.
Info |
---|
JCR access security can be bypassed for the |
Command level security access is the lowest level of access you can configure by role for REST endpointsonly applies to the commands endpoint.
Role-based access to specific commands can be are configured in the rest-services
module: /modules/rest-services/rest-endpoints/commands/enabledCommands/
Include Page | ||||
---|---|---|---|---|
|
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:
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
....
...
Mgnl f |
---|
...
Mgnl f |
---|
...
Mgnl f |
---|
...
Mgnl n |
---|
...
Mgnl n |
---|
...
Mgnl n |
---|
...
Mgnl n |
---|
...
Mgnl n |
---|
...
Mgnl p |
---|
...
rest-admin
...
Mgnl p |
---|
...
website
...
Mgnl p |
---|
...
activate
...
Mgnl n |
---|
...
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 rest-admin
role. The property name is arbitrary but the value must be a valid role name.
...
catalogName
...
required
Catalog where the command resides.
...
commandName
...
required
Command definition name.
...
Endpoints always require URI access, they may also require JCR access or a specific role defined at a command level.
...
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 |
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 – 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 consumer role grants GET permissions to Magnolia's content delivery REST API.rest-backup
– – The REST backup role backup role grants permission to execute the backup
command 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.
Magnolia recommends you create custom REST roles granting specific access for specific use cases.
Todo | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|
To be further specified into
|
...
The custom roles you create depend on your individual project requirements. In general, we recommend you: