Google Cloud Workload Identity
Every Google Cloud workload has a metadata service atmetadata.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 with a second factor
(passkey, security key or authenticator-app code; an emailed code does not count),
made within the last 5 minutes for this action: it must carry
"action_scope": "oauth.client". 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 with "requires_step_up": true,
"action_scope": "oauth.client" and "allowed_methods": ["passkey", "2fa"]. On the
same session, first call POST /auth/2fa/verify-step-up with
{"totp_code": "<code>", "action_scope": "oauth.client"}, or complete a WebAuthn
step-up in a browser with the same action_scope (POST /auth/passkey/verify-step-up
for a passkey, or POST /auth/2fa/webauthn/step-up-options then
POST /auth/2fa/webauthn/verify-step-up for a security key), then replay the request
inside the 5-minute window. A verification made for a different action, such as one a
Dashboard prompt raised, carries that action’s scope and does not satisfy this gate.
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.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 nestedgoogleobject, 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
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; setKNOXCALL_CLIENT_ID+KNOXCALL_CLIENT_SECRETfor local dev.invalid_grant: no binding matched— verify the service account email matches what’s in the binding. Rungcloud auth print-identity-token --audiences=knoxcall:apion the host and decode it.- Network egress — if your GKE pod has restricted egress, allow
metadata.google.internal:80.