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 repo to 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
- Client & server certificate
- Client certificate - openssl-cert-gen-template/intermediate/certs/admin.cert.pem
- Client key - openssl-cert-gen-template/intermediate/private/admin.key.pem
- Server certificate - openssl-cert-gen-template/intermediate/certs/localhost.cert.pem
- Server key - openssl-cert-gen-template/intermediate/private/localhost.key.pem
- Certificate keystore - openssl-cert-gen-template/keystore/keystore.jks
- 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:
<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"/>
Configure APS for Keycloak Authentication
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
# 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.pemVerify certificates using YubiKey PIV Manager
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.
Browser Configuration
Install OpenSC
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
Configure Browser
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
Configure Keycloak
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
For more details on X.509 client certificate authentication configuration, please refer enable-x-509-client-certificate-user-authentication.
- Copy the openssl-cert-gen-template/keystore/keystore.jks & openssl-cert-gen-template/truststore/truststore.jks files to $KEYCLOAK_HOME/standalone/configuration.
- Open the standalone.xml file and add the following ssl-realm to management/security-realms group in the xml.
<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>- Add a https-listener to the profile/subsystem[xmlns='urn:jboss:domain:undertow:4.0']/server[name="default-server"] in the standalone.xml
<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>- 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 “admin@app.activiti.com” by going to Keycloak -> <your realm> -> Users -> Add user
Configure Direct Grant
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:
Configure Browser Flow
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:
Configure Authentication Bindings
Demo
Direct Grant
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.pemBrowser Auth Demo
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!
1 Comment
