- Jun 2, 2021
- 5 min
Powerful, file-based configuration in Magnolia
-
Maxime MichelSite Reliability Engineer, Magnolia
Magnolia in action
Take 12 minutes and a coffee break to discover how Magnolia can elevate your digital experience.
The configuration of Magnolia in Light Modules via YAML is an extremely handy feature that we started shipping with Magnolia 6.1. It's been quite a few months since I first used it, but I still remember getting excited when I realized its potential, and I am eager to showcase it here.
Besides configuring dialogs and templates, you can now also change some of Magnolia's core functionality using YAML. The benefit of this low-code approach is a faster implementation of configuration changes without having to deploy a Java module.
In this blog, I will show examples of the configuration of two new Magnolia features using YAML:
Cross-Origin Resource Sharing (CORS)
Single Sign-On (SSO)
CORS configuration
One common requirement in headless projects is CORS, but did you know that you can configure CORS faster than ever using Light Development?
While not explicitly mentioned in our documentation, it is possible to configure CORS through YAML decoration in a Light Module.
These are the prerequisites that can be configured by following the documentation for REST endpoints and CORS:
A REST endpoint: For this demonstration
- I will use the status endpoint.
The site-aware CORS filter: This is the default. To be sure
- check /server/filters/cors.
A CORS configuration for your site
- for example /modules/multisite/config/sites/<YOUR_SITE>/cors/<YOUR_SITE_CORS_NAME>
Please note that Magnolia offers two options of Magnolia DX Core - with and without our travel demo. I used Magnolia DX Core without the travel demo because the demo’s configuration of the fallback site would interfere with the example.
Since a configuration node now exists, you can use definition decoration from the scope of the Light Module to extend it.
Create the following file:
modules/<YOUR_LIGHT_MODULE>/decorations/multisite/config.yaml.
Now configure CORS as per the documentation and allow requests from localhost:8080:
1sites:
2 fallback:
3 cors:
4 fallback:
5 uris:
6 rest:
7 patternString: /.rest/*
8 allowedOrigins:
9 - http://localhost:8080
10 allowedMethods:
11 - GET
12 allowedHeaders:
13 - Accept
14 - Content-Type
15 - Origin
16 - X-PINGOTHER
17 - X-Requested-With The security settings are now applied to the endpoint, changing its response to an unauthorized origin. You can verify the result using the following command:
1curl 'http://localhost:8080/.rest/status' -H "Origin: http://localhost:8081" -v -o /dev/null You should see a 403 error code:
1% Total % Received % Xferd Average Speed Time Time Time Current
2 Dload Upload Total Spent Left Speed
3 0 0 0 0 0 0 0 0 --:--:-- --:--:-- --:--:-- 0* Trying ::1...
4* TCP_NODELAY set
5* Connected to localhost (::1) port 8080 (#0)
6> GET /.rest/status HTTP/1.1
7> Host: localhost:8080
8> User-Agent: curl/7.64.1
9> Accept: */*
10> Origin: http://localhost:8081
11>
12 0 0 0 0 0 0 0 0 --:--:-- 0:00:02 --:--:-- 0< HTTP/1.1 403
13< Set-Cookie: JSESSIONID=06AC2693F1AB32108B6CF6E1EA8C6551; Path=/; HttpOnly
14< Pragma: no-cache
15< Cache-Control: no-cache, no-store, must-revalidate, max-age=0
16< Expires: Thu, 01 Jan 1970 00:00:00 GMT
17< WWW-Authenticate: FormBased
18< Content-Type: text/html;charset=UTF-8
19< Transfer-Encoding: chunked
20< Date: Mon, 31 May 2021 08:10:05 GMT
21<
22{ [1386 bytes data]
23100 1379 0 1379 0 0 478 0 --:--:-- 0:00:02 --:--:-- 478
24* Connection #0 to host localhost left intact
25* Closing connection 0 This configuration approach has the following benefits over the standard configuration:
It is independent from the instance's configuration
- and you do not have to write it to JCR using a Java module.
Updating this configuration is much easier. Just update the file for Magnolia to implement the change immediately.
It is stored in a plain text file that can easily be added to a Git repository with all its benefits.
Low-code Development
Simplify and speed up development with Magnolia using file-based configuration.
SSO configuration
The new pac4j-based Magnolia SSO module also uses YAML decoration, simplifying the complex integration with authentication services as much as possible.
A word of caution: When you install the module, we assume you'll want to use it, and the module will attempt to take control of your instance. We recommend installing the module in a development environment before rolling it out to production, but I assume that this is already an established good practice.
The initial configuration file is empty, waiting to be decorated. Once the configuration is tuned, Magnolia will implement any changes instantly.
This is the first half of the configuration file
<MODULE_NAME>/decorations/magnolia-sso/config.yaml:
1authenticationService:
2 path: /.magnolia/admincentral
3 callbackUrl: http://localhost:8080/.auth
4 groupMappings:
5 /magnolia-sre:
6 roles:
7 - superuser This configuration:
Delegates authentication for your instance's AdminCentral to a third-party identity provider
Asks the identity provider to redirect to callbackUrl when a user has been logged in
Applies groupMappings to the user's groups property to grant access to AdminCentral
Integration with pac4j's file-based configuration
I'm very eager to share a great improvement in the latest version of the module: it integrates with pac4j's YAML configuration. This means that the module is compatible with any OpenID Connect identity provider.
We’ve validated the use case with Keycloak and Okta. This is the configuration we've used to describe the client's OpenId Connect properties for pac4j to assess incoming requests from the identity provider.
1authenticationService:
2 pac4j:
3 oidc.id: magnolia-sso
4 oidc.secret: 2ff75b44-c7ef-4932-91c8-59e6ea5f35b6
5 oidc.scope: openid profile email
6 oidc.discoveryUri: https://<YOUR_OIDC_IDP_DOMAIN>/…/.well-known/openid-configuration
7 oidc.preferredJwsAlgorithm: RS256 This is what the entire configuration file looks like:
1authenticationService:
2 path: /.magnolia/admincentral
3 callbackUrl: http://localhost:8080/.auth
4 groupMappings:
5 /magnolia-sre:
6 roles:
7 - superuser
8 pac4j:
9 oidc.id: magnolia-sso
10 oidc.secret: 2ff75b44-c7ef-4932-91c8-59e6ea5f35b6
11 oidc.scope: openid profile email
12 oidc.discoveryUri: https://<YOUR_OIDC_IDP_DOMAIN>/…/.well-known/openid-configuration
13 oidc.preferredJwsAlgorithm: RS256 Conclusion
I hope this article was helpful in explaining definition decoration. It’s an auxiliary mechanism that is explained in later sections of our documentation and often considered in later stages of a project. There’s a bit of overhead for the setup, but I hope I have convinced you that the benefits are well worth the effort.
If you need help getting this implemented, you can send me an email.
