This project is an example setup that takes advantage of the orchestration capabilities that PingAM provides. It connects PingFederate with PingAM and demonstrates how PingAM MFA features can be combined with PingFederates authentication policies.
The target audiences for this setup are administrators and developers who want to understand more about this configuration and run it on-prem or in a private cloud.
All products are configured via APIs call, no manual tasks are needed. This makes it very easy to get started and have the setup up and running after just a few minutes.
Overview
The environment of this setup looks like this:
Please read the document first before starting to set it up.
Good to know
- This setup was developed on a MacBook. If this is used on a Windows machine, the provided instructions may not work as expected
- Download links can be found at the bottom of this document
This webinar uses the following products and integration kits:
Products:
- PingFederate 12.3
- PingDirectory 10.3
- PingAM 8.0.1
- PingDS 8.0
Download those products, place them here: ./products/... and follow the README.md instructions per product. It is important to match the specified version.
Licenses for PingFederate and PingDirectory should be requested at your CSM.
Additionally, download the PingAM integration kit:
- https://www.pingidentity.com/en/resources/downloads/pingfederate.html
- tab Add-Ons
- PingAM Integration Kit 1.3.1 // older versions are not suitable for this setup
Unzip the file and place the extracted jar-file at this location:
- docker-build/add-ons/pingfederate/server/default/deploy/pf-pingam-adapter-1.3.1.jar
The setup uses these technologies throughout:
- Docker
- Java17
- Maven
- Make (this is just for convenience)
Note: further down are instructions on how to build this setup if Maven is not available!
To simulate a more realistic environment update the local hosts file:
sudo vi /etc/hosts- add {your-current-ip-address} pf.webinar.local pd.webinar.local openam.webinar.local ds.webinar.local playground.webinar.local
- replace {your-current-ip-address} with the current IP address of your computer. Do NOT use localhost or 127.0.0.1
- example: 192.168.0.12 pf.webinar.local ...
- add {your-current-ip-address} pf.webinar.local pd.webinar.local openam.webinar.local ds.webinar.local playground.webinar.local
In order to use example PingAM trees/ journeys install Frodo-cli:
brew tap rockcarver/frodo-clibrew install frodo-cli
Tip: To learn more about this tool, check the Links section further down.
In the current directory, open a terminal and run these commands:
sh initialize-dev-environment.sh- creates an .env file for docker and is used as input for initialize-dev-tls-keypair.sh
- it also contains the configuration details for this setup
- running this script again pushes generated files to dev/.env.bak
- the first time execution may display an error mv: rename .env to dev/.env.bak: No such file or directory which can be ignored
sh initialize-dev-tls-keypair.sh- generates a keystore for this setup. Find generated files in ./dev
- the same keystore is used by PingFederate, PingAM, PingDirectory and PingDS
- the first time execution may display an error mv: rename ./dev/tlskey.p12 to ./dev/tlskey.p12.bak: No such file or directory which can be ignored
All configuration details are taken out of .env. The settings in this file are used throughout all configuration steps further down.
For the purpose of this setup all values can most likely stay as they are.
The only exceptions are these:
- update the file to configure and register an oauth client in PingFederate
- update the file to use the journey WebinarJourneySNS which requires AWS SNS credentials
- this feature requires PingAM to be accessible from the internet
make build_prereq- this will create the docker images webinar/tomcat:10, webinar/openjdk:17
- these are used later
- this has to be executed only once
To build the java code, two options are available:
Option 1: Java and Maven are available:
make build_all- builds all java code and docker images
Option 2: Maven is not available:
make build_builder- this creates a docker image that contains Java and Maven
- repeat this only if pom.xml changes or anything within /libs
make build_all_builder- the same as make build_all, but it uses the builder image to compile the code
Tip: Wherever make is used, have a look into Makefile to learn more about the details.
As temporary docker images have been built, remove them by running this:
docker rmi $(docker images -f "dangling=true" -q)docker builder prune
These are the steps to launch and use the setup. Repeat these steps after stopping the setup.
All previous instructions are required once only and may be repeated if java code or the dockerfiles have been modified.
All docker images have been built and are ready to be launched for the first time:
docker compose up- view the file docker-compose.yml for browser admin URLs and username/ passwords for the different products
make configure_setup- this configures all products
- run this in a separate terminal
frodo conn add -k https://openam.webinar.local:8449/openam amAdmin 'Password1'- This needs to be run only once.
- It adds a connection for frodo and saves it here: ~/.frodo/Connections.json
- run
cat ~/.frodo/Connections.jsonto check if you already have an entry
make import_journeys- this imports all example journeys into PingAM
- Tip: if this fails, wait 5-10 minutes and try again (for some reason that works). Successful imports should include Importing first journey in file... in the console output
All journeys can be found here after they have been imported; their names start with Webinar:
- https://openam.webinar.local:8449/openam
- realm webinar // the realm you configured in .env (PINGAM_REALM)
- Authentication
- Trees
- Authentication
The products are now ready for use. Open the consoles in your browser:
- PingFederate: https://pf.webinar.local:9999 / Administrator / Password1
- PingAM: https://openam.webinar.local:8449/openam/XUI/#login / amAdmin / Password1
- PingDirectory: https://pd.webinar.local:9443/console / cn=administrator/ Password1
- PingDS: no console available / uid=admin / Password1
Test users are stored in PingDirectory and PingFederate and PingAM are connected to it.
Usernames follow this pattern:
- user.1/ password
- ...
- user.10/ password
If there are any issues, here is where to find log files:
PingAM:
docker exec -it openamwebinarlocal bash// this takes you into the running PingAM containercd /root/openam/var/ls -la// several log files are listed
PingFederate:
docker exec -it pfwebinarlocal bash// this takes you into the running PingFederate containercd /opt/pingfederate/logls -la// several log files are listed
This setup comes with different PingFederate policies and PingAM journeys.
| PingFederate policy | IDP Adapter | Description | Notes |
|---|---|---|---|
| WebinarPingAMTree | PingAMIdpAdapter | PingFederate delegates authentication to PingAM. The adapter is configured to execute this journey in PingAM: WebinarJourney. This is the defautl policy and is active | Update the adapter configuration to execute other journeys. Choose from these: WebinarJourneySNS (requires public access via the internet), WebinarJourneyWebAuthN (requires a valid TLS keypair (not self-signed)), WebinarJourneyOAthPush (users need the ForgeRock Authenticator app) |
| WebinarPingAMBCATree | PingAMBackChannelAuthIdpAdapter | Use this with an authorization code flow that includes the parameter login_hint. PingFederate forwards the value to PingAM where the user has to provide his password. The adapter is configured to execute this journey in PingAM: WebinarJourneyBackChannelAuth | |
| WebinarMfaTree | PingAMMfaOnlyIdpAdapter | The user gets authenticated in PingFederate via the HTMLFormAdapter. Afterwards, the user is redirected to PingAM where an OTP based MFA flow is executed. The adapter is configured to execute this journey in PingAM: WebinarJourneyMfaOnly |
Tip: Enable/ disable the policy you want to try out.
If you have configured an oauth client in .env open your client and select the Login button or whatever it may be that initiates an authorization_code flow.
PingFederate will execute the configured policy.
Tip: To install and use OAuthPlayground (which is a test/ demo OAuth client) follow these instructions:
- docker-build/add-ons/oauthplayground/README.md
Even without an oauth client it is possible to try out a journey. However, this does not use PingFederate.
Open a browser to invoke a journey without involving PingFederate:
Replace ...=WebinarJourney with another journey. Find available journey names in Makefile or in the PingAM UI.
The successful journey ends with a view of the user's profile.
Once done with this setup stop it by running the following in the active terminal:
ctrl+cdocker compose down
If you wonder what docker images have been built throughout this setup, run this command:
docker images | grep webinar// the result includes the images IDsdocker rmi {image_id} {image_id} ...// use this to remove the images
If the build process fails, due to missing resources, try these first:
docker rmi $(docker images -f "dangling=true" -q)docker builder prune
If nothing helps, and you run into space limitations you cannot solve:
docker system prune --all --force --volumes-
- WATCH OUT, this will blow away ALL images on your machine!
-
If you want to connect into a running image, use this:
docker exec -it {container_name} bash- {container_name} -- see docker-compose.yml
When done with the evaluation of this setup it could be useful to remove the images as they are large in size:
docker rmi $(docker images --filter=reference="webinar/*" -q)- any image tagged as webinar/ will be deleted
- Download PingFederate:
- https://www.pingidentity.com/en/resources/downloads/pingfederate.html
- the PingAM integration kit is already part of this setup, no need to download it separately
- Download PingAM:
- Download PingDirectory:
- PingFederate Swagger-UI:
- PingAM Swagger-UI:
- Frodo, a management tool for PingAM:
- Create a WebAuthN tree in PingAM
- Learn more about setting up a push notification service leveraging AWS SNS:
- Manage directory schemas with LDIF:
- PingIdentity on YouTube:
- Webinar: This setup was used during a webinar and can be found here:
- sometimes (completely random as far as I am concerned) running
make import_journeysfails. Wait 5-10 minutes and try again - when images startup and PingDirectory or PingDS warn about limited resources (disk space), free up space by running commands as shown further up, stop the setup and launch again
This is not a production environment and is meant for educational purposes only.
It does not come with any kind of warranty, it is provided as is, it was not reviewed for potential performance or security weaknesses.
Logs are verbose to provide insight into the configuration and may include secrets used during this demo.
Use this project to evaluate this setup. Modify it as much or as little as you like.
Report any issues here in GitHub, PingIdentities support team cannot provide assistance of any kind.
This code is to be used exclusively in connection with Ping Identity Corporation software or services. Ping Identity Corporation only offers such software or services to legal entities who have entered into a binding license agreement with Ping Identity Corporation.
This is licensed under the Apache License 2.0.