Cookie-based authentication is the popular choice to secure customer facing web apps. For .NET programmers, ASP.NET Core has a good approach that is worth looking into. In this take, I will delve deep into the auth cookie using ASP.NET Core 2.1. Version 2.1 is the latest LTS version as of the time of this writing. So, feel free to follow along, I\u2019ll assume you\u2019re on Visual Studio or have enough C# chops to use a text editor. I will omit namespaces and using statements to keep code samples focused. If you get stuck, download the sample code found at the end.<\/p>\n
With ASP.NET 2.1, you can use cookie-based authentication out of the box. There is no need for additional NuGet packages. New projects include a metapackage that has everything, which is Microsoft.AspNetCore.App<\/em>. To follow along, type For those of you who come from classic .NET, you may be aware of the OWIN<\/em> auth cookie. You will be happy to know those same skills transfer over to ASP.NET Core quite well. The two implementations remain somewhat similar. With ASP.NET Core, you still configure the auth cookie, set up middleware, and set identity claims.<\/p>\n To begin, I\u2019ll assume you know enough about the ASP.NET MVC framework to gut the scaffolding into a skeleton web app. You need a HomeController<\/em> with an I\u2019ll use debug logs to show critical events inside the cookie authentication. Be sure to enable debug logs in appsettings.json<\/em> and disable Microsoft and system logs.<\/p>\n My log setup looks like this:<\/p>\n Now you\u2019re ready to build a basic app with cookie authentication. I\u2019ll forgo HTML forms with a user name and password input fields. These front-end concerns only add clutter to what is more important which is the auth cookie. Starting with a skeleton app shows how effective it is to add an auth cookie from scratch. The app will sign you in automatically and land on an Index page with an auth cookie. Then, you can log out or revoke user access. I want you to pay attention to what happens to the auth cookie as I put authentication in place.<\/p>\n Begin by configuring auth cookie options through middleware inside the Startup<\/strong> class. Cookie options tell the authentication middleware how the cookie behaves in the browser. There are many options, but I will only focus on those that affect cookie security the most.<\/p>\n There are cookie options for both the auth cookie and a global cookie policy. Stay alert since the cookie policy can override auth cookie options and vice versa. Setting In the This creates the middleware service with the The In this same Take a good look at Invoke this middleware inside the request pipeline in the The cookie policy middleware is order sensitive. This means it only affects components after invocation. By invoking the authentication middleware, you will get a In the Inside the With the app secure, configure the cookie name and login \/ logout paths. Find where the rest of the This will cause the app to redirect to the login endpoint to sign in. However, before you can take this for a spin, you\u2019ll need to create the auth cookie.<\/p>\n Do this inside the To take this for a spin load up the browser by going to the home or Index page. Note it redirects to Login which redirects back to Index with an auth cookie.<\/p>\n Once this loads it looks something like this. Be sure to take a good look at how the auth cookie is set:<\/p>\n Often, an auth cookie isn\u2019t enough to secure API endpoints or microservices. For the web app to call a service, it can use a JWT bearer token to authenticate. To make the access token accessible, place it inside the identity claims.<\/p>\n In the Login action method within I must caution, don\u2019t ever do this is in production. Here, I use the user id as the signing key which is symmetric to keep it simple. In a prod environment use an asymmetric signing key with public and private keys. Client apps will then use a well-known configuration endpoint to validate the JWT.<\/p>\n Placing the JWT in In the The _<\/strong> To log out of the web app and clear the auth cookie do:<\/p>\n This belongs inside the Logout action method in the There are use cases where the app needs to react to back-end user access changes. The auth cookie will secure the application, but, remains valid for the lifetime of the cookie. With a valid cookie, the end-user will not see any changes until they log out or the cookie expires. In ASP.NET Core 2.1, one way to validate changes is through cookie authentication events. The validation event can do back-end lookups from identity claims in the auth cookie. Create the event by extending For example:<\/p>\n To have Revoke access by setting the cache inside the After visiting the To register this event, be sure to set the For example:<\/p>\n The Setting a JWT in the claims to have a convenient way to access identity data works well. However, every identity claim you put in the principal ends up in the auth cookie. If you inspect the cookie, you will notice it doubles in size with an access token. As you add more claims in the principal the auth cookie gets bigger. You may hit HTTP header limits in a prod environment with many auth cookies. In IIS, the default max limit is set to 8KB-16KB depending on the version. You can increase the limit, but this means bigger payloads per request because of the cookies.<\/p>\n There are many ways to quell this problem, like a user session to keep all JWTs out of the auth cookie. If you have current code that accesses the identity through the principal, then this is not ideal. Moving identity data out of the principal is risky because it may lead to a complete rewrite.<\/p>\n One alternative is to use the Say you want to use in-memory persistence instead of the auth cookie:<\/p>\n Set an instance of this class in A better approach is to use the options pattern in ASP.NET Core. Post-configuration scenarios set or change options at startup. With this solution, you leverage dependency injection without reinventing the wheel.<\/p>\n To put in place this options pattern, implement\u00a0 To register both dotnet new mvc<\/code> in a CLI or do File > New Project<\/em> in Visual Studio.<\/p>\nSetup<\/h2>\n
Index<\/code>, Login<\/code>, Logout<\/code>, and Revoke<\/code> action methods. Login<\/code> will redirect to Index<\/code> after it signs you in, so it doesn\u2019t need a view. I\u2019ll omit showing view sample code since views are not the focus here. If you get lost, be sure to download the entire demo to play with it.<\/p>\n\"LogLevel\": {\n \"Default\": \"Debug\",\n \"System\": \"Warning\",\n \"Microsoft\": \"Warning\"\n}<\/pre>\nCookie Options<\/h2>\n
\n
HttpOnly<\/code> to false in the auth cookie will override cookie policy options. While setting SameSite<\/code> in the cookie policy overrides auth cookie options. In my demo, I\u2019ll illustrate both scenarios, so it is crystal clear how this works.<\/p>\nStartup<\/code> class, find the ConfigureServices<\/code> method and type:<\/p>\nservices.AddAuthentication(CookieAuthenticationDefaults.AuthenticationScheme)\n .AddCookie(options =>\n {\n options.Cookie.HttpOnly = true;\n options.Cookie.SecurePolicy = _environment.IsDevelopment()\n ? CookieSecurePolicy.None : CookieSecurePolicy.Always;\n options.Cookie.SameSite = SameSiteMode.Lax;\n });<\/pre>\nAddAuthentication<\/code> and AddCookie<\/code> methods. AuthenticationScheme<\/code> is useful when there is more than one auth cookie. Many instances of\u00a0 the cookie authentication let you protect endpoints with many schemes. You supply any string value; the default is set to Cookies. Note that the options<\/strong> object is an instance of the CookieAuthenticationOptions<\/code> class.<\/p>\nSecurePolicy<\/code> is set through a ternary operator that comes from _<\/strong>environment<\/code>. This is a private property that gets set in the Startup<\/code> constructor. Add IHostingEnvironment<\/code> as a parameter and let dependency injection do the rest.<\/p>\nConfigureServices<\/code> method, add the global cookie policy through middleware:<\/p>\nservices.Configure<CookiePolicyOptions>(options =>\n{\n options.MinimumSameSitePolicy = SameSiteMode.Strict;\n options.HttpOnly = HttpOnlyPolicy.None;\n options.Secure = _environment.IsDevelopment()\n ? CookieSecurePolicy.None : CookieSecurePolicy.Always;\n});<\/pre>\nSameSite<\/code> and HttpOnly<\/code> settings for both cookie options. When I set the auth cookie, you will see this set to HttpOnly<\/code> and Strict<\/code>. This illustrates how both options override each other.<\/p>\nConfigure<\/code> method:<\/p>\napp.UseCookiePolicy();\napp.UseAuthentication();<\/pre>\n
HttpContext.User<\/code> property. Be sure to call this UseAuthentication<\/code> method before calling UseMvc<\/code>.<\/p>\nLogin<\/h2>\n
HomeController<\/code> add an AllowAnonymous<\/code> filter to the Login and Logout methods. There are only two action methods available without an auth cookie.<\/p>\nStartup<\/code> class, look for the AddMvc<\/code> extension method and add a global auth filter:<\/p>\nservices.AddMvc(options => options.Filters.Add(new AuthorizeFilter()))<\/pre>\n
CookieAuthenticationOptions<\/code> are and do:<\/p>\noptions.Cookie.Name = \"SimpleTalk.AuthCookieAspNetCore\";\noptions.LoginPath = \"\/Home\/Login\";\noptions.LogoutPath = \"\/Home\/Logout\";<\/pre>\n
Login<\/code> action method in the HomeController<\/code>:<\/p>\nvar claims = new List<Claim>\n{\n new Claim(ClaimTypes.Name, Guid.NewGuid().ToString())\n};\n\nvar claimsIdentity = new ClaimsIdentity(\n claims, CookieAuthenticationDefaults.AuthenticationScheme);\nvar authProperties = new AuthenticationProperties();\n\nawait HttpContext.SignInAsync(\n CookieAuthenticationDefaults.AuthenticationScheme,\n new ClaimsPrincipal(claimsIdentity),\n authProperties);<\/pre>\nAuthenticationProperties<\/code> drive further auth cookie behavior in the browser. For example, the IsPersistent<\/code> property persists the cookie across browser sessions. Be sure to get explicit user consent when you enable this property. ExpiresUtc<\/code> sets an absolute expiration, be sure to enable IsPersistent<\/code> and set it to true. The default values will give you a session cookie that goes away when you close the tab or browser window. I find the default values in this object enough for most use cases.<\/p>\n![](\"https:\/\/www.red-gate.com\/simple-talk\/wp-content\/uploads\/2019\/02\/word-image.png\")
<\/p>\nJWT Identity Claim<\/h2>\n
HomeController<\/code>, expand the list of claims with a JWT:<\/p>\nvar userId = Guid.NewGuid().ToString();\nvar claims = new List<Claim>\n{\n new Claim(ClaimTypes.Name, userId),\n new Claim(\"access_token\", GetAccessToken(userId))\n};\n\nprivate static string GetAccessToken(string userId)\n{\n const string issuer = \"localhost\";\n const string audience = \"localhost\";\n\n var identity = new ClaimsIdentity(new List<Claim>\n {\n new Claim(\"sub\", userId)\n });\n\n var bytes = Encoding.UTF8.GetBytes(userId);\n var key = new SymmetricSecurityKey(bytes);\n var signingCredentials = new SigningCredentials(\n key, SecurityAlgorithms.HmacSha256);\n\n var now = DateTime.UtcNow;\n var handler = new JwtSecurityTokenHandler();\n\n var token = handler.CreateJwtSecurityToken(\n issuer, audience, identity,\n now, now.Add(TimeSpan.FromHours(1)),\n now, signingCredentials);\n\n return handler.WriteToken(token);\n}<\/pre>\nClaimsIdentity<\/code> makes it accessible through the HttpContex.User<\/code> property. For this app, say you want to put the JWT in a debug log to show off this fancy access token.<\/p>\nStartup<\/code> class, create this middleware inside the Configure<\/code> method:<\/p>\napp.Use(async (context, next) =>\n{\n var principal = context.User as ClaimsPrincipal;\n var accessToken = principal?.Claims\n .FirstOrDefault(c => c.Type == \"access_token\");\n\n if (accessToken != null)\n {\n _logger.LogDebug(accessToken.Value);\n }\n\n await next();\n});<\/pre>\nlogger<\/code> is another private property you set through the constructor. Add ILogger<Startup><\/code> as a parameter and let dependency injection do the rest. Note the ClaimsPrincipal<\/code> has a list of Claims<\/code> you can iterate through. What I find useful is to look for a Type<\/code> of claim like an access_token<\/code> and get a Value<\/code>. Because this is middleware always call next()<\/code> so it doesn\u2019t block the request pipeline.<\/p>\nLogout<\/h2>\n
await HttpContext.SignOutAsync(\n CookieAuthenticationDefaults.AuthenticationScheme);<\/pre>\n
HomeController<\/code>. Note that you specify the authentication scheme. This tells the sign-out method which auth cookie it needs to blot out. Inspecting HTTP response headers reveals Cache-Control<\/code> and Pragma<\/code> headers set to no-cache<\/code>. This shows the auth cookie disables browser caching when it wants to update the cookie. The Login<\/code> action method responds with the same HTTP headers.<\/p>\nRevocation<\/h2>\n
CookieAuthenticationEvents<\/code>. Override the ValidatePrincipal<\/code> method and set the event in the auth cookie options.<\/p>\npublic class RevokeAuthenticationEvents : CookieAuthenticationEvents\n{\n private readonly IMemoryCache _cache;\n private readonly ILogger _logger;\n\n public RevokeAuthenticationEvents(\n IMemoryCache cache,\n ILogger<RevokeAuthenticationEvents> logger)\n {\n _cache = cache;\n _logger = logger;\n }\n\n public override Task ValidatePrincipal(\n CookieValidatePrincipalContext context)\n {\n var userId = context.Principal.Claims\n .First(c => c.Type == ClaimTypes.Name);\n\n if (_cache.Get<bool>(\"revoke-\" + userId.Value))\n {\n context.RejectPrincipal();\n\n _cache.Remove(\"revoke-\" + userId.Value);\n _logger.LogDebug(\"Access has been revoked for: \"\n + userId.Value + \".\");\n }\n\n return Task.CompletedTask;\n }\n}<\/pre>\nIMemoryCache<\/code> set by dependency injection, put AddMemoryCache<\/code> inside the ConfigureSerices<\/code> method in the Startup<\/code> class. Calling RejectPrincipal<\/code> has an immediate effect and kicks you back out to Login to get a new auth cookie. Note this relies on in-memory persistence which gets set in the Revoke action method. Keep in mind that this event runs once per every request, so you want to use an efficient caching strategy. Doing an expensive lookup at every request will affect performance.<\/p>\nRevoke<\/code> method in the HomeController<\/code>:<\/p>\nvar principal = HttpContext.User as ClaimsPrincipal;\nvar userId = principal?.Claims\n .First(c => c.Type == ClaimTypes.Name);\n\n_cache.Set(\"revoke-\" + userId.Value, true);\nreturn View();<\/pre>\n
Revoke<\/code> endpoint, the change does not have an immediate effect. After revocation, navigating home will show the debug log and redirect to Login. Note that landing in the Index page again will have a brand new auth cookie.<\/p>\nEventsType<\/code> in the CookieAuthenticationOptions<\/code>. You will need to provide a scoped service to register this RevokeAuthenticationEvents<\/code>. Both are set inside the ConfigureServices<\/code> method in the Startup<\/code> class.<\/p>\noptions.EventsType = typeof(RevokeAuthenticationEvents);\nservices.AddScoped<RevokeAuthenticationEvents>();<\/pre>\n
CookieValidatePrincipalContext<\/code> in ValidatePrincipal<\/code> can do more than revocation if necessary. This context has ReplacePrincipal<\/code> to update the principal, then renew the cookie by setting ShouldRenew<\/code> to true.<\/p>\nSession Store<\/h2>\n
SessionStore<\/code> found in CookieAuthenticationOptions<\/code>. OWIN, for example, has a similar property. Implement the ITicketStore<\/code> interface and find a way to persist data in the back-end. Setting the SessionStore<\/code> property defines a container to store the identity across requests. Only a session identifier gets sent to the browser in the auth cookie.<\/p>\npublic class InMemoryTicketStore : ITicketStore\n{\n private readonly IMemoryCache _cache;\n\n public InMemoryTicketStore(IMemoryCache cache)\n {\n _cache = cache;\n }\n\n public Task RemoveAsync(string key)\n {\n _cache.Remove(key);\n\n return Task.CompletedTask;\n }\n\n public Task<AuthenticationTicket> RetrieveAsync(string key)\n {\n var ticket = _cache.Get<AuthenticationTicket>(key);\n\n return Task.FromResult(ticket);\n }\n\n public Task RenewAsync(string key, AuthenticationTicket ticket)\n {\n _cache.Set(key, ticket);\n\n return Task.CompletedTask;\n }\n\n public Task<string> StoreAsync(AuthenticationTicket ticket)\n {\n var key = ticket.Principal.Claims\n .First(c => c.Type == ClaimTypes.Name).Value;\n\n _cache.Set(key, ticket);\n\n return Task.FromResult(key);\n }\n}<\/pre>\nSessionStore<\/code> inside CookieAuthenticationOptions<\/code>, these options are set in the ConfigureServices<\/code> method in the Startup<\/code> class. One caveat is getting an instance since it needs a provider from BuildServiceProvider<\/code>. A temporary IoC container here feels hacky and pines after a better solution.<\/p>\nIPostConfigureOptions<CookieAuthenticationOptions>:<\/code><\/p>\npublic class ConfigureCookieAuthenticationOptions\n : IPostConfigureOptions<CookieAuthenticationOptions>\n{\n private readonly ITicketStore _ticketStore;\n\n public ConfigureCookieAuthenticationOptions(ITicketStore ticketStore)\n {\n _ticketStore = ticketStore;\n }\n\n public void PostConfigure(string name, \n CookieAuthenticationOptions options)\n {\n options.SessionStore = _ticketStore;\n }\n}<\/pre>\nInMemoryTicketStore<\/code> and ConfigureCookieAuthenticationOptions<\/code>, place this in ConfigureServices<\/code>:<\/p>\nservices.AddTransient<ITicketStore, InMemoryTicketStore>();\nservices.AddSingleton<IPostConfigureOptions<CookieAuthenticationOptions>,\n ConfigureCookieAuthenticationOptions>();<\/pre>\n