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