Skip to main content

​
Azure Workload Identity

Azure workloads with a system-assigned or user-assigned Managed Identity get a local metadata endpoint that issues short-lived tokens. KnoxCall accepts these via RFC 8693.

​
1. Enable Managed Identity on your resource

Azure portal: Identity → System assigned: On (or attach a user-assigned identity). This sets the env vars on every request:
  • IDENTITY_ENDPOINT — local metadata URL
  • IDENTITY_HEADER — header value the metadata service requires

​
2. Configure the trust binding

Create the binding in the dashboard with Settings → API → Workload Identity → Connect workload, or call the admin API on the admin host (admin.knoxcall.com). The admin API is authenticated by your dashboard session JWT plus an X-Tenant-ID header (it is not the API-key data plane on 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 Managed Identity object id (oid claim). You can also lock tid (tenant) or appid for tighter control.

​
3. Call KnoxCall

The SDK calls $IDENTITY_ENDPOINT?resource=knoxcall:api with the X-IDENTITY-HEADER, gets the JWT, exchanges it for a KnoxCall token.

​
Troubleshooting

  • Could not detect KnoxCall credentials — Managed Identity isn’t enabled or env vars aren’t propagated. Check the resource’s Identity blade.
  • invalid_target — resource param in the metadata call must be exactly knoxcall:api; we set this automatically.
  • invalid_grant: no binding matched — verify the oid of your Managed Identity (run az identity show --ids <resource-id> --query principalId) matches the binding.