cleandataengineering.aiAgent Harness, drawn simply
You are here: Tech stack › L16 · Identity & authz

Agent Harness Tutorial · Tech stack

L16 · Identity & authz

Who is asking, and whose authority the agent acts with. Family: Control · one turn, in order.

AZURE OPTIONSEntra ID · managed identity · Key Vault✓ used: the identity platformEntra External ID◐ planned: for real policyholdersazure-identity SDK✗ dropped: fetches tokens, doesn't check oursMSAL✗ dropped: hidden retries hide failure kindsOUR CHOICEMicrosoft Entra IDsign-in, on-behalf-ofManaged identity + Key Vaultover plain RESTPyJWTRS256 token check, keys cached 5 minOPEN-SOURCE OPTIONSPyJWT✓ used: standard JWT libraryKeycloak· considered: reference agent onlyHashiCorp Vault· considered: not pickedWHO DOES THE WORKAzure gives 70% · we code once 20% · each agent team still does 10%
Dark boxes are what we run. Solid boxes are used or planned; dashed boxes were considered or dropped (crossed). The bar: grey is what Azure gives, dark is what we code once, hatched is what each agent team writes.
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.
OptionWhere fromVerdictWhy
Microsoft Entra IDours✓ chosensign-in, on-behalf-of
Managed identity + Key Vaultours✓ chosenover plain REST
PyJWTours✓ chosenRS256 token check, keys cached 5 min
Entra ID · managed identity · Key VaultAzure✓ usedthe identity platform
Entra External IDAzure◐ plannedfor real policyholders
azure-identity SDKAzure✗ droppedfetches tokens, doesn't check ours
MSALAzure✗ droppedhidden retries hide failure kinds
PyJWTopen source✓ usedstandard JWT library
Keycloakopen source· consideredreference agent only
HashiCorp Vaultopen source· considerednot picked

How it works inside the harness: Front door.

Compared: Which library checks and gets identity tokens?

PyJWT + PyJWKClie…open sourcechosenPlain httpx form …ourschosenAzure SDK (azure-…Azuredrop hereMSALvendorrejectedIdentity port (Ve…ourskeepKeycloak adapteropen sourcereference agent
Dark: what we chose. Crossed and dashed: rejected or not for us. From the Series.
OptionFromVerdictWhat it doesChecks tokens users sendGets tokens for usHides failure kindsWhy
PyJWT + PyJWKClientopen sourcechosenchecks signature, issuer, audienceyes, locally, keys cachednonono Entra call per request
Plain httpx form postsourschosensign-in, refresh, on-behalf-ofnoyes: one form post eachno: refused, misconfigured, downcode branches on each failure
Azure SDK (azure-identity)Azuredrop heregets tokens to call Azurenoyes: managed identitypartlywrong tool for checking tokens
MSALvendorrejectedsign-in, refresh, OBO, cachingnoyes, with caching, retriesyes: hidden caching, retrieshides the failures we branch on
Identity port (Verifier, Exchange, Login)ourskeepone interface, many adaptersvia the adaptervia the adapternoleaving Entra is configuration
Keycloak adapteropen sourcereference agentlocal identity providervia the Verifier portvia the Login portnoruns 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}