Headless Magnolia: REST Endpoint Security and CORS
If you want to learn about Magnolia’s take on headless content management but don't know where to start, you've come to the right place. As part of our “Headless Magnolia” series, we’ll break down relevant features that allow you to use Magnolia as a headless CMS. In this article, we’ll discuss REST endpoint security and CORS.
REST endpoint security
REST endpoints are a powerful tool but if wrongly secured, they can expose a site to unauthorized access. To safeguard your data, Magnolia blocks all access over REST by default, including published and publicly available website data.
There is nothing wrong with granting anonymous access to public data, for example, allowing a SPA or another front end to fetch it. You can selectively give anonymous access to specific endpoints or configure user-based access using "basic" HTTP authentication"basic" HTTP authentication.
When a REST request is issued, three levels of control apply:
The permissions for REST endpoints are managed in the Security app using Magnolia’s role-based access control.
Magnolia’s access management system provides the means to sign in to applications and authenticates users to verify their identity. It also authorizes users to perform actions such as editing pages, ensuring they have the required permissions.
The Security app is used to manage system access by administering users, user groups, and user roles.
You can change your system’s security settings in two ways:
Modify an existing role
Create a new role and assign it to an existing user user
Web access is checked for every endpoint. The filter checks if the user’s roles allow the user to request a given path using a given method.
Web permissions are granted to roles as web access lists:
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.
By default, Magnolia has a ‘rest-anonymous’ role that is assigned to the ‘anonymous’ system user. Any request that is not explicitly authorized uses this user. The rest-anonymous role grants Get permissions for Magnolia’s content delivery REST API:
Tip: Magnolia has a default user role called ‘rest-anonymous’. It grants the anonymous user access to the /.rest/delivery/* path. To fetch data from the delivery endpoint, use ‘delivery’ as part of the endpoint path.
Headless Magnolia: The Delivery Endpoint API
The Headless Magnolia series explains how to use Magnolia as a headless CMS. Use the Delivery endpoint API to consume content and assets from any front end.
JCR access security is a feature of the JCR standard and applies to every endpoint that reads or writes JCR data.
You can grant Read-only or Read/Write permissions to a role per workspace on path level.
Tip: To bypass JCR security, you can set the endpoint configuration property ‘bypassWorkspaceAcls’ to true. Use this property with care and for development purposes only.
Cross-Origin Resource Sharing (CORS) is a mechanism that uses HTTP headers to instruct browsers to load resources from another origin (domain, protocol, or port) than the original one.
The following CORS filters are available in Magnolia 6.2.4 and up:
Global CORS filter ‘SelfConfiguredCorsFilter’
Site-aware CORS filter ‘SiteAwareCorsFilter’
Filters are specified in the Magnolia filter chain in the Configuration app under /server/filters/cors.
Global CORS filter
The SelfConfiguredCorsFilter is a global CORS filter and its properties are configured in the server, for example:
server: filters: cors: class: info.magnolia.cors.SelfConfiguredCorsFilter uris: rest: patternString: /.rest/* allowedOrigins: - https://example.com - https://magnolia-cms.com allowedMethods: - GET - OPTIONS - POST allowedHeaders: - '*'
Site-aware CORS filter
In a multisite setup, a SiteAwareCorsFilter is configured separately for each site in the Site app or under /modules/multisite/config/sites/<site-name>/cors, for example:
modules: multisite: config: sites: travel: cors: travel: uris: rest: patternString: /.rest/* allowedOrigins: - '*' allowedMethods: - GET allowedHeaders: - Accept - Content-Type - Origin - X-PINGOTHER - X-Requested-With
If you are using a SiteAwareCorsFilter, make sure it is also configured in the server:
server: filters: cors: class: info.magnolia.module.site.filters.SiteAwareCorsFilter
Learn more about Magnolia’s headless features
This Headless Magnolia series will cover the following topics:
REST Endpoint Security and CORS (you are here)
Virtual URI Mapping
Nodes Endpoint API and Commands Endpoint API