This is of particular importance for horizontal scalability. In a multi instances setup like the publish farm depicted below, load balancing cannot be achieved in an optimal manner. With stateful authentication, the persisted authentication state will only be available on the instance where the user is first authenticated.
Take the following scenario as an example:
A user may be authenticated on publish instance one, but if a subsequent request goes to publish instance two, that instance does not have that persisted authentication state, because that state was persisted in the repository of publish one and publish two has its own repository.
The solution for this is to configure sticky connections at the load balancer level. With sticky connections a user would always be directed to the same publish instance. As a consequence, truly optimal load balancing is not possible.
In case a publish instance becomes unavailable, all the users authenticated on that instance will lose their session. This is because repository access is needed to validate the authentication cookie.
The solution for horizontal scalability is stateless authentication with the use of the new Encapsulated Token support in AEM.
The Encapsulated Token is a piece of cryptography that allows AEM to securely create and validate authentication information offline, without accessing the repository. This way, an authentication request can happen on all the publish instances and with no need for sticky connections. It also has the advantage of improving authentication performance since the repository does not need to be accessed for every authentication request.
You can see how this works in a geographically distributed deployment with MongoMK authors and TarMK publish instances below:
Please note that the Encapsulated Token is about authentication. It ensures that the cookie can be validated without having to access the repository. However, it is still required that the user exists on all the instances and that the information stored under that user can be accessed by every instance.
For example, if a new user is created on publish instance number one, due to the way the Encapsulated Token works, it will be authenticated successfully on publish number two. If the user does not exist on the second publish instance, the request will still not be successful.
All authentication handlers that synchronize users and rely on token authentication (like SAML & OAuth) will only work with encapsulated tokens if:
Sticky sessions are enabled, or
Users are already created in AEM when the synchronization starts. This means that encapsulated tokens will not be supported in situations where the handlers create users during the sync process.
There are a few things you need to take into consideration when configuring the Encapsulated Token:
The HMAC key is present as a binary property of
/etc/key in the repository. You can download it separately by pressing the view link next to it:
In order to replicate the key across instances, you need to:
Access the AEM instance, typically an author instance, that contains the key material to copy;
com.adobe.granite.crypto.file bundle in the local file system. For example, under this path:
bundle.info file inside each folder will identify the bundle name.
Navigate to the data folder. For example:
Copy the HMAC and master files.
Then, go to the target instance you want to duplicate the HMAC key to, and navigate to the data folder. For example:
Paste the two files you previously copied.
Refresh the Crypto Bundle if the target instance is already running.
Repeat the above steps for all instances you want to replicate the key to.
Once the HMAC key has been replicated, you can enable the Encapsulated Token via the Web Console: