Harbor na Prática — Parte 3 Gestão de Usuários, LDAP e Robot Accounts

Nesta parte, vamos configurar a gestão de usuários no Harbor criando usuários locais, integrando com LDAP/Active Directory e criando Robot Accounts com permissões limitadas para pipelines CI/CD.

Modos de autenticação

O Harbor suporta três modos de autenticação. Apenas um pode estar ativo por vez:

Modo	Quando usar
Database	Ambientes simples ou de desenvolvimento. Usuários criados e geridos localmente.
LDAP / Active Directory	Empresas com diretório corporativo. Usuários autenticam com credenciais da empresa.
OIDC	Integração com Keycloak, Azure AD, Okta ou outro provider OpenID Connect.

Para verificar o modo atual:

Administration → Configuration → Authentication

Usuários locais (modo Database)

Criar usuário via Interface Web

Acesse Administration → Users → New User e preencha:

Username — identificador único
Email — endereço de e-mail
First Name / Last Name — nome completo
Password — senha (mínimo 8 caracteres)

Criar usuário via API

curl -X POST "https://harbor.empresa.com/api/v2.0/users" \
  -H "Content-Type: application/json" \
  -u "admin:suasenha" \
  -d '{
    "username": "joao.silva",
    "email": "joao.silva@empresa.com",
    "realname": "João Silva",
    "password": "Senha@2024",
    "comment": "Desenvolvedor backend"
  }'

Listar usuários

curl -s "https://harbor.empresa.com/api/v2.0/users?page_size=100" \
  -u "admin:suasenha" | jq '.[] | {username, email}'

Integração com LDAP / Active Directory

A integração com LDAP centraliza a autenticação — os usuários não precisam de senha separada para o Harbor. Eles usam as credenciais corporativas.

Configuração via Interface Web

Acesse Administration → Configuration → Authentication e altere o modo para LDAP.

Preencha os campos:

Campo	Descrição	Exemplo
LDAP URL	Endereço do servidor LDAP	`ldap://ldap.empresa.com`
LDAP Search DN	DN usado para busca	`cn=harbor,ou=service,dc=empresa,dc=com`
LDAP Search Password	Senha do DN de busca	`senhaservico`
LDAP Base DN	Base de busca de usuários	`ou=users,dc=empresa,dc=com`
LDAP Filter	Filtro opcional	`(objectClass=person)`
LDAP UID	Atributo que identifica o usuário	`uid` (OpenLDAP) ou `sAMAccountName` (AD)
LDAP Scope	Profundidade da busca	`Subtree`

Clique em Test LDAP Server para validar a conexão antes de salvar.

Importar usuários LDAP manualmente

Após configurar o LDAP, você pode importar usuários antes do primeiro login:

Administration → Users → Import Users from LDAP

Pesquise pelo nome do usuário e clique em Import.

Importar via API

# Pesquisar usuário no LDAP
curl -X GET "https://harbor.empresa.com/api/v2.0/ldap/users/search?username=joao" \
  -u "admin:suasenha" | jq '.'

# Importar o usuário encontrado
curl -X POST "https://harbor.empresa.com/api/v2.0/ldap/users/import" \
  -H "Content-Type: application/json" \
  -u "admin:suasenha" \
  -d '{
    "ldap_uid_list": ["joao.silva"]
  }'

Como funciona na prática: Com LDAP configurado, o usuário simplesmente acessa o Harbor com suas credenciais corporativas. No primeiro login, o Harbor cria automaticamente o registro do usuário — sem necessidade de importação manual.

Verificar se um usuário é LDAP ou local

# Via banco de dados (acesso direto ao PostgreSQL do Harbor)
kubectl exec -it -n harbor harbor-database-0 -- \
  psql -U postgres -d registry -c "
    SELECT username, email,
      CASE WHEN password = '' OR password IS NULL THEN 'LDAP' ELSE 'Local' END AS tipo
    FROM registry_user
    WHERE deleted = false
    ORDER BY username;"

Adicionando usuários a projetos

Um usuário importado não tem acesso a nenhum projeto automaticamente. É preciso adicioná-lo explicitamente com um role.

Roles disponíveis

