rutgerblom.com

I’ve been spending some more time with VCF Automation 9.1 in the lab lately.

One thing I wanted to test was organization-level OIDC authentication. Not global VCF SSO this time, but OIDC directly for a VCF Automation organization.

Since I already have Keycloak running as part of my Provider Box project, it made sense to use that as the identity provider.

Provider Box is my small bootstrap stack for VCF labs. It provides DNS, NTP, PKI, identity, IPAM, object storage and SFTP from a single node. The goal is not to build a full enterprise platform around the lab, but to have enough supporting services to make the environment feel complete and repeatable.

This post walks through what finally worked for me when using Keycloak as an OIDC identity provider for a VCF Automation organization.

Lab setup

The lab setup is pretty simple:

• VCF Automation: 9.1
• VCF Automation organization: tenant-blue
• VCF Automation URL: https://pod-240-auto.sddc.lab

• Keycloak URL: https://auth.sddc.lab:8443
• Keycloak realm: provider-box
• Keycloak client: vcfa-tenant-blue
• Keycloak user: tenant-admin
• Keycloak group: vcf-tenant-blue-admins

• OIDC group claim: groups
• VCF Automation imported group: vcf-tenant-blue-admins

The goal was simple: authenticate the user with Keycloak and authorize access in VCF Automation based on group membership.

Keycloak realm

The first thing I needed was a Keycloak realm to represent the identity provider used by the VCF Automation organization.

In my lab I used the realm:

provider-box

The realm was created by the Provider Box setup and is exposed through the Keycloak instance at:

https://auth.sddc.lab:8443

The realm-specific OIDC well-known endpoint is therefore:

https://auth.sddc.lab:8443/realms/provider-box/.well-known/openid-configuration

This endpoint is important later because VCF Automation can use it for autodiscovery. Instead of manually entering all OIDC endpoint URLs, I can point VCF Automation to the well-known configuration endpoint and let it populate the authorization endpoint, token endpoint, issuer and logout endpoint automatically.

Nothing special was required in the realm itself for this setup. The important configuration was done on the Keycloak client, the user/group objects and the client scopes.

Keycloak client

Next I created an OpenID Connect client in Keycloak for the VCF Automation organization.

In my lab the client was called:

vcfa-tenant-blue

I enabled Client authentication, since VCF Automation authenticates to Keycloak using the client ID and client secret. I also kept Standard flow enabled, since VCF Automation uses the browser-based authorization code flow.

Redirect URI

The redirect URI comes from the VCF Automation organization OIDC configuration screen under:

Administer → Connections → Identity Providers → OIDC

Here VCF Automation shows the Client Configuration Redirect URI. In my lab this was:

https://pod-240-auto.sddc.lab/login/oauth?service=tenant:tenant-blue

I added this value to the Keycloak client under Valid redirect URIs.

So the flow is slightly circular:

1. Open the VCFA organization OIDC page.
2. Copy the Client Configuration Redirect URI.
3. Add it to the Keycloak client.
4. Finish the Keycloak client configuration.
5. Return to VCFA and complete the OIDC setup.

This is easy to miss because most of the IdP-side configuration is done in Keycloak, but the correct redirect URI is generated by VCF Automation for the specific organization.

Keycloak user and group

For the lab I created a dedicated Keycloak user for the VCF Automation organization.

The user was:

tenant-admin

In Keycloak, the only strictly required attribute when creating the user is the username. However, I recommend adding email, first name and last name immediately. Otherwise Keycloak may ask the user to update the account information during the first login.

In my lab the user had:

• Username: tenant-admin
• Email: tenant-admin@sddc.lab
• Email verified: On
• First name: Tenant
• Last name: Admin

I also set a password for the user and set Temporary to Off. That means the user is not forced to change the password at first login.

I then created a Keycloak group for the VCF Automation organization administrators:

vcf-tenant-blue-admins

The tenant-admin user was added as a member of that group.

This group becomes important later when VCF Automation maps the authenticated user to an organization role.

In my lab the intended mapping was:

vcf-tenant-blue-admins → Organization Administrator

So the model is:

Keycloak user → Keycloak group → VCF Automation organization role

Keycloak group mapper

The next part was one of the things that made the difference in my setup.

VCF Automation needs group information from the identity provider so it can map the authenticated user to an organization role. In Keycloak, I exposed that information by adding a group membership mapper to the client’s dedicated scope.

I opened it from the client configuration:

Clients → vcfa-tenant-blue → Client scopes → vcfa-tenant-blue-dedicated

From there, I selected:

Configure a new mapper

The mapper type was:

Group Membership

I named the mapper:

groups

The mapper name is mostly for readability in Keycloak, but I used groups to match what the mapper is doing.

The important setting is the token claim name. I set that to:

groups

This is the claim name that VCF Automation later uses in the claims mapping:

Groups → groups

I also changed Full group path to Off.

This is important. With full group path enabled, Keycloak returned the group as:

/vcf-tenant-blue-admins

With full group path disabled, Keycloak returned the cleaner group name:

vcf-tenant-blue-admins

That is the value I wanted to use later when importing the group in VCF Automation.

For my test user, the relevant Keycloak group was:

vcf-tenant-blue-admins

This group is returned in the OIDC groups claim and is later mapped to an organization role in VCF Automation.

In my lab the intended mapping was:

