Skip to main content

Google Cloud Workload Identity

Every Google Cloud workload has a metadata service at metadata.google.internal that issues short-lived OIDC tokens signed by Google. KnoxCall accepts these tokens via RFC 8693 token exchange.

1. Configure the trust binding

Create the workload binding in the dashboard with Settings → API → Workload Identity → Connect workload, or call the admin API directly. The /admin/* routes are served on the admin host (admin.knoxcall.com / any knoxcall.com host) and are authenticated by your logged-in admin/owner session — a session JWT plus the X-Tenant-ID header — not an API key against api.knoxcall.com.
Creating a binding requires a recent step-up verification (passkey, TOTP or emailed code) within the last 5 minutes — a binding is a trust that lets an external workload mint tenant tokens, so it carries the same bar as creating an OAuth client. A curl carrying only a session JWT answers 403 {"requires_step_up": true}: verify in the Dashboard (any action that prompts for your passkey or TOTP), then replay the request inside the 5-minute window. Each verification is single-use, so a retried request needs a fresh one. Listing and revoking bindings need no verification — containment must never be gated.
Lock to the service account email claim, or to its numeric sub. A rule must pin one of the two: https://accounts.google.com signs tokens for every Google account, so a rule without an identifying claim would match other projects’ service accounts, and KnoxCall refuses it with a 400. Conditions compare top-level claims by exact string match. Two conditions that look reasonable do not work today, so do not add them:
  • email_verified — Google sends it as a boolean, and a condition value is a string, so the rule would never match.
  • google.compute_engine.project_id / instance_id — these sit inside a nested google object, and a dotted key is not a path. Instance-level binding is not supported yet; use one service account per workload you want to tell apart.

2. Run with the right service account

Cloud Run / Cloud Functions

GKE Workload Identity

GCE

The VM’s default or attached service account is used automatically.

3. Call KnoxCall

The SDK hits http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=knoxcall:api, fetches the signed token, and exchanges it for a KnoxCall access token.

Troubleshooting

  • Could not detect KnoxCall credentials — the metadata service isn’t reachable. This is normal locally; set KNOXCALL_CLIENT_ID + KNOXCALL_CLIENT_SECRET for local dev.
  • invalid_grant: no binding matched — verify the service account email matches what’s in the binding. Run gcloud auth print-identity-token --audiences=knoxcall:api on the host and decode it.
  • Network egress — if your GKE pod has restricted egress, allow metadata.google.internal:80.