Using Cookie Authentication without ASP.NET Core Identity

By Rick Anderson and Luke Latham

As you've seen in the earlier authentication topics, ASP.NET Core Identity is a complete, full-featured authentication provider for creating and maintaining logins. However, you may want to use your own custom authentication logic with cookie-based authentication at times. You can use cookie-based authentication as a standalone authentication provider without ASP.NET Core Identity.

View or download sample code (how to download)

For information on migrating cookie-based authentication from ASP.NET Core 1.x to 2.0, see Migrating Authentication and Identity to ASP.NET Core 2.0 topic (Cookie-based Authentication).

Configuration

If you aren't using the Microsoft.AspNetCore.All metapackage, install version 2.0+ of the Microsoft.AspNetCore.Authentication.Cookies NuGet package.

In the ConfigureServices method, create the Authentication Middleware service with the AddAuthentication and AddCookie methods:

services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie();

AuthenticationScheme 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. Setting the AuthenticationScheme to CookieAuthenticationDefaults.AuthenticationScheme provides a value of "Cookies" for the scheme. You can supply any string value that distinguishes the scheme.

In the Configure method, use the UseAuthentication method to invoke the Authentication Middleware that sets the HttpContext.User property. Call the UseAuthentication method before calling AddMvcWithDefaultRoute in an MVC app or AddMvc in a Razor Pages app:

app.UseAuthentication();

AddCookie Options

The CookieAuthenticationOptions class is used to configure the authentication provider options.

Option Description
AccessDeniedPath Provides the path to supply with a 302 Found (URL redirect) when triggered by HttpContext.ForbidAsync. The default value is /Account/AccessDenied.
ClaimsIssuer The issuer to use for the Issuer property on any claims created by the cookie authentication service.
Cookie.Domain The domain name where the cookie is served. By default, this is the host name of the request. The browser only sends the cookie in requests to a matching host name. You may wish to adjust this to have cookies available to any host in your domain. For example, setting the cookie domain to .contoso.com makes it available to contoso.com, www.contoso.com, and staging.www.contoso.com.
Cookie.Expiration Gets or sets the lifespan of a cookie. Currently, this option no-ops and will become obsolete in ASP.NET Core 2.1+. Use the ExpireTimeSpan option to set cookie expiration. For more information, see Clarify behavior of CookieAuthenticationOptions.Cookie.Expiration.
Cookie.HttpOnly A flag indicating if the cookie should be accessible only to servers. Changing this value to false permits client-side scripts to access the cookie and may open your app to cookie theft should your app have a Cross-site scripting (XSS) vulnerability. The default value is true.
Cookie.Name Sets the name of the cookie.
Cookie.Path Used to isolate apps running on the same host name. If you have an app running at /app1 and want to restrict cookies to that app, set the CookiePath property to /app1. By doing so, the cookie is only available on requests to /app1 and any app underneath it.
Cookie.SameSite Indicates whether the browser should allow the cookie to be attached to same-site requests only (SameSiteMode.Strict) or cross-site requests using safe HTTP methods and same-site requests (SameSiteMode.Lax). When set to SameSiteMode.None, the cookie header value isn't set. Note that Cookie Policy Middleware might overwrite the value that you provide. To support OAuth authentication, the default value is SameSiteMode.Lax. For more information, see OAuth authentication broken due to SameSite cookie policy.
Cookie.SecurePolicy A flag indicating if the cookie created should be limited to HTTPS (CookieSecurePolicy.Always), HTTP or HTTPS (CookieSecurePolicy.None), or the same protocol as the request (CookieSecurePolicy.SameAsRequest). The default value is CookieSecurePolicy.SameAsRequest.
DataProtectionProvider Sets the DataProtectionProvider that's used to create the default TicketDataFormat. If the TicketDataFormat property is set, the DataProtectionProvider option isn't used. If not provided, the app's default data protection provider is used.
Events The handler calls methods on the provider that give the app control at certain processing points. If Events aren't provided, a default instance is supplied that does nothing when the methods are called.
EventsType Used as the service type to get the Events instance instead of the property.
ExpireTimeSpan The TimeSpan after which the authentication ticket stored inside the cookie expires. ExpireTimeSpan is added to the current time to create the expiration time for the ticket. The ExpiredTimeSpan value always goes into the encrypted AuthTicket verified by the server. It may also go into the Set-Cookie header, but only if IsPersistent is set. To set IsPersistent to true, configure the AuthenticationProperties passed to SignInAsync. The default value of ExpireTimeSpan is 14 days.
LoginPath Provides the path to supply with a 302 Found (URL redirect) when triggered by HttpContext.ChallengeAsync. The current URL that generated the 401 is added to the LoginPath as a query string parameter named by the ReturnUrlParameter. Once a request to the LoginPath grants a new sign-in identity, the ReturnUrlParameter value is used to redirect the browser back to the URL that caused the original unauthorized status code. The default value is /Account/Login.
LogoutPath If the LogoutPath is provided to the handler, then a request to that path redirects based on the value of the ReturnUrlParameter. The default value is /Account/Logout.
ReturnUrlParameter Determines the name of the query string parameter that's appended by the handler for a 302 Found (URL redirect) response. ReturnUrlParameter is used when a request arrives on the LoginPath or LogoutPath to return the browser to the original URL after the login or logout action is performed. The default value is ReturnUrl.
SessionStore An optional container used to store identity across requests. When used, only a session identifier is sent to the client. SessionStore can be used to mitigate potential problems with large identities.
SlidingExpiration A flag indicating if a new cookie with an updated expiration time should be issued dynamically. This can happen on any request where the current cookie expiration period is more than 50% expired. The new expiration date is moved forward to be the current date plus the ExpireTimespan. An absolute cookie expiration time can be set by using the AuthenticationProperties class when calling SignInAsync. An absolute expiration time can improve the security of your app by limiting the amount of time that the authentication cookie is valid. The default value is true.
TicketDataFormat The TicketDataFormat is used to protect and unprotect the identity and other properties that are stored in the cookie value. If not provided, a TicketDataFormat is created using the DataProtectionProvider.
Validate Method that checks that the options are valid.

