vCenter Server Identity Federation with Kanidm

Looks like I will be expanding my collection of identity providers (Authentik, KeyCloak, Synology SSO, Pocket ID and Zitadel) that can be used with vCenter Server and/or VMware Cloud Foundation (VCF) Identity Federation!

Fellow colleague, Eric Gray just made me aware of another self-hosted IdP called Kanidm, which he had success setting up and thought I might be interested.

Kanidm is another basic free IdP that allows users to easily setup to play with vCenter Server and/or VCF Identity Federation, but what makes this IdP unique is that it is completely managed using a CLI, there is no web interface like ones listed above.

Additionally, Kanidm supports both traditional username/password authentication and modern passkeys. If you decide to use traditional passwords, Kanidm does require setting up Time-based One-Time Passwords (TOTP) using something like Google Authenticator and provides another factor of authentication, which is pretty neat!

Step 0 (Optional)  - If you do not have an existing TLS certificate, here is a quick snippet for using OpenSSL to create a self-signed TLS certificate with the following required files:

• key.pem - Private Key
• cert.crt - Certificate
• fullchain.pem - Certificate Chain

openssl req -new -key key.pem -out csr.pem -subj "/C=US/ST=CA/L=Palo Alto/O=WilliamLam/OU=R&D/CN=auth.williamlam.local"
openssl x509 -req -in csr.pem -signkey key.pem -out cert.crt -days 365
cat cert.crt key.pem > fullchain.pem

Step 1 - Install the Kanidm CLI by following this documentation as this is the only way to administer your Kanidm deployment.

Step 2 - Create a server.toml configuration file and replace the values with your environment.

bindaddress = "[::]:443"
db_path = "/data/kanidm.db"
tls_chain = "/data/fullchain.pem"
tls_key = "/data/key.pem"
log_level = "info"
domain = "auth.williamlam.local"
origin = "https://auth.williamlam.local:443"
[online_backup]
path = "/data/kanidm/backups/"
schedule = "00 22 * * *"

Note: The tls_chain and tls_key values represent the path within the Kanidm container, this is not on your local file system and in the next step, you will transfer the files using Docker to the running container, so make sure this path matches up in the next step.

Step 3 - This is an abbreviated set of steps from the Kanidm Evaluation Quickstart guide to getting Kanidm up and running

# Pull Kanidm Server Container
docker pull docker.io/kanidm/server:latest

# Start the Kanidm Container using port 443 and /data volume in container for configuration files
docker create --name kanidmd \
  -p '443:443' \
  -p '636:3636' \
  -v kanidmd:/data \
  docker.io/kanidm/server:latest

# Copy server.toml, TLS private key & full chain certificate files into the container
docker cp server.toml kanidmd:/data/server.toml
docker cp key.pem kanidmd:/data/key.pem
docker cp fullchain.pem kanidmd:/data/fullchain.pem

# Verify the server.toml configuration is good
docker run --rm -i -t -v kanidmd:/data \
kanidm/server:latest /sbin/kanidmd configtest

# Start Kanidm Container
docker start kanidmd

Step 4 - We need to retrieve the auto-generated passwords for the admin and idm_admin account by running the following commands and making a note of the passwords on the screen:

docker exec -i -t kanidmd \
  kanidmd recover-account admin

docker exec -i -t kanidmd \
  kanidmd recover-account idm_admin

Step 5 - Create the the Kanidm client configuration which should be stored in ~/.config/kanidm and replace the uri with the origin value stored in server.toml configuration file as shown below:

uri = "https://auth.williamlam.local:443"
verify_ca = false

To confirm that we can access our Kanidm deployment, we will login using the idm_admin account and provide the password from the previous step.

kanidm login --name idm_admin

Step 6 - Now we are going to create a new user (e.g. lamw) and a group (e.g. vcf-admins) where the user will be placed within that group by running the following commands:

kanidm person create lamw "William Lam" --name idm_admin
kanidm group create vcf-admins --name idm_admin
kanidm group add-members vcf-admins lamw --name idm_admin

