Activation keys

This page describes the function of activation keys in Magnolia, what they’re used for, possible reasons for their replacement and how to overcome issues which may occur during the replacement process.

In Magnolia 6.2.44 and later, the Password Manager module key pair is no longer linked to the activation key pair described on this page.

Understanding activation keys and their functions

Magnolia uses a pair of keys for the publishing process.

Activation is used here as a technical term for publishing content from an author instance to public instances. Both the private key and the public key are involved in this process.

magnolia-activation-keypair.properties

Both keys are stored in a file called magnolia-activation-keypair.properties in the filesystem. The path to this file is configured in the Magnolia property magnolia.author.key.location. The file and the keys are created during the installation of a Magnolia author instance.

Private key

The private is present only in the magnolia-activation-keypair.properties file.

Public key

The public key is stored also in the config JCR workspace at /server/activation@publicKey.

On the author instance

On the author instance, the public key is copied to the config workspace during the installation phase.

On the public instance

Immediately after the installation of Magnolia, a public instance doesn’t have a public key yet. The public key is sent to the public instance with the first publishing process.

Cooperation of the keys during publishing

During the publishing process, the keys work together. On the author instance, both the private and the public keys are used to encrypt and sign publication packages. On the public instance, the public key is required to decrypt the incoming publication package.

Publishing requires to have the same public key on the author and on the public instances.

If there already is a public key on the public instances, and if you re-generate the key on the author instance, publishing will no longer work. (See regenerating the keys.)

If you need to regenerate the key pair, you must propagate the public key to the public instances.

When and how to create new keys

As long as your system isn’t compromised, don’t create new keys.

Only if your system running the author instance is corrupted, regenerate the key pair on the author instance and propagate the new public key to the public instances.

Regenerating the key pair

Create a new key pair only if it’s necessary!

If you already have a public key on the author instances, and if you regenerate the key pair afterward, your system gets into a state where you can no longer publish any content. This means that you can’t publish the newly generated key either!

Propagate the new public key to the public instance as soon as possible.

The re-creation of the key pair must be done on the author instance.

  1. Go to AdminCentral.

  2. Open the Publishing Tools app.

    click publishing tools app

  3. Click on Generate new key.

    publishing tools app click generate new key

    The system creates both keys and stores them in the magnolia-activation-keypair.properties file. In addition, the system stores the public key in the author system’s JCR.

Replacing the public key on the public instances

Using Magnolia PaaS?

When using Magnolia PaaS, the keys are automatically distributed to the public instance with the help of a dedicated sidecar.

The following options are for DX-Core users.

If you have an old public key on the public instances after you have regenerated new keys on the author instance, your system is in a state where you can’t publish content. If this situation arises, there are two ways to propagate the new public key to the public instances:

  • Option I: Copy the /server/activation@publicKey property, stored in the config workspace, from the author instance to each public instance.

  • Option II: Delete the /server/activation@publicKey property in the config workspace on every public instance.

In both cases, publishing will work again. Using Option II, the new public key is transferred to the public instances during the first publishing after the deletion of the property.

The Option II can be considered less secure. As long as there is no public key on the public instance, in theory, an unauthorized publishing of content by somebody else could take place. If you choose Option II, you should carry out a publication immediately after the deletion.

You can delete or set the publicKey property on the /server/activation node in the config workspace:

  • Manually via the Configuration app.

  • Via REST, which is explained in the next section.

Replacing the public key on public instances via REST

For the deletion option, you can use the Magnolia Properties API. This approach can be handy if you want to create scripts to replace the public key on your author instances without the need of logging in the AdminCentral UI of public instances.

We assume that you have read and understood REST security.

This said, the following shows what a REST call done with cURL could look like:

curl -X DELETE https://public1.example.com/.rest/properties/v1/config/server/activation/publicKey \
--user johns-user-name:johns-secret-password
curl -X DELETE http://localhost:8080/magnoliaPublic/.rest/properties/v1/config/server/activation/publicKey \
--user superuser:superuser

  • WARNING: Always use SSL/HTTPS for REST calls containing a username and password!

  • The user who executes a REST call also needs:

    • JCR Write permissions for the config workspace and the /server/activation path.

    • Web access (GET & POST) for the /.rest/properties/v1/config/server/activation path.

  • If you have more than one public instance, you must execute the REST call on each public instance.

  • Publish some content immediately after key deletion to enforce the propagation of the new public key from the author instance to the public instances. You can do this also via REST by utilizing the Commands API.

Further tips:

  • With bash or python you can merge multiple REST calls into one script.

  • To automate things: Create a distinct user and a distinct role granting the user the required JCR write permissions and Web access for the REST calls.

  • Add/apply further security layer(s) on Apache or at a network level to restrict the REST calls – for example – to more specific paths such as:

    • /<domain>/.rest/properties/v1/config/server/activation

    • /<domain>/.rest/nodes/v1/config/server/activation

  • Add/apply subnet-based or IP range based restrictions.

For Legacy cloud users

The following sections are for Legacy Cloud only and not Magnolia PaaS.

Magnolia Cloud customers

If you are running a cloud installation managed by Magnolia, Magnolia is responsible for the integrity of the system. In this case you have no obligation to regenerate the keys. If you have accidentally created a new key pair on an author instance, please contact Cloud Help Desk as soon as possible.

Custom cloud solutions

If you manage your own, custom-built cloud solution to run a Magnolia installation, we highly recommend, within the possibilities of your infrastructure, setting up an automated system to replace the public key on your public instances.

The Client Hosted Magnolia offer does not provide a one-click, out-of-the-box solution to replace the public keys on the author instances.

See Replacing the public key on public instances via REST for inspiration.
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules