AEM Forms – “2-way-SSL” Setup and Workbench configuration

In the past two years almost, I have been working with AEM (Adobe Experience Manager) Forms. The road taken by this project was full of problem because of security constraints that AEM has/had big trouble dealing with. In this blog, I will talk about one security aspect which brings some trouble: how to setup and use the “2-way-SSL” (I will describe below why I put that in quote) for the AEM Workbench.

I have been using AEM Forms 6.4.0 initially (20180228) with its associated Workbench version. I will consider that the AEM Forms has been installed already and is working properly. In this case, I used AEM Forms on a WebLogic Server (12.2) which I configured in HTTPS. So once you have that, what do you need to do to configure and use the AEM Workbench with “2-way-SSL”? Well first, let’s ensure that the AEM Workbench is working properly and then start with the setup.

Open the AEM Workbench and configure a new “Server”:

• Open the AEM Workbench (run the workbench.exe file)
• Click on “File > Login“
• Click on “Configure...”
• Click on the “+” sign to add a new Server
  • Set the Server Title to: <AEM_HOST> – SimpleAuth
  • Set the Hostname to: <AEM_HOST>
  • Set the Protocol to: Simple Object Access Protocol (SOAP/HTTPs)
  • Set the Server Port Number to: <AEM_PORT>
  • Click on “OK“
• Click on “OK“
• Set the Log on to the newly created Server (“<AEM_HOST> – SimpleAuth“)
• Set the Username to: administrator (or whatever other account you have)
• Set the Password for this account
• Click on “Login“

If everything was done properly, the login should be working. The next step is to configure AEM for the “2-way-SSL” communications. As mentioned at the beginning of this blog, I put that in quote because it’s a 2-way-SSL but there is one security layer that is bypassed when doing that. With the AEM Workbench in 1-way-SSL, you need to enter a username and a credential. Adding a 2-way-SSL instead would normally just add another layer of security where the server and client will exchange their certificate and will trust each other but the user’s authentication is still needed!

In the case of the AEM Workbench, the “2-way-SSL” setup actually completely bypass the user’s authentication and therefore I do not really consider that as a real 2-way-SSL setup… It might even be considered as a security issue (it’s a shame for a feature that is supposed to increase security) because, as you will see below, as soon as you have the Client SSL Certificate (and its password obviously), then you will be able to access AEM Workbench. So protect this certificate with great care.

To configure the AEM, you will then need to create an Hybrid Domain:

• Open the AEM AdminUI (https://<AEM_HOST>:<AEM_PORT>/adminui)
• Login with the administrator account (or whatever other account you have)
• Navigate to: Settings > User Management > Domain Management
• Click on “New Hybrid Domain”
  • Set the ID to: SSLMutualAuthProvider
  • Set the Name to: SSLMutualAuthProvider
  • Check the “Enable Account Locking” checkbox
  • Uncheck the “Enable Just In Time Provisioning” checkbox
  • Click on “Add Authentication”
    • Set the “Authentication Provider” to: Custom
    • Check the “SSLMutualAuthProvider” checkbox
    • Click on “OK“
  • Click on “OK“

Note: If “SSLMutualAuthProvider” isn’t available on the Authentication page, then please check this blog.

Then you will need to create a user. In this example, I will use a generic account but it is possible to have several accounts for each of your devs for example, in which case each user must have their own SSL Certificate. The user Canonical Name and ID must absolutely match the CN used to generate the SSL Certificate that the Client will use. So if you generated an SSL Certificate for the Client with “/C=CH/ST=Jura/L=Delemont/O=dbi services/OU=IT/CN=aem-dev“, then the Canonical Name and ID to be used for the user in AEM should be “aem-dev“:

• Navigate to: Settings > User Management > Users and Groups
• Click on “New User“
• On the New User (Step 1 of 3) screen:
  • Uncheck the “System Generated” checkbox
  • Set the Canonical Name to: <USER_CN>
  • Set the First Name to: 2-way-SSL
  • Set the Last Name to: User
  • Set the Domain to: SSLMutualAuthProvider
  • Set the User Id to: <USER_CN>
  • Click on “Next“
• On the New User: 2-way-SSL (Step 2 of 3) screen:
  • Click on “Next“
• On the New User: 2-way-SSL (Step 3 of 3) screen:
  • Click on “Find Roles”
    • Check the checkbox for the Role Name: Application Administrator (or any other valid role that you want this user to be able to use)
    • Click on “OK“
• Click on “Finish“

At this point, you can configure your Application Server to handle the 2-way-SSL communications. In WebLogic Server, this is done by setting the “Two Way Client Cert Behavior” to “Client Certs Requested and Enforced” in the SSL subtab of the Managed Server(s) hosting the AEM Forms applications.

Finally the last step is to get back to the AEM Workbench and try your 2-way-SSL communications. If you try again to use the SimpleAuth that we defined above, it should fail because the Application Server will require the Client SSL Certificate, which isn’t provided in this case. So let’s create a new “Server”:

• Click on “File > Login“
• Click on “Configure...”
• Click on the “+” sign to add a new Server
  • Set the Server Title to: <AEM_HOST> – MutualAuth
  • Set the Hostname to: <AEM_HOST>
  • Set the Protocol to: Simple Object Access Protocol (SOAP/HTTPs) Mutual Auth
  • Set the Server Port Number to: <AEM_PORT>
  • Click on “OK“
• Click on “OK“
• Set the Log on to the newly created Server (“<AEM_HOST> – MutualAuth“)
• Set the Key Store to: file:C:\Users\Morgan\Documents\AEM_Workbench\aem-dev.jks (Adapt to wherever you put the keystore)
• Set the Key Store Password to: <KEYSTORE_PWD>
• Set the Trust Store to: file:C:\Users\Morgan\Documents\AEM_Workbench\trust.jks (Adapt to wherever you put the truststore)
• Set the Trust Store Password to: <TRUSTSTORE_PWD>
• Click on “Login“

In the above login screen, the KeyStore is the SSL Certificate that was created for the Client and the TrustStore will be used to validate/trust the SSL Certificate of the AEM Server. It can be the cacerts from the AEM Workbench for example. If you are using a Self-Signed SSL Certificate, don’t forget to add the Trust Chain into the TrustStore.