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"

And in the 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            # without this GitHub does not issue the OIDC token
    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

Whatever roles the pipeline needs (Artifact Registry, Cloud Run, GKE…) go to github-actions@… like to any service account.

Why

The classic alternative is exporting a service account JSON key and storing it as a GitHub secret. That key never expires, anyone with access to the repo or the logs can copy it, and rotating it is manual work nobody does. With Workload Identity Federation GitHub issues a short-lived OIDC token for each job, Google verifies it against GitHub’s issuer, checks your attribute condition, and hands out temporary service account credentials. There is no secret to store or rotate, and you can restrict who gets in down to the repo or branch.

The pieces

To restrict to a branch, map the claim and use it in both the condition and the binding:

1
2

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

With Terraform

The official module creates pool, provider, and bindings in one block:

 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 }

The output is exactly the value that goes into the workflow’s workload_identity_provider.

Without a service account

auth@v3 also supports direct federation: the principalSet gets IAM roles without going through a service account (workload_identity_provider and project_id, no service_account). Fewer pieces, but not every service accepts federated principals; Artifact Registry, GCS, and most APIs do, and it is the path Google recommends for new setups.

Traps

• id-token: write in the job’s permissions. Without it, auth fails with “Unable to get ACTIONS_ID_TOKEN_REQUEST_URL”.
• Project number, not ID, in the provider path and the principalSet: projects/123456789012/….
• Permission 'iam.serviceAccounts.getAccessToken' denied: the roles/iam.workloadIdentityUser binding is missing or attribute.repository does not match (case and exact repo name).
• The condition must reference mapped claims: if you use assertion.ref in the condition without mapping it to an attribute, the provider gets created but never matches.
• Forks and external PRs: tokens from a fork’s PR carry the fork’s repository; a condition on repository_owner keeps them out, which is usually what you want.
• Rotation: nothing to rotate, but something to review. gcloud iam workload-identity-pools providers describe and the STS audit logs tell you who is coming in.

Reference: google-github-actions/auth and Workload Identity Federation in the Google Cloud documentation.

In Keycloak: Clients → Create client → OpenID Connect, Client ID proxmox, Client authentication On, Standard flow On, Valid redirect URIs https://pve.example.local:8006 and https://pve.example.local:8006/*. Copy the secret from the Credentials tab.

On a Proxmox node:

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'

Users log in as alice@keycloak. They are created on first login, with no permissions; permissions are still Proxmox ACLs:

1
2
3

pveum group add sso-admins
pveum acl modify / --groups sso-admins --roles Administrator
pveum user modify alice@keycloak --groups sso-admins     # after their first login

How it works

Proxmox has supported openid realms since PVE 7. From issuer-url it downloads /.well-known/openid-configuration and takes the endpoints from there; the login screen shows the realm in the dropdown and the Login button redirects to Keycloak. On the way back, the value of the claim you picked in username-claim becomes the user <claim>@<realm>.

username-claim accepts any claim name. Keycloak sends preferred_username by default (it comes from the username mapper in the profile client scope), so the extra mapper old guides added to expose a claim called username is not needed. If you prefer the email, --username-claim email.

Keycloak, step by step (26)

1. Realm. Use the one you have (lab in the example). The issuer is https://id.example.local/realms/lab. Since Keycloak 17 there is no /auth/ in the path; if you copy /auth/realms/... from an old guide, discovery fails.
2. Clients → Create client.
   • Client type: OpenID Connect. Client ID: proxmox. Name: whatever you like.
   • Capability config: Client authentication On (confidential client, with secret). Standard flow On. Everything else 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 and https://pve.example.local:8006/*. Web origins empty: it is a redirect flow, there is no CORS.
3. Credentials → Client secret. That is the --client-key.
4. Groups (optional). 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 and Add to userinfo On.

Proxmox, step by step

Through the GUI: Datacenter → Permissions → Realms → Add → OpenID Connect Server: Issuer URL, Realm (the short name, keycloak), Client ID, Client Key, Username Claim preferred_username, Autocreate Users. Or the pveum realm add from the TL;DR; the configuration lands in /etc/pve/domains.cfg and replicates across the cluster.

With groups coming from Keycloak, on recent PVE 8 releases and on PVE 9 (pveum realm add --help tells you whether your version has --groups-claim):

1

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

Each group in the claim is created as <group>-keycloak and the user joins them on every login; you assign the ACLs to those groups.

Test before touching anything else: login screen → Realm Keycloak → Login → you come back authenticated and pveum user list shows alice@keycloak.

Traps

• Invalid parameter: redirect_uri in Keycloak: the URL you typed in the browser (name, port 8006, https) is not in Valid redirect URIs. If you use both the IP and the FQDN, add both.
• The node must trust Keycloak’s certificate, not just your browser. With an internal CA: copy the .crt to /usr/local/share/ca-certificates/ and run update-ca-certificates.
• issuer-url has to match exactly the iss in the tokens: https, no trailing slash, /realms/<realm>.
• Time. A skewed clock invalidates tokens; chrony on the nodes.
• Do not let users edit their own username in Keycloak (a warning from Proxmox’s own docs): renaming yourself to root is switching accounts in Proxmox.
• Do not set --default 1 until it works, and keep root@pam as the emergency door: if Keycloak is down, the openid realm cannot authenticate anyone.
• API and CLI. OIDC users have no password in Proxmox; for Terraform, Ansible, or pvesh from outside create a token: pveum user token add alice@keycloak automation --privsep 0.

Reference: User Management — OpenID Connect in the Proxmox guide and client creation in the Keycloak documentation.