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 (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.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.