How authentik signs users into Harbor over OIDC
The supported way to sign users into Harbor with authentik is an OAuth2/OpenID provider in authentik, configured for Harbor's OIDC authentication mode, as described in the authentik integrations catalog. For a platform team, the reason is governance: Harbor holds images and Helm charts that need controlled access, and local database accounts are hard to manage as staff join, change teams or leave. With OIDC, authentik becomes the place where identity is proven, and Harbor accepts the login it receives from authentik instead of maintaining its own password for each person.
The integration covers authentication only. authentik answers the question of who the user is and which groups they belong to, and Harbor uses the OIDC claims to create or match the local user. It does not transfer permissions. Harbor's own project RBAC still decides what each user can push, pull, scan or administer, so group membership in authentik has to be translated into Harbor project roles and system-level settings deliberately. Confirm in the Harbor documentation for your release how group claims are mapped to project roles, and test that a user who is removed from a group loses access in Harbor as expected.
Plan for what the integration does not replace. Automated tools and CI pipelines still need credentials for docker login, and those are handled as CLI secrets rather than interactive SSO sessions. Keep at least one local administrator account documented for recovery if authentik is unavailable, and decide who may use it and how it is audited. Confirm the Harbor version you run against the Harbor GitHub releases before you start, since the OIDC settings and claim handling are the parts most likely to change between releases.
What you need before configuring Harbor SSO
Harbor SSO touches three systems that must agree: the authentik instance issuing tokens, the Harbor instance consuming them, and the group structure that decides who can do what in each project. Confirm each of the items below before you create the OAuth2/OpenID provider, because a mismatch in hostnames or group names is the most common reason sign-in fails silently.
Supported authentik version
Confirm your authentik deployment is on a line the security policy lists as receiving security fixes. The policy currently names 2026.5.x and 2026.8.x. Check the latest release on the GitHub releases page before you start, and plan any upgrade of authentik as a separate change so the OIDC settings are not tested against a moving target. Security releases are announced at least 24 hours in advance, so keep a window for them.
Harbor with administrator access
You need an existing Harbor instance and an account with system administrator rights, since OIDC mode and the authentication settings are changed at the system level. Record the current authentication mode before you change it, and keep the local admin account working so you can recover if the OIDC login fails. Confirm the Harbor version against the current release notes before any upgrade, because release notes can introduce breaking changes.
Stable HTTPS hostnames
Harbor and authentik each need a fixed HTTPS hostname that users and the browser reach directly. The OIDC redirect URI and the Harbor external URL must match exactly, including scheme, port and trailing path. Changing either hostname later means re-registering the client in authentik and updating Harbor's configuration, and docker login clients will point at the Harbor hostname, so pick it once.
Installation prerequisites and Trivy
Check Harbor's installation prerequisites against the hosts you plan to use, including CPU, memory, disk and container runtime requirements. If you intend to scan images, decide at install time whether to use the bundled Trivy through the installer option or an external scanner, because that choice is easier to make before the first deployment than after. Confirm the Trivy version bundled with your Harbor release in its release notes.
Group structure that matches projects
Harbor grants project roles based on what it receives from the identity provider, so design the authentik groups first. Map each Harbor project role to one authentik group, for example a group for developers who push to a given project and another for project administrators. Agree on names with the team that owns Harbor, and confirm that the group claim will be included in the tokens authentik issues for this client.
A tested break-glass path
Before you enforce SSO, confirm who can sign in with the local administrator account and where its password is stored. Test the break-glass login on a non-production Harbor if one exists. Keep the procedure documented alongside the OIDC configuration, so an operator can revert the authentication mode during an authentik outage without guessing.
Configuration sequence for authentik and Harbor
This sequence takes Harbor from database authentication to OIDC sign-in through authentik, with each step checked before the next one starts so that a failure is easy to isolate. The result is a working browser login, a verified group claim, and a Harbor instance that still has a local administrator for recovery.
Confirm the target versions and the integration guide
The platform engineer responsible for both systems confirms the authentik version running in the environment and the Harbor version, then reads the authentik Harbor guide in the integrations catalog before changing anything. Check the supported versions in the authentik security policy and the Harbor release notes for the version in use, because Harbor v2.15.2 and v2.15.3 include changes that affect upgrades and webhooks. Record the Harbor external URL, since it becomes the basis for the redirect URI. The step is done when the team has written down both versions, the external URL, and the guide version they are following.
Create the OAuth2/OpenID provider in authentik
An authentik administrator creates an OAuth2/OpenID provider and an application for Harbor, using the settings the authentik Harbor guide specifies for client type, redirect URI, signing key and scopes. Copy the client ID and client secret into a secure store, and confirm that the scopes include the ones needed to return the group claim Harbor will read. Bind the application to a group or policy so that only the intended users can sign in. The step is done when the provider and application appear in authentik and the client ID is recorded. The provider is the single place where the redirect URI lives, so any later change to the Harbor URL needs to be made here too.
Verify the OIDC discovery endpoint
Before touching Harbor, the administrator checks that the issuer URL for the authentik application resolves from the network segment where Harbor runs, not only from a workstation. Request the OpenID discovery document from the issuer and confirm that it lists the authorization, token and userinfo endpoints. Because Harbor calls authentik from the server side, a failed DNS entry, a certificate the Harbor host does not trust or a blocked egress rule will fail here and look like a login problem later. The step is done when the discovery document returns successfully from the Harbor host and the issuer certificate validates.
Confirm the group claim in authentik
The administrator signs in to authentik as a test user who belongs to a group intended to map to a Harbor project role, then inspects the token or userinfo response the application returns. Confirm that the groups claim lists the expected group names exactly as Harbor will expect them, because Harbor matches on the claim value. If the claim is missing, check the scope mappings on the provider and the group membership before editing Harbor. The step is done when the test user's groups claim contains the group the team plans to map, with spelling and case matching the plan.
Switch Harbor to OIDC with the client settings
A Harbor administrator changes the authentication mode in the Harbor administration interface to OIDC and enters the issuer URL, client ID, client secret, redirect settings and group claim name that match the authentik provider. Keep the local admin account active and keep a session open in the Harbor administration console before saving, so that a misconfiguration does not lock every administrator out. The step is done when Harbor saves the OIDC configuration without error and the login page offers the OIDC sign-in option.
Test a browser login with a test user
A test user who is not a Harbor administrator signs in through the browser from the OIDC option on the Harbor login page. The user is redirected to authentik, authenticates, and returns to Harbor, where an account should be created or linked on first login according to the Harbor settings in use. The administrator then checks the user's profile in Harbor and confirms that the account exists with the expected username and email. The step is done when the test user reaches the Harbor interface and the account appears in the user list. If the redirect fails, check the redirect URI registered in authentik against the Harbor external URL before changing anything else.
Map group claims to project roles and test access
Once browser login works, the administrator maps the verified group claim to Harbor project roles, using the group names confirmed in the earlier step, and then checks that the test user receives the role only in the projects intended. The administrator confirms that a user outside the group cannot pull or push to the protected project. Test the Docker CLI separately, because CLI access uses a CLI secret rather than the browser session, and confirm that a docker login with the CLI secret succeeds for the test user. The step is done when the role assignments match the written plan and both browser and CLI access behave as expected for the test users.
How group claims map to Harbor project roles
The admin group controls system-wide Harbor administration, such as configuring authentication, managing users and changing global settings. Map it to a small, named set of authentik groups, because membership in that group grants the most privileged access in the registry. Harbor compares the group names it receives in the OIDC claim against its own group configuration, so the admin mapping only works if the name in authentik matches the name Harbor expects, character for character.
- Keep the set small: Restrict the admin group to platform operators who already hold administrative rights on the hosting infrastructure.
- Name it explicitly: Use a dedicated group in authentik rather than reusing a broad group such as all engineers.
- Confirm the admin option: Check in the current Harbor documentation how the system administrator group is configured and which claim it reads.
- Keep a local admin: Retain the built-in local administrator account for recovery if the OIDC provider is unavailable.
- Review membership: Audit who belongs to the group in authentik on a set schedule.
Before go-live, confirm the exact claim name and group-handling option in the Harbor documentation for your version, and test an admin login with a non-production user first.
Developers need to push and pull images in the projects they work on. Harbor assigns project roles per project, so the usual pattern is one authentik group per team or application, with that group granted the developer role in the matching Harbor project. Membership changes in authentik then flow to Harbor at the next login, which removes the need to add users to projects by hand. Group names should be stable and descriptive, because renaming a group in authentik can silently break an existing project assignment.
- One group per project: Create groups such as a team name tied to a single Harbor project, not one shared developer group for every project.
- Grant push rights deliberately: Developer rights include pushing images, so limit them to projects whose pipelines need write access.
- Plan for CI pipelines: Pipelines should use dedicated robot or CLI credentials rather than personal SSO sessions.
- Document the mapping: Keep a table of group name, Harbor project and role, and review it when teams change.
- Test with two projects: Confirm that a developer in one team cannot push to another team's project.
Check that the group claim reaches Harbor for developers in your environment, since a missing or mismatched claim leaves the user with no project role.
Guests need read-only access, for example to pull images for a deployment environment or to review scan results without changing content. The guest role is the lowest project role and suits auditors, partner teams and deployment systems that only consume artifacts. Use a separate authentik group for guests so their access is visibly narrower than developer access and can be reviewed on its own. Guest access is often where unintended exposure happens, so review it more often than developer access.
- Separate the group: Keep guest membership in its own authentik group, not as a sub-setting of developer groups.
- Pull only: Use the guest role for consumers that deploy images and do not build them.
- Limit scope: Attach guest access only to the projects a consumer needs, not to every project.
- Expire access: Remove partner or contractor accounts from the group when the engagement ends.
- Check scan visibility: Confirm which vulnerability information guests can see in your Harbor version.
Confirm the role permissions for guests in the current Harbor documentation, since role capabilities can change between releases.
Attributes and roles mapped between authentik and Harbor
This table lists the authentik user attributes and groups claim that Harbor reads during OIDC sign-in, along with the Harbor field or role each one populates. Use it to decide which values must be unique, which mappings you set in authentik and which you set in Harbor, and what to confirm in your own environment before rollout.
| Authentik source | Harbor field or role | Uniqueness and notes | Where it is set |
|---|---|---|---|
| Username claim (preferred username) | Harbor username | Must be unique across the authentik instance; Harbor uses it as the login name, so changing it later can orphan existing Harbor accounts | Claim configured in the authentik OAuth2/OIDC provider and the Harbor OIDC settings |
| Email claim | Harbor email address | Should be unique per user; confirm with your Harbor version whether email is required and how it handles duplicates | Scope and claim mapping in authentik; Harbor reads it on first login |
| Display name claim | Harbor full name shown in the UI | Informational only; does not affect authorization or project membership | Property mapping in authentik; Harbor displays it after sign-in |
| Groups claim | Input for Harbor group-based project roles | Group names must match the names Harbor expects; confirm the claim name and whether group IDs or names are sent in your authentik version | Groups scope and property mapping in authentik; group-to-role mapping in Harbor |
| Group membership (authentik group) | Harbor user group assigned to a project with a role such as admin, maintainer, developer or guest | Each Harbor project role is granted per project or per group; confirm role names against the Harbor release you run | Project membership and group assignment in Harbor; group membership in authentik |
| Admin group membership | Harbor system administrator flag | Grant only to a small, named set of users; keep a local Harbor admin account for recovery if SSO is unavailable | Administrator group setting in Harbor; membership managed in authentik |
| Client ID and client secret (CLI secret) | Used for docker login and CLI access after SSO | Treat as a credential; confirm in the Harbor UI whether the CLI secret is generated per user and how it is rotated | Generated in Harbor for the signed-in user; the OIDC client secret is set in authentik and Harbor |
| Redirect URI | Harbor external URL and OIDC callback | Must match the Harbor external URL exactly, including scheme and port; a mismatch is a common sign-in failure | Redirect URI in the authentik provider; external URL in Harbor configuration |
Using CLI secrets for docker login after SSO
Browser sign-in through authentik does not cover docker login or helm push. Those commands run in a terminal or a pipeline runner, where no browser can complete the OIDC redirect, so Harbor needs a separate credential for them. For OIDC users, Harbor issues a CLI secret that the user enters as the password alongside their username. Decide early which workloads will use personal CLI secrets and which will use robot accounts. Personal secrets suit engineers working from their own workstations. Pipelines should use robot accounts with the narrowest project permissions they need, so that a departing engineer does not break a release job.
Plan rotation and revocation before the first user is onboarded. Disabling a user or changing their group membership in authentik stops browser sign-in and changes the project roles Harbor assigns at the next login, but it does not automatically invalidate a CLI secret that was already issued. Confirm with your Harbor version how a CLI secret is regenerated, whether it can be revoked per user, and whether a disabled OIDC user can still authenticate with one. Set a rotation schedule, and make removing a user part of the offboarding checklist that also covers the CLI secret. The authentik Harbor integration guide explains the OIDC settings, which you should verify against your Harbor release.
Store CLI secrets only in the CI platform's secret store, marked as masked and limited to the jobs that need them, and never in repository files, container images or shared chat. Keep a non-SSO administrator path for recovery. Before you switch the authentication mode, confirm that Harbor's local administrator account still signs in and that its password is held in a sealed store with restricted access. Test the break-glass login in a staging instance, and record each use of that account so that a return to database authentication, or a fix to the authentik provider, can be carried out without guesswork during an outage.
Hardening the Harbor and authentik trust path
Signing in to Harbor through authentik moves the trust boundary to the identity provider, so the links in that chain need to be hardened together. The cards cover transport, secret handling, project creation rights, audit evidence, patch currency and scanning checks that should be verified after the switch.
Enforce HTTPS on both ends
Harbor's external URL and the authentik issuer and redirect URIs should all use HTTPS with certificates your team controls. Mixed schemes are a common cause of failed logins, and a plain-HTTP token exchange exposes authorization codes. Confirm that the redirect URI registered in authentik matches Harbor's external address exactly, including the scheme and port, and that the Harbor CLI and browser both reach the same hostname.
Keep the client secret out of files
The OIDC client secret that Harbor uses to talk to authentik should be stored in a secrets manager or an injected environment variable, not in a values file committed to Git or a shared configuration export. Limit read access to the people who deploy Harbor, rotate the secret when administrators change, and confirm that backups of Harbor's configuration do not leak it in plain text.
Restrict who can create projects
Harbor's project creation setting decides whether any signed-in user can create a project and become its owner. After SSO, a group claim from authentik can grant login, but that does not limit project creation by itself. Review the project creation rule and the group-to-role mappings, and confirm that only the platform team can create top-level projects while application teams receive scoped project roles.
Enable and forward audit logs
Harbor records audit events for user and project actions, which gives the SOC a trail for account changes, pushes and deletions. Confirm which events Harbor logs in your version, decide where those logs are shipped, and set retention to match your review cycle. Test that a sign-in through authentik and a failed sign-in both produce a traceable record that includes the username.
Stay on a supported patch line
Harbor v2.15.4 is the latest stable release, and the 2.14 and 2.13 lines still received patch releases in October 2026. Harbor v2.15.3 fixed a batch of security advisories and added two breaking changes: webhooks to internal network addresses are blocked by default, and signing unsigned images fails in projects that enforce content trust. Review both before upgrading, and test webhook and signing workflows after the change.
Verify scanning after the switch
Trivy scanning is configured separately from authentication, so switching to OIDC does not confirm that scanning still works. Harbor's Trivy setup is enabled at install time with the --with-trivy option or can point to an external Trivy instance. After the switch, push a test image, confirm the scan report appears, and check that the scanner account and any project policies still function under the new identity model.
Switching an existing Harbor from database auth
Start the cutover with a complete backup of the Harbor instance, because switching the authentication mode changes how every user signs in and the release notes for Harbor upgrades recommend a backup before any change of this kind. Confirm the backup can be restored into a separate environment before you touch the live authentication settings. Keep the database and the image storage backup together so that project memberships, robot accounts and image references stay consistent if you need to roll back.
Decide which local accounts move to authentik and which stay on database auth. Keep at least one local administrator on database auth as a recovery path in case the OIDC provider or its group claims fail, and record its credentials in your secrets store with a named owner. Map each existing project membership to an authentik group that matches the role you intend, and confirm how Harbor treats users who sign in through OIDC for the first time before you rely on group claims for project roles. Expect that some local accounts will have no matching group, so list them and decide whether they are removed, disabled or kept as exceptions.
Tell users and CI owners what changes before the switch. Pipelines that use stored Harbor user passwords for docker login will fail once those credentials stop being valid for interactive sign-in, so inventory every pipeline and service account, and move each one to a CLI secret or a robot account. Publish a dated notice with the new sign-in URL, the group-to-role mapping and the name of the person who handles access problems. Run a test login with a pilot group, and keep the rollback plan written down: restore the backup, switch the authentication mode back to database and notify the same audiences.
Common Harbor OIDC failures and how to fix them
This table pairs each common failure when signing Harbor in with authentik over OIDC with its likely cause and fix. Work through the rows in order, starting with the logs on both the authentik and Harbor sides, since most of these failures show a specific message in one of them.
| Failure | Likely cause | Fix |
|---|---|---|
| Redirect URI mismatch after clicking Login via OIDC | The redirect URI registered in the authentik OAuth2/OIDC provider does not match the callback URL Harbor sends, usually because of a different scheme, hostname, port or trailing path. | Copy the callback URL from Harbor's OIDC settings exactly into the provider's redirect URIs in authentik, then retest. Check the authentik logs for the rejected redirect. |
| Login fails with invalid client or unauthorized client | The client secret in Harbor's OIDC configuration was copied incorrectly, rotated in authentik without updating Harbor, or pasted with trailing whitespace. | Regenerate or re-copy the client secret from the authentik provider, paste it into Harbor again and save. Confirm the client ID also matches. |
| User signs in but has no project access or sees no projects | The group claim is missing from the ID token, named differently from what Harbor expects, or the user is not a member of the group that maps to a Harbor role. | Confirm the groups scope and the group claim are included for the provider, check the claim contents for a test user, and match the group name or the Harbor group setting character for character. |
| Login returns an error about the token or time validity | Clock skew between the authentik host, the Harbor host and the browser makes the token look issued in the future or already expired. | Synchronize the server clocks with NTP on every node running authentik and Harbor, then retry. Check time settings on the hosts first, not only inside the applications. |
| Harbor cannot reach authentik or reports a certificate error | Harbor does not trust the certificate chain of the authentik endpoint, often because the certificate is issued by an internal certificate authority that is not in Harbor's trust store. | Add the internal CA certificate to the trust store used by the Harbor components that call authentik, then restart them. Verify the chain with a command-line TLS test from the Harbor host. |
| docker login fails after SSO works in the browser | The CLI secret was not generated or was generated for a different user, the user is not in a permitted group, or the client is using the password instead of the CLI secret. | Have the user generate a CLI secret from their Harbor profile after signing in, then use the username and that secret with docker login. Confirm the account has push or pull rights on the project. |
| Expected users are missing or created with unexpected names | Username or email claims differ from the values Harbor uses, or the user was created earlier by database authentication and now maps to a different account. | Compare the username and email claims in the ID token with the Harbor account settings and align the claim mapping. Review existing local accounts before switching the auth mode. |
| Harbor logs show OIDC errors but authentik shows no failed login | The request never reached the authentik provider, so the fault is in Harbor configuration, network routing, proxy headers or the discovery endpoint URL. | Check the Harbor core logs first, then test the discovery URL from the Harbor host. Verify reverse proxy forwarding headers and that the endpoint URL uses the correct scheme. |
Questions teams ask before connecting Harbor to authentik
Can our own team connect Harbor to authentik without a partner?
Yes, if you have people who administer both authentik and Harbor and can test changes safely. The core steps are to create an OAuth2/OpenID provider in authentik, then point Harbor's OIDC authentication mode at it, which the authentik Harbor guide walks through. The harder parts are group design, role mapping for projects, and keeping a working admin path while you test. Teams without that experience usually find the mapping and rollback planning take the longest, so weigh your own capacity honestly against those tasks.
What makes the effort for a Harbor SSO project grow or shrink?
The main drivers are the number of Harbor projects that need different access, how your authentik groups map to project roles, and how many existing local Harbor accounts must be linked or retired. CI pipelines add work because each robot or build account needs a decision about whether it keeps a CLI secret. Scope also grows if you run replication, proxy cache or vulnerability scanning settings that depend on user identity. Fewer projects, a simple group model and few legacy accounts keep the work small.
What does our team need to provide for the work?
Plan for an authentik administrator, a Harbor administrator and someone who owns the group and role model for your organization. You will also need a test group of users who can try sign-in before everyone is moved, and a change window where existing users can be switched without surprise. Ask the implementation partner to list these roles in the written scope so you can confirm who is available and when.
How long will connecting Harbor to authentik take?
The duration depends on scope, so ask for a written plan rather than a general estimate. A plan should list the authentik provider and application settings, the Harbor OIDC configuration, the group claim mapping, the test cases, the cutover steps and the rollback steps, each with an owner. Confirm whether the plan covers CI pipelines and existing accounts, because those are the items most often underestimated. The timeline should follow from that list.
Does single sign-on replace CLI secrets for docker login?
No. Signing in to the Harbor web interface with authentik does not remove the need for CLI credentials. Automated tools such as docker login, Helm and CI jobs still need a credential that Harbor accepts, which is typically a CLI secret or a robot account created for that purpose. Plan how each pipeline gets its credential, where it is stored and how it is rotated. Confirm the exact sign-in behavior for your Harbor version in its documentation before you change any pipeline.
What does an open-source license mean for the cost of this setup?
Harbor is licensed under Apache-2.0 according to its GitHub repository, and authentik's core code is under the MIT license according to its LICENSE file. Using them does not require a license fee, but the cost of planning, building, testing and running the integration still exists. authentik's enterprise code sits in a separate directory under its own license, and the authentik pricing page lists the enterprise plans. Check whether any feature you need falls under those plans before you assume the open-source edition covers it.
Which Harbor version should we test the SSO setup against?
Test against the exact Harbor version you run in production, and plan any upgrade separately. The Harbor releases page lists the current stable line and patch releases, and some releases change behavior that could affect sign-in or CI workflows. Read the release notes for your target version before the change window. Keep your authentik version within a supported line as listed in its security policy so the identity provider receives fixes too.
How DeployOpen scopes and delivers Harbor SSO with authentik
DeployOpen plans, implements, integrates, documents and supports this authentik and Harbor SSO integration inside your own infrastructure, so the identity provider, the registry and the switch away from database authentication are handled as one controlled change. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing before work starts.
How we scope
- Confirm the Harbor version, deployment method and whether Harbor runs on Docker or Kubernetes in your environment.
- Map which authentik groups should become Harbor project roles, and who approves that mapping before rollout.
- Agree in writing how existing database-authenticated users, admin accounts and CLI access will be handled during the switch.
How we build
- Configure the OAuth2/OpenID provider in authentik for Harbor's OIDC authentication mode, with redirect URIs matched to your Harbor hostname.
- Test group claims against sample accounts so project role assignments match the agreed mapping before any real users sign in.
- Set up CLI secret handling for docker login and rehearse the cutover on a copy of the Harbor instance first.
How we hand over
- Document the authentik provider settings, claim mappings, group-to-role table and the emergency local admin procedure.
- Walk your platform and security teams through sign-in, CLI login and the rollback path, then record the sign-off in writing.
- Provide a backup and upgrade checklist that covers Harbor's release notes, so your team can plan future version changes.
How we support
- Ongoing support, upgrades and continuous testing are available as retainers, scoped separately from the original delivery.
- Retainer work can cover re-checking claim mappings after authentik or Harbor upgrades, subject to the agreed scope.
- Confirm with DeployOpen which support level, response expectations and upgrade windows apply before the engagement starts.
