Authentication & RBAC System
Relevant source files
The following files were used as context for generating this wiki page:
The Authentication and Role-Based Access Control (RBAC) system in Harbor provides a secure framework for managing identities and governing access to container registry resources. It supports multiple authentication backends, including local database, LDAP/AD, and OpenID Connect (OIDC), allowing users to authenticate via their preferred identity provider.
At the core of the system is a project-based isolation model. Users are assigned specific roles within projects, which grant permissions for operations such as pulling and pushing artifacts, managing members, or configuring project policies. This ensures that access is restricted according to the principle of least privilege across the entire registry.
Sources: README.md, api/v2.0/swagger.yaml
Authentication Mechanisms
Harbor supports several authentication modes (auth_mode) which can be configured at the system level. These include Local Database, LDAP/AD, and OIDC.
Supported Authentication Modes
| Auth Mode | Description | Key Configuration Items |
|---|---|---|
db_auth | Users are stored and authenticated against the local Harbor database. | self_registration |
ldap_auth | Authentication is delegated to an external LDAP or Active Directory server. | ldap_url, ldap_base_dn, ldap_uid |
oidc_auth | Leverages OpenID Connect for single sign-on (SSO) and identity verification. | oidc_endpoint, oidc_client_id, oidc_scope |
Sources: src/lib/config/metadata/metadatalist.go:94-159, api/v2.0/swagger.yaml:2366-2465
Authentication Configuration Flow
The following diagram illustrates how authentication is processed based on the configured mode.
Role-Based Access Control (RBAC)
RBAC in Harbor is primarily scoped to Projects. Permissions are defined by the role assigned to a user or group within a specific project.
Project Roles and Permissions
Harbor defines five standard project roles. The permissions escalate from Limited Guest to Project Admin.
| Role | Role ID | Typical Permissions |
|---|---|---|
| Project Admin | 1 | Full control: Manage members, policies, and artifacts. |
| Maintainer | 4 | Manage artifacts, tags, and scanners; pull/push images. |
| Developer | 2 | Pull and Push images; view project information. |
| Guest | 3 | Read-only access: Pull images and view logs. |
| Limited Guest | 5 | Pull images only; restricted metadata visibility. |
Sources: api/v2.0/swagger.yaml:2543-2555, tests/testcases/Group3-RBAC/3-11-DB-admin-user-manage-project-members.md:30-50
RBAC Entity Relationship
Harbor allows both individual users and user groups (imported from LDAP/OIDC) to be project members.
System-Level Administration
Beyond project roles, Harbor defines system-level privileges for infrastructure management.
System Administrator
A system administrator (sysadmin_flag) has unrestricted access to all Harbor resources, including:
- Modifying system configurations (
/configurations). - Managing all users and user groups globally.
- Running system-wide tasks like Garbage Collection and "Scan All".
- Viewing audit logs for all projects.
Sources: api/v2.0/swagger.yaml:245-280, src/portal/src/i18n/lang/en-us-lang.json:170-185
Robot Accounts
Robot accounts are special identities used for automation (e.g., CI/CD pipelines). They use secrets instead of passwords and can be scoped to either a project or the entire system.
- Project Robot: Permissions limited to a single project.
- System Robot: Permissions can span multiple projects or system operations.
Sources: api/v2.0/swagger.yaml:1480-1550, src/portal/src/i18n/lang/en-us-lang.json:440-520
User Management and Onboarding
The system handles user lifecycles differently depending on the authentication backend.
Onboarding Flow
- Local DB: Users are created via the
/usersendpoint or self-registration if enabled. - LDAP: Users are authenticated against the LDAP server. Groups can be imported and mapped to project roles before users even log in.
- OIDC: On first login, users are "onboarded." Harbor can automatically create the user account based on OIDC tokens (
oidc_auto_onboard).
CLI Secrets
For OIDC users who cannot use their SSO password for Docker CLI operations, Harbor provides "CLI Secrets." Users can generate and refresh these secrets via their profile to authenticate with the Docker/Helm clients.
Sources: api/v2.0/swagger.yaml:1915-1945, src/portal/src/i18n/lang/en-us-lang.json:115-130
API Endpoints for Auth & RBAC
| Category | Endpoint | Method | Description |
|---|---|---|---|
| User | /users | GET/POST | List or create local users. |
| User | /users/{user_id}/sysadmin | PUT | Toggle system admin status. |
| Member | /projects/{pid}/members | GET/POST | Manage project memberships. |
| Group | /usergroups | GET/POST | Manage user groups for RBAC. |
| LDAP | /ldap/ping | POST | Test LDAP configuration. |
| OIDC | /users/{user_id}/cli_secret | PUT | Set CLI secret for OIDC user. |
Sources: api/v2.0/swagger.yaml:90-1950
Summary
The Authentication & RBAC System provides the multi-tenant security architecture required for an enterprise registry. By combining flexible authentication backends (DB, LDAP, OIDC) with granular project-level roles and system-wide administrative controls, Harbor ensures that both human users and automated systems have appropriate and secure access to OCI artifacts.