--- title: Use cookie authentication without ASP.NET Core Identity author: rick-anderson description: Learn how to use cookie authentication without ASP.NET Core Identity. monikerRange: '>= aspnetcore-3.1' ms.author: riande ms.date: 1/1/2022 uid: security/authentication/cookie --- # Use cookie authentication without ASP.NET Core Identity By [Rick Anderson](https://twitter.com/RickAndMSFT) :::moniker range=">= aspnetcore-6.0" [ASP.NET Core Identity](xref:security/authentication/identity) is a complete, full-featured authentication provider for creating and maintaining logins. However, a cookie-based authentication provider without ASP.NET Core Identity can be used. For more information, see . [View or download sample code](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/security/authentication/cookie/samples) ([how to download](xref:index#how-to-download-a-sample)) For demonstration purposes in the sample app, the user account for the hypothetical user, Maria Rodriguez, is hardcoded into the app. Use the **Email** address `maria.rodriguez@contoso.com` and any password to sign in the user. The user is authenticated in the `AuthenticateUser` method in the `Pages/Account/Login.cshtml.cs` file. In a real-world example, the user would be authenticated against a datastore. ## Add cookie authentication * Add the Authentication Middleware services with the and methods. * Call and to set the `HttpContext.User` property and run the Authorization Middleware for requests. `UseAuthentication` and `UseAuthorization` must be called before `Map` methods such as and [!code-csharp[](cookie/samples/6.x/CookieSample/Program.cs?name=snippet1&highlight=8-9,24-28)] passed to `AddAuthentication` sets the default authentication scheme for the app. `AuthenticationScheme` is useful when there are multiple instances of cookie authentication and the app needs to [authorize with a specific scheme](xref:security/authorization/limitingidentitybyscheme). Setting the `AuthenticationScheme` to [CookieAuthenticationDefaults.AuthenticationScheme](xref:Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationDefaults.AuthenticationScheme) provides a value of `"Cookies"` for the scheme. Any string value can be used that distinguishes the scheme. The app's authentication scheme is different from the app's cookie authentication scheme. When a cookie authentication scheme isn't provided to , it uses [`CookieAuthenticationDefaults.AuthenticationScheme`](xref:Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationDefaults.AuthenticationScheme). [The `CookieAuthenticationDefaults.AuthenticationScheme` GitHub Source](https://github.com/dotnet/aspnetcore/blob/v6.0.1/src/Security/Authentication/Cookies/src/CookieAuthenticationDefaults.cs#L16) shows it's set to `"Cookies"`. The authentication cookie's property is set to `true` by default. Authentication cookies are allowed when a site visitor hasn't consented to data collection. For more information, see . The class is used to configure the authentication provider options. Configure in the method: [!code-csharp[](cookie/samples/6.x/CookieSample/Program.cs?name=snippet2&highlight=8-14)] ## Cookie Policy Middleware The [Cookie Policy Middleware (GitHub Source)](https://github.com/dotnet/aspnetcore/blob/main/src/Security/CookiePolicy/src/CookiePolicyMiddleware.cs) enables cookie policy capabilities. Middleware is processed in the order it's added: ```csharp app.UseCookiePolicy(cookiePolicyOptions); ``` Use provided to the Cookie Policy Middleware to control global characteristics of cookie processing and hook into cookie processing handlers when cookies are appended or deleted. The default value is `SameSiteMode.Lax` to permit OAuth2 authentication. To strictly enforce a same-site policy of `SameSiteMode.Strict`, set the `MinimumSameSitePolicy`. Although this setting breaks OAuth2 and other cross-origin authentication schemes, it elevates the level of cookie security for other types of apps that don't rely on cross-origin request processing. ```csharp var cookiePolicyOptions = new CookiePolicyOptions { MinimumSameSitePolicy = SameSiteMode.Strict, }; ``` The Cookie Policy Middleware setting for `MinimumSameSitePolicy` can affect the setting of `Cookie.SameSite` in `CookieAuthenticationOptions` settings according to the matrix below. | MinimumSameSitePolicy | Cookie.SameSite | Resultant Cookie.SameSite setting | | --------------------- | --------------- | --------------------------------- | | SameSiteMode.None | SameSiteMode.None
SameSiteMode.Lax
SameSiteMode.Strict | SameSiteMode.None
SameSiteMode.Lax
SameSiteMode.Strict | | SameSiteMode.Lax | SameSiteMode.None
SameSiteMode.Lax
SameSiteMode.Strict | SameSiteMode.Lax
SameSiteMode.Lax
SameSiteMode.Strict | | SameSiteMode.Strict | SameSiteMode.None
SameSiteMode.Lax
SameSiteMode.Strict | SameSiteMode.Strict
SameSiteMode.Strict
SameSiteMode.Strict | ## Create an authentication cookie To create a cookie holding user information, construct a . The user information is serialized and stored in the cookie. Create a with any required s and call to sign in the user. `Login.cshtml.cs` in the sample app contains the following code: [!code-csharp[](cookie/samples/6.x/CookieSample/Pages/Account/Login.cshtml.cs?name=snippet1&highlight=22-59)] [!INCLUDE[request localized comments](~/includes/code-comments-loc.md)] `SignInAsync` creates an encrypted cookie and adds it to the current response. If `AuthenticationScheme` isn't specified, the default scheme is used. is only used on a few specific paths by default, for example, the login path and logout paths. For more information see the [CookieAuthenticationHandler source](https://github.com/dotnet/aspnetcore/blob/f2e6e6ff334176540ef0b3291122e359c2106d1a/src/Security/Authentication/Cookies/src/CookieAuthenticationHandler.cs#L334). ASP.NET Core's [Data Protection](xref:security/data-protection/using-data-protection) system is used for encryption. For an app hosted on multiple machines, load balancing across apps, or using a web farm, [configure data protection](xref:security/data-protection/configuration/overview) to use the same key ring and app identifier. ## Sign out To sign out the current user and delete their cookie, call : [!code-csharp[](cookie/samples/6.x/CookieSample/Pages/Account/Login.cshtml.cs?name=snippet2)] If `CookieAuthenticationDefaults.AuthenticationScheme` or ["Cookies"](https://github.com/dotnet/aspnetcore/blob/v6.0.1/src/Security/Authentication/Cookies/src/CookieAuthenticationDefaults.cs#L16) isn't used as the scheme, supply the scheme used when configuring the authentication provider. Otherwise, the default scheme is used. For example, if "ContosoCookie" is used as the scheme, supply the scheme used when configuring the authentication provider. When the browser closes it automatically deletes session based cookies (non-persistent cookies), but no cookies are cleared when an individual tab is closed. The server is not notified of tab or browser close events. ## React to back-end changes Once a cookie is created, the cookie is the single source of identity. If a user account is disabled in back-end systems: * The app's cookie authentication system continues to process requests based on the authentication cookie. * The user remains signed into the app as long as the authentication cookie is valid. The event can be used to intercept and override validation of the cookie identity. Validating the cookie on every request mitigates the risk of revoked users accessing the app. One approach to cookie validation is based on keeping track of when the user database changes. If the database hasn't been changed since the user's cookie was issued, there's no need to re-authenticate the user if their cookie is still valid. In the sample app, the database is implemented in `IUserRepository` and stores a `LastChanged` value. When a user is updated in the database, the `LastChanged` value is set to the current time. In order to invalidate a cookie when the database changes based on the `LastChanged` value, create the cookie with a `LastChanged` claim containing the current `LastChanged` value from the database: ```csharp var claims = new List { new Claim(ClaimTypes.Name, user.Email), new Claim("LastChanged", {Database Value}) }; var claimsIdentity = new ClaimsIdentity( claims, CookieAuthenticationDefaults.AuthenticationScheme); await HttpContext.SignInAsync( CookieAuthenticationDefaults.AuthenticationScheme, new ClaimsPrincipal(claimsIdentity)); ``` To implement an override for the `ValidatePrincipal` event, write a method with the following signature in a class that derives from : ```csharp ValidatePrincipal(CookieValidatePrincipalContext) ``` The following is an example implementation of `CookieAuthenticationEvents`: [!code-csharp[](cookie/samples/6.x/CookieSample/CookieAuthenticationEvents.cs?name=snippet)] Register the events instance during cookie service registration. Provide a [scoped service registration](xref:fundamentals/dependency-injection#service-lifetimes) for your `CustomCookieAuthenticationEvents` class: [!code-csharp[](cookie/samples/6.x/CookieSample/Program.cs?name=snippet_cc&highlight=8-14)] Consider a situation in which the user's name is updated—a decision that doesn't affect security in any way. If you want to non-destructively update the user principal, call `context.ReplacePrincipal` and set the `context.ShouldRenew` property to `true`. > [!WARNING] > The approach described here is triggered on every request. Validating authentication cookies for all users on every request can result in a large performance penalty for the app. ## Persistent cookies You may want the cookie to persist across browser sessions. This persistence should only be enabled with explicit user consent with a "Remember Me" checkbox on sign in or a similar mechanism. The following code snippet creates an identity and corresponding cookie that survives through browser closures. Any sliding expiration settings previously configured are honored. If the cookie expires while the browser is closed, the browser clears the cookie once it's restarted. Set to `true` in : ```csharp // using Microsoft.AspNetCore.Authentication; await HttpContext.SignInAsync( CookieAuthenticationDefaults.AuthenticationScheme, new ClaimsPrincipal(claimsIdentity), new AuthenticationProperties { IsPersistent = true }); ``` ## Absolute cookie expiration An absolute expiration time can be set with . To create a persistent cookie, `IsPersistent` must also be set. Otherwise, the cookie is created with a session-based lifetime and could expire either before or after the authentication ticket that it holds. When `ExpiresUtc` is set, it overrides the value of the option of , if set. The following code snippet creates an identity and corresponding cookie that lasts for 20 minutes. This ignores any sliding expiration settings previously configured. ```csharp // using Microsoft.AspNetCore.Authentication; await HttpContext.SignInAsync( CookieAuthenticationDefaults.AuthenticationScheme, new ClaimsPrincipal(claimsIdentity), new AuthenticationProperties { IsPersistent = true, ExpiresUtc = DateTime.UtcNow.AddMinutes(20) }); ``` :::moniker-end :::moniker range="< aspnetcore-6.0" [ASP.NET Core Identity](xref:security/authentication/identity) is a complete, full-featured authentication provider for creating and maintaining logins. However, a cookie-based authentication provider without ASP.NET Core Identity can be used. For more information, see . [View or download sample code](https://github.com/dotnet/AspNetCore.Docs/tree/main/aspnetcore/security/authentication/cookie/samples) ([how to download](xref:index#how-to-download-a-sample)) For demonstration purposes in the sample app, the user account for the hypothetical user, Maria Rodriguez, is hardcoded into the app. Use the **Email** address `maria.rodriguez@contoso.com` and any password to sign in the user. The user is authenticated in the `AuthenticateUser` method in the `Pages/Account/Login.cshtml.cs` file. In a real-world example, the user would be authenticated against a database. ## Configuration In the `Startup.ConfigureServices` method, create the Authentication Middleware services with the and methods: [!code-csharp[](cookie/samples/3.x/CookieSample/Startup.cs?name=snippet1)] passed to `AddAuthentication` sets the default authentication scheme for the app. `AuthenticationScheme` is useful when there are multiple instances of cookie authentication and you want to [authorize with a specific scheme](xref:security/authorization/limitingidentitybyscheme). Setting the `AuthenticationScheme` to [CookieAuthenticationDefaults.AuthenticationScheme](xref:Microsoft.AspNetCore.Authentication.Cookies.CookieAuthenticationDefaults.AuthenticationScheme) provides a value of "Cookies" for the scheme. You can supply any string value that distinguishes the scheme. The app's authentication scheme is different from the app's cookie authentication scheme. When a cookie authentication scheme isn't provided to , it uses `CookieAuthenticationDefaults.AuthenticationScheme` ("Cookies"). The authentication cookie's property is set to `true` by default. Authentication cookies are allowed when a site visitor hasn't consented to data collection. For more information, see . In `Startup.Configure`, call `UseAuthentication` and `UseAuthorization` to set the `HttpContext.User` property and run Authorization Middleware for requests. Call the `UseAuthentication` and `UseAuthorization` methods before calling `UseEndpoints`: [!code-csharp[](cookie/samples/3.x/CookieSample/Startup.cs?name=snippet2)] The class is used to configure the authentication provider options. Set `CookieAuthenticationOptions` in the service configuration for authentication in the `Startup.ConfigureServices` method: ```csharp services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) .AddCookie(options => { ... }); ``` ## Cookie Policy Middleware [Cookie Policy Middleware](xref:Microsoft.AspNetCore.CookiePolicy.CookiePolicyMiddleware) enables cookie policy capabilities. Adding the middleware to the app processing pipeline is order sensitive—it only affects downstream components registered in the pipeline. ```csharp app.UseCookiePolicy(cookiePolicyOptions); ``` Use provided to the Cookie Policy Middleware to control global characteristics of cookie processing and hook into cookie processing handlers when cookies are appended or deleted. The default value is `SameSiteMode.Lax` to permit OAuth2 authentication. To strictly enforce a same-site policy of `SameSiteMode.Strict`, set the `MinimumSameSitePolicy`. Although this setting breaks OAuth2 and other cross-origin authentication schemes, it elevates the level of cookie security for other types of apps that don't rely on cross-origin request processing. ```csharp var cookiePolicyOptions = new CookiePolicyOptions { MinimumSameSitePolicy = SameSiteMode.Strict, }; ``` The Cookie Policy Middleware setting for `MinimumSameSitePolicy` can affect the setting of `Cookie.SameSite` in `CookieAuthenticationOptions` settings according to the matrix below. | MinimumSameSitePolicy | Cookie.SameSite | Resultant Cookie.SameSite setting | | --------------------- | --------------- | --------------------------------- | | SameSiteMode.None | SameSiteMode.None
SameSiteMode.Lax
SameSiteMode.Strict | SameSiteMode.None
SameSiteMode.Lax
SameSiteMode.Strict | | SameSiteMode.Lax | SameSiteMode.None
SameSiteMode.Lax
SameSiteMode.Strict | SameSiteMode.Lax
SameSiteMode.Lax
SameSiteMode.Strict | | SameSiteMode.Strict | SameSiteMode.None
SameSiteMode.Lax
SameSiteMode.Strict | SameSiteMode.Strict
SameSiteMode.Strict
SameSiteMode.Strict | ## Create an authentication cookie To create a cookie holding user information, construct a . The user information is serialized and stored in the cookie. Create a with any required s and call to sign in the user: [!code-csharp[](cookie/samples/3.x/CookieSample/Pages/Account/Login.cshtml.cs?name=snippet1)] [!INCLUDE[request localized comments](~/includes/code-comments-loc.md)] `SignInAsync` creates an encrypted cookie and adds it to the current response. If `AuthenticationScheme` isn't specified, the default scheme is used. is only used on a few specific paths by default, for example, the login path and logout paths. For more information see the [CookieAuthenticationHandler source](https://github.com/dotnet/aspnetcore/blob/f2e6e6ff334176540ef0b3291122e359c2106d1a/src/Security/Authentication/Cookies/src/CookieAuthenticationHandler.cs#L334). ASP.NET Core's [Data Protection](xref:security/data-protection/using-data-protection) system is used for encryption. For an app hosted on multiple machines, load balancing across apps, or using a web farm, [configure data protection](xref:security/data-protection/configuration/overview) to use the same key ring and app identifier. ## Sign out To sign out the current user and delete their cookie, call : [!code-csharp[](cookie/samples/3.x/CookieSample/Pages/Account/Login.cshtml.cs?name=snippet2)] If `CookieAuthenticationDefaults.AuthenticationScheme` (or "Cookies") isn't used as the scheme (for example, "ContosoCookie"), supply the scheme used when configuring the authentication provider. Otherwise, the default scheme is used. When the browser closes it automatically deletes session based cookies (non-persistent cookies), but no cookies are cleared when an individual tab is closed. The server is not notified of tab or browser close events. ## React to back-end changes Once a cookie is created, the cookie is the single source of identity. If a user account is disabled in back-end systems: * The app's cookie authentication system continues to process requests based on the authentication cookie. * The user remains signed into the app as long as the authentication cookie is valid. The event can be used to intercept and override validation of the cookie identity. Validating the cookie on every request mitigates the risk of revoked users accessing the app. One approach to cookie validation is based on keeping track of when the user database changes. If the database hasn't been changed since the user's cookie was issued, there's no need to re-authenticate the user if their cookie is still valid. In the sample app, the database is implemented in `IUserRepository` and stores a `LastChanged` value. When a user is updated in the database, the `LastChanged` value is set to the current time. In order to invalidate a cookie when the database changes based on the `LastChanged` value, create the cookie with a `LastChanged` claim containing the current `LastChanged` value from the database: ```csharp var claims = new List { new Claim(ClaimTypes.Name, user.Email), new Claim("LastChanged", {Database Value}) }; var claimsIdentity = new ClaimsIdentity( claims, CookieAuthenticationDefaults.AuthenticationScheme); await HttpContext.SignInAsync( CookieAuthenticationDefaults.AuthenticationScheme, new ClaimsPrincipal(claimsIdentity)); ``` To implement an override for the `ValidatePrincipal` event, write a method with the following signature in a class that derives from : ```csharp ValidatePrincipal(CookieValidatePrincipalContext) ``` The following is an example implementation of `CookieAuthenticationEvents`: ```csharp using System.Linq; using System.Threading.Tasks; using Microsoft.AspNetCore.Authentication; using Microsoft.AspNetCore.Authentication.Cookies; public class CustomCookieAuthenticationEvents : CookieAuthenticationEvents { private readonly IUserRepository _userRepository; public CustomCookieAuthenticationEvents(IUserRepository userRepository) { // Get the database from registered DI services. _userRepository = userRepository; } public override async Task ValidatePrincipal(CookieValidatePrincipalContext context) { var userPrincipal = context.Principal; // Look for the LastChanged claim. var lastChanged = (from c in userPrincipal.Claims where c.Type == "LastChanged" select c.Value).FirstOrDefault(); if (string.IsNullOrEmpty(lastChanged) || !_userRepository.ValidateLastChanged(lastChanged)) { context.RejectPrincipal(); await context.HttpContext.SignOutAsync( CookieAuthenticationDefaults.AuthenticationScheme); } } } ``` Register the events instance during cookie service registration in the `Startup.ConfigureServices` method. Provide a [scoped service registration](xref:fundamentals/dependency-injection#service-lifetimes) for your `CustomCookieAuthenticationEvents` class: ```csharp services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme) .AddCookie(options => { options.EventsType = typeof(CustomCookieAuthenticationEvents); }); services.AddScoped(); ``` Consider a situation in which the user's name is updated—a decision that doesn't affect security in any way. If you want to non-destructively update the user principal, call `context.ReplacePrincipal` and set the `context.ShouldRenew` property to `true`. > [!WARNING] > The approach described here is triggered on every request. Validating authentication cookies for all users on every request can result in a large performance penalty for the app. ## Persistent cookies You may want the cookie to persist across browser sessions. This persistence should only be enabled with explicit user consent with a "Remember Me" checkbox on sign in or a similar mechanism. The following code snippet creates an identity and corresponding cookie that survives through browser closures. Any sliding expiration settings previously configured are honored. If the cookie expires while the browser is closed, the browser clears the cookie once it's restarted. Set to `true` in : ```csharp // using Microsoft.AspNetCore.Authentication; await HttpContext.SignInAsync( CookieAuthenticationDefaults.AuthenticationScheme, new ClaimsPrincipal(claimsIdentity), new AuthenticationProperties { IsPersistent = true }); ``` ## Absolute cookie expiration An absolute expiration time can be set with . To create a persistent cookie, `IsPersistent` must also be set. Otherwise, the cookie is created with a session-based lifetime and could expire either before or after the authentication ticket that it holds. When `ExpiresUtc` is set, it overrides the value of the option of , if set. The following code snippet creates an identity and corresponding cookie that lasts for 20 minutes. This ignores any sliding expiration settings previously configured. ```csharp // using Microsoft.AspNetCore.Authentication; await HttpContext.SignInAsync( CookieAuthenticationDefaults.AuthenticationScheme, new ClaimsPrincipal(claimsIdentity), new AuthenticationProperties { IsPersistent = true, ExpiresUtc = DateTime.UtcNow.AddMinutes(20) }); ``` :::moniker-end