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
The first step is to create the following certificates:
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 repo to generate the following certificates which will be required for the subsequent sections of this blog:
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:
<Connector
protocol="org.apache.coyote.http11.Http11NioProtocol"
port="8443" maxThreads="200"
scheme="https" secure="true" SSLEnabled="true"
keystoreFile="/Users/cijujoseph/openssl-cert-gen-template/keystore/keystore.jks"
keystorePass="keystore"
clientAuth="false" sslProtocol="TLS"/>
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
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.
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.
# 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
# Import Certificate
$pivtool_home/bin/yubico-piv-tool -k $key -a import-certificate -s 9a < $cert_dir/intermediate/certs/admin.cert.pem
# Import Key
$pivtool_home/bin/yubico-piv-tool -k $key -a import-key -s 9a < $cert_dir/intermediate/private/admin.key.pem
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!
Preferences -> Privacy & Security -> Security Devices -> Load
- Module name -> “PKCS#11 Module”
- 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!
For more details on X.509 client certificate authentication configuration, please refer enable-x-509-client-certificate-user-authentication.
<security-realm name="ssl-realm">
<server-identities>
<ssl>
<keystore path="keystore.jks" relative-to="jboss.server.config.dir" keystore-password="keystore"/>
</ssl>
</server-identities>
<authentication>
<truststore path="truststore.jks" relative-to="jboss.server.config.dir" keystore-password="truststore" />
</authentication>
</security-realm>
<subsystem xmlns="urn:jboss:domain:undertow:4.0">
...
<server name="default-server">
...
<https-listener name="https" socket-binding="https" security-realm="ssl-realm" verify-client="REQUESTED"/>
...
</server>
...
</subsystem>
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 “admin@app.activiti.com” by going to Keycloak -> <your realm> -> Users -> Add user
Configuring direct grant is the easiest way to verify the configuration. For more details refer adding-x-509-client-certificate-authentication-to-a-direct-grant-flow. Screenshots below:
The following screenshots will show how to configure the browser flow to use X.509 authentication. For more details, please refer adding-x-509-client-certificate-authentication-to-a-browser-flow. Screenshots below:
Use the following command to test the direct grant (please change the certificate path as per your configuration). For more details refer adding-x-509-client-certificate-authentication-to-a-direct-grant-flow
curl https://localhost:8543/auth/realms/alfresco/protocol/openid-connect/token \
--insecure \
--data "grant_type=password&scope=openid profile&client_id=aps&client_secret=5323135f-36bb-46c4-a641-907ad359827a" \
-E /Users/cijujoseph/openssl-cert-gen-template/intermediate/certs/admin.cert.pem \
--key /Users/cijujoseph/openssl-cert-gen-template/intermediate/private/admin.key.pem
Insert the smart card into your computer and test the browser authentication flow as shown in the below video
References
Special thanks to the following references!
Blog posts and updates about Alfresco Process Services and Activiti.
By using this site, you are agreeing to allow us to collect and use cookies as outlined in Alfresco’s Cookie Statement and Terms of Use (and you have a legitimate interest in Alfresco and our products, authorizing us to contact you in such methods). If you are not ok with these terms, please do not use this website.