Encapsulated Token Support
- Topics:
- Administering
CREATED FOR:
- Admin
Introduction
By default, AEM uses the Token Authentication Handler to authenticate each request. However, in order to serve authentication requests the Token Authentication Handler requires access to the repository for every request. This happens because cookies are used to maintain the authentication state. Logically, the state needs to be persisted in the repository in order to validate subsequent requests. In effect, this means that the authentication mechanism is stateful.
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.
Stateless Authentication with the Encapsulated Token
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:
Configuring the Encapsulated Token
-
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:
- Because of the cryptography involved, all of the instances need to have the same HMAC key. Since AEM 6.3, the key material is no longer stored in the repository, but on the actual filesystem. With this in mind, the best way to replicate the keys is to copy them from the filesystem of the source instance to that of the target instance(s) you want to replicate the keys to. See more info under “Replicating the HMAC key” below.
- The Encapsulated Token needs to be enabled. This can be done through the Web Console.
Replicating the HMAC key
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;
-
Locate the
com.adobe.granite.crypto.file
bundle in the local file system. For example, under this path:- <author-aem-install-dir>/crx-quickstart/launchpad/felix/bundle21
The
bundle.info
file inside each folder will identify the bundle name. -
Navigate to the data folder. For example:
<author-aem-install-dir>/crx-quickstart/launchpad/felix/bundle21/data
-
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:
<publish-aem-install-dir>/crx-quickstart/launchpad/felix/bundle21/data
-
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.
Enabling the Encapsulated Token
Once the HMAC key has been replicated, you can enable the Encapsulated Token via the Web Console:
- Point your browser to
https://serveraddress:port/system/console/configMgr
- Look for an entry called Day CRX Token Authentication Handler and click it.
- In the following window, tick the Enable encapsulated token support box and press Save.
Experience Manager
- Administering User Guide overview
- Sites Features
- Website Administration
- Reusing Content: Multi Site Manager and Live Copy
- Live Copy Overview Console
- Configuring Live Copy Synchronization
- Creating and Synchronizing Live Copies
- MSM Rollout Conflicts
- MSM Best Practices
- Translating Content for Multilingual Sites
- Managing Translation Projects
- Identifying Content to Translate
- Preparing Content for Translation
- Creating a Language Root Using the Classic UI
- Connecting to Microsoft Translator
- Configuring the Translation Integration Framework
- Language Copy Wizard
- Translation Enhancements
- Translation Best Practices
- Configurations and the Configuration Browser
- AEM FAQs
- Operations
- Dashboards
- Operations Dashboard
- Backup and Restore
- Data Store Garbage Collection
- Monitoring Server Resources Using the JMX Console
- Working with Logs
- Configure the Rich Text Editor
- Configure the Video component
- The Bulk Editor
- Configuring Email Notification
- Configuring RTE for Producing Accessible Sites
- The Link Checker
- Troubleshooting AEM
- Audit Log Maintenance in AEM 6
- Editor
- Managing Access to Workflows
- Using cURL with AEM
- Configuring Undo for Page Editing
- Proxy Server Tool (proxy.jar)
- Configuring for AEM Apps
- Administering Workflows
- Configuring Search Forms
- Tools Consoles
- Reporting
- Administering Workflow Instances
- Configuring Layout Container and Layout Mode
- Enabling Access to Classic UI
- Starting Workflows
- Configure the Rich Text Editor plug-ins
- Admin Consoles
- Security
- User Administration and Security
- User, Group and Access Rights Administration
- Security Checklist
- OWASP Top 10
- Running AEM in Production Ready Mode
- Identity Management
- Adobe IMS Authentication and Admin Console Support for AEM Managed Services
- Creating a Closed User Group
- Mitigating serialization issues in AEM
- User Synchronization
- Encapsulated Token Support
- Single Sign On
- How to Audit User Management Operations in AEM
- SSL By Default
- SAML 2.0 Authentication Handler
- Closed User Groups in AEM
- Granite Operations - User and Group Administration
- Enabling CRXDE Lite in AEM
- Configuring LDAP with AEM 6
- Configure the Admin Password on Installation
- Service Users in AEM
- Encryption Support for Configuration Properties
- Handling GDPR Requests for the AEM Foundation
- Content Disposition Filter
- Personalization
- eCommerce
- Integration
- Integrating with Third-Party Services
- Integrating with Salesforce
- Integrating with Adobe Target
- Integrating with Adobe Analytics
- Connecting to Adobe Analytics and Creating Frameworks
- Configuring Link Tracking for Adobe Analytics
- Mapping Component Data with Adobe Analytics Properties
- Configuring Video Tracking for Adobe Analytics
- HTTP2 Delivery of Content FAQ
- Troubleshooting your Adobe Campaign Integration
- SharePoint Connector Licenses, Copyright Notices, and Disclaimers
- SharePoint Connector
- DHTML Viewer End-of-Life FAQs
- Integrating with Adobe Campaign Classic
- Related Community Articles
- Integrating with Adobe Campaign Standard
- Flash Viewers End-of-Life Notice
- Integrating with Adobe Creative Cloud
- Integrating with Adobe Dynamic Tag Management
- Opting Into Adobe Analytics and Adobe Target
- AEM Portals and Portlets
- Integrating with Dynamic Media Classic
- Troubleshooting Integration Issues
- Integrating with BrightEdge Content Optimizer
- Best Practices for Email Templates
- Catalog Producer
- Integrating with Silverpop Engage
- Integrating with Adobe Campaign
- Integrating with ExactTarget
- Analytics with External Providers
- Integrating with the Adobe Marketing Cloud
- Manually Configuring the Integration with Adobe Target
- Prerequisites for Integrating with Adobe Target
- Adobe Classifications
- Solutions Integration
- Target Integration with Experience Fragments
- Best Practices
- Content Management