32 KiB

Raw Blame History

title	author	description	ms.author	ms.date	uid
Use cookie authentication without ASP.NET Core Identity	rick-anderson	An explanation of using cookie authentication without ASP.NET Core Identity	riande	10/11/2017	security/authentication/cookie

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 demonstration purposes in the sample app, the user account for the hypothetical user, Maria Rodriguez, is hardcoded into the app. Use the Email username "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.

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

To use ASP.NET Core Identity, see the Introduction to Identity topic.

Configuration

ASP.NET Core 2.x

If the app doesn't use the Microsoft.AspNetCore.App metapackage, create a package reference in the project file for the Microsoft.AspNetCore.Authentication.Cookies package (version 2.1.0 or later).

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

[!code-csharp]

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 UseMvcWithDefaultRoute or UseMvc:

[!code-csharp]

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 =>
    {
        ...
    });

ASP.NET Core 1.x

ASP.NET Core 1.x uses cookie middleware that serializes a user principal into an encrypted cookie. On subsequent requests, the cookie is validated, and the principal is recreated and assigned to the HttpContext.User property.

Install the Microsoft.AspNetCore.Authentication.Cookies NuGet package in your project. This package contains the cookie middleware.

Use the UseCookieAuthentication method in the Configure method in your Startup.cs file before UseMvc or UseMvcWithDefaultRoute:

app.UseCookieAuthentication(new CookieAuthenticationOptions()
{
    AccessDeniedPath = "/Account/Forbidden/",
    AuthenticationScheme = CookieAuthenticationDefaults.AuthenticationScheme,
    AutomaticAuthenticate = true,
    AutomaticChallenge = true,
    LoginPath = "/Account/Unauthorized/"
});

CookieAuthenticationOptions Options

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

Option	Description
AuthenticationScheme	Sets the authentication scheme. `AuthenticationScheme` is useful when there are multiple instances of 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.
AutomaticAuthenticate	Sets a value to indicate that the cookie authentication should run on every request and attempt to validate and reconstruct any serialized principal it created.
AutomaticChallenge	If true, the authentication middleware handles automatic challenges. If false, the authentication middleware only alters responses when explicitly indicated by the `AuthenticationScheme`.
ClaimsIssuer	The issuer to use for the Issuer property on any claims created by the cookie authentication middleware.
CookieDomain	The domain name where the cookie is served. By default, this is the host name of the request. The browser only serves the cookie 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`.
CookieHttpOnly	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`.
CookiePath	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.
CookieSecure	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`.
Description	Additional information about the authentication type which is made available to the app.
ExpireTimeSpan	The `TimeSpan` after which the authentication ticket expires. It's added to the current time to create the expiration time for the ticket. To use `ExpireTimeSpan`, you must set `IsPersistent` to `true` in the `AuthenticationProperties` passed to `SignInAsync`. The default value is 14 days.
SlidingExpiration	A flag indicating whether the cookie expiration date resets when more than half of the `ExpireTimeSpan` interval has passed. The new exipiration time 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`.

Set CookieAuthenticationOptions for the Cookie Authentication Middleware in the Configure method:

app.UseCookieAuthentication(new CookieAuthenticationOptions
{
    ...
});

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.

ASP.NET Core 2.x

Create a ClaimsIdentity with any required Claims and call SignInAsync to sign in the user:

[!code-csharp]

ASP.NET Core 1.x

Call SignInAsync to sign in the user:

await HttpContext.Authentication.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.

Sign out

ASP.NET Core 2.x

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

[!code-csharp]

ASP.NET Core 1.x

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

await HttpContext.Authentication.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.

React 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's 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));

ASP.NET Core 2.x

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>();

ASP.NET Core 1.x

To implement an override for the ValidateAsync event, write a method with the following signature:

ValidateAsync(CookieValidatePrincipalContext)

ASP.NET Core Identity implements this check as part of its SecurityStampValidator. An example looks like the following:

public static class LastChangedValidator
{
    public static async Task ValidateAsync(CookieValidatePrincipalContext context)
    {
        // Pull database from registered DI services.
        var userRepository = 
            context.HttpContext.RequestServices
                .GetRequiredService<IUserRepository>();
        var userPrincipal = context.Principal;

        // Look for the last changed 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);
        }
    }
}

app.UseCookieAuthentication(new CookieAuthenticationOptions
{
    Events = new CookieAuthenticationEvents
    {
        OnValidatePrincipal = LastChangedValidator.ValidateAsync
    }
});

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.

ASP.NET Core 2.x

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

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

ASP.NET Core 1.x

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

The AuthenticationProperties class resides in the Microsoft.AspNetCore.Http.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.

ASP.NET Core 2.x

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

ASP.NET Core 1.x

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

32 KiB Raw Blame History

Use cookie authentication without ASP.NET Core Identity

Configuration

Cookie Policy Middleware

Create an authentication cookie

Sign out

React to back-end changes

Persistent cookies

Absolute cookie expiration

Additional resources

32 KiB

Raw Blame History