RBAC y control de acceso (Business+)

En el plan Community, cualquier persona con el token admin hace todo. Eso es aceptable para equipos pequeños, pero escala mal. A partir del plan Business, el cluster gana un modelo de roles con granularidad fina.

Este documento explica el modelo, muestra cómo asignar roles, y cierra con prácticas que funcionan en producción.

El modelo en cuatro conceptos

Un usuario tiene uno o más tokens. Cada token lleva uno o más roles. Cada rol es un conjunto de políticas. Cada política autoriza capacidades sobre recursos.

Cuando una llamada llega al cluster, el token se resuelve al conjunto efectivo de capacidades. Si la operación solicitada está en el conjunto, sigue. Si no, recibe 403 Forbidden.

Roles built-in

Para la mayoría de los equipos, los cuatro roles ya listos cubren lo necesario:

Lista lo que existe:

heroctl acl role list
heroctl acl role describe operator

Políticas customizadas

Cuando los roles built-in no bastan, escribe una política en 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

Aplica:

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 comunes:

• read / list — lectura
• submit / update — creación y modificación
• stop / delete — finalización
• logs — acceso a stdout/stderr de asignaciones
• exec — abrir shell en asignación corriendo

Atención: exec en producción es una de las capacidades más peligrosas. Trátala como acceso de root en el contenedor. Restringe a no más de dos o tres operadores.

Creando tokens

El token es lo que va en la variable HEROCTL_TOKEN o en el 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

La salida incluye el secret del token una sola vez. Si lo pierdes, generas otro — no hay recuperación.

Long-lived vs short-lived

Tokens cortos con renovación automática son preferibles. El costo operativo cayó mucho desde que los CI/CD ganaron OIDC nativo.

Revocación

En cualquier momento:

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

La revocación es inmediata y propaga en segundos a todos los nodos. Usa esto cuando alguien sale del equipo, cuando sospeches de compromiso, o cuando rotes.

Para revocar todos los tokens de un usuario de una vez:

heroctl acl token revoke --user joao --all

Audit log

Toda llamada autenticada queda registrada. Incluye llamadas que fallaron por permiso.

# ú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 tiene: timestamp, identidad, IP de origen, recurso objetivo, operación, resultado. Exporta para análisis externo en JSON:

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

Integración SSO (Business)

Para equipos más grandes, gestionar tokens a mano no escala. SSO vía SAML u OIDC integra con tu proveedor de identidad 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

Los usuarios se autentican por el panel web y reciben automáticamente el conjunto de roles correspondiente a los grupos del IdP. Cuando salen de la empresa, son desprovisionados en el IdP, y el acceso al cluster termina junto.

Para CLI, OIDC device flow:

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

Buenas prácticas

1. Least privilege. Empieza negando todo, abre exactamente lo necesario. Es más fácil aflojar después que apretar.
2. Sin token compartido. Cada persona, cada servicio, cada pipeline tiene el suyo. La auditoría solo funciona si la identidad es única.
3. Rotación trimestral. Los tokens de larga duración rotan en ciclos previsibles. Marca en el calendario.
4. Revisión mensual del audit. Treinta minutos por mes mirando el log. Patrones extraños aparecen si se buscan.
5. Break-glass documentado. Ten un token admin de emergencia, con expiración larga, guardado fuera de banda (cofre físico, gestor de contraseñas con 2FA dedicado). Úsalo una vez al año, máximo.
6. Onboarding y offboarding por checklist. Cuando alguien entra: crear tokens, asignar roles. Cuando sale: revocar. No confíes en la memoria.
7. Tokens de CI sin credenciales externas. Usa OIDC del proveedor de CI directo contra el cluster, sin secret estático. Reduce la superficie de fuga.

Próximos pasos

• Revisar la configuración de secretos, que tiene su propio modelo de permisos.
• Ver métricas y logs para correlacionar eventos de auditoría con comportamiento del cluster.