Configure single sign-on (SSO) for Harbor

The Container Registry (Harbor) managed service supports single sign-on (SSO) through the OIDC and SAML 2.0 protocols. You can connect Harbor to your Identity Provider (IdP) to centralize access management, strengthen security and simplify the user experience.

note

SSO is configured through the Harbor administration interface. The Numspot API does not support direct management of SSO authentication settings.

Prerequisites

note

Before configuring SSO, ensure that:

1. You have system administrator rights on your Harbor instance;
2. You have access to the administration console of your Identity Provider (Keycloak, Azure AD, Okta, etc.);
3. Your Container Registry is in the "RUNNING" state;
4. The network allows HTTPS traffic between Harbor and your IdP;
5. You have retrieved the administrator password (see Retrieve the password).

Choose the protocol type

Protocol	Use case	IdP examples
OIDC	Modern applications, OAuth 2.0 flows, JWT tokens	Keycloak, Azure AD, Okta, Google
SAML 2.0	Legacy integration, identity federation	ADFS, Shibboleth, OneLogin

tip

When in doubt, favor OIDC. It offers better compatibility with Harbor and native group mapping.

Configure an OIDC provider

Step 1: create the application in your IdP

1. Sign in to the administration console of your IdP;
2. Create a new application (or client) named Harbor Registry;
3. Set the client type to Web application or Confidential;
4. Configure the Redirect URI: https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/c/oidc/callback;
5. Enable the following authorization flows:
   • Authorization Code (mandatory)
   • Refresh Token (recommended for proactive sign-out)
