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
- 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
- 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 |
- 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)
- 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