This page describes the function of activation keys in Magnolia, what they are used for, possible reasons for their replacement and how to overcome issues which may occur during the replacement process.
Understanding activation keys and their functions
Magnolia uses a pair of keys for the activation process. Activation is 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.
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.
The private is present only in the
The public key is stored also in the
config JCR workspace at
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 does not have a public key yet. The public key is sent to the public instance with the first activation process.
Cooperation of the keys during activation
During an activation process the keys work together. On the author instance both the private and the public keys are used to encrypt and sign activation packages. On the public instance, the public key is required to decrypt the incoming activation package.
Activation 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, activation will no longer work. (See also regenerating the keys.)
If you need to regenerate the key pair, you must propagate the public key to the public instances.
Password manager is using the public key
The Password Manager module uses the public activation key to "hash" plain text passwords. The public key is used for both encryption and decryption. If you change the public key, passwords managed by the Password manager become unusable and you must re-enter them.
When and how to create new keys
As long as your system is not compromised, do not 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 is necessary!
If you already have a public key on the author instances, and if you regenerate the key pair afterwards, your system gets into a state where you can no longer activate any content. This means that you cannot publish the newly generated key either!
If you are using the Password manager module, you may lose access to third-party systems and connectors due to the public key change.
Propagate the new public key to the author instance as soon as possible. In case you are using passwords managed by the Password manager, re-establish the passwords as well.
The re-creation of the key pair must be done on the author instance. Go to Tools > Publishing Tools and click on Generate new key. The system will create both keys and store them in the
magnolia-activation-keypair.properties file. In addition, the system will store the public key in the author system's JCR.
Replacing the public key on the public instances
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 cannot publish (activate) 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@publicKeyproperty, stored in the
configworkspace, from the author instance to each public instance.
- Option II: Delete the
/server/activation@publicKeyproperty in the
configworkspace 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 author instance, in theory an unauthorized activation of content by somebody else could take place. If you choose Option II, you should carry out an activation immediately after the deletion.
You can delete or set the
publicKey property on the
/server/activation node in the
- 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 endpoint 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.
REST endpoints are a powerful tool but can also make your site very vulnerable. Make sure you understand how to implement a strong security strategy to safeguard your system.
This said, the following shows what a REST call done with
cURL could look like:
- Always use SSL/HTTPS for REST calls containing a username and password!
- The user who executes a REST call also needs:
- If you have more than one public instance, you must execute the REST call on each public instance.
- Activate 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 endpoint API.
- 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 network level to restrict the REST calls – for example – to more specific paths such as:
- Add/apply subnet-based or IP range based restrictions.
Re-establishing the passwords in the Passwords app
If you are using the Password manager module and if you had to regenerate the activation key pair, proceed with the following steps only after you have replaced the new public key on the public instances:
- Open the Passwords app (Setup > Passwords) on the author instance.
- Use the Edit password action to re-enter the password for each item.
- Publish all the password items which are required on the public instances.
For cloud users
Magnolia cloud customers
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 our Support for Magnolia cloud customers as soon as possible.If you are running a
Custom cloud solutions
The Magnolia on-premises offer does not provide a one-click, out-of-the-box solution to replace the public keys on the author instances.
See also Replacing the public key on public instances via REST for inspiration.