We also need to retrieve the UUID for each user that we created as this will be required to make vCenter Server's Identity Broker (vIDB) aware of our user for vSphere Permission assignment.

kanidm person get lamw --name idm_admin

Lastly, we need to setup the credentials for our user which is done by running the following command:

kanidm person credential create-reset-token lamw --name idm_admin

This will generate a QR Code and URL which is intended for your end users to visit and setup their desired credentials.

When users open the link using a browser, they will have choice of using modern passkeys (e.g. YubiKey or Face ID) or old school passwords, which also requires setting up TOTP as mentioned earlier.

Step 7 - Login to your vCenter Server and navigate to Administration->Single Sign On->Configuration->Identity Provider and select the PingFederate option and populate the directory name and DNS domain.

Copy the vCenter Server Redirect URI and then head back to your Kanidm server to retrieve the rest of the required configurations.

Step 8 - We will now create our Kanidm OIDC application, which we will name "vcenter" and using the vSphere UI as our landing page URL along with the redirect URL from Step 7. In addition, we also need to scope the users from our "vcf-admins" group to access the application.

kanidm system oauth2 create vcenter "vCenter Server" "https://vc03.williamlam.local/ui" --name idm_admin
kanidm system oauth2 add-redirect-url vcenter https://vc03.williamlam.local/federation/t/CUSTOMER/auth/response/oauth2 --name idm_admin
kanidm system oauth2 update-scope-map vcenter vcf-admins email openid groups profile --name idm_admin
kanidm system oauth2 warning-insecure-client-disable-pkce vcenter --name idm_admin

Note: Disabling PKCE may not be necessary but I did not get a chance to test as I had ran into some deployment issues earlier and was recommended to try disabling that as well.

After creating our OIDC application, we also need to retrieve the client secret, which we can retrieve by running the following command:

kanidm system oauth2 show-basic-secret vcenter --name idm_admin

Step 9 - Navigate back to your vCenter Server to complete the configuration and populate all fields as shown in the screenshot below along with full certificate chain.

Note: The OpenID Address will be https://<KANIDM-FQDN>/oauth2/openid/<OUATH-CLIENT-NAME>/.well-known/openid-configuration (e.g. https://auth.williamlam.local/oauth2/openid/vcenter/.well-known/openid-configuration)

Step 10 - We now need to publish the Kanidm users into vIDB and to simplify this process, I have created a shell script that needs to be run directly within the VCSA that accepts a CSV file that contains the list of users and their configurations.

Using the information from Step 6, create a CSV file that contains list of users in the following format:

# Username, First Name, Last Name, Email, External Id
lamw, William, Lam, lamw[at]williamlam.local, 9c98c56f-4cc3-4371-9755-c6274e0110b7

Note: Any entries with a "#" will be ignored by the script, so you can easily comment out entries that you do not wish to publish to vIDB.

Next, download the manual-scim-sync-users.sh script and the user CSV file to your VCSA and run the script with the following three arguments: vSphere admin username, password and the name of your CSV text file as shown in the screenshot below.

./manual-scim-sync-users.sh 'administrator[at]vsphere.local' 'VMware1!' external_users.txt

Step 11 - Login to your vCenter Server with your vSphere SSO account and you should now be able to lookup users from Kanidm and assign vSphere Permissions. Once you have assigned the desired vSphere Permission, you can open an incognito window and after authenticating with Kanidm and successfully log into vCenter Server!

If you need to remove users from vIDB, you can download the manual-scim-remove-users.sh script that can help with automating that process. Create a simliar CSV file with the list of users that you wish to un-publish and then run the script with the following three arguments: vSphere admin username, password and the name of your CSV text file as shown in the screenshot below.

./manual-scim-remove-users.sh 'administrator[at]vsphere.local' 'VMware1!' external_users.txt

Step 12 - Finally, login to your vCenter Server using the SSO option and we should be redirected Kanidm and you will provide the username that has been configured and select the method of authentication

If you are using classic passwords, you will first be prompted to enter your TOTP code and then the configured password before being allowed to login.

If you are using modern passkeys, you can authenticate with a variety of options, below is an example of using YubiKey to login.