REST security

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 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 info.magnolia.cms.security.URISecurityFilter. The filter checks whether the role(s) of the requesting user allow 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 and DELETE 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/

Command

Commands are custom actions executed at pre-defined trigger points. Magnolia uses commands to publish 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:

Method Web access security required JCR access security Specific role-based security

	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

delivery

GET

/.rest/delivery/*

Read-only access for the delivery API path

nodes

GET