Agent Identity with Azure Entra ID

Confirm each of the following before starting. The directory sync path and the gateway-local validation path each carry their own floor, and discovering a version gap in the middle of phase 3 is avoidable.

Verification: read the gateway version from the Admin Settings page or from the deployed image tag, and confirm it clears the highest floor that applies to the phases you intend to run. If you are on AI Gateway Cloud, phase 3 does not apply and the 2.5.0 floor is irrelevant.

This decision changes which phases you run, so make it first rather than discovering it in phase 5.

• Attribute to a person — a human is signed in and the agent acts on their behalf. Run every phase. The token must carry that person's email, and that person must already be a workspace member.
• Attribute to an application — the agent runs unattended on a schedule or a queue. Skip the JWT path entirely and issue the agent its own workspace service key, naming the agent in request metadata. Phases 1 and 2 are then unnecessary.
• Attribute to a named service account — you want the agent to appear in the workspace member list. Run phase 1, then issue a User API key against the provisioned user rather than using JWTs.

Verification: write down which of the three you chose and which phases it implies. If the answer is the second one, stop here and follow the service key path in the LLM API Key Management guide instead.

1. In Strata Cloud Manager, open Settings → Identity Services → Cloud Identity Engine.
2. Add a directory and choose Azure AD as the directory type. Okta and on-premises Active Directory are the other two options and behave identically from the gateway's point of view.
3. Authorise the directory against your Entra tenant. This grants Cloud Identity Engine read access to users and groups.
4. Set the User Identity Attribute. The choice is between UPN and Mail.

Verification: open the directory's user list in Cloud Identity Engine and confirm that the identity column shows the address you expect for several users, including at least one who was created recently. A user whose chosen attribute is empty is skipped during sync without raising an error, so a shorter list than you expected is a signal rather than a coincidence.

1. In the AI Gateway, open Admin Settings → Organisation → Directory Sync.
2. Select the Cloud Identity Engine groups you want to provision from.
3. Map each group to exactly one workspace. The relationship is one group to one workspace, not many to many.
4. Assign the workspace role that members of that group should inherit.

Background sync then provisions new members as they appear in the directory and deprovisions them when they leave. Nothing in this step runs per request.

Verification: open the target workspace's member list and confirm that users from the mapped group appear, each with the role you assigned. Then remove a test user from the group in Entra, wait for the next sync, and confirm they disappear from the workspace. Deprovisioning is the half of this that nobody tests and the half that matters at audit time.

1. Create an app registration in the Entra tenant for the agent.
2. Choose the grant that matches the attribution decision from P.2. Client credentials for an unattended agent. On-behalf-of when the agent acts for a signed-in person and the token must carry that person's identity.
3. Define an audience the gateway's tokens will carry, for example api://ai-gateway.
4. Note the tenant ID. It forms part of the JWKS URL in the next step.

Verification: acquire a token with the grant you configured and decode it. Confirm the header carries alg: RS256, typ: JWT and a kid, and that the payload carries iss, aud, sub and exp. If you chose on-behalf-of, confirm an email claim is present. If you chose client credentials, it will not be, and that is expected.

1. In the AI Gateway, open Admin Settings → Organisation → Authentication.
2. Paste either a JWKS URL or the static JWKS JSON. For Entra the URL is the tenant discovery endpoint.
3. If more than one issuer needs to be trusted, supply a comma-separated list of URLs. The keys from all of them are merged into one set.

https://login.microsoftonline.com/<tenant-id>/discovery/v2.0/keys

Verification: fetch the JWKS URL from a host on the same network path the gateway uses, not from your laptop. The gateway has to be able to reach it, and an egress policy that blocks it produces a signing-key error that looks nothing like a connectivity problem. JWKS fetches honour HTTPS_PROXY and TLS_CA, so a proxied environment can be made to work rather than needing an exception.

On AI Gateway Cloud the management plane validates every token. There is no local validation option and no environment variable to set. Phase 2 is the whole of the configuration, and you can move straight to phase 4.

Verification: confirm your deployment is Cloud rather than hybrid. If you administer the gateway containers yourself, it is not Cloud, and step 3.2 applies.

Set the following on the gateway data plane. The feature requires gateway 2.5.0 or higher, and air-gapped deployments additionally require backend v1.13.0 or higher.

JWT_ENABLED=ON
ORGANISATIONS_TO_SYNC=<your-org-id>
PORTKEY_CLIENT_AUTH=<client-auth-token>
JWT_LOCAL_AUTH_DEFAULT_SCOPES=completions.write,mcp.invoke

Verification: restart the gateway and send one authenticated call. Then make the management plane unreachable, from the gateway's network rather than by deleting anything, and send the same call again. If local validation is active the second call succeeds. If it fails with an authentication error, JWT_ENABLED did not take effect.

Two headers are accepted. Use either one, not both.

# Option 1: the raw token, with no prefix
curl https://api.portkey.ai/v1/chat/completions \
  -H "x-portkey-api-key: $JWT" \
  -H "Content-Type: application/json" \
  -d '{"model":"@azure-foundry/gpt-4o","messages":[{"role":"user","content":"ping"}]}'

