Agent Harness Tutorial · Tech stack
L16 · Identity & authz
Who is asking, and whose authority the agent acts with. Family: Control · one turn, in order.
Why our choiceChecking a token is local and needs no call to Entra; a standard JWT library is Microsoft's own advice for Python APIs. Ports make leaving Entra a configuration change.
| Option | Where from | Verdict | Why |
|---|---|---|---|
| Microsoft Entra ID | ours | ✓ chosen | sign-in, on-behalf-of |
| Managed identity + Key Vault | ours | ✓ chosen | over plain REST |
| PyJWT | ours | ✓ chosen | RS256 token check, keys cached 5 min |
| Entra ID · managed identity · Key Vault | Azure | ✓ used | the identity platform |
| Entra External ID | Azure | ◐ planned | for real policyholders |
| azure-identity SDK | Azure | ✗ dropped | fetches tokens, doesn't check ours |
| MSAL | Azure | ✗ dropped | hidden retries hide failure kinds |
| PyJWT | open source | ✓ used | standard JWT library |
| Keycloak | open source | · considered | reference agent only |
| HashiCorp Vault | open source | · considered | not picked |
How it works inside the harness: Front door.
Compared: Which library checks and gets identity tokens?
| Option | From | Verdict | What it does | Checks tokens users send | Gets tokens for us | Hides failure kinds | Why |
|---|---|---|---|---|---|---|---|
| PyJWT + PyJWKClient | open source | chosen | checks signature, issuer, audience | yes, locally, keys cached | no | no | no Entra call per request |
| Plain httpx form posts | ours | chosen | sign-in, refresh, on-behalf-of | no | yes: one form post each | no: refused, misconfigured, down | code branches on each failure |
| Azure SDK (azure-identity) | Azure | drop here | gets tokens to call Azure | no | yes: managed identity | partly | wrong tool for checking tokens |
| MSAL | vendor | rejected | sign-in, refresh, OBO, caching | no | yes, with caching, retries | yes: hidden caching, retries | hides the failures we branch on |
| Identity port (Verifier, Exchange, Login) | ours | keep | one interface, many adapters | via the adapter | via the adapter | no | leaving Entra is configuration |
| Keycloak adapter | open source | reference agent | local identity provider | via the Verifier port | via the Login port | no | runs the reference agent off Azure |
DecisionWe check tokens locally with PyJWT and get tokens with plain httpx form posts, all behind our identity port. MSAL and azure-identity would hide the failure kinds our code branches on; we would only revisit if token flows grew beyond single form posts.
How it is done: the real code
Cut from the live repositories each time the site is built, so it always matches what runs.
identity:
adapter: entra-id
tenant: {env: AZURE_TENANT_ID}
# A v2 access token's `aud` is the API's client id, not its api:// URI
# (FINDINGS F-55), so the agent's own app id, which the Entra hook records.
audience: {env: ENTRA_APP_ID}
# A1: the claims system's token on every MCP call — on behalf of the
# policyholder (their session in, a token for api://claims-system out), and
# for the payout workflow the agent's own app token (its app role
# payouts.issue). The agent's app proves itself with a client secret the
# Entra hook writes to Key Vault; nothing here is a value.
client_id: {env: ENTRA_APP_ID}
client_secret: {key_vault: agent-obo-client-secret}
far_end_scope: api://claims-system/.default
worker_scope: api://claims-system/.default
# The app registration's app role (infra/hooks/entra-app.sh) and what it
# grants at the desk: the handler reads and closes escalations and decides
# approvals (F-30). A role is a job; the desk checks scopes.
role_scopes:
desk.handler: [escalations:read, escalations:review, approvals:read, approvals:decide]
# A2: the policyholder id. A directory extension attribute on the user,
# emitted by Entra as `extn.<name>` (infra/hooks/entra-app.sh, FINDINGS F-91).
# One setting: the claims system reads the same name
# (config/claims-system/azure.yaml), and the hook names the attribute from it.
holder_claim: {env: HOLDER_CLAIM}
# A2: the policyholder's sign-in — the code flow with PKCE and a nonce
# against this tenant's /authorize and /token, as the app registration
# above (a confidential client: its secret, client_secret, is the one it
# already has). The redirect URI is the agent's own /signin/callback, which
# the hook registers; the cookies are sealed with a key derived from
# session_key (a different purpose from state's).
login_redirect_uri: {env: ENTRA_REDIRECT_URI}
login_scopes: [api://claims-fnol/claims:read, api://claims-fnol/claims:write]
session_key: {key_vault: agent-session-key}