Harbor Registry with Keycloak OIDC

Yuwei Sung
5 min readMay 27, 2023


Photo by Nik on Unsplash

In this tutorial, I demo how to install and setup key cloak, then use Harbor Registry with OIDC authentication.

Keycloak is a single sign on solution that supports OAuth2, OpenID Connect (OIDC), and SAML. It is one of key components in cloud native platform. Before installing Keycloak in k8s, you need to setup a database and TLS certificate. Here is my ansible-playbook and manifest. Use ‘ansible-playbook’ to deploy it.

From the above, you can see that I update my playbook with ansible k8s and helm modules.

In above manifest, I add a “pre-defined” realm json file as ConfigMap and use the postgresql db as the backend database. I use MetalLB as a layer2 load balancer and expose one of my home lab LAN IP and DNS.

Click on “Administration Console” and you should be redirected to admin console. As the manifest showed, the login is admin/admin.

Switch to the “pre-created” realm, sn-lab, so we can start to setup client, user and roles. You can also create new Realm from the realm drop down box.

In the bottom-left, under Configure, Click “realm settings” and you should see the realm OIDC Endpoints. The OpenID endpoint will bring you to the “well-known openid configuration”.

The endpoint contains all information you need to setup client application. In keycloak, the target application (harbor in this example) is called a “client”.

Before continuing the client application setting, I deploy the harbor registry. Here is the ansible playbook and manifests. Use “ansible-playbook” to deploy the manifest.

The harbor service is also exposed as a load balancer in my home lab. The TLS certificate looks like this.

After the deployment, you can access the harbor portal with the default username and password (admin/Harbor12345). You can change it in the helm chart values.yaml.

Once you have the access, note down the harbor URL (my example: https://harbor.home.lab). We can go back to Keycloak and setup the client application (harbor).
In sn-lab realm, click “Clients” on the left panel and click “Create client”. Use the default “Client type”, OpenID Connect. Set the Client ID to “harbor”, give a Name “my homelab harbor”, then click Next.

In Capability config, turn ON “Client authentication”, check “Service accounts roles”, then click “Next”.

In Login settings, give the harbor service URL(https://harbor.home.lab) in Root URL and Home URL, give the same service URLwith a wide card in Valid redirect URIs, then click “Save”.

Once the client saved, you can see the harbor client details. Go to “Credentials” tab, make sure the “Client Authenticator” set to “Client Id and Secret”, then “copy” the “Client secret” to your notebook. We will need the secret in harbor authentication configuration.

On the left panel, click on “Users” and pick “Add user” to add our first single sign on user. The Required user actions are optional.

After the test1 user is created, go to “Credentials” tab in the test1 user page and click “Set password”. You will need to type the password twice and keep “Temporary” ON.
Now we have the client application and a single sign on user created. Go back to harbor web UI to setup the authentication.
Login harbor as admin user and go to “Administration”, “Configuration”, click “Authentication”, then fill in the information as showing below. Make sure that 1) OIDC endpoint (https://kc.home.lab:8443/realms/sn-lab), 2) OIDC Client ID (harbor) and OIDC Client Secret are correct. In OIDC Scope, put “openid,profile,roles”.
If everything is good, click “TEST OIDC SERVER” and you should get a green bar showing it is success.

Now, log out the admin from the top-right and this should bring you back to the harbor login. You should see the new login option (LOGIN VIA OIDC PROVIDER).

Now click on “LOGIN VIA OIDC PROVIDER” and you should see the login page. Type the single sign on username and password you just set in Keycloak.

Since I added a “Update Password” action when creating the user in Keycloak, the login page will ask you to update the password. After update the password and login with new password, you are in.

This is part 1. Next part, let’s go back to Keycloak to setup different roles.



Yuwei Sung

A data nerd started from data center field engineer to cloud database reliability engineer.