vCloud Director 2FA with Google Authenticator


VMware vCloud Director (since 10.1 version Cloud Director) delivers whole stack to set up and deliver infrastructure as a service to end user. It has a bunch of some cool features, especially in network aspects delivered by NSX, as well as support for buzz word of the last time - Kubernetes, but there is one missing functionality when it comes about more secure access to tenant portal. Well, maybe not missing, but not provided out of the box - I mean 2FA. I will show you how to set up this with SAML Identity Provider, in this case - Keycloak and Google Authenticator . Let’s dig around of it!

All tenant System Administrators defined in vCloud Director has a possibility to configure SAML provider, to authenticate and authorize access to tenant portal in vCloud Director in external Identity Provider. To set this up, first we need to configure Identity Provider in our case Keycloak - Open Source Identity and Access Management. For production purposes, you probably want to take care more about SSL certificates and high arability of Keycloak, but for our demonstration we skip this aspects.

1 Setup Keycloak

For our needs we run Keycloak as docker container, so let’s run:

docker run -p 8080:8080 -e KEYCLOAK_USER=admin -e KEYCLOAK_PASSWORD=admin

when logs shows line as below, Keycloak is ready to use:

07:37:29,398 INFO [] (Controller Boot Thread) WFLYSRV0025: Keycloak 10.0.1 (WildFly Core 11.1.1.Final) started in 67444ms - Started 689 of 994 services (708 services are lazy, passive or on-demand)

Now we can log in to admin Keycloack console, which is accessible with this url:


In our case, user and admin password is admin, as we passed to container as environmental variables: KEYCLOAK_USER and KEYCLOAK_PASSWORD above.

Keycloak Login Page

After logging in, first we need to create new Realm for our vCloud Tenant, set up name for your realm.

Create Realm

Let’s now create first test user:

Create User

Do not forget, to set up password for user, if you don’t want to change password next login, disable Temporary flag:

Set Password

Now it is time to set up client for our new Realm, what is cool, we don’t have to configure whole this manually, we can preconfigure it via import file from vcloud tenant SAML metadata. To get this file, log in to vCloud Director tenant portal as Organization Administrator. First of all, you need to set up Entity ID by edit saml config - save it, it is super important it MUST match with Client ID in Keycloak.

After that click on the link, and download metadata, it will be .xml file which we use in Keycloak to preconfigure Realm Client:

vCloud SAML Metadata

If we have .xml file from tenant portal, let’s back to Keycloak, and import it to Realm Client.


Client ID MUST match with Entity ID in tenant portal SAML configuration or it won’t work.

Set Client Protocol as SAML:

Create Realm Client


If you want to log in to vcloud via username, not by whole email, change in Settings tab: Name Id Format to username:

Name Id Format

When an external user attempts to log in, vCloud extract some attributes from SAML token, if available, and use them for describe user:

email address = "EmailAddress" - important, if email is not correct remove user from vCloud wont be possible (I think it is bug)
user name = "UserName" - important it is login name for our user in vCloud
full name = "FullName" - not so important as email, but usefull
user's groups = "Groups"- important if you want to authentication based on group membership
user's roles = "Roles" - important if you want to manage roles via Keycloak, we skip this it is not part of this blog post

If Keycloak should pass some attributes within SAML token to vCloud we must define Mappers for our client, we defined earlier. Go to client configuration, select Mappers tab and define them:

Define Mappers

Configure it, as follow:

Email Mapper

FullName Mapper

Groups Mapper

Username Mapper

Before we test if our setup works, let’s create some group, for example orgAdmin:

Create Group

and add user to that group:

Add to Group

Finally it is time to test it in vcloud, copy SAML Identity Provider Metadata from Keycloak, we use it to finish setup form vCloud side:

Keycloak SAML Metadata

Let’s log in now as local tenant admin to vCloud tenant portal, go to Administration, and edit SAML configuration. Activate SAML provider, and paste metadata you copied before:

Import Metadata

Last thing before we log out local admin from the console, go to Group, click Import Groups and add our orgAdmin group we created before in Keycloak, assign Organization Administrator role.


Keep in mind, that vCloud does not check if this group exists in Keycloak during “import”, so watch out any typo in the name.

Import Group

Log out from console it is time to test our work. After you activated SAML in vcloud, when you enter tenant portal url in web browser:


you should be now redirected to Keycloak login page:

Tenant Login Page

Enter logn and passord you user, and voalá, we are in:

Logged In

2 Setup 2FA

For now we successfully set up SAML based group authentication between vCloud Director Tenant Portal and Keycloak SAML Identity Provider. One step left to complete goal of this blog post. Thankfully all dirty job was done so far, only some simple tuning left.

2FA in Keycloak is preconfigured, it is based on OTP and supported by Google Authenticator or FreeOTP, in our case we will be using Google Authenticator android app, download it on your mobile device to complete this step.

To set up 2FA in Keycloak, we simply need to activate it as Required Action on Realm, simply by activate checkbox Default Action:

Force 2FA

This action activated 2FA ONLY for new created user, if we have user already exist, we must force Required User Action for that users:

User 2FA

Save it and log out from vCloud Tenant portal. Next time user log in, Keycloak ask to set up 2FA device in our case Google Authenticator App, follow instruction on screen:

2FA Setup

From this time, each time user log in to vCloud, he will be prompted to enter one time token, generated by Google Authenticator App;

Enter Token

3 Conclusion

Finally we reached out to the end of this blog post, we have working configuration of 2FA in vCloud Director, provided by SAML integration with Keycloak. As I mentioned before, if you plan to deploy this configuration in production environment, take more attention on certificates and high avabality of Keycloak. If you have any question, or suggesstions feel free to leave comment below.