1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

export PROJECT_ID=my-project
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
export GITHUB_ORG=my-org
export REPO=my-org/my-repo

gcloud iam workload-identity-pools create github \
  --project=$PROJECT_ID --location=global --display-name="GitHub Actions"

gcloud iam workload-identity-pools providers create-oidc github-oidc \
  --project=$PROJECT_ID --location=global --workload-identity-pool=github \
  --display-name="GitHub OIDC" \
  --issuer-uri="https://token.actions.githubusercontent.com" \
  --attribute-mapping="google.subject=assertion.sub,attribute.actor=assertion.actor,attribute.repository=assertion.repository,attribute.repository_owner=assertion.repository_owner" \
  --attribute-condition="assertion.repository_owner == '$GITHUB_ORG'"

gcloud iam service-accounts create github-actions --project=$PROJECT_ID --display-name="GitHub Actions"
gcloud iam service-accounts add-iam-policy-binding github-actions@$PROJECT_ID.iam.gserviceaccount.com \
  --project=$PROJECT_ID --role=roles/iam.workloadIdentityUser \
  --member="principalSet://iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/github/attribute.repository/$REPO"

Y en el workflow:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write            # sin esto GitHub no emite el token OIDC
    steps:
      - uses: actions/checkout@v4
      - id: auth
        uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: projects/123456789012/locations/global/workloadIdentityPools/github/providers/github-oidc
          service_account: github-actions@my-project.iam.gserviceaccount.com
      - uses: google-github-actions/setup-gcloud@v3
      - run: gcloud storage ls

Los roles que necesite el pipeline (Artifact Registry, Cloud Run, GKE…) se los das a github-actions@… como a cualquier service account.

Por qué

La alternativa clásica es exportar una llave JSON del service account y guardarla como secreto en GitHub. Esa llave no caduca, cualquiera con acceso al repo o a los logs puede copiarla, y rotarla es un trabajo manual que nadie hace. Con Workload Identity Federation GitHub emite un token OIDC de corta vida para cada job, Google lo verifica contra el issuer de GitHub, comprueba tu attribute condition y entrega credenciales temporales del service account. No hay secreto que guardar ni rotar, y puedes limitar quién entra hasta el nivel de repo o rama.

Las piezas

Para restringir a una rama, mapea el claim y úsalo en la condición y en el binding:

1
2

--attribute-mapping="…,attribute.ref=assertion.ref"
--attribute-condition="assertion.repository_owner == 'my-org' && assertion.ref == 'refs/heads/main'"

Con Terraform

El módulo oficial hace pool, proveedor y bindings en un bloque:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

module "github_actions_sa" {
  source     = "terraform-google-modules/service-accounts/google"
  version    = "~> 4.0"
  project_id = var.project_id
  names      = ["github-actions"]
  project_roles = ["${var.project_id}=>roles/artifactregistry.writer"]
}

module "gh_oidc" {
  source              = "terraform-google-modules/github-actions-runners/google//modules/gh-oidc"
  project_id          = var.project_id
  pool_id             = "github"
  provider_id         = "github-oidc"
  attribute_condition = "assertion.repository_owner == 'my-org'"
  sa_mapping = {
    "github-actions" = {
      sa_name   = "projects/${var.project_id}/serviceAccounts/${module.github_actions_sa.email}"
      attribute = "attribute.repository/my-org/my-repo"
    }
  }
}

output "workload_identity_provider" { value = module.gh_oidc.provider_name }

El output es exactamente el valor que va en workload_identity_provider del workflow.

Sin service account

auth@v3 también admite federación directa: el principalSet recibe roles IAM sin pasar por un service account (workload_identity_provider y project_id, sin service_account). Menos piezas, pero no todos los servicios aceptan principales federados; para Artifact Registry, GCS y la mayoría de APIs sí, y es el camino que Google recomienda para casos nuevos.

Trampas

• id-token: write en permissions del job. Sin él, auth falla con “Unable to get ACTIONS_ID_TOKEN_REQUEST_URL”.
• Número de proyecto, no ID, en la ruta del proveedor y del principalSet: projects/123456789012/….
• Permission 'iam.serviceAccounts.getAccessToken' denied: falta el binding roles/iam.workloadIdentityUser o el attribute.repository no coincide (mayúsculas y nombre exacto del repo).
• La condición debe referirse a claims mapeados: si usas assertion.ref en la condición sin haberlo mapeado a un atributo, el proveedor se crea pero nunca casa.
• Forks y PRs externos: los tokens de un PR desde un fork llevan repository del fork; una condición por repository_owner los deja fuera, que suele ser lo que quieres.
• Rotación: no hay nada que rotar, pero sí que revisar. gcloud iam workload-identity-pools providers describe y los logs de auditoría de STS dicen quién está entrando.

