Customize HCMS configuration upon installation

This section contains several examples of configuration and settings changes required for typical projects. A complete description of all possible options can be found in the reference documentation of the CLI tool.

Note that for readability, all command line tool invocations in this section are shown without -s(--server) and -u (--user) options.

Output Channels

Default value

root.hcms. is used for reading and writing assets.

Customization

The output channel is used to control which content should be made available via HCMS. Only the assets assigned to one of these output channels - through the asset feature "Output Channel hierarchy" - will be accessible. Output channels are usually project-specific, often also environment-specific (one for staging, one for production). The command line tool can be used for creating output channels and adding them to the HCMS configuration.

Things to remember:

The output channel id must be a proper hierarchical id, starting with root. and with a dot at the end.
If the read and write channels are the same, you only need to set up the write channel, and the read one will be added/changed automatically with the same value.

Create a new output channel (if does not exist yet):

CODE

./hcms channel create root.sample1.staging. --name "sample1 staging" --description "staging for sample project 1"

Use this output channel in the CMS configuration; -wc sets the write channel, -rc sets the read channel.

CODE

./hcms configuration update sample-01 -wc root.sample1.staging.

Enable trust for X-Forwarded headers

Any special headers added by load balancers (starting with X-Forwarded-, for example X-Forwarded-For) are, by default, ignored.
This is the safe default for a setup when HCMS is directly accessible by the general Internet traffic.

If the HCMS is accessible only through a reverse proxy (i.e., a load balancer), such headers should be trusted to allow generating correct links. This needs to be done using two options together:

--forwarded needs to be set to true
optionally, --forwarded-levels may be set to some number: this limits the maximum depth of HTTP proxies accepted in forwarded requests

Example command for an HCMS configuration with the id sample-01:

CODE

./hcms configuration update sample-01 --forwarded true --forwarded-levels 1

Security headers

There is a growing number of special security-related headers (as a starting point, OWASP) that should be set by every web application. The HTTP server used by the HCMS satellite also supports security headers. They can be added:

In the WebServer.xml configuration asset on the censhare Server
Starting from the HCMS version 3.2, it can be also managed via the commandline client:

CODE

./hcms configuration update sample-01 -H Strict-Transport-Security:max-age=31536000  -H X-Frame-Options:DENY

Note that the header name and value are separated by a colon, without a space. Any spaces in the value itself must be escaped, or the whole argument must be put inside quotes. Warning: header names and their values are not validated in any way. Some headers are very dangerous and setting them this way would completely break the application, or even the HTTP protocol itself.

JWT Authorization

Default authorization

Upon registering your HCMS configuration, one http-basic user named admin is created, with a random password and full permissions.

Enabling JWT authorization

JSON Web Token (JWT) is the recommended way to authorize requests to Headless CMS. See Authorization reference documentation for details. Two algorithms are supported: HMAC (hash-based message authentication code with shared secret) and RSA (asymmetric cipher signature). Only one of them can be used, it is not allowed to use both at the same time.

To use the HMAC algorithm, simply create an authorization provider with a chosen secret (password):

CODE

./hcms authorization create sample-01 --jwt --secret '6by@m*;2Oq'

Note that the secret must not contain any control characters (e.g., no "\x20").

To use the RSA algorithm, you need to generate an RSA key pair, save it as a .pem file and provide it as an argument to the authorization create command:

CODE

./hcms authorization create sample-01 --jwt --pem jwt-pub.pem

S3 Storage Configuration

Default value

All files - storage items are stored on the local filesystem inside the Docker container. S3 is a recommended alternative.

How to set up S3 storage and configure HCMS to use it

Things to keepn in mind

Even if AWS ECS service is assigned with sufficient permissions to access the S3 bucket via Task Roles, the access/secret key pair is still needed to provide credentials for censhare server.
Those S3 user credentials will be stored in the censhare server.

Steps

Create an AWS user that would be used to access the S3 storage or find some already existing user suitable for this purpose.
Create a new access key and a corresponding secret key.
Create an S3 Bucket and grant this user full read/write access.
Use the hcms command line tool to change the HCMS configuration, providing the new S3 bucket name, access key and secret key.

CODE

./hcms configuration update sample-01 -s s3push -s3bucket hcms-sample-01 -s3region eu-central-1 -s3accessKey AKIA57HXKG2F5BJ6Q7X -s3secretKey K/5pkTogmsunre2aCDhaxK03qdIYgCl6Ghu7oP2V