Set CookieAuthenticationOptions in the service configuration for authentication in the ConfigureServices method:

services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        ...
    });

Cookie Policy Middleware enables cookie policy capabilities in an app. Adding the middleware to the app processing pipeline is order sensitive; it only affects components registered after it in the pipeline.

app.UseCookiePolicy(cookiePolicyOptions);

The CookiePolicyOptions provided to the Cookie Policy Middleware allow you to control global characteristics of cookie processing and hook into cookie processing handlers when cookies are appended or deleted.

Property Description
HttpOnly Affects whether cookies must be HttpOnly, which is a flag indicating if the cookie should be accessible only to servers. The default value is HttpOnlyPolicy.None.
MinimumSameSitePolicy Affects the cookie's same-site attribute (see below). The default value is SameSiteMode.Lax. This option is available for ASP.NET Core 2.0+.
OnAppendCookie Called when a cookie is appended.
OnDeleteCookie Called when a cookie is deleted.
Secure Affects whether cookies must be Secure. The default value is CookieSecurePolicy.None.

MinimumSameSitePolicy (ASP.NET Core 2.0+ only)

The default MinimumSameSitePolicy 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.

var cookiePolicyOptions = new CookiePolicyOptions
{
    MinimumSameSitePolicy = SameSiteMode.Strict,
};

The Cookie Policy Middleware setting for MinimumSameSitePolicy can affect your 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

To create a cookie holding user information, you must construct a ClaimsPrincipal. The user information is serialized and stored in the cookie.

Call SignInAsync to sign in the user:

await HttpContext.SignInAsync(
    CookieAuthenticationDefaults.AuthenticationScheme, 
    new ClaimsPrincipal(claimsIdentity));

SignInAsync creates an encrypted cookie and adds it to the current response. If you don't specify an AuthenticationScheme, the default scheme is used.

Under the covers, the encryption used is ASP.NET Core's Data Protection system. If you're hosting app on multiple machines, load balancing across apps, or using a web farm, then you must configure data protection to use the same key ring and app identifier.

Signing out

To sign out the current user and delete their cookie, call SignOutAsync:

await HttpContext.SignOutAsync(
    CookieAuthenticationDefaults.AuthenticationScheme);

If you aren't using CookieAuthenticationDefaults.AuthenticationScheme (or "Cookies") as the scheme (for example, "ContosoCookie"), supply the scheme you used when configuring the authentication provider. Otherwise, the default scheme is used.

Reacting to back-end changes

Once a cookie is created, it becomes the single source of identity. Even if you disable a user in your back-end systems, the cookie authentication system has no knowledge of this, and a user stays logged in as long as their cookie is valid.

The ValidatePrincipal event in ASP.NET Core 2.x or the ValidateAsync method in ASP.NET Core 1.x can be used to intercept and override validation of the cookie identity. This approach mitigates the risk of revoked users accessing the app.

One approach to cookie validation is based on keeping track of when the user database has been changed. If the database hasn't been changed since the user's cookie was issued, there is no need to re-authenticate the user if their cookie is still valid. To implement this scenario, the database, which is implemented in IUserRepository for this example, stores a LastChanged value. When any 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:

var claims = new List<Claim>
{
    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 you derive from CookieAuthenticationEvents:

ValidatePrincipal(CookieValidatePrincipalContext)

An example looks like the following:

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 ConfigureServices method. Provide a scoped service registration for your CustomCookieAuthenticationEvents class:

services.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)
    .AddCookie(options =>
    {
        options.EventsType = typeof(CustomCookieAuthenticationEvents);
    });

services.AddScoped<CustomCookieAuthenticationEvents>();

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. This 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 login 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.

await HttpContext.SignInAsync(
    CookieAuthenticationDefaults.AuthenticationScheme,
    new ClaimsPrincipal(claimsIdentity),
    new AuthenticationProperties
    {
        IsPersistent = true
    });

The AuthenticationProperties class resides in the Microsoft.AspNetCore.Authentication namespace.

You can set an absolute expiration time with ExpiresUtc. You must also set IsPersistent; otherwise, ExpiresUtc is ignored and a single-session cookie is created. When ExpiresUtc is set on SignInAsync, it overrides the value of the ExpireTimeSpan option of CookieAuthenticationOptions, 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.

await HttpContext.SignInAsync(
    CookieAuthenticationDefaults.AuthenticationScheme,
    new ClaimsPrincipal(claimsIdentity),
    new AuthenticationProperties
    {
        IsPersistent = true,
        ExpiresUtc = DateTime.UtcNow.AddMinutes(20)
    });

See also