vcf-tenant-blue-admins → Organization Administrator

VCF Automation OIDC general settings

With the Keycloak side prepared, I moved back to the VCF Automation organization.

The OIDC configuration is done inside the tenant organization. In my lab that organization was:

tenant-blue

In VCF Automation I went to:

Administer → Connections → Identity Providers → OIDC

From there I selected:

Configure

In the first step of the wizard, I configured the general OIDC settings.

The client ID must match the Keycloak client created earlier.

The client secret comes from the Keycloak client credentials.

I enabled configuration discovery so VCF Automation could read the OIDC metadata directly from Keycloak.

After entering the well-known endpoint, VCF Automation automatically populated the authorization endpoint, token endpoint, issuer ID and logout endpoint in the next step.

VCF Automation OIDC endpoints

The second step in the wizard did not require any input in my setup.

Because configuration discovery was enabled in the previous step, VCF Automation automatically populated the endpoint values from the Keycloak well-known configuration endpoint.

In my lab the discovered values were:

I did not change these values manually.

VCF Automation OIDC scopes

The third step in the wizard defines the scopes requested by VCF Automation during login.

I kept the standard OIDC scopes:

openid
email
profile

These scopes are enough for the basic OIDC login and user profile information.

The group information used for authorization was added on the Keycloak side by configuring a group membership mapper on the client’s dedicated scope. I did not need to add a separate groups scope in this step.

VCF Automation OIDC claims mapping

The next step is claims mapping.

Most of the mappings were populated automatically after VCF Automation read the Keycloak well-known configuration.

I left the standard user mappings unchanged, but added one important mapping manually:

Groups → groups

This was easy to miss. Keycloak authentication worked, and Keycloak showed successful LOGIN and CODE_TO_TOKEN events, but VCF Automation still rejected the login.

The reason was that VCF Automation did not know which claim to use for group membership. After adding the Groups → groups mapping, VCF Automation could use the group returned by Keycloak and match it to the imported organization group.

The final claims mapping was:

VCF Automation populated Name in Source with sub. I left that value unchanged, since the login and group-based authorization worked with this mapping.

VCF Automation OIDC key configuration

The key configuration was also populated automatically from the Keycloak discovery information.

Since the well-known configuration endpoint includes the Keycloak JWKS endpoint, VCF Automation was able to discover the signing keys without me uploading a PEM file manually.

In the wizard, the discovered keys appeared automatically in the key list.

I left Automatic Key Refresh disabled in this setup, since the required keys were already discovered during configuration.

The important part is that VCF Automation can validate the tokens signed by Keycloak. With configuration discovery enabled, this was handled automatically in my lab.

VCF Automation OIDC button label

The last step in the wizard controls the label shown on the VCF Automation login screen.

The default label is:

Log in with OIDC

I changed it to:

Log in with Provider Box

This is optional, but it makes the login screen a bit clearer in the lab since Provider Box is where Keycloak is running.

VCF Automation group-to-role mapping

After the OIDC provider was configured, the next step was to give the external group access inside the VCF Automation organization.

The Keycloak user was a member of this group:

vcf-tenant-blue-admins

That group is returned by Keycloak in the OIDC groups claim.

In VCF Automation I went to:

Administer → Access Control → Groups

From there I selected:

Import Groups

I imported the OIDC group:

vcf-tenant-blue-admins

and assigned it the role:

Organization Administrator

So the final authorization model became:

Keycloak user → Keycloak group → OIDC groups claim → imported VCF Automation group → organization role

In this lab:

tenant-admin → vcf-tenant-blue-admins → Organization Administrator

This is the part that controls what the user can actually do after login. The OIDC configuration handles authentication, but the imported group and role assignment handle authorization inside the VCF Automation organization.

Testing the login

After the OIDC provider and group mapping were in place, I tested the login from the VCF Automation organization login page.

Clicking the login button redirected me to Keycloak, where I logged in as:

tenant-admin

After successful authentication, Keycloak redirected the browser back to VCF Automation.

At this point there are two things that need to work.

First, the OIDC flow itself needs to complete. In Keycloak, I could see successful events for the login and token exchange:

LOGIN
CODE_TO_TOKEN

Second, VCF Automation needs to authorize the user inside the organization. That part depends on the group claim and the imported group mapping.

In my setup, the user was a member of this Keycloak group:

vcf-tenant-blue-admins

That group was returned in the OIDC groups claim, imported into VCF Automation, and mapped to the Organization Administrator role.

Once both parts were in place, the user could log in to the VCF Automation organization successfully.

Closing thoughts

After this, the setup worked as expected.

Keycloak handled the authentication, VCF Automation consumed the OIDC claims, and access inside the organization was controlled through the imported group and role assignment.

The two things that mattered most were the group mapper in Keycloak and the claims mapping in VCF Automation.

On the Keycloak side, the group membership mapper needed to return a clean groups claim:

vcf-tenant-blue-admins

On the VCF Automation side, I had to add the mapping:

Groups → groups

Without that mapping, the OIDC login and token exchange still succeeded, but VCF Automation could not use the Keycloak group membership for authorization.

This is also a good example of why I like having Provider Box in the lab. It gives me a small and repeatable identity provider close to the rest of the VCF supporting services, without having to depend on an external IdP just to test organization-level authentication.

Not a complex setup in the end, but there were a few details that were easy to miss.