Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
Users call a fleet agent with an access token for the blueprint's access_agent scope. Every agent in the fleet shares that audience, so token validation proves who the user is but not which agent they're allowed to use. The runtime routes each request to an agent and enforces per-agent access itself.
Prerequisites
- Complete Call APIs as an agent in a fleet with the Auth SDK sidecar.
- The
access_agentscope exposed on the blueprint. - An upstream client that signs in users and requests the scope
api://<agent-identity-blueprint-client-id>/access_agent.
Configure token validation
Token validation is the same as for a single agent. Configure the sidecar with the blueprint client ID and the access_agent scope, and validate each inbound token with GET /Validate. For details, see Authenticate users with the Auth SDK sidecar. Keep the fleet's per-request identity overrides from the preceding articles and the shared network namespace for local sidecar requests; don't replace them with the single-instance defaults.
To limit which users can call the fleet at all, require an app role assignment on the blueprint principal. Those app roles apply to every agent in the fleet.
Enforce per-agent access
Decide who can use each agent, and store that decision in the runtime. For example, record the users and groups that an agent's owner shares it with. Identify the user by the validated tid and oid claims. Don't use the user principal name or email as a stable key.
Route requests to agents
Put the runtime's agent ID in the route. Validate the token, confirm the agent exists, and check the access policy before running the agent. The following examples assume an access_policy object that implements the runtime's per-agent access check.
import requests
SIDECAR_URL = "http://localhost:5000"
class AgentNotFound(Exception):
"""Return 404 Not Found to the caller."""
def authorize_agent_request(inbound_auth_header: str, agent_id: str) -> dict:
response = requests.get(
f"{SIDECAR_URL}/Validate",
headers={"Authorization": inbound_auth_header},
timeout=5,
)
if response.status_code in (401, 403):
raise PermissionError("The sidecar rejected the caller's access token.")
response.raise_for_status()
result = response.json()
claims = result.get("claims", {})
object_id = claims.get("oid")
tenant_id = claims.get("tid")
if (
result.get("protocol", "").lower() != "bearer"
or not object_id
or not tenant_id
):
raise PermissionError("The token isn't a validated user bearer token.")
scopes = claims.get("scp", "").split()
if "access_agent" not in scopes:
raise PermissionError("The token doesn't contain the access_agent scope.")
if directory.find(agent_id) is None or not access_policy.can_use_agent(
tenant_id, object_id, agent_id
):
raise AgentNotFound(agent_id)
return claims
# For a request to POST /agents/{agent_id}/messages:
claims = authorize_agent_request(request.headers.get("Authorization"), agent_id)
Return 401 Unauthorized when the token is missing or invalid. Return 404 Not Found both for an unknown agent and for an agent the user can't use, so callers can't discover other agents in the fleet. After these checks pass, use the same agent ID for every token request made while handling the request.
Next step
Call APIs as a user in a fleet with the Auth SDK sidecar