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