Skip to content

Commit 2c46deb

Browse files
.NET: Clarify hosting authentication, authorization, and isolation guidance (#8677)
* docs: clarify AG-UI hosting configuration guidance Co-authored-by: Copilot App <[email protected]> * docs: refine hosting guidance Co-authored-by: Copilot App <[email protected]> * samples: fix AGUIServer local session store configuration Co-authored-by: Copilot App <[email protected]> * samples: fix AgentWebChat local session store configuration Co-authored-by: Copilot App <[email protected]> * docs: clarify OpenAI Responses session store configuration Co-authored-by: Copilot App <[email protected]> * hosting: refine claims-based isolation key resolution Co-authored-by: Copilot App <[email protected]> * Fix formatting Co-authored-by: Copilot App <[email protected]> --------- Co-authored-by: Copilot App <[email protected]>
1 parent 024dd99 commit 2c46deb

36 files changed

Lines changed: 536 additions & 23 deletions

File tree

‎dotnet/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -29,6 +29,7 @@ Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Fram
2929
- [Getting Started with Agents](./samples/02-agents/Agents): basic agent creation and tool usage
3030
- [Agent Provider Samples](./samples/02-agents/AgentProviders): samples showing different agent providers
3131
- [Workflow Samples](./samples/03-workflows): advanced multi-agent patterns and workflow orchestration
32+
- [Hosting guidance](./samples/04-hosting/README.md): authentication, endpoint authorization, and caller isolation across hosting protocols
3233

3334
## Agent Framework Documentation
3435

‎dotnet/samples/02-agents/AGUI/README.md‎

Lines changed: 58 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,9 @@
22

33
This directory contains samples that demonstrate how to build AG-UI (Agent UI Protocol) servers and clients using the Microsoft Agent Framework.
44

5+
> [!WARNING]
6+
> These samples do not authenticate AG-UI callers and are intended for local development. Before exposing an endpoint to other users, configure endpoint authorization and caller-scoped session isolation as described in [Security considerations](#security-considerations). Signing in with `az login` authenticates the server to Azure OpenAI, not users to the AG-UI endpoint.
7+
58
## Prerequisites
69

710
- .NET 9.0 or later
@@ -223,9 +226,62 @@ dotnet run
223226

224227
## Security considerations
225228

226-
`ConversationId` keeps request/response continuity. It is not proof that the caller owns that conversation. In multi-user deployments, authenticate each AG-UI request and authorize conversation access using your application's real boundary, such as the authenticated user, tenant, or workspace.
229+
See the [shared hosting guide](../../04-hosting/README.md) for the common authentication, authorization, and isolation model, including differences between AG-UI, A2A, and OpenAI hosting.
230+
231+
### Endpoint access and session isolation are separate controls
232+
233+
The AG-UI `threadId` identifies a conversation to resume; it does not prove that the caller owns it. `AGUIChatClient` does not expose an `IChatClient` `ConversationId`, so do not rely on that property to authorize AG-UI requests.
234+
235+
Multi-user hosts need both controls:
236+
237+
- **Authentication and authorization:** Validate the caller's credentials and require authorization on the AG-UI endpoint. `AddAGUIServer()` and `MapAGUIServer()` do not configure these controls. Protect endpoints even without session persistence, because callers can consume model resources and invoke the agent's exposed tools.
238+
- **Session isolation:** Register an `AgentIsolationKeyProvider` so persisted sessions are partitioned by a trusted caller identity. Authentication alone does not prevent one authenticated caller from supplying another caller's `threadId`.
239+
240+
`MapAGUIServer` automatically wraps a keyed `AgentSessionStore` in `IsolationKeyScopedAgentSessionStore` unless the decorator is already present. Both session lookups and saves use the isolation partition. Two users presenting the same `threadId` therefore access different sessions when their isolation keys differ. This applies to directly registered stores, including the Step04 sample; using `WithSessionStore(...)` or `WithInMemorySessionStore(...)` is not required for the endpoint to add the wrapper.
241+
242+
Without a provider, the endpoint-added wrapper leaves storage keys unchanged. Any caller who knows a persisted thread's ID can then resume that session. With a provider, that wrapper rejects missing or blank isolation keys instead of falling back to shared storage. A preconfigured isolation decorator retains its own options; the `WithSessionStore(...)` and `WithInMemorySessionStore(...)` helpers use strict isolation by default, requiring a key even if no provider was registered.
243+
244+
If no session store is registered, sessions are not persisted across requests. Step04 explicitly enables persistence because approval continuations require server-recorded state. Approval matching does not replace caller isolation or endpoint authorization.
245+
246+
### Configure a multi-user host
247+
248+
Reference `Microsoft.Agents.AI.Hosting.AspNetCore` for the claims-based provider and import `Microsoft.Agents.AI.Hosting`. Configure a real [ASP.NET Core authentication scheme](https://learn.microsoft.com/aspnet/core/security/authentication/) for your application first, using `AddAuthentication(...).Add...(...)` to validate the credentials your clients send. The following additions are **not** a replacement for that scheme.
249+
250+
Before `builder.Build()`:
251+
252+
```csharp
253+
using Microsoft.Agents.AI.Hosting;
254+
255+
// Keep the application's authentication scheme registration here.
256+
builder.Services.AddAuthorization();
257+
builder.Services.AddHttpContextAccessor();
258+
builder.Services.UseClaimsBasedAgentIsolation();
259+
```
260+
261+
After `builder.Build()`, use the sample's existing agent when mapping the endpoint:
262+
263+
```csharp
264+
app.UseAuthentication();
265+
app.UseAuthorization();
266+
267+
app.MapAGUIServer("/", agent).RequireAuthorization();
268+
```
269+
270+
Use the sample's actual route and agent variable (`baseAgent` in Step04), or apply `RequireAuthorization()` to the named-agent overload. For a host with multiple AG-UI endpoints, protect each one or their route group. Use an application-specific authorization policy when only some authenticated callers may access an agent; tools must also enforce any resource-specific permissions they require.
271+
272+
`UseClaimsBasedAgentIsolation()` defaults to `ClaimTypes.NameIdentifier`. Your authentication scheme must populate that claim with a stable identifier unique across all callers served by the host. If it exposes the subject as an unmapped `sub` claim, configure the provider explicitly:
273+
274+
```csharp
275+
builder.Services.UseClaimsBasedAgentIsolation(new() { ClaimType = "sub" });
276+
```
277+
278+
Use this instead of the default registration, not in addition to it. A subject or object ID may only be unique within one issuer or tenant. Hosts accepting multiple issuers or tenants may need a custom `AgentIsolationKeyProvider` that combines validated issuer/tenant and subject values. Do not use display names, client-submitted user IDs, or `threadId` as caller identity. A tenant-only key intentionally shares sessions within that tenant; use a per-user key when users within a tenant must be isolated.
279+
280+
### Authenticate every client request
281+
282+
Clients must send the authenticated caller's credentials on every AG-UI request, including tool continuations and approval responses. Configure the `HttpClient` used by `AGUIChatClient` for your authentication scheme, and handle challenges or authorization failures. The sample clients do not acquire or send these credentials as shipped.
227283

228-
If your ASP.NET Core host shares session storage across users, pair `MapAGUIServer` with an isolation strategy such as `UseClaimsBasedAgentIsolation(...)` so the storage key includes a principal-specific dimension instead of relying on the conversation identifier alone.
284+
For a web application that forwards requests to a separate AG-UI server, signing a user into the web application does not automatically authenticate the outbound AG-UI call. Propagate an appropriate validated per-user credential; a single shared service identity would place all users in the same isolation partition.
229285

230286
## Troubleshooting
231287

‎dotnet/samples/02-agents/AGUI/Step01_GettingStarted/Server/Program.cs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,12 @@
1414
// make sure to also register an AgentIsolationKeyProvider to scope sessions by principal in multi-user
1515
// deployments, e.g.:
1616
// builder.Services.UseClaimsBasedAgentIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
17+
//
18+
// This sample does not authenticate AG-UI callers. Multi-user hosts must configure authentication
19+
// and enforce endpoint authorization, for example with MapAGUIServer(...).RequireAuthorization().
20+
// For claims-based isolation of persisted sessions, call builder.Services.AddHttpContextAccessor()
21+
// and builder.Services.UseClaimsBasedAgentIsolation(), using a claim that uniquely identifies each caller.
22+
// See the AG-UI samples README's "Security considerations" for configuration and client requirements.
1723

1824
WebApplication app = builder.Build();
1925

‎dotnet/samples/02-agents/AGUI/Step02_BackendTools/Server/Program.cs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,12 @@
2020
// make sure to also register an AgentIsolationKeyProvider to scope sessions by principal in multi-user
2121
// deployments, e.g.:
2222
// builder.Services.UseClaimsBasedAgentIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
23+
//
24+
// This sample does not authenticate AG-UI callers. Multi-user hosts must configure authentication
25+
// and enforce endpoint authorization, for example with MapAGUIServer(...).RequireAuthorization().
26+
// For claims-based isolation of persisted sessions, call builder.Services.AddHttpContextAccessor()
27+
// and builder.Services.UseClaimsBasedAgentIsolation(), using a claim that uniquely identifies each caller.
28+
// See the AG-UI samples README's "Security considerations" for configuration and client requirements.
2329

2430
WebApplication app = builder.Build();
2531

‎dotnet/samples/02-agents/AGUI/Step03_FrontendTools/Server/Program.cs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,12 @@
1414
// make sure to also register an AgentIsolationKeyProvider to scope sessions by principal in multi-user
1515
// deployments, e.g.:
1616
// builder.Services.UseClaimsBasedAgentIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
17+
//
18+
// This sample does not authenticate AG-UI callers. Multi-user hosts must configure authentication
19+
// and enforce endpoint authorization, for example with MapAGUIServer(...).RequireAuthorization().
20+
// For claims-based isolation of persisted sessions, call builder.Services.AddHttpContextAccessor()
21+
// and builder.Services.UseClaimsBasedAgentIsolation(), using a claim that uniquely identifies each caller.
22+
// See the AG-UI samples README's "Security considerations" for configuration and client requirements.
1723

1824
WebApplication app = builder.Build();
1925

‎dotnet/samples/02-agents/AGUI/Step04_HumanInLoop/Server/Program.cs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,12 @@
2727
// WARNING: When session persistence is enabled, in a multi-user deployment you must also register an
2828
// AgentIsolationKeyProvider to scope sessions by principal, e.g.:
2929
// builder.Services.UseClaimsBasedAgentIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
30+
//
31+
// This sample does not authenticate AG-UI callers. Multi-user hosts must configure authentication
32+
// and enforce endpoint authorization, for example with MapAGUIServer(...).RequireAuthorization().
33+
// For claims-based isolation of persisted sessions, call builder.Services.AddHttpContextAccessor()
34+
// and builder.Services.UseClaimsBasedAgentIsolation(), using a claim that uniquely identifies each caller.
35+
// See the AG-UI samples README's "Security considerations" for configuration and client requirements.
3036

3137
WebApplication app = builder.Build();
3238

‎dotnet/samples/02-agents/AGUI/Step05_StateManagement/Server/Program.cs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,12 @@
2323
// make sure to also register an AgentIsolationKeyProvider to scope sessions by principal in multi-user
2424
// deployments, e.g.:
2525
// builder.Services.UseClaimsBasedAgentIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
26+
//
27+
// This sample does not authenticate AG-UI callers. Multi-user hosts must configure authentication
28+
// and enforce endpoint authorization, for example with MapAGUIServer(...).RequireAuthorization().
29+
// For claims-based isolation of persisted sessions, call builder.Services.AddHttpContextAccessor()
30+
// and builder.Services.UseClaimsBasedAgentIsolation(), using a claim that uniquely identifies each caller.
31+
// See the AG-UI samples README's "Security considerations" for configuration and client requirements.
2632

2733
WebApplication app = builder.Build();
2834

0 commit comments

Comments
 (0)