From 4773fc0799389e05ae4b91912ac59cc4820eb37a Mon Sep 17 00:00:00 2001 From: mguinness Date: Tue, 13 Jan 2026 14:49:35 -0800 Subject: [PATCH 1/4] Update token-based authentication section Clarify token usage details and expiration settings for access and refresh tokens. --- .../security/authentication/identity-api-authorization.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/aspnetcore/security/authentication/identity-api-authorization.md b/aspnetcore/security/authentication/identity-api-authorization.md index 75551c53e7a5..47c216f34f7c 100644 --- a/aspnetcore/security/authentication/identity-api-authorization.md +++ b/aspnetcore/security/authentication/identity-api-authorization.md @@ -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. @@ -309,6 +309,8 @@ If `useCookies` is `false` or omitted, token-based authentication is enabled. Th For more information about these properties, see . +Use the [BearerTokenOptions.BearerTokenExpiration](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.bearertoken.bearertokenoptions.bearertokenexpiration) property to set how long the access token will remain valid for. + Put the access token in a header to make authenticated requests, as shown in the following example ```http @@ -340,6 +342,8 @@ If the call is successful, the response body is a new Date: Tue, 13 Jan 2026 15:14:54 -0800 Subject: [PATCH 2/4] Update links to BearerTokenOptions properties --- .../security/authentication/identity-api-authorization.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/aspnetcore/security/authentication/identity-api-authorization.md b/aspnetcore/security/authentication/identity-api-authorization.md index 47c216f34f7c..0fafca32320e 100644 --- a/aspnetcore/security/authentication/identity-api-authorization.md +++ b/aspnetcore/security/authentication/identity-api-authorization.md @@ -309,7 +309,7 @@ If `useCookies` is `false` or omitted, token-based authentication is enabled. Th For more information about these properties, see . -Use the [BearerTokenOptions.BearerTokenExpiration](https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.authentication.bearertoken.bearertokenoptions.bearertokenexpiration) property to set how long the access token will remain valid for. +Use the [BearerTokenOptions.BearerTokenExpiration](/dotnet/api/microsoft.aspnetcore.authentication.bearertoken.bearertokenoptions.bearertokenexpiration) property to set how long the access token will remain valid for. Put the access token in a header to make authenticated requests, as shown in the following example @@ -342,7 +342,7 @@ If the call is successful, the response body is a new Date: Wed, 14 Jan 2026 10:44:48 -0800 Subject: [PATCH 3/4] Document SignOut handling and security stamp validation Added section on SignOut handling and security stamp validation. --- .../security/authentication/identity-api-authorization.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/aspnetcore/security/authentication/identity-api-authorization.md b/aspnetcore/security/authentication/identity-api-authorization.md index 0fafca32320e..8c905dc20b2d 100644 --- a/aspnetcore/security/authentication/identity-api-authorization.md +++ b/aspnetcore/security/authentication/identity-api-authorization.md @@ -226,6 +226,14 @@ public signOut() { responseType: 'text' ``` +## SignOut everywhere + +Apps need to react to events involving security sensitive actions like changed password, or other security sensitive events. This is achieved using the [security stamp](/dotnet/api/microsoft.aspnetcore.identity.identityuser-1.securitystamp) feature of Identity. + +How often the security stamp is validated is configured using [SecurityStampValidatorOptions.ValidationInterval](/dotnet/api/microsoft.aspnetcore.identity.securitystampvalidatoroptions.validationinterval) for cookie-based authentication, or [BearerTokenOptions.RefreshTokenExpiration](/dotnet/api/microsoft.aspnetcore.authentication.bearertoken.bearertokenoptions.refreshtokenexpiration) for token-based authentication. + +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: From b5b84015040e3313879ec26a735ad463398fc5fa Mon Sep 17 00:00:00 2001 From: mguinness Date: Wed, 14 Jan 2026 10:56:00 -0800 Subject: [PATCH 4/4] Fix BearerTokenOptions reference in identity API docs Updated the reference for BearerTokenOptions to correct property for token expiration. --- .../security/authentication/identity-api-authorization.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/aspnetcore/security/authentication/identity-api-authorization.md b/aspnetcore/security/authentication/identity-api-authorization.md index 8c905dc20b2d..389cfc1c9eac 100644 --- a/aspnetcore/security/authentication/identity-api-authorization.md +++ b/aspnetcore/security/authentication/identity-api-authorization.md @@ -230,7 +230,7 @@ public signOut() { Apps need to react to events involving security sensitive actions like changed password, or other security sensitive events. This is achieved using the [security stamp](/dotnet/api/microsoft.aspnetcore.identity.identityuser-1.securitystamp) feature of Identity. -How often the security stamp is validated is configured using [SecurityStampValidatorOptions.ValidationInterval](/dotnet/api/microsoft.aspnetcore.identity.securitystampvalidatoroptions.validationinterval) for cookie-based authentication, or [BearerTokenOptions.RefreshTokenExpiration](/dotnet/api/microsoft.aspnetcore.authentication.bearertoken.bearertokenoptions.refreshtokenexpiration) for token-based authentication. +How often the security stamp is validated is configured using [SecurityStampValidatorOptions.ValidationInterval](/dotnet/api/microsoft.aspnetcore.identity.securitystampvalidatoroptions.validationinterval) for cookie-based authentication, or [BearerTokenOptions.BearerTokenExpiration](/dotnet/api/microsoft.aspnetcore.authentication.bearertoken.bearertokenoptions.bearertokenexpiration) for token-based authentication. 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.