Alfresco Process Services v1.9 released a few weeks ago introduced a new authentication module which is based on an open source IAM project called Keycloak which provides a wide range of authentication options! Since Keycloak supports X.509 Client Certificate User Authentication natively, the moment APS 1.9 was announced, I purchased a smart card called Yubikey which supports Personal Identity Verification (PIV) (FIPS 201, a US government standard) to test the X.509 support of Keycloak. This blog is to help Alfresco customers and/or partners looking to implement PIV authentication on Alfresco platform. The steps involved in getting this to work end-end are:
Please note that the steps in this blog is based on my experiments on my macOS. If you are not a macOS user you may want to adjust some of the config steps to match your OS
Generate SSL Certificates
The first step is to create the following certificates:
Server certificate issued and signed by an “Intermediate CA” which will be used to secure both Keycloak and APS apps.
Client certificate which can be used to authenticate the user. This client certificate will be loaded into the PIV smart card
In production scenarios, it is recommended to use internationally trusted CAs (eg: VeriSign) to sign your server and client certificates. Every organization will have best practices in place around certificate issuing and usage, so if you need SSL certificates to secure your apps, check with your security team first! For the purpose of this blog, I’ll be creating root & intermediate CAs by myself. The intermediate CA will be used to sign both the client and server certificates on behalf of the root CA.
Please follow the instructions in my GitHub repoto generate the following certificates which will be required for the subsequent sections of this blog:
Root CA pair
Root CA certificate - openssl-cert-gen-template/certs/ca.cert.pem
Intermediate CA key - openssl-cert-gen-template/private/ca.key.pem
Intermediate CA pair
Intermediate CA certificate - openssl-cert-gen-template/intermediate/certs/intermediate.cert.pem
Intermediate CA key - openssl-cert-gen-template/intermediate/private/intermediate.key.pem
CA truststore - openssl-cert-gen-template/truststore/truststore.jks
Configure Alfresco Process Services
Configure APS for SSL
Enable the HTTPS Connector in tomcat/conf/server.xml using the keystore created in the above mentioned “Generate SSL Certificates” section. My connector config on tomcat version 8.5.11 looks like below:
APS version 1.9 added a new way of authentication based on Keycloak 3.4.3. I’m not going to go through the configuration details here, so please refer APS identity service documentation & APS 1.9 blog for more details on this configuration. Once APS is configured with Keycloak, the authentication flow will be driven by the configurations you make on the Keycloak server. My activiti-identity-service.properties configuration file in APS is shown below:
# -------------------------- # IDENTITY SERVICE # --------------------------
# set to false to fully disable keycloak keycloak.enabled=true keycloak.realm=alfresco keycloak.auth-server-url=https://localhost:8543/auth keycloak.ssl-required=external keycloak.resource=aps keycloak.principal-attribute=email keycloak.credentials.secret=5323135f-36bb-46c4-a641-907ad359827a keycloak.always-refresh-token=true keycloak.autodetect-bearer-only=true keycloak.token-store=cookie keycloak.enable-basic-auth=true keycloak.use-resource-role-mappings=true keycloak.public-client=false keycloak.disable-trust-manager=true
Configure Yubikey (PIV/Smart Card)
I’m using a Yubikey Neo as the PIV smart card where I’ll load my client authentication certificate which will be used to login to APS. The smart card configuration steps are basically based on Yubikey documentation which you can find here.
Install Yubico PIV Tool
The Yubico PIV tool allow you to configure a PIV-enabled YubiKey through a command line interface. Download this tool and use the following commands to load the certificate and key into the authentication slot 9a of your smart card. You may need to configure the device and set a management key to run the following commands. The device setup instructions can be found here.
Commands to load the client certs into Yubikey
# Set pivtool home and openssl-cert-gen-template directories pivtool_home=~/MyApps/yubico-piv-tool-1.5.0-mac cert_dir=/Users/cijujoseph/openssl-cert-gen-template
This is an optional step. The YubiKey PIV Manager enables you to configure a PIV-enabled YubiKey through a graphical user interface. Once the certificate and key is imported, you can verify the imported certificates via this utility. The installer can be found here. When a certificate is successfully loaded into the authentication slot of your Yubikey, the PIV manager will display it as shown below.
As you can see from the OpenSC wiki page, this project provides a set of libraries and utilities to work with smart cards. Since I’m using a Mac, I followed the instructions on this page to get it installed using the DMG file provided by OpenSC
Though I am a Chrome user, I used Firefox (version 60.0.2) for testing the Smart Card Authentication into APS.
If you really want to test this on Chrome, you can use the Smart Card Connector Chrome app to test this. Though this app is intended for Chrome on Chrome OS, it worked for me on my Mac too. However it may prompt you for the Yubikey admin pin too many times which is quite annoying!
My recommendation is to install Firefox and configure Firefox with the OpenSC PKCS11 module as explained below!
Module filename -> “/Library/OpenSC/lib/opensc-pkcs11.so” (installed as part of the OpenSC installation above)
Import the root and intermediate CAs openssl-cert-gen-template/certs/ca.cert.pem & openssl-cert-gen-template/intermediate/certs/intermediate.cert.pem respectively via Preferences -> Privacy & Security -> View Certificates -> Authorities -> Import so that the browser will trust servers configured with certificates issued by these CAs
First step is to install Keycloak 3.4.3 as documented here. The Keycloak documentation is quite detailed, hence I’m not going to detail it out here again. In the next few sections, I’ll go through the X.509 specific configuration of Keycloak which is essential to get this working!
Configure Keycloak for two-way/mutual authentication
Start Keycloak standalone using the command “$KEYCLOAK_HOME/bin/standalone.sh -Djboss.socket.binding.port-offset=100 -b 0.0.0.0” which will start the server by offsetting the default ports by 100. This is helpful to avoid port conflicts on your localhost. With this command, the https port will become 8543 instead of default 8443.
Configure Keycloak authentication flows
Login to Keycloak by going to https://localhost:8543/ (admin/admin) is the default admin user credentials. Add a new user with a username that matches with the certificate attributes. Username “admin” and email “email@example.com” by going to Keycloak -> <your realm> -> Users -> Add user