# Option 2: the standard Authorization header, with the Bearer prefix
curl https://api.portkey.ai/v1/chat/completions \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"model":"@azure-foundry/gpt-4o","messages":[{"role":"user","content":"ping"}]}'

Verification: the call returns a completion. If it returns an authentication error, decode the token and check its expiry before changing anything else, because an expired token and a malformed header produce the same message.

A successful call ran four resolutions you did not see. Knowing their order turns a vague authentication failure into a specific one.

Small clock skew is tolerated on exp. The iat and nbf claims are recommended rather than required. The portkey. prefix on a scope is optional, so completions.write and portkey.completions.write are both accepted.

Verification: deliberately request a token without the scope your endpoint needs and send the same call. It should be refused even though the signature is valid, which confirms that scope resolution is running rather than being skipped. Restore the scope afterwards.

The gateway takes the first of these claims that is present, in this order, and uses it as the user identity for logging and metrics.

Verification: decode the token your agent actually sends and find the first of those three claims it carries. That value, and nothing else, is what the next step compares.

If the token's email matches an AI Gateway user in the target workspace, the request is attributed to that person and inherits their workspace role. Logs, metrics and per-user budget policies all then resolve to a human being.

Verification: send a call with a token carrying a known workspace member's email, then open the gateway logs and confirm the entry names that person. Then send a call with a token carrying an address that is deliberately not a member, and confirm the entry attributes to the workspace service key rather than failing. Seeing both outcomes is how you know the comparison is live rather than coincidental.

A client-credentials token carries a service principal rather than a person, so precedence falls through to sub. There is no email to compare, so the comparison in 5.2 cannot match a workspace member.

Where attribution of an unattended agent matters, send metadata alongside the call. The _user key inside x-portkey-metadata is reserved, and from version 1.17.0 onward metadata._user can be used as a match key for budget and rate-limit policies.

-H 'x-portkey-metadata: {"_user":"invoice-reconciliation-agent","team":"finance"}'

Verification: send the call with the metadata header and confirm the log entry carries the value you set. Then build a budget policy keyed on metadata._user and confirm it matches that agent and not others.

In the gateway's provider configuration for Azure AI Foundry, supply one of:

• API key — the simplest option, and the one that requires no Entra configuration at all
• Entra service principal — a client ID and secret or certificate, scoped to the Foundry resource
• Managed identity — available when the gateway runs on Azure compute, and the option that avoids holding a secret

Verification: make a call through the gateway, then check the Azure activity or diagnostic log on the Foundry resource. The caller recorded there should be the gateway's service principal or managed identity. If you expected to see the end user there, this is the step that explains why you do not.

When the token is minted by something you own, gateway-specific claims can be added to it and everything travels in the token.

{
  "sub": "agent-7",
  "email_id": "ana@corp.example",
  "portkey_oid": "org_abc123",
  "portkey_workspace": "ws_ai_platform",
  "scope": "completions.write mcp.invoke",
  "usage_limits": { "credit_limit": 1000 },
  "rate_limits": { "requests_per_minute": 60 },
  "defaults": { "metadata": { "team": "finance" } },
  "exp": 1767225600
}

Nothing has to be configured on the gateway side beyond the JWKS, because organisation, workspace, scopes and limits all arrive with the request.

A token from a commercial IdP carries a schema you cannot extend. It can be as thin as this and still authenticate.

{
  "iss": "https://login.microsoftonline.com/<tenant-id>/v2.0",
  "aud": "api://ai-gateway",
  "sub": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "exp": 1767225600
}

Everything the token cannot carry has to be supplied somewhere else.

A Cloud Identity Engine group maps to a workspace, and membership of that workspace carries a workspace role. The group itself does not travel with the request and cannot be matched in a policy the way a firewall rule matches a User-ID group. If you need per-group differentiation, it has to be expressed as separate workspaces, or as metadata the application sends.

Phase 6 covers this. The provider sees the gateway. Per-user accounting against the provider's own bill is not available, and the gateway's logs are the only place that attribution exists.

The MCP Gateway can forward caller identity to an MCP server three ways: a claims header, passing the original bearer token straight through, or a gateway-signed JWT in a header you name. The Agent Gateway has no equivalent. A client authenticates to it with a gateway API key carrying the Agent Gateway toggle and the agents.invoke scope, and access control works per agent and per skill. Access control for specific users, skill control within a workspace, and skill control for an individual user are all listed as coming soon.

Step 5.3 covers this. A client-credentials token has no email, so no amount of directory configuration will make it attribute to a human. Use a service key and metadata instead.

Every invalid-JWT error is written to the audit log, with the token redacted to its first and last few characters. Start there rather than from the client-side error, because the audit entry names the actual reason.

Everything in this guide is drawn from the product documentation listed above, as mirrored locally on 21 September 2026, together with the Palo Alto Networks Cloud Identity Engine documentation. One statement is an inference rather than a quotation and is marked as such where it appears.