This article is a first-hand account of lab-based testing to configure Keycloak SSO with Duo two-factor authentication (2FA) for VMware’s vCloud Director (vCD) in a lab environment. All testing and documentation were performed by phoenixNAP’s own Joe Benga. Joe is our trusted Enterprise Architect for cloud, infrastructure, and networking technologies.
I have grown fond of Keycloak as a product. I find it to be a strong source of identity and an Access Management Solution (AMS).
I wanted to leverage Keycloak in my lab for VMware’s vCloud Director (vCD), and test Active Directory (AD) integration with two-factor authentication (2FA) support.
In this first-hand account, I list the steps I took in a lab environment to provide Security Assertion Markup Language (SAML) integration with Keycloak at an organizational level. Additionally, I explain how I provide Duo Security 2FA to the front-facing portal.
As always, these are just basic steps. Please keep security and best practices for your company in mind.
Keycloak
For this experiment, we are fortunate that Keycloak has a pre-built Docker package to jumpstart everything.
With a few simple commands, I was able to get a core product up and running on a CentOS 7 Virtual Machine (VM). At this point, I decided that instead of running everything standalone, I would back it with a Postgres container. For your experiment, you can decide what you need for your own lab, with different options provided in the info link below. I added color coding to show how commands are related to each other.
For full info: https://hub.docker.com/r/jboss/keycloak/
Prerequisites: Docker CE, Firewall settings (if required).
1. Create a shared user network for the Database and Keycloak container:
docker network create keycloak-network
2. Start DB Container (optional, I went with Postgres):
docker run -d --name postgres --net keycloak-network -e POSTGRES_DB=keycloak -e POSTGRES_USER=keycloak -e POSTGRES_PASSWORD=password postgres
3. Start Keycloak:
docker run -p 8080:8080 --name keycloak --net keycloak-network -e KEYCLOAK_USER=username -e KEYCLOAK_PASSWORD=password jboss/keycloak
4. Once you have completed these steps, you should be able to log in to Keycloak at (username and password are what you defined in green text):
http://ip_addr:8080/auth/admin/
For production use, consider using a secure secret storage service to handle credentials passed to the container.
Keycloak vCloud Director Configuration
1. Create a new realm based on your vCloud Org’s name by selecting the drop-down arrow next to Master and clicking Add Realm.
If you are not going to leverage SSL once your realm is created, navigate to the login TAB and set Require SSL to none
2. While in Keycloak, create a local User to use as a test. (Later, we will leverage an Active Directory User.) Under our Realm in the left pane, navigate to Manage > Users.
3. In the right pane, select Add user
4. Enter the info for the User. Make sure to include an email address, as we will specify email as the Name ID Format in this log. Then select Save
5. Navigate to the Credentials tab. Enter and confirm the new password and deselect Temporary. Then click Reset Password
6. Now that we have your realm and user, we will need to grab your org’s metadata. Log in to your org. Navigate to Administration in the left pane under Settings > Federation and select the Metadata link.
7. Download the spring_saml_metadata.xml file. This file will provide us with the certificate and config file that can easily be imported into Keycloak’s client setup
8. In Keycloak, navigate to the left pane under Configure > Clients and select Create in the right pane.
9. Click on Select File and import the spring_saml_metadata.xml that was just downloaded. Select Save.
10. Navigate to the Installation Tab and in the Format Option: select SAML Metadata IDPSSODescriptor, then copy or download the text that shows up in the dialog box
11. In vCD, navigate under Administration. In the left pane Settings > Federation select Use SAML Identity Provider and then copy or upload the SAML Metadata IDPSSODescriptor info from above. Then click Apply. Depending on the network setup, you may need to adjust the IP info in the Metadata XML manually.
12. Import the Keycloak user. In the right pane under Members > Users. Select Import Users Icon. Then, enter the email address of the user we created above and select the desired vCD Role. During this step, I also include the Active Directory user email that I will be using later.
13. Log in to vCloud Director org, and we will be redirected to the Keycloak Realm login screen.
We now have our Identity Manager Application providing authentication for our vCloud Director portal. Next, we will sync with the Active Directory underlying this setup through a Duo proxy and show how to leverage 2FA. I will also show how to add OTP to any user to quickly leverage Google Authentication.
Integrating Duo into Keycloak
Prerequisites:
- Active Directory is already running.
- Duo Auth Proxy Running (https://duo.com/docs/authproxy-overview) and connected to Active Directory.
Note: My Duo Proxy Configuration
1. Under our Realm in the left pane, navigate to Configure > User Federation. In the right pane, add an LDAP provider.
2. Set your Edit Mode: Vendor: Active Directory (this is due to my Duo proxy connecting to Win2012 AD), Connection URL, User DN, Auth Type, Bind DN, Bind Credentials, Connection Search Scope: SubTree (unless you working in the same level), Cache Policy: No Cache (we want the request to hit the proxy for every request)
3. Select Save, and then select Synchronize: All Users.
4. If you didn’t pre-add your Duo user, add it now by repeating Step 14.
5. In the vCD login screen, use the email of the backing AD account that is leveraging Duo. Please note that the login screen will not display any prompt that it is awaiting 2FA approval.
The screen will just appear stuck until you approve on your 2FA hardware device.
Adding One-Time Password (OTP)
Use this process to quickly add an OTP.
1. Under our Realm in the left pane, navigate to Configure > Authentication. Select the OTP Policy and configure your settings. You may need to adjust your look-ahead window to accommodate mismatched time settings on your servers.
2. In the left pane, navigate to Manage > Users and select the user we created in Step 6.
3. Under the Detail tab, in the Required User Actions config, select Configure OTP, and select Save.
4. Log in to vCD with this user. Before we can access vCloud Director, we need to set up a 2FA authenticator. This can be done from the screen shown below.
5. You can leverage any OTP app, such as Duo or Google Authenticator. Once you verify, you will be directed to your VCD Org.
The next time you log in, you will be presented with the following prompt:
Enter your code from the App, and you're all set.
