​

GitHub Actions Workload Identity

​

1. Add the workflow permission

permissions:
  id-token: write   # required to mint the GHA OIDC token
  contents: read    # standard

​

2. Configure the trust binding in KnoxCall

curl -X POST https://admin.knoxcall.com/admin/oauth/workload-bindings \
  -H "Authorization: Bearer $SESSION_JWT" \
  -H "X-Tenant-ID: $TENANT_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "oauth_client_id": "<your_oauth_client_id>",
    "name": "gha-acme-api-deploy",
    "issuer": "https://token.actions.githubusercontent.com",
    "audience": "knoxcall:api",
    "attribute_conditions": {
      "repository": "acme/api",
      "ref": "refs/heads/main",
      "workflow": "deploy"
    },
    "allowed_scopes": ["routes:write", "secrets:read"],
    "access_token_ttl_seconds": 3600
  }'

​

3. Call KnoxCall from the workflow

jobs:
  deploy:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm install @knoxcall/sdk
      - run: node deploy.js
        env:
          KNOXCALL_TENANT: acme

import { KnoxCall } from "@knoxcall/sdk";
const client = new KnoxCall({ tenant: process.env.KNOXCALL_TENANT });
const routes = await client.routes.list();

​

What’s in the OIDC token

​

Recommendations

• For production paths: require environment + ref + repository. GitHub Environments add a manual-approval gate you should leverage.
• For PR / CI paths: require event_name != pull_request to avoid third-party fork PRs minting tokens.
• Use one binding per logical workload, not one per repo. Granular bindings make last_used_at data actually useful.

​

Troubleshooting

• invalid_grant: no binding matched — JWT attributes don’t match. Fetch and decode the OIDC token to inspect its claims and compare them to your binding:
  curl -s -H "Authorization: Bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
    "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=knoxcall:api" \
    | python3 -c 'import sys,json,base64; t=json.load(sys.stdin)["value"].split("."); print(base64.urlsafe_b64decode(t[1]+"=="*(-len(t[1])%4)).decode())'
  
• invalid_request: subject_token signature invalid — Audience mismatch. The SDK appends &audience=knoxcall:api to the OIDC request — make sure your binding’s audience field is exactly knoxcall:api.
• invalid_request: subject_token expired — Clock skew. Ensure your runner’s clock is sane (NTP).