Skip to main content

AWS Workload Identity

KnoxCall accepts AWS-issued OIDC tokens from EKS pods (IRSA) and other workloads with AWS_WEB_IDENTITY_TOKEN_FILE configured. STS workload identity for ECS / Lambda is supported via the same pattern.

1. Set up the IAM role + EKS service account (IRSA)

Existing AWS IAM setup — your cluster’s OIDC provider must be registered. See AWS docs. Once configured, your pod has these env vars automatically:
  • AWS_WEB_IDENTITY_TOKEN_FILE (path to a file containing a signed JWT)
  • AWS_ROLE_ARN

2. Configure the KnoxCall 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.
Lock attribute conditions to the assumed IAM role ARN. The OIDC token from sts.amazonaws.com carries the role ARN in the arn claim.

3. Call KnoxCall

The SDK reads AWS_WEB_IDENTITY_TOKEN_FILE, exchanges the token for a KnoxCall access token, and uses it. No secrets stored.

Lambda / EC2 without IRSA — static client credentials

If you’re on Lambda or EC2 without IRSA, the SDK falls back to plain client_credentials: the static KNOXCALL_CLIENT_ID + KNOXCALL_CLIENT_SECRET env vars. There is no IMDSv2 / EC2 instance-identity path — the SDK only reads AWS_WEB_IDENTITY_TOKEN_FILE for the OIDC flow and otherwise uses these env vars. Store them in AWS Secrets Manager or Lambda environment variables encrypted with a KMS key. For Lambda with IRSA via container images, the IRSA env vars are set automatically by the Lambda runtime — same SDK works.

Troubleshooting

  • Could not detect KnoxCall credentials — AWS_WEB_IDENTITY_TOKEN_FILE is unset. Verify the pod’s service account is annotated with eks.amazonaws.com/role-arn.
  • invalid_grant: no binding matched — decode the JWT (cat $AWS_WEB_IDENTITY_TOKEN_FILE | cut -d. -f2 | base64 -d) and compare its arn claim to your binding.