Secure your Harbor registry using Keycloak as an OpenID Connect (OIDC) identity provider. This guide walks you through configuring Keycloak and Harbor for single sign-on (SSO), and Docker CLI access.
Prerequisites
- Keycloak accessible at:
https://keycloak.maksonlee.com - Harbor instance at:
https://harbor.maksonlee.com - A Keycloak realm (e.g.
maksonlee.com) - HTTPS configured for both services
If you still need to deploy the services, start with installing Keycloak with MariaDB and an NGINX reverse proxy and installing Harbor 2.13.1 on Ubuntu 24.04 with HAProxy and HTTPS.
1. Create a Client in Keycloak
In your Keycloak realm:
- Navigate to Clients → Create client
- Use these general settings:
| Field | Value |
|---|---|
| Client type | OpenID Connect |
| Client ID | harbor |
| Name | harbor |
- Click Next and configure capabilities:
| Capability | Value |
|---|---|
| Client authentication | On |
| Authorization | Off |
| Standard flow | Enabled |
| All others (CIBA, Token Exchange, Device Grant, etc.) | Disabled |
- Login Settings
| Field | Value |
|---|---|
| Root URL | https://harbor.maksonlee.com |
| Valid redirect URIs | https://harbor.maksonlee.com/c/oidc/callback |
| Valid post logout redirect URIs | (optional) |
| Web origins | https://harbor.maksonlee.com |
- Click Save.
After Saving: Get the Client Secret
- Open the
harborclient - Go to the Credentials tab
- Copy the Client Secret — needed in Harbor
2. Configure Harbor for OIDC
In Harbor’s web UI:
- Go to Administration → Configuration → Authentication
- Set the following:
| Field | Value |
|---|---|
| Auth Mode | OIDC |
| Primary Auth Mode | Enable |
| OIDC Provider Name | keycloak |
| OIDC Endpoint | https://keycloak.maksonlee.com/realms/maksonlee.com |
| OIDC Client ID | harbor |
| OIDC Client Secret | (from Keycloak) |
| OIDC Scope | openid,profile,email |
| Username Claim | preferred_username |
| Verify Certificate | Yes |
| Automatic Onboarding | Yes |
| OIDC Session Logout | Optional |
3. Log In via Keycloak
Visit https://harbor.maksonlee.com. The login screen should now show:
Click LOGIN WITH keycloak to sign in.
- Users are redirected to Keycloak for authentication
- First-time users are auto-onboarded (if enabled)
4. Docker CLI Authentication & CLI Secret
Harbor does not allow you to use your Keycloak password or token directly in docker login. Instead, you must manually generate a CLI Secret from the web UI.
How to Get the CLI Secret
- Log in to Harbor via the UI using OIDC
- Click your username (top-right corner) → User Profile
- Go to the Account Settings tab
- Click Generate next to CLI Secret
- Copy the generated secret
Use it in the Docker CLI:
docker login harbor.maksonlee.com
Username: <your OIDC username>
Password: <CLI Secret>The secret is base64-encoded and stored in ~/.docker/config.json after login.
CLI Behavior
| Scenario | Result |
|---|---|
| CLI login with CLI Secret | ✅ Works |
| Harbor restarts or token expires | ❌ Harbor loses OIDC token, CLI login fails |
| CLI Secret still valid | ✅ You do not need to re-generate it |
| Fix | ✅ Re-login via Harbor Web UI to refresh the backend token |
| Best for automation | ❌ Not ideal — use Robot Accounts for CI/CD |
For official instructions on CLI login with OIDC, see:
Harbor OIDC Authentication Docs – Docker CLI Login