Integrate Service Accounts with Robot Accounts in Container Registry

This guide explains how to integrate STACKIT Service Accounts with Robot Accounts within the STACKIT Container Registry. Linking a Service Account gives you the opportunity to replace legacy, static Robot Account credentials with secure, token-based authentication managed centrally through STACKIT.

Prerequisites

You need an active STACKIT Service Account, to begin integration. If you have not created one yet, follow the official documentation:

• Manage Service Accounts

Step-by-step integration guide

Step 1: Retrieve Service Account details

1. Navigate to the STACKIT Portal and open your target Service Account.

2. Go to the Overview section.

3. Locate and copy the following two fields:

   • ID (e.g., fbb2743f-7fb5-4091-9d36-6e8cabe75347)
   • E-mail (e.g., testcrsa-2c3zt7i8@sa.stackit.cloud)

Step 2: Configure the Robot Account in Container Registry

1. Open the Container Registry application.

2. Navigate to the Robot Accounts section.

3. Open either the Create wizard or the Update/Edit dialog of an existing robot account.

4. Locate the association fields for the STACKIT Service Account. You can use the Edit or Clean buttons to modify this mapping.

5. Provide the details copied in the previous step and click OK:

   • Email: Paste the copied Service Account email.
   • ID: Paste the copied Service Account ID.

Step 3: Define permissions

The permissions assigned to this robot account remain fully governed by the Container Registry application.

• Configure standard Harbor robot account permissions during the final step of the creation/update wizard.
• The linked STACKIT Service Account inherits these exact scopes upon successful authentication.

Critical rules & constraints

Important Mapping Constraints

• 1:1 association limit: You can associate at most one STACKIT Service Account per Robot Account.
• No sharing: A single STACKIT Service Account cannot be associated with more than one Robot Account across the registry.

Authentication workflows

Depending on whether a STACKIT Service Account is linked, the authentication method for the robot account changes dynamically.

No Service Account Associated (Legacy Authentication)

If the Robot Account remains unassociated, authentication falls back to standard legacy credentials provided natively by Harbor:

docker login -u <robot_name> -p <robot_credentials>

Service Account Associated (Token-Based Authentication)

As soon as a STACKIT Service Account is linked to the Robot Account, legacy credentials are permanently discarded for safety.

Note on Authentication Methods:

The STACKIT CLI workflow outlined below is just one of multiple ways to authenticate a service account. Any other method or tool used to authenticate the service account is entirely valid, provided that the credentials sent to the docker login command are always the service account email (as the username) and the retrieved token (as the password).

Examples

Workflow via STACKIT CLI

Activate your service account using your locally saved JSON key file:

stackit auth activate-service-account --service-account-key-path <path_to_your_json_file>

Retrieve the current access token:

stackit auth get-access-token

Log in to the Container Registry via Docker using the Service Account email as the username and the generated token as your password:

docker login <registry server> -u <service_account_email> -p <token>

API Workflow via cURL

You can also use the service account email and retrieved token to authenticate and call the Container Registry API (Harbor API) directly:

  curl -X 'GET' \
  'https://<registry server>/api/v2.0/projects?page=1&page_size=10&with_detail=true' \
  -H 'accept: application/json' \
  -u '<service_account_email>:<token>' | jq