Referencia: google-github-actions/auth y Workload Identity Federation en la documentación de Google Cloud.

En Keycloak: Clients → Create client → OpenID Connect, Client ID proxmox, Client authentication On, Standard flow On, Valid redirect URIs https://pve.example.local:8006 y https://pve.example.local:8006/*. Copia el secret de la pestaña Credentials.

En un nodo Proxmox:

1
2
3
4
5
6
7

pveum realm add keycloak --type openid \
  --issuer-url https://id.example.local/realms/lab \
  --client-id proxmox \
  --client-key '<client-secret>' \
  --username-claim preferred_username \
  --autocreate 1 \
  --comment 'Keycloak'

Los usuarios entran como alice@keycloak. Se crean solos al primer login, sin permisos; los permisos siguen siendo ACLs de Proxmox:

1
2
3

pveum group add sso-admins
pveum acl modify / --groups sso-admins --roles Administrator
pveum user modify alice@keycloak --groups sso-admins     # después de su primer login

Cómo funciona

Proxmox soporta realms openid desde PVE 7. Con issuer-url descarga /.well-known/openid-configuration y de ahí saca los endpoints; en la pantalla de login aparece el realm en el desplegable y el botón Login redirige a Keycloak. Al volver, el valor del claim que elegiste en username-claim se convierte en el usuario <claim>@<realm>.

username-claim acepta cualquier nombre de claim. Keycloak manda preferred_username por defecto (viene del mapper username del client scope profile), así que no hace falta el mapper adicional que traían las guías antiguas para exponer un claim llamado username. Si prefieres el correo, --username-claim email.

Keycloak, paso a paso (26)

1. Realm. Usa el que tengas (lab en el ejemplo). El issuer es https://id.example.local/realms/lab. Desde Keycloak 17 ya no hay /auth/ en la ruta; si copias /auth/realms/... de una guía vieja, el discovery falla.
2. Clients → Create client.
   • Client type: OpenID Connect. Client ID: proxmox. Name: lo que quieras.
   • Capability config: Client authentication On (cliente confidencial, con secret). Standard flow On. Todo lo demás Off: Direct access grants, Implicit flow, Service accounts, Authorization.
   • Login settings: Root URL https://pve.example.local:8006; Valid redirect URIs https://pve.example.local:8006 y https://pve.example.local:8006/*. Web origins vacío: es un flujo de redirección, no hay CORS.
3. Credentials → Client secret. Es el --client-key.
4. Grupos (opcional). Clients → proxmox → Client scopes → proxmox-dedicated → Add mapper → By configuration → Group Membership: Name groups, Token Claim Name groups, Full group path Off, Add to ID token y Add to userinfo On.

Proxmox, paso a paso

Por GUI: Datacenter → Permissions → Realms → Add → OpenID Connect Server: Issuer URL, Realm (el nombre corto, keycloak), Client ID, Client Key, Username Claim preferred_username, Autocreate Users. O el pveum realm add del En corto; la configuración queda en /etc/pve/domains.cfg y se replica al clúster.

Con grupos desde Keycloak, en versiones recientes de PVE 8 y en PVE 9 (pveum realm add --help te dice si tu versión tiene --groups-claim):

1

pveum realm modify keycloak --groups-claim groups --groups-autocreate 1

Cada grupo del claim se crea como <grupo>-keycloak y el usuario entra en ellos en cada login; los ACLs los asignas a esos grupos.

Prueba antes de tocar nada más: pantalla de login → Realm Keycloak → Login → vuelves autenticado y pveum user list muestra alice@keycloak.

Trampas

• Invalid parameter: redirect_uri en Keycloak: la URL con la que entras al navegador (nombre, puerto 8006, https) no está en Valid redirect URIs. Si usas la IP y el FQDN, agrega las dos.
• El certificado de Keycloak lo tiene que aceptar el nodo, no solo tu navegador. Con una CA interna: copia el .crt a /usr/local/share/ca-certificates/ y update-ca-certificates.
• issuer-url tiene que coincidir exactamente con el iss de los tokens: https, sin barra final, /realms/<realm>.
• Hora. Un reloj desfasado invalida los tokens; chrony en los nodos.
• No dejes que el usuario edite su propio username en Keycloak (aviso de la propia documentación de Proxmox): cambiarse el nombre a root es cambiarse de cuenta en Proxmox.
• No pongas --default 1 hasta que funcione, y deja root@pam como puerta de emergencia: si Keycloak cae, el realm openid no puede autenticar a nadie.
• API y CLI. Los usuarios OIDC no tienen contraseña en Proxmox; para Terraform, Ansible o pvesh desde fuera crea un token: pveum user token add alice@keycloak automation --privsep 0.

Referencia: User Management — OpenID Connect en la guía de Proxmox y la creación de clientes en la documentación de Keycloak.