RBAC e controle de acesso (Business+)

No plano Community, qualquer pessoa com o token admin faz tudo. Isso é aceitável para times pequenos, mas escala mal. A partir do plano Business, o cluster ganha um modelo de papéis com granularidade fina.

Este documento explica o modelo, mostra como atribuir papéis, e fecha com práticas que funcionam em produção.

O modelo em quatro conceitos

Um usuário tem um ou mais tokens. Cada token carrega um ou mais papéis. Cada papel é um conjunto de políticas. Cada política autoriza capacidades sobre recursos.

Quando uma chamada chega no cluster, o token é resolvido para o conjunto efetivo de capacidades. Se a operação solicitada está no conjunto, segue. Se não, recebe 403 Forbidden.

Papéis built-in

Para a maioria dos times, os quatro papéis prontos cobrem o necessário:

Liste o que existe:

heroctl acl role list
heroctl acl role describe operator

Políticas customizadas

Quando os papéis built-in não bastam, escreva uma política em YAML:

# arquivo: deployer-prod.yaml
name: deployer-prod
description: "Submete jobs no namespace prod, sem ler segredos"

rules:
  - resource: job
    namespace: "prod"
    capabilities: ["read", "list", "submit", "stop"]

  - resource: namespace
    name: "prod"
    capabilities: ["read"]

  - resource: alloc
    namespace: "prod"
    capabilities: ["read", "logs"]

  - resource: secret
    capabilities: []  # negado explicitamente

Aplique:

heroctl acl policy create -f deployer-prod.yaml

# anexa a política a um papel novo
heroctl acl role create --name deploy-prod --policies deployer-prod

Capacidades comuns:

• read / list — leitura
• submit / update — criação e modificação
• stop / delete — encerramento
• logs — acesso a stdout/stderr de alocações
• exec — abrir shell em alocação rodando

Atenção: exec em produção é uma das capacidades mais perigosas. Trata como acesso de root no contêiner. Restrinja a no máximo dois ou três operadores.

Criando tokens

Token é o que vai na variável HEROCTL_TOKEN ou no header X-Heroctl-Token:

# token de longa duração para operador humano
heroctl acl token create \
  --name "joao-deploy-prod" \
  --policies deploy-prod \
  --ttl 90d

# token curto para CI/CD
heroctl acl token create \
  --name "ci-pipeline" \
  --policies deployer \
  --ttl 1h \
  --bound-cidr 10.20.0.0/16

A saída inclui o secret do token uma única vez. Se você perder, gera outro — não tem recuperação.

Long-lived vs short-lived

Tokens curtos com renovação automática são preferíveis. O custo operacional caiu muito desde que CI/CDs ganharam OIDC nativo.

Revogação

Em qualquer momento:

heroctl acl token list
heroctl acl token revoke <id-do-token>

A revogação é imediata e propaga em segundos para todos os nós. Use isso quando alguém sai do time, quando suspeitar de comprometimento, ou quando rotacionar.

Para revogar todos os tokens de um usuário de uma vez:

heroctl acl token revoke --user joao --all

Audit log

Toda chamada autenticada é registrada. Inclui chamadas que falharam por permissão.

# últimos 7 dias para um usuário específico
heroctl audit log --user joao --since 7d

# todas as falhas de autorização
heroctl audit log --result deny --since 24h

# tudo o que tocou um job específico
heroctl audit log --resource job --name api-pagamentos --since 30d

Cada registro tem: timestamp, identidade, IP de origem, recurso alvo, operação, resultado. Exporte para análise externa em JSON:

heroctl audit log --since 30d --format json

Integração SSO (Business)

Para times maiores, gerenciar tokens à mão não escala. SSO via SAML ou OIDC integra com seu provedor de identidade existente:

sso:
  type: oidc
  issuer: https://idp.empresa.com.br
  client_id: heroctl-prod
  client_secret: ${secret.oidc_client_secret}
  group_to_role:
    "engineering-prod": operator
    "engineering-dev": deployer
    "sre": admin
    "*": viewer

Usuários se autenticam pelo painel web e recebem automaticamente o conjunto de papéis correspondente aos grupos do IdP. Quando saem da empresa, são desprovisionados no IdP, e o acesso ao cluster termina junto.

Para CLI, OIDC device flow:

heroctl auth login
# abre navegador, completa autenticação no IdP, volta para o terminal

Boas práticas

1. Least privilege. Comece negando tudo, abra exatamente o necessário. É mais fácil afrouxar depois do que apertar.
2. Sem token compartilhado. Cada pessoa, cada serviço, cada pipeline tem o seu. Auditoria só funciona se a identidade é única.
3. Rotação trimestral. Tokens de longa duração rodam em ciclos previsíveis. Marca no calendário.
4. Revisão mensal de audit. Trinta minutos por mês olhando o log. Padrões estranhos aparecem se você procura.
5. Quebra-vidro documentado. Tenha um token admin de emergência, com expiração longa, guardado fora de banda (cofre físico, gerente de senhas com 2FA dedicado). Use uma vez por ano, no máximo.
6. Onboarding e offboarding por checklist. Quando alguém entra: criar tokens, atribuir papéis. Quando sai: revogar. Não confie na memória.
7. Tokens de CI sem credenciais externas. Use OIDC do provedor de CI direto contra o cluster, sem secret estático. Reduz superfície de vazamento.

Próximos passos

• Revisar a configuração de segredos, que tem seu próprio modelo de permissão.
• Ver métricas e logs para correlacionar eventos de auditoria com comportamento do cluster.