Skip to content

Document SignalR authentication refresh (.NET 11) - #37537

Open
BrennanConroy wants to merge 1 commit into
mainfrom
brennanconroy-signalr-auth-refresh
Open

Document SignalR authentication refresh (.NET 11)#37537
BrennanConroy wants to merge 1 commit into
mainfrom
brennanconroy-signalr-auth-refresh

Conversation

@BrennanConroy

@BrennanConroy BrennanConroy commented Aug 25, 2026

Copy link
Copy Markdown
Member

.NET 11 adds SignalR authentication refresh, which lets a connected client update its authentication credentials for an active connection without dropping and reconnecting. This PR documents the feature across the SignalR docs.

What's documented

authn-and-authz.md (main feature section, gated to >= aspnetcore-11.0):

  • Enable refresh on the server (EnableAuthenticationRefresh, paired with CloseOnAuthenticationExpiration as the safety net that closes connections which aren't refreshed before their token expires).
  • Refresh from the .NET client (WithAuthenticationRefresh, RefreshAuthenticationAsync, and the AuthenticationRefreshed / AuthenticationRefreshFailed events).
  • Refresh from the JavaScript client (withAuthenticationRefresh, refreshAuthentication, onAuthenticationRefreshed / onAuthenticationRefreshFailed).
  • React to a refresh in the hub (OnAuthenticationRefreshedAsync).
  • Bidirectional cross-links with the existing "User and role changes during the connection lifetime" section.

configuration.md: Adds the new HttpConnectionDispatcherOptions members (EnableAuthenticationRefresh, MaximumAuthenticationExpiration, OnAuthenticationRefresh) to the advanced HTTP options table.

client-features.md: Adds an "Authentication Refresh" row to the client feature matrix (Server / .NET / JavaScript = 11.0.0; Java and Swift not supported).

Notes for reviewers

  • Every API name, signature, default, and behavior was verified against current dotnet/aspnetcore main source rather than the original API proposal. Some behavior changed late: a refresh whose principal maps to a different SignalR user is rejected with HTTP 403 (the connection stays alive with its current user), and a refresh never rekeys Context.UserIdentifier or Clients.User routing. The client callbacks also moved off the options object onto HubConnection events.
  • Preview APIs aren't in the API browser yet, so they're written as inline code instead of <xref:> to avoid unresolved-xref build warnings.
  • New content is moniker-gated to >= aspnetcore-11.0 using the close/reopen pattern, since Learn monikers can't nest.
  • Blazor's ComponentHub override of OnAuthenticationRefreshedAsync is intentionally out of scope here; it belongs in the Blazor docs.

Internal previews

File Preview link
aspnetcore/signalr/authn-and-authz.md aspnetcore/signalr/authn-and-authz
aspnetcore/signalr/client-features.md aspnetcore/signalr/client-features
aspnetcore/signalr/configuration.md aspnetcore/signalr/configuration

Add documentation for the new SignalR authentication refresh feature, which lets a
connected client update its authentication credentials for an active connection without
reconnecting.

- authn-and-authz.md: Add an "Authentication refresh" section (gated to .NET 11) covering
  how to enable it on the server, refresh from the .NET and JavaScript clients, and react
  to a refresh in the hub. Cross-link the "User and role changes" section.
- configuration.md: Document the new HttpConnectionDispatcherOptions members
  (EnableAuthenticationRefresh, MaximumAuthenticationExpiration, OnAuthenticationRefresh)
  in the advanced HTTP options.
- client-features.md: Add an "Authentication Refresh" row to the client feature matrix.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@BrennanConroy
BrennanConroy force-pushed the brennanconroy-signalr-auth-refresh branch from dec62a2 to 0780a6c Compare August 25, 2026 22:27

@wadepickett wadepickett left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@BrennanConroy: Approved. Looks great, I'm not spotting any issues. I'll put off merging however until the original requested reviewer has a chance to look it over.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants