From ea7c593dcbaef7ed85dd3ad53c5694bf5cc05d80 Mon Sep 17 00:00:00 2001 From: mguinness Date: Mon, 23 Mar 2026 18:38:39 -0700 Subject: [PATCH] Update token-based authentication section (#36622) * Update token-based authentication section Clarify token usage details and expiration settings for access and refresh tokens. * Update links to BearerTokenOptions properties * Document SignOut handling and security stamp validation Added section on SignOut handling and security stamp validation. * Fix BearerTokenOptions reference in identity API docs Updated the reference for BearerTokenOptions to correct property for token expiration. * Apply suggestions from code review Co-authored-by: Wade Pickett * Change publication date to March 23, 2026 Update the date for the identity API authorization document. --------- Co-authored-by: Wade Pickett --- .../identity-api-authorization.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/aspnetcore/security/authentication/identity-api-authorization.md b/aspnetcore/security/authentication/identity-api-authorization.md index 75551c53e7a5..b4cda3fff204 100644 --- a/aspnetcore/security/authentication/identity-api-authorization.md +++ b/aspnetcore/security/authentication/identity-api-authorization.md @@ -4,7 +4,7 @@ author: tdykstra description: Learn how to use Identity to secure a Web API backend for single page applications (SPAs). monikerRange: '>= aspnetcore-3.0' ms.author: tdykstra -ms.date: 05/01/2024 +ms.date: 03/23/2026 uid: security/authentication/identity/spa --- # How to use Identity to secure a Web API backend for SPAs @@ -204,7 +204,7 @@ Some web clients might not include cookies in the header by default: We recommend using cookies in browser-based applications, because, by default, the browser automatically handles them without exposing them to JavaScript. -A custom token (one that is proprietary to the ASP.NET Core identity platform) is issued that can be used to authenticate subsequent requests. The token is passed in the `Authorization` header as a bearer token. A refresh token is also provided. This token allows the application to request a new token when the old one expires without forcing the user to log in again. +A custom token (one that is proprietary to the ASP.NET Core identity platform) is issued that can be used to authenticate subsequent requests. The short-lived access token is passed in the `Authorization` header as a bearer token. A longer-lived refresh token is also provided. This refresh token allows the application to request a new access token when the old one expires without forcing the user to log in again. The tokens aren't standard JSON Web Tokens (JWTs). The use of custom tokens is intentional, as the built-in Identity API is meant primarily for simple scenarios. The token option isn't intended to be a full-featured identity service provider or token server, but instead an alternative to the cookie option for clients that can't use cookies. @@ -226,6 +226,17 @@ public signOut() { responseType: 'text' ``` +## SignOut everywhere + +Apps need to react to events involving security-sensitive actions such as password changes, or other security-sensitive events. This is achieved using the [security stamp](/dotnet/api/microsoft.aspnetcore.identity.identityuser-1.securitystamp) feature of Identity. + +Apps need to react to security-sensitive actions such as password changes. Identity achieves this using the [security stamp](/dotnet/api/microsoft.aspnetcore.identity.identityuser-1.securitystamp) feature: + +* For cookie-based authentication, the security stamp is periodically revalidated based on [SecurityStampValidatorOptions.ValidationInterval](/dotnet/api/microsoft.aspnetcore.identity.securitystampvalidatoroptions.validationinterval). +* For token-based authentication, the access token lifetime set by [BearerTokenOptions.BearerTokenExpiration](/dotnet/api/microsoft.aspnetcore.authentication.bearertoken.bearertokenoptions.bearertokenexpiration) limits how long a session remains active after a security-sensitive change. + +The validation interval is a balance between immediate session invalidation and database performance. A shorter interval requires more frequent database hits, while a longer one leaves a small window where an old, potentially compromised session might remain active. + ## The `MapIdentityApi` endpoints The call to `MapIdentityApi` adds the following endpoints to the app: @@ -309,6 +320,8 @@ If `useCookies` is `false` or omitted, token-based authentication is enabled. Th For more information about these properties, see . +Use the [BearerTokenOptions.BearerTokenExpiration](/dotnet/api/microsoft.aspnetcore.authentication.bearertoken.bearertokenoptions.bearertokenexpiration) property to set how long the access token remains valid. + Put the access token in a header to make authenticated requests, as shown in the following example ```http @@ -340,6 +353,8 @@ If the call is successful, the response body is a new