This document describes how to integrate Ping Identity's PingID multifactor authentication with Gluu Server by means of an interception script. The script allows users to receive push notifications to their corresponding registered mobile devices in order to get access to applications protected by Gluu Server.
For a successful deployment the following is required:
A PingOne Cloud Platform account. A trial account can be obtained here
Access to a Gluu Server installation
PingID mobile app (for testing users)
Test users at Gluu and (optionally) at PingOne
Mapping of local and remote identities#
Configuring the correspondence between local (Gluu) users and remote (PingOne) users is key. Assuming that Gluu
uid equals to PingOne
username may not be practical. For this purpose it is required to setup an attribute in Gluu's local database to store the reference to the external identity, ie. PingOne username. If your underlying database is LDAP, this page explains how to add an attribute to openDJ schema.
The authentication flow the custom interception script implements may create users at ping side: if a user attempts to login (with Gluu) and the username referenced by the mapping attribute is not found as a pingID user, a new (remote) user is added. This applies as long as the script is parameterized with the
When the mapping attribute is not populated, authentication is performed by means of user+password combination only. The next section provides more information about the actual flow steps.
Authentication flow overview#
The script is implemented as a multi-step authentication flow. The number of steps varies according to the particular circumstances presented at login time:
One step: the user attempting to login does not map to a PingOne identity
Two steps: the user already has a registered device at PingID (will receive a push notification as 2nd step)
Three steps: the user does not have a registered device at PingID (will make enrollment as 2nd step, and receive a push notification as 3rd)
Since enrollment of a mobile device is attempted in the three-stepped flow, this may trigger a change in the user status stored at PingID. Status values are explained here. Note that for suspended accounts authentication will always fail.
The following sequence diagram depicts a successful sample journey in the context of a 3-stepped flow and illustrates the entities involved in the solution.
Note that PingID may detect the recipient device for a push is not reachable (eg. due to network problems). In this case, the user is prompted for the OTP code appearing in the screen of the mobile application. This may also happen when the user has explicitly disabled the swipe gesture in the app.
Ping Identity setup#
This section describes configurations to be carried out with your PingID platform account.
Enable multifactor authentication#
In the PingOne admin portal, visit the "Your Environments" home
Add an environment
Choose "Build your own solution" and if using a trial account, ensure the "show trials" toggle is on.
From "Cloud services" section select "PingOne SSO" and "Ping ID"
Continue with the wizard steps and ensure sample users are generated
When finished, go back to the environments home and click on the row of the recently created environment
Both PingOne SSO and PingID should appear listed under "Services"
On the left menu, click on "Experiences" (smiley icon), and then on "Authentication policies"
A policy named "Multi_Factor" appears listed. Expand the row and click on the edit icon
Click on "make default" under the policy name
Gather Ping ID properties file#
Back in the environments home, click on the ID widget appearing on the row of the environment created on the previous step. You will be taken to Ping ID's admin console
Client integration settingsand download the properties file regarded in the section "INTEGRATE WITH PINGFEDERATE AND OTHER CLIENTS". Store this file in a safe please
Gather test users#
In the PingID's admin console click on
Users by serviceand select the PingID checkbox
Expand some 2-3 users. Those will show a disabled status with no devices listed. Grab their user names
Note: A username appears right below the full user name (at the top)
This section describes configurations to be carried out in Gluu Server.
Transfer script assets#
Extract this file to the root (ie.
/) of your Gluu server. In a standard CE installation this means extraction should take place under
The zip file contains UI pages (forms) and other miscellaneous files. When extracting use the
Deploy oxauth-pingid library#
Transfer this file to your Gluu instance inside folder
/opt/gluu/jetty/oxauth/webappsand edit the file
oxauth.xmlso that in the
extraClasspathsection the following path is added:
If you want to generate the jar file on your own (and possibly inspect the source code) follow the steps below
Transfer script assets and load oxauth-pingid library#
There are two methods of loading files into the deployment which can be used to load the files from the two steps below:
Extract script assets from this file.
wget https://github.com/GluuFederation/oxAuth/raw/version_4.5.0/Server/integrations/pingid/bundle.zip && unzip bundle.zip -d bundle
Get oxauth-pingid library from this file. If you want to generate the jar file on your own (and possibly inspect the source code) follow the steps below
Create a ConfigMap that contains all the files extracted i.e
template.xhtmland the jar file
kubectl create cm oxauth-pingid-integration --from-file=bundle/opt/gluu/jetty/oxauth/custom/i18n/oxauth.properties --from-file=bundle/opt/gluu/jetty/oxauth/custom/pages/auth/pingid/enroll.xhtml --from-file=bundle/opt/gluu/jetty/oxauth/custom/pages/auth/pingid/login.xhtml --from-file=bundle/opt/gluu/jetty/oxauth/custom/pages/auth/pingid/ppm.xhtml --from-file=bundle/opt/gluu/jetty/oxauth/custom/pages/auth/pingid/template.xhtml --from-file=oxauth-pingid-1.0.jar -n <gluu-namespace>
Mount the created ConfigMap in your helm values.yaml inside oxauth
oxauth: volumes: - name: oxauth-pingid-integration-properties configMap: name: oxauth-pingid-integration items: - key: "oxauth.properties" path: "oxauth.properties" - name: oxauth-pingid-integration-enroll configMap: name: oxauth-pingid-integration items: - key: "enroll.xhtml" path: "enroll.xhtml" - name: oxauth-pingid-integration-login configMap: name: oxauth-pingid-integration items: - key: "login.xhtml" path: "login.xhtml" - name: oxauth-pingid-integration-ppm configMap: name: oxauth-pingid-integration items: - key: "ppm.xhtml" path: "ppm.xhtml" - name: oxauth-pingid-integration-template configMap: name: oxauth-pingid-integration items: - key: "template.xhtml" path: "template.xhtml" - name: oxauth-pingid-integration-lib configMap: name: oxauth-pingid-integration items: - key: "oxauth-pingid-1.0.jar" path: "oxauth-pingid-1.0.jar" volumeMounts: - name: oxauth-pingid-integration-properties mountPath: /opt/gluu/jetty/oxauth/custom/i18n/oxauth.properties subPath: oxauth.properties - name: oxauth-pingid-integration-enroll mountPath: /opt/gluu/jetty/oxauth/custom/pages/auth/pingid/enroll.xhtml subPath: enroll.xhtml - name: oxauth-pingid-integration-login mountPath: /opt/gluu/jetty/oxauth/custom/pages/auth/pingid/login.xhtml subPath: login.xhtml - name: oxauth-pingid-integration-ppm mountPath: /opt/gluu/jetty/oxauth/custom/pages/auth/pingid/ppm.xhtml subPath: ppm.xhtml - name: oxauth-pingid-integration-template mountPath: /opt/gluu/jetty/oxauth/custom/pages/auth/pingid/template.xhtml subPath: template.xhtml - name: oxauth-pingid-integration-lib mountPath: /opt/gluu/jetty/oxauth/custom/libs/oxauth-pingid-1.0.jar subPath: oxauth-pingid-1.0.jar
Run helm upgrade
helm upgrade <release-name> gluu/gluu -f ./values.yaml -n <namespace> --set global.upgrade.enabled=true --set global.persistence.enabled=false
Connect to your Jackrabbit
After connecting to Jackrabbit move the extracted content from bundel.zip and the oxauth-pingid library which should be mapped correctly as below inside jackrabbit
+--- opt | +--- gluu | | +--- jetty | | | +--- oxauth | | | | +--- custom | | | | | +--- libs | | | | | | +--- oxauth-pingid-1.0.jar | | | | | +--- i18n | | | | | | +--- oxauth.properties | | | | | +--- pages | | | | | | +--- auth | | | | | | | +--- pingid | | | | | | | | +--- enroll.xhtml | | | | | | | | +--- login.xhtml | | | | | | | | +--- ppm.xhtml | | | | | | | | +--- template.xhtml
After verifying the content has been moved to jackrabbit. Restart oxauth deployment.
Add the custom script#
Log into oxTrust with admin credentials
Person Authentication Scripts. At the bottom click on
Add custom script configurationand fill values as follows:
nameuse a meaningful identifier, like
scriptfield use the contents of this file
For the rest of fields, you can accept the defaults
Add new property. On the left enter
use_base64_keyon the right copy the corresponding value you will find in the properties file downloaded earlier
Repeat the process for
Add another property called
pingUserAttrand set its value to the name of the attribute that will contain the reference to the remote pingID user, as explained here
(Optional) Add a property
addNonExistentPingUserif you require users to be created at ping when nonexisting.
Scroll down and click on the
Updatebutton at the bottom of the page
Building oxauth-pingid library#
If you want to generate the jar file on your own (and possibly inspect the source code) follow the steps below:
In a development machine, ensure Java 8+ and Maven build tool are installed. Download oxAuth project and extract it to a temporary location
mvn package. Ensure the process finishes successfully
target. Resulting file is