Role	Push	Pull	Delete	Gerenciar membros	Gerenciar projeto
Project Admin	✅	✅	✅	✅	✅
Maintainer	✅	✅	✅	❌	❌
Developer	✅	✅	❌	❌	❌
Guest	❌	✅	❌	❌	❌
Limited Guest	❌	✅*	❌	❌	❌

*Limited Guest só acessa repositórios públicos dentro do projeto.

Adicionar membro via Interface Web

Acesse o projeto → Members → + User → pesquise o usuário e selecione o role.

Adicionar membro via API

curl -X POST "https://harbor.empresa.com/api/v2.0/projects/backend/members" \
  -H "Content-Type: application/json" \
  -u "admin:suasenha" \
  -d '{
    "role_id": 3,
    "member_user": {
      "username": "joao.silva"
    }
  }'

Referência dos role_id:

1 → Project Admin
2 → Developer
3 → Guest
4 → Maintainer

Robot Accounts — tokens para CI/CD

Robot Accounts são credenciais como as Services Account(SA) — não representam uma pessoa, mas sim uma aplicação (pipeline, script, cluster Kubernetes). São a forma correta de autenticar pipelines CI/CD no Harbor.

Criar Robot Account via Interface Web

Existem dois escopos para Robot Accounts:

Sistema (acesso a todos os projetos): Administration → Robot Accounts → New Robot Account

Projeto (acesso a um projeto específico): Projeto → Robot Accounts → New Robot Account

Preencha:

Name — identificador do robot (ex: gitlab-ci, kubernetes-pull)
Expiration — data de expiração do token
Permissions — selecione push e/ou pull

Após criar, copie o token imediatamente — ele não será exibido novamente.

O nome completo do robot terá o prefixo robot$:

robot$backend+gitlab-ci

Criar Robot Account via API

# Robot com permissão apenas de pull em um projeto específico
curl -X POST "https://harbor.empresa.com/api/v2.0/projects/backend/robots" \
  -H "Content-Type: application/json" \
  -u "admin:suasenha" \
  -d '{
    "name": "kubernetes-pull",
    "description": "Pull-only para o cluster Kubernetes de produção",
    "duration": 365,
    "permissions": [
      {
        "kind": "project",
        "namespace": "backend",
        "access": [
          {"resource": "repository", "action": "pull"}
        ]
      }
    ]
  }'

A resposta incluirá o name e o secret (token). Guarde-os em segurança.

Robot Account com permissão de push e pull (para CI/CD)

curl -X POST "https://harbor.empresa.com/api/v2.0/projects/backend/robots" \
  -H "Content-Type: application/json" \
  -u "admin:suasenha" \
  -d '{
    "name": "gitlab-ci",
    "description": "Pipeline GitLab CI — push e pull",
    "duration": 365,
    "permissions": [
      {
        "kind": "project",
        "namespace": "backend",
        "access": [
          {"resource": "repository", "action": "push"},
          {"resource": "repository", "action": "pull"}
        ]
      }
    ]
  }'

Boas práticas

Um Robot Account por sistema — não compartilhe o mesmo token entre GitLab CI e Kubernetes. Se um for comprometido, o outro não é afetado.
Menor privilégio — o Kubernetes só precisa fazer pull. O GitLab CI precisa de push e pull. Nunca dê mais permissões do que o necessário.
Defina expiração — tokens sem expiração são um risco de segurança. Configure rotação periódica.
Nomes descritivos — use nomes que identifiquem claramente o sistema que usa o token: robot$projeto+kubernetes-prod, robot$projeto+gitlab-ci.

Próximo artigo

Na Parte 4, vamos colocar a mão na massa e enviar imagens para o Harbor — configurando o Docker na máquina local, fazendo login, push e pull de imagens, e entendendo a estrutura de tags.

Modos de autenticação​

Usuários locais (modo Database)​

Criar usuário via Interface Web​

Criar usuário via API​

Listar usuários​

Integração com LDAP / Active Directory​

Configuração via Interface Web​

Importar usuários LDAP manualmente​

Importar via API​

Verificar se um usuário é LDAP ou local​

Adicionando usuários a projetos​

Roles disponíveis​

Adicionar membro via Interface Web​

Adicionar membro via API​

Robot Accounts — tokens para CI/CD​

Criar Robot Account via Interface Web​

Criar Robot Account via API​

Robot Account com permissão de push e pull (para CI/CD)​

Boas práticas​

Próximo artigo​