feat: Add UserIdentityScopedSessionStore

Add support for using the ASP.Net Core ambient `ClaimsIdentity` User, along with a user-specified claim type to scope the session store based on authenticated identity.

Co-authored-by: lokitoth <6936551+lokitoth@users.noreply.github.com>
This commit is contained in:
Jacob Alber
2026-05-07 09:50:23 -04:00
committed by GitHub
Unverified
parent dd359c5c46
commit 9d55d40493
6 changed files with 513 additions and 12 deletions
+1
View File
@@ -590,6 +590,7 @@
<Project Path="src/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
<Project Path="src/Microsoft.Agents.AI.Hosting.AzureFunctions/Microsoft.Agents.AI.Hosting.AzureFunctions.csproj" />
<Project Path="src/Microsoft.Agents.AI.Hosting.OpenAI/Microsoft.Agents.AI.Hosting.OpenAI.csproj" />
<Project Path="src/Microsoft.Agents.AI.Hosting.AspNetCore/Microsoft.Agents.AI.Hosting.AspNetCore.csproj" />
<Project Path="src/Microsoft.Agents.AI.Hosting/Microsoft.Agents.AI.Hosting.csproj" />
<Project Path="src/Microsoft.Agents.AI.Hyperlight/Microsoft.Agents.AI.Hyperlight.csproj" />
<Project Path="src/Microsoft.Agents.AI.Mem0/Microsoft.Agents.AI.Mem0.csproj" />
@@ -0,0 +1,30 @@
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>$(TargetFrameworksCore)</TargetFrameworks>
<RootNamespace>Microsoft.Agents.AI.Hosting.AspNetCore</RootNamespace>
<VersionSuffix>preview</VersionSuffix>
<NoWarn>$(NoWarn)</NoWarn>
</PropertyGroup>
<Import Project="$(RepoRoot)/dotnet/nuget/nuget-package.props" />
<PropertyGroup>
<InjectSharedThrow>true</InjectSharedThrow>
<InjectSharedDiagnosticIds>true</InjectSharedDiagnosticIds>
<InjectExperimentalAttributeOnLegacy>true</InjectExperimentalAttributeOnLegacy>
</PropertyGroup>
<ItemGroup>
<FrameworkReference Include="Microsoft.AspNetCore.App" />
</ItemGroup>
<ItemGroup>
<ProjectReference Include="..\Microsoft.Agents.AI.Hosting\Microsoft.Agents.AI.Hosting.csproj" />
</ItemGroup>
<PropertyGroup>
<!-- NuGet Package Settings -->
<Title>Microsoft Agent Framework Hosting ASP.NET Core</Title>
<Description>Provides Microsoft Agent Framework support for hosting agents in an ASP.NET Core context.</Description>
</PropertyGroup>
</Project>
@@ -0,0 +1,76 @@
// Copyright (c) Microsoft. All rights reserved.
using System;
using System.Linq;
using System.Security.Claims;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
namespace Microsoft.Agents.AI.Hosting;
/// <summary>
/// A delegating <see cref="AgentSessionStore"/> that scopes session keys by a claim value
/// extracted from the current user's identity, ensuring that sessions are isolated per user.
/// The current user is extracted from the ambient ASP.NET <see cref="HttpContext"/>.
/// </summary>
/// <remarks>
/// This relies on <see cref="IHttpContextAccessor"/>, which uses <see cref="AsyncLocal{T}"/>
/// to provide access to the current <see cref="HttpContext"/>.
/// </remarks>
public class UserIdentityScopedSessionStore : DelegatingAgentSessionStore
{
private readonly IHttpContextAccessor? _httpContextAccessor;
private readonly string _claimType;
private readonly bool _strict;
/// <summary>
/// Initializes a new instance of the <see cref="UserIdentityScopedSessionStore"/> class.
/// </summary>
/// <param name="innerStore">The underlying <see cref="AgentSessionStore"/> to delegate to.</param>
/// <param name="contextAccessor">
/// The <see cref="IHttpContextAccessor"/> used to retrieve the current user's claims.
/// </param>
/// <param name="claimType">
/// The claim type to extract from the user's identity for scoping. Defaults to <see cref="ClaimsIdentity.DefaultNameClaimType"/>.
/// </param>
/// <param name="strict">
/// If <see langword="true"/>, an exception is thrown when the specified claim is not found.
/// If <see langword="false"/>, operations proceed without scoping when the claim is absent.
/// </param>
public UserIdentityScopedSessionStore(AgentSessionStore innerStore,
IHttpContextAccessor? contextAccessor,
string claimType = ClaimsIdentity.DefaultNameClaimType,
bool strict = true) : base(innerStore)
{
this._httpContextAccessor = contextAccessor;
this._claimType = claimType;
this._strict = strict;
}
private string? GetScopeFromIdentity()
{
Claim? claim = this._httpContextAccessor?
.HttpContext?
.User?.Claims.FirstOrDefault(c => c.Type == this._claimType);
if (this._strict && claim == null)
{
throw new InvalidOperationException($"No claim of type '{this._claimType}' found in principal.");
}
return claim?.Value;
}
private string? ScopeId => this.GetScopeFromIdentity();
private string GetScopedConversationId(string bareConversationId) => $"{this.ScopeId}:{bareConversationId}";
/// <inheritdoc />
public override ValueTask<AgentSession> GetSessionAsync(AIAgent agent, string conversationId, CancellationToken cancellationToken = default)
=> this.InnerStore.GetSessionAsync(agent, this.GetScopedConversationId(conversationId), cancellationToken);
/// <inheritdoc />
public override ValueTask SaveSessionAsync(AIAgent agent, string conversationId, AgentSession session, CancellationToken cancellationToken = default)
=> this.InnerStore.SaveSessionAsync(agent, this.GetScopedConversationId(conversationId), session, cancellationToken);
}
@@ -72,20 +72,20 @@ public class DelegatingAgentSessionStoreTests
public async Task GetSessionAsyncDelegatesToInnerStoreAsync()
{
// Arrange
const string expectedConversationId = "test-conversation-id";
const string ExpectedConversationId = "test-conversation-id";
var expectedCancellationToken = new CancellationToken();
this._innerStoreMock
.Setup(x => x.GetSessionAsync(
It.Is<AIAgent>(a => a == this._agentMock.Object),
It.Is<string>(c => c == expectedConversationId),
It.Is<string>(c => c == ExpectedConversationId),
It.Is<CancellationToken>(ct => ct == expectedCancellationToken)))
.ReturnsAsync(this._testSession);
// Act
var session = await this._delegatingStore.GetSessionAsync(
this._agentMock.Object,
expectedConversationId,
ExpectedConversationId,
expectedCancellationToken);
// Assert
@@ -93,7 +93,7 @@ public class DelegatingAgentSessionStoreTests
this._innerStoreMock.Verify(
x => x.GetSessionAsync(
this._agentMock.Object,
expectedConversationId,
ExpectedConversationId,
expectedCancellationToken),
Times.Once);
}
@@ -105,14 +105,14 @@ public class DelegatingAgentSessionStoreTests
public async Task SaveSessionAsyncDelegatesToInnerStoreAsync()
{
// Arrange
const string expectedConversationId = "test-conversation-id";
const string ExpectedConversationId = "test-conversation-id";
var expectedCancellationToken = new CancellationToken();
var expectedSession = new TestAgentSession();
this._innerStoreMock
.Setup(x => x.SaveSessionAsync(
It.Is<AIAgent>(a => a == this._agentMock.Object),
It.Is<string>(c => c == expectedConversationId),
It.Is<string>(c => c == ExpectedConversationId),
It.Is<AgentSession>(s => s == expectedSession),
It.Is<CancellationToken>(ct => ct == expectedCancellationToken)))
.Returns(ValueTask.CompletedTask);
@@ -120,7 +120,7 @@ public class DelegatingAgentSessionStoreTests
// Act
await this._delegatingStore.SaveSessionAsync(
this._agentMock.Object,
expectedConversationId,
ExpectedConversationId,
expectedSession,
expectedCancellationToken);
@@ -128,7 +128,7 @@ public class DelegatingAgentSessionStoreTests
this._innerStoreMock.Verify(
x => x.SaveSessionAsync(
this._agentMock.Object,
expectedConversationId,
ExpectedConversationId,
expectedSession,
expectedCancellationToken),
Times.Once);
@@ -141,7 +141,7 @@ public class DelegatingAgentSessionStoreTests
public async Task GetSessionAsyncAwaitsInnerStoreResultAsync()
{
// Arrange
const string expectedConversationId = "test-conversation-id";
const string ExpectedConversationId = "test-conversation-id";
var taskCompletionSource = new TaskCompletionSource<AgentSession>();
var innerStoreMock = new Mock<AgentSessionStore>();
@@ -152,7 +152,7 @@ public class DelegatingAgentSessionStoreTests
var delegatingStore = new TestDelegatingAgentSessionStore(innerStoreMock.Object);
// Act
var resultTask = delegatingStore.GetSessionAsync(this._agentMock.Object, expectedConversationId);
var resultTask = delegatingStore.GetSessionAsync(this._agentMock.Object, ExpectedConversationId);
// Assert
Assert.False(resultTask.IsCompleted);
@@ -168,7 +168,7 @@ public class DelegatingAgentSessionStoreTests
public async Task SaveSessionAsyncAwaitsInnerStoreCompletionAsync()
{
// Arrange
const string expectedConversationId = "test-conversation-id";
const string ExpectedConversationId = "test-conversation-id";
var expectedSession = new TestAgentSession();
var taskCompletionSource = new TaskCompletionSource();
@@ -180,7 +180,7 @@ public class DelegatingAgentSessionStoreTests
var delegatingStore = new TestDelegatingAgentSessionStore(innerStoreMock.Object);
// Act
var resultTask = delegatingStore.SaveSessionAsync(this._agentMock.Object, expectedConversationId, expectedSession);
var resultTask = delegatingStore.SaveSessionAsync(this._agentMock.Object, ExpectedConversationId, expectedSession);
// Assert
Assert.False(resultTask.IsCompleted);
@@ -6,6 +6,7 @@
<ItemGroup>
<ProjectReference Include="..\..\src\Microsoft.Agents.AI.Hosting\Microsoft.Agents.AI.Hosting.csproj" />
<ProjectReference Include="..\..\src\Microsoft.Agents.AI.Hosting.AspNetCore\Microsoft.Agents.AI.Hosting.AspNetCore.csproj" />
</ItemGroup>
</Project>
@@ -0,0 +1,393 @@
// Copyright (c) Microsoft. All rights reserved.
using System;
using System.Security.Claims;
using System.Threading;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Moq;
namespace Microsoft.Agents.AI.Hosting.UnitTests;
/// <summary>
/// Unit tests for the <see cref="UserIdentityScopedSessionStore"/> class.
/// </summary>
public class UserIdentityScopedSessionStoreTests
{
private const string TestUserId = "test-user-id";
private const string TestConversationId = "test-conversation-id";
private const string CustomClaimType = "custom-claim-type";
private const string CustomClaimValue = "custom-claim-value";
private const string User1 = "user-1";
private const string User2 = "user-2";
private readonly Mock<AgentSessionStore> _innerStoreMock;
private readonly Mock<AIAgent> _agentMock;
private readonly Mock<IHttpContextAccessor> _httpContextAccessorMock;
private readonly AgentSession _testSession;
/// <summary>
/// Initializes a new instance of the <see cref="UserIdentityScopedSessionStoreTests"/> class.
/// </summary>
public UserIdentityScopedSessionStoreTests()
{
this._innerStoreMock = new Mock<AgentSessionStore>();
this._agentMock = new Mock<AIAgent>();
this._httpContextAccessorMock = new Mock<IHttpContextAccessor>();
this._testSession = new TestAgentSession();
this._innerStoreMock
.Setup(x => x.GetSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<CancellationToken>()))
.ReturnsAsync(this._testSession);
this._innerStoreMock
.Setup(x => x.SaveSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<AgentSession>(), It.IsAny<CancellationToken>()))
.Returns(ValueTask.CompletedTask);
}
#region Constructor Tests
/// <summary>
/// Verify that constructor throws ArgumentNullException when innerStore is null.
/// </summary>
[Fact]
public void RequiresInnerStore() =>
Assert.Throws<ArgumentNullException>("innerStore", () => new UserIdentityScopedSessionStore(null!, this._httpContextAccessorMock.Object));
/// <summary>
/// Verify that constructor accepts null IHttpContextAccessor.
/// </summary>
[Fact]
public void Constructor_WithNullHttpContextAccessor_DoesNotThrow()
{
// Act & Assert - should not throw
var store = new UserIdentityScopedSessionStore(this._innerStoreMock.Object, contextAccessor: null, strict: false);
Assert.NotNull(store);
}
#endregion
#region GetSessionAsync Tests
/// <summary>
/// Verify that GetSessionAsync scopes the conversation ID with the user's claim value.
/// </summary>
[Fact]
public async Task GetSessionAsyncScopesConversationIdWithUserClaimAsync()
{
// Arrange
this.SetupHttpContextWithClaim(ClaimsIdentity.DefaultNameClaimType, TestUserId);
var store = new UserIdentityScopedSessionStore(this._innerStoreMock.Object, this._httpContextAccessorMock.Object);
// Act
await store.GetSessionAsync(this._agentMock.Object, TestConversationId);
// Assert
this._innerStoreMock.Verify(
x => x.GetSessionAsync(
this._agentMock.Object,
$"{TestUserId}:{TestConversationId}",
It.IsAny<CancellationToken>()),
Times.Once);
}
/// <summary>
/// Verify that GetSessionAsync uses custom claim type when specified.
/// </summary>
[Fact]
public async Task GetSessionAsyncUsesCustomClaimTypeAsync()
{
// Arrange
this.SetupHttpContextWithClaim(CustomClaimType, CustomClaimValue);
var store = new UserIdentityScopedSessionStore(
this._innerStoreMock.Object,
this._httpContextAccessorMock.Object,
claimType: CustomClaimType);
// Act
await store.GetSessionAsync(this._agentMock.Object, TestConversationId);
// Assert
this._innerStoreMock.Verify(
x => x.GetSessionAsync(
this._agentMock.Object,
$"{CustomClaimValue}:{TestConversationId}",
It.IsAny<CancellationToken>()),
Times.Once);
}
/// <summary>
/// Verify that GetSessionAsync throws InvalidOperationException when claim is missing in strict mode.
/// </summary>
[Fact]
public async Task GetSessionAsyncThrowsWhenClaimMissingInStrictModeAsync()
{
// Arrange
this.SetupHttpContextWithClaim("other-claim", "value");
var store = new UserIdentityScopedSessionStore(
this._innerStoreMock.Object,
this._httpContextAccessorMock.Object,
strict: true);
// Act & Assert
var exception = await Assert.ThrowsAsync<InvalidOperationException>(
async () => await store.GetSessionAsync(this._agentMock.Object, TestConversationId));
Assert.Contains(ClaimsIdentity.DefaultNameClaimType, exception.Message);
}
/// <summary>
/// Verify that GetSessionAsync does not throw when claim is missing in non-strict mode.
/// </summary>
[Fact]
public async Task GetSessionAsyncDoesNotThrowWhenClaimMissingInNonStrictModeAsync()
{
// Arrange
this.SetupHttpContextWithClaim("other-claim", "value");
var store = new UserIdentityScopedSessionStore(
this._innerStoreMock.Object,
this._httpContextAccessorMock.Object,
strict: false);
// Act - should not throw
await store.GetSessionAsync(this._agentMock.Object, TestConversationId);
// Assert - conversation ID should use null scope
this._innerStoreMock.Verify(
x => x.GetSessionAsync(
this._agentMock.Object,
$":{TestConversationId}",
It.IsAny<CancellationToken>()),
Times.Once);
}
/// <summary>
/// Verify that GetSessionAsync returns the session from the inner store.
/// </summary>
[Fact]
public async Task GetSessionAsyncReturnsSessionFromInnerStoreAsync()
{
// Arrange
this.SetupHttpContextWithClaim(ClaimsIdentity.DefaultNameClaimType, TestUserId);
var store = new UserIdentityScopedSessionStore(this._innerStoreMock.Object, this._httpContextAccessorMock.Object);
// Act
var result = await store.GetSessionAsync(this._agentMock.Object, TestConversationId);
// Assert
Assert.Same(this._testSession, result);
}
#endregion
#region SaveSessionAsync Tests
/// <summary>
/// Verify that SaveSessionAsync scopes the conversation ID with the user's claim value.
/// </summary>
[Fact]
public async Task SaveSessionAsyncScopesConversationIdWithUserClaimAsync()
{
// Arrange
this.SetupHttpContextWithClaim(ClaimsIdentity.DefaultNameClaimType, TestUserId);
var store = new UserIdentityScopedSessionStore(this._innerStoreMock.Object, this._httpContextAccessorMock.Object);
var sessionToSave = new TestAgentSession();
// Act
await store.SaveSessionAsync(this._agentMock.Object, TestConversationId, sessionToSave);
// Assert
this._innerStoreMock.Verify(
x => x.SaveSessionAsync(
this._agentMock.Object,
$"{TestUserId}:{TestConversationId}",
sessionToSave,
It.IsAny<CancellationToken>()),
Times.Once);
}
/// <summary>
/// Verify that SaveSessionAsync uses custom claim type when specified.
/// </summary>
[Fact]
public async Task SaveSessionAsyncUsesCustomClaimTypeAsync()
{
// Arrange
this.SetupHttpContextWithClaim(CustomClaimType, CustomClaimValue);
var store = new UserIdentityScopedSessionStore(
this._innerStoreMock.Object,
this._httpContextAccessorMock.Object,
claimType: CustomClaimType);
var sessionToSave = new TestAgentSession();
// Act
await store.SaveSessionAsync(this._agentMock.Object, TestConversationId, sessionToSave);
// Assert
this._innerStoreMock.Verify(
x => x.SaveSessionAsync(
this._agentMock.Object,
$"{CustomClaimValue}:{TestConversationId}",
sessionToSave,
It.IsAny<CancellationToken>()),
Times.Once);
}
/// <summary>
/// Verify that SaveSessionAsync throws InvalidOperationException when claim is missing in strict mode.
/// </summary>
[Fact]
public async Task SaveSessionAsyncThrowsWhenClaimMissingInStrictModeAsync()
{
// Arrange
this.SetupHttpContextWithClaim("other-claim", "value");
var store = new UserIdentityScopedSessionStore(
this._innerStoreMock.Object,
this._httpContextAccessorMock.Object,
strict: true);
var sessionToSave = new TestAgentSession();
// Act & Assert
var exception = await Assert.ThrowsAsync<InvalidOperationException>(
async () => await store.SaveSessionAsync(this._agentMock.Object, TestConversationId, sessionToSave));
Assert.Contains(ClaimsIdentity.DefaultNameClaimType, exception.Message);
}
/// <summary>
/// Verify that SaveSessionAsync does not throw when claim is missing in non-strict mode.
/// </summary>
[Fact]
public async Task SaveSessionAsyncDoesNotThrowWhenClaimMissingInNonStrictModeAsync()
{
// Arrange
this.SetupHttpContextWithClaim("other-claim", "value");
var store = new UserIdentityScopedSessionStore(
this._innerStoreMock.Object,
this._httpContextAccessorMock.Object,
strict: false);
var sessionToSave = new TestAgentSession();
// Act - should not throw
await store.SaveSessionAsync(this._agentMock.Object, TestConversationId, sessionToSave);
// Assert - conversation ID should use null scope
this._innerStoreMock.Verify(
x => x.SaveSessionAsync(
this._agentMock.Object,
$":{TestConversationId}",
sessionToSave,
It.IsAny<CancellationToken>()),
Times.Once);
}
#endregion
#region Edge Cases
/// <summary>
/// Verify behavior when HttpContextAccessor returns null HttpContext.
/// </summary>
[Fact]
public async Task WhenHttpContextIsNullAndStrictThrowsAsync()
{
// Arrange
this._httpContextAccessorMock.Setup(x => x.HttpContext).Returns((HttpContext?)null);
var store = new UserIdentityScopedSessionStore(
this._innerStoreMock.Object,
this._httpContextAccessorMock.Object,
strict: true);
// Act & Assert
await Assert.ThrowsAsync<InvalidOperationException>(
async () => await store.GetSessionAsync(this._agentMock.Object, TestConversationId));
}
/// <summary>
/// Verify behavior when HttpContextAccessor returns null HttpContext in non-strict mode.
/// </summary>
[Fact]
public async Task WhenHttpContextIsNullAndNonStrictProceedsAsync()
{
// Arrange
this._httpContextAccessorMock.Setup(x => x.HttpContext).Returns((HttpContext?)null);
var store = new UserIdentityScopedSessionStore(
this._innerStoreMock.Object,
this._httpContextAccessorMock.Object,
strict: false);
// Act - should not throw
await store.GetSessionAsync(this._agentMock.Object, TestConversationId);
// Assert
this._innerStoreMock.Verify(
x => x.GetSessionAsync(
this._agentMock.Object,
$":{TestConversationId}",
It.IsAny<CancellationToken>()),
Times.Once);
}
/// <summary>
/// Verify that different users get different scoped conversation IDs.
/// </summary>
[Fact]
public async Task DifferentUsersGetDifferentScopedConversationIdsAsync()
{
// Arrange
string? capturedConversationId1 = null;
string? capturedConversationId2 = null;
this._innerStoreMock
.Setup(x => x.GetSessionAsync(It.IsAny<AIAgent>(), It.IsAny<string>(), It.IsAny<CancellationToken>()))
.Callback<AIAgent, string, CancellationToken>((_, conversationId, _) =>
{
if (capturedConversationId1 == null)
{
capturedConversationId1 = conversationId;
}
else
{
capturedConversationId2 = conversationId;
}
})
.ReturnsAsync(this._testSession);
// Act - User 1
this.SetupHttpContextWithClaim(ClaimsIdentity.DefaultNameClaimType, User1);
var store1 = new UserIdentityScopedSessionStore(this._innerStoreMock.Object, this._httpContextAccessorMock.Object);
await store1.GetSessionAsync(this._agentMock.Object, TestConversationId);
// Act - User 2
this.SetupHttpContextWithClaim(ClaimsIdentity.DefaultNameClaimType, User2);
var store2 = new UserIdentityScopedSessionStore(this._innerStoreMock.Object, this._httpContextAccessorMock.Object);
await store2.GetSessionAsync(this._agentMock.Object, TestConversationId);
// Assert
Assert.Equal($"{User1}:{TestConversationId}", capturedConversationId1);
Assert.Equal($"{User2}:{TestConversationId}", capturedConversationId2);
Assert.NotEqual(capturedConversationId1, capturedConversationId2);
}
#endregion
#region Helper Methods
private void SetupHttpContextWithClaim(string claimType, string claimValue)
{
var claims = new[] { new Claim(claimType, claimValue) };
var identity = new ClaimsIdentity(claims);
var principal = new ClaimsPrincipal(identity);
var httpContext = new DefaultHttpContext
{
User = principal
};
this._httpContextAccessorMock.Setup(x => x.HttpContext).Returns(httpContext);
}
private sealed class TestAgentSession : AgentSession;
#endregion
}