Edit

Authenticate users and route requests to agents in a fleet with ASP.NET Core

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

Configure token validation

Token validation is the same as for a single agent. Use the blueprint client ID as the expected audience. For upstream client setup and validation details, see Authenticate users to an ASP.NET Core agent API.

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. Define an access policy that the runtime checks on every request:

using System.Security.Claims;

public interface IAgentAccessPolicy
{
    Task<bool> CanUseAgentAsync(ClaimsPrincipal user, string agentId);
}

Identify the user by the tid and oid claims. Don't use the user principal name or email as a stable key.

Implement IAgentAccessPolicy against your sharing records and register it in dependency injection before mapping the endpoint. The interface alone doesn't enforce access.

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:

using Microsoft.Identity.Web.Resource;

app.MapPost("/agents/{agentId}/messages", async (
    string agentId,
    HttpContext context,
    IAgentDirectory directory,
    IAgentAccessPolicy accessPolicy) =>
{
    context.VerifyUserHasAnyAcceptedScope("access_agent");

    if (await directory.FindAsync(agentId) is null
        || !await accessPolicy.CanUseAgentAsync(context.User, agentId))
    {
        return Results.NotFound();
    }

    // Run the agent for this request.
    return Results.Accepted();
})
.RequireAuthorization();

The endpoint returns 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 agentId for every token request made while handling the request.

Before adding agent work, test with a user who can access one agent but not another. The allowed request reaches the placeholder 202 Accepted response; requests for the other agent and an unknown agent return 404 Not Found. Confirm that neither rejected request runs agent work or requests a downstream token. The placeholder response verifies routing and access checks, not agent execution.

Next step

Call APIs as a user in a fleet with ASP.NET Core