6. Note the following credentials:
   • Client ID
   • Client Secret
   • Issuer URL (OpenID discovery URL, usually https://<idp>/.well-known/openid-configuration).

Step 2: configure Harbor for OIDC

1. Sign in to the Harbor interface as an administrator;
2. Go to Administration → Configuration → Authentication;
3. In the Auth Mode list, select OIDC;
4. Fill in the fields:

Field	Description
OIDC Provider Name	Name displayed on the sign-in screen (Keycloak, Azure AD, etc.)
OIDC Endpoint	The Issuer URL (e.g. https://keycloak.example.com/realms/master)
OIDC Client ID	Client identifier generated by the IdP
OIDC Client Secret	Client secret
Group Claim Name	Name of the claim containing the groups (groups, realm_access.roles, etc.)
OIDC Scope	Requested scopes (openid,email,profile,offline_access,groups)
Verify Certificate	Enabled in production

5. Click Test OIDC Server to check connectivity;
6. Click Save to enable OIDC SSO.

Step 3: map groups and roles

To automatically assign Harbor roles to users based on their group membership:

1. In Administration → Configuration → Authentication, set the Group Claim Name;
2. Create the corresponding groups in Harbor: Administration → Groups → + New Group;
3. Associate these groups with the projects with the required role.

info

If the group does not yet exist in Harbor, the SSO user will be able to sign in but will have no access to the projects until you add them to an existing Harbor group.

OIDC sign-in flow

The following describes how a user sign-in proceeds once OIDC SSO is enabled:

1. The user accesses the Harbor interface;
2. They click Sign in with OIDC;
3. Harbor redirects the user to the IdP with an authorization request;
4. The user authenticates with their IdP;
5. The IdP returns an authorization code to Harbor through the callback URL;
6. Harbor exchanges this code for a JWT token with the IdP;
7. Harbor creates or updates the local user account from the token claims;
8. The user is signed in to Harbor with the permissions matching their profile.

Configure a SAML 2.0 provider

Create the application in your IdP

1. Create a SAML application in your IdP;
2. Set the Assertion Consumer Service (ACS) URL: https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/c/saml/acs;
3. Set the Entity ID: https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com;
4. Export the X.509 certificate and the SAML metadata from your IdP.

Configure Harbor for SAML

1. Go to Administration → Configuration → Authentication;
2. Select Auth Mode → SAML;
3. Fill in the fields:

Field	Description
Name	Provider name (ADFS, Shibboleth)
Endpoint	SAML service URL (sign-in URL)
Certificate	Content of the IdP X.509 certificate (PEM format)
Private Key	Your private key to sign requests (optional)
Token Signing Algorithm	Signing algorithm (RSA-SHA256)

4. Download the Harbor SAML metadata to import it into your IdP;
5. Click Save.

Configure UAA or LDAP

Harbor also supports authentication through UAA (Cloud Foundry) and LDAP.

Configure UAA

1. Sign in to the Harbor interface as an administrator;
2. Go to Administration → Configuration → Authentication;
3. Select Auth Mode → UAA;
4. Fill in the fields:

Field	Description
UAA Endpoint	URL of your UAA server (e.g. https://uaa.example.com)
Client ID	UAA client identifier
Client Secret	UAA client secret
Verify Certificate	Enabled in production

5. Click Test UAA Server, then Save.

Configure LDAP

1. In Administration → Configuration → Authentication, select Auth Mode → LDAP;
2. Fill in the connection fields:

Field	Description
LDAP URL	URL of the LDAP server (e.g. ldaps://ldap.example.com:636)
LDAP Base DN	Base Distinguished Name for the search (e.g. dc=example,dc=com)
LDAP Filter	User search filter (e.g. (objectClass=person))
LDAP UID	Attribute identifying the user (uid, sAMAccountName, mail)
LDAP Search DN	DN of the service account for the LDAP search
LDAP Search Password	Service account password
Verify Certificate	Enabled for LDAPS connections

3. Click Test LDAP Server, then Save.

tip

For Active Directory, use sAMAccountName as the LDAP UID and prefix the LDAP Search DN with the DOMAIN\user format.

Associate SSO users with projects

Users signing in through SSO are not automatically members of the projects. You must add them manually or through group mapping.

Through the Harbor interface

1. Go to the project;
2. Click Members;
3. Click + Add Member;
4. For OIDC users, enter the user name or the email;
5. For groups, enter the exact group name;
6. Select the required role (Guest, Developer, Master or Admin);
7. Click OK.

Through the API

curl -X POST "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/projects/{project_id}/members" \
  -u "admin:{password}" \
  -H "Content-Type: application/json" \
  -d '{
    "role_id": 3,
    "member_user": {
      "username": "user@example.com"
    }
  }'

Troubleshooting

Symptom	Probable cause	Resolution
Invalid client or Unauthorized on the sign-in page	Wrong Client ID or Client Secret in Harbor	Check that the credentials match exactly those of the IdP;

If the problem persists, regenerate the secret on the IdP side and update the Harbor configuration. | | Forbidden after sign-in | The user is not a member of any project and no group is mapped | Add the user or their group to the project with the appropriate role. | | Docker login returns a 401 error | The account used is an SSO account with no local password | Use a robot account for Docker CLI operations (push/pull). | | Certificate verify failed during the connection test | Self-signed or unrecognised IdP TLS certificate | Import the certificate authority into the Harbor truststore, or disable Verify Certificate in a test environment only. | | Group claim not found | Incorrect claim name or insufficient scope | Check the Group Claim Name and ensure that the groups scope is included in the OIDC request. | | The user is signed out quickly | The access token has a very short lifetime | Check the token lifetime on the IdP side and enable the Refresh Token if possible. |

warning

Do not disable Verify Certificate in production. This exposes Harbor to man-in-the-middle attacks on the authentication channel.

Security considerations

Privilege segregation

Separate the Harbor system administration groups from the development groups. Map only the required groups and apply the principle of least privilege.

Local backup administrator account

Keep at least one local administrator account active. If the Identity Provider fails, this account allows you to restore access to Harbor without external intervention.

curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/users" \
  -u "admin:{password}" | jq '.[] | select(.username == "admin")'

Secret rotation

Renew the IdP credentials (client secret, SAML certificates) regularly to limit the impact of a leak. Schedule a quarterly rotation at a minimum.

SSO sign-in auditing

Harbor logs authentication events. Monitor sign-ins and failures:

curl -X GET "https://registry-{registryId}.hcp.cloudgouv-eu-west-1.numspot.com/api/v2.0/logs?operation=login" \
  -u "admin:{password}"

Restrict system administration

Limit the number of users with the system administrator role. Favor assignment by group to centralize revocation when someone leaves.

Best practices

Recommendation	Justification
Use OIDC rather than SAML	Better native support and simplified group mapping
Enable group mapping	Centralized permission management through the IdP
Keep a local admin account	Backup access if the Identity Provider is unavailable
Renew secrets regularly	Reduced risk in the event of an IdP credentials leak
Restrict Harbor admin groups	Limit the number of system administrators to the strict minimum