Skip to content

Update token-based authentication section #36622

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mguinness wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Update token-based authentication section #36622

Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
4773fc0
Update token-based authentication section
mguinness Jan 13, 2026
5a933f9
Update links to BearerTokenOptions properties
mguinness Jan 13, 2026
769ca00
Document SignOut handling and security stamp validation
mguinness Jan 14, 2026
b5b8401
Fix BearerTokenOptions reference in identity API docs
mguinness Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 13 additions & 1 deletion aspnetcore/security/authentication/identity-api-authorization.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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.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.

## The `MapIdentityApi<TUser>` endpoints

The call to `MapIdentityApi<TUser>` adds the following endpoints to the app:
Expand Down Expand Up @@ -309,6 +317,8 @@ If `useCookies` is `false` or omitted, token-based authentication is enabled. Th

For more information about these properties, see <xref:Microsoft.AspNetCore.Authentication.BearerToken.AccessTokenResponse>.

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

```http
Expand Down Expand Up @@ -340,6 +350,8 @@ If the call is successful, the response body is a new <xref:Microsoft.AspNetCore
}
```

Use the [BearerTokenOptions.RefreshTokenExpiration](/dotnet/api/microsoft.aspnetcore.authentication.bearertoken.bearertokenoptions.refreshtokenexpiration) property to set how long the refresh token will remain valid for.

## Use the `GET /confirmEmail` endpoint

If Identity is set up for email confirmation, a successful call to the `/register` endpoint sends an email that contains a link to the `/confirmEmail` endpoint. The link contains the following query string parameters:
Expand Down