一直以来都有一个说法,在对Asp.Net Core Web Api进行安全验证时,只能使用Token而不能使用Cookie.
事实并非如此,在对Web Api进行验证和授权时,你可以使用Cookie,跟普通的Web Application并无区别。而且跟使用JWT Token比起来,使用Cookie配置更简单。只是,有一点点知识你需要了解。
这篇博客是关于如何使用Cookie对Asp.Net Core Web Api进行安全验证的,如果你想了解如何使用JWT Token,请参考 Secure a Web Api in ASP.NET Core and Refresh Tokens in ASP.NET Core Web Api
使Cookie能在Web Api中工作的一些必备配置
如果Web Api的客户端是Web Application(如Angular app), 且Web Api和Web Application运行在不同的域名下(这是很常见的场景), 如果不做一些额外的配置,Cookie是无法工作的。
这或许就是人们默认使用JWT Token的原因吧。如果你尝试着按传统的Web Application(如Asp.Net MVC)那样去配置验证,然后通过AJAX请求进行登录和注销的话,很快你就会发现这根本行不通。
举个例子,当你试图通过JQuery登录Web Api的时候
$.post('https://yourdomain.com/api/account/login', "username=theUsername&password=thePassword")
响应不显示任何错误信息,如果你监视响应,它甚至包含Set-Cookie的Header, 但是Cookie好像被浏览器给忽略了。
更加让人困惑的是,即便你正确的配置了CORS,情况依然如此。
结论就是你还需要在客户端做一些额外的配置。接下来将会介绍你还需要做哪些工作,包括服务端和客户端两方面。
这里提供了一个示例项目,仅仅是一个默认模板的Asp.Net,用于验证单一用户账号,并且剔除了所有的UI以便能够做为Web Api被调用。项目中还包含一个Angular程序,用于调用Web Api
服务端的配置
服务端要做的工作是配置Asp.Net的Cookie验证中间件和CORS, 以便你的Web Api“声明”它接受来自客户端所在域发来的请求。
要配置Cookie验证中间件,你需要在Startup.cs的ConfigurateServices方法中配置验证中间件。
public void ConfigureServices(IServiceCollection services) { //... services.AddAuthentication(options => { options.DefaultScheme = "Cookies"; }).AddCookie("Cookies", options => { options.Cookie.Name = "auth_cookie"; options.Cookie.SameSite = SameSiteMode.None; options.Events = new CookieAuthenticationEvents { OnRedirectToLogin = redirectContext => { redirectContext.HttpContext.Response.StatusCode = 401; return Task.CompletedTask; } }; });
在这里,我把Cookie验证的schema命名为"Cookies"(也就是AddCookie方法的第一个参数)。后面我们实现登录方法的时候需要用到这个名字。
我还把要创建的Cookie命名为auth_cookie(options.Cookie.Name = "auth_cookie")。如果你的Web Api的调用者是web客户端(例如Angular程序),你不用管cookie的名字;但是如果调用者是用C#写的客户端,通过HttpClient来调用,你就需要手动读取和保存cookie的值。一个显式的命名比默认的名字—— .Asp.Net. + schema name(在这个例子中是 .Asp.Net.Cookies)——更容易记住。
至于SameSiteMode,我把它设置成了None。 SameSite在设置Cookie的时候会用到(它控制着Set-Cookie header中一个同名的属性)。它的值既严格又宽松。严格指的是只有跟Cookie同域名的请求,浏览器才会发送cookie。宽松指的是浏览器只对同域的请求发送cookie,而跨域的语法不会有任何的副作用。
如果你像我一样把它设置成SameSiteMode.None, set-cookie中不会包含samesite属性,那么浏览器后续发送的所有请求都要携带cookie,这正是我们想要的。
插一句题外话,如果你想调试问题,尽量选择FireFox的开发者工具,而不是Chrome的。因为如果不是同域的请求,Chrome不会显示Set-Cookie头。
最后我还重定义了当验证失败应该如何处理。通常Cookie中间件会给登录页返回302重定向, 因为我们是在构建一个Web Api, 我们需要给客户端返回一个401未授权。这些是在自定义OnRedirectToLogin的时候要做的事情。
当使用Asp.Net Core Identity(示例项目中用的就是这个),配置有一点点不同。你不需要关心cookie shcema的名字,因为 ASP.NET Core Identity会给出一个默认值。此外,OnRedirectToLogin的重定义也有一点不同(很相似,看示例代码就明白了)
之前说的是都是授权中间件的配置,此外,ConfigureServices方法中我们还要加CORS, 就一行代码:
services.AddCors();
最后,在Startup.cs的
Configure方法里,给管道加上验证和CORS中间件(在MVC管道前面)
public void Configure(IApplicationBuilder app, IHostingEnvironment env) { //... app.UseCors(policy => { policy.AllowAnyHeader(); policy.AllowAnyMethod(); policy.AllowAnyOrigin(); policy.AllowCredentials(); }); app.UseAuthentication(); //... app.UseMvc();
我们的CORS配置未对潜在的客户端作任何限制。需要强调的是AllowCredentials选项,没有它,浏览器会忽略所有带有cookie的请求的响应(参考MSDN关于CORS的文档中的Access-Control-Allow-Credentials)。
登录和注销
登录和注销的实现方式,跟在MVC的情况很相似。唯一的不同之处在于不返回Content,只是返回一个状态码。
登录方法的示例如下:
[HttpPost] public async Task<IActionResult> Login(string username, string password) { if (!IsValidUsernameAndPasswod(username, password)) return BadRequest(); var user = GetUserFromUsername(username); var claimsIdentity = new ClaimsIdentity(new[] { new Claim(ClaimTypes.Name, user.Username), //... }, "Cookies"); var claimsPrincipal = new ClaimsPrincipal(claimsIdentity); await Request.HttpContext.SignInAsync("Cookies", claimsPrincipal); return NoContent(); }
注意,这里的“Cookies"就是之前在Startup.cs中定义的schema的名字。
注销方法的示例如下:
[HttpPost] public async Task<IActionResult> Logout() { await HttpContext.SignOutAsync(); return NoContent(); }
我们的demo工程依赖ASP.NET Core Identity, 里面提供了UserManager和SignInManager两个类, 这两个类实现与上面描述的相同的功能。
客户端
当使用浏览器作为客户端去调用基于cookie的Web API时,你需要了解一些关于XMLHttpRequest或者Fetch API的知识;如果你的客户端不是基于浏览器的(如c#程序), 你还需要知道如何保存、恢复cookie.
有两种方式可以在浏览器里进行AJAX请求:XMLHttpRequest或者Fetch API。即便你使用的是一些框架或者库(JQuery或者Angular),底层用的还是这二者中的一种。
当你执行请求时,如果你使用了某些选项,包含 Set-Cookie header的响应将会被忽略。当你要返回一个响应时,你需要把withCredentials标识设置为true才能保证该响应不会被忽略;当你要发送一个携带cookie的请求时,也需要设置withCredentials。总之,这个标识有两种不同的用途。
你很可能不会手动使用XMLHttpRequest发送请求,我就不再提供关于它的使用方法的例子。下面分别提供关于JQuery、Angular和Fetch Api版本的例子。
JQuery版
当使用JQuery时,你可以通过如下方式设置withCredentials
$.ajax({ url: 'http://yourdomain.com/api/account/login?username=theUsername&password=thePassword', method: 'POST', xhrFields: { withCredentials: true } });
每次请求都要带上withCredentials
标识
如果使用$.ajax来这么做的话,你很快就会觉得沉闷乏味。幸好你还可能通过$.ajaxSetup进行设置
$.ajaxSetup({xhrFields: {withCredentials: true}});
设置之后,接下来每个通过JQuery发送的请求($.get, $.post等)都会带有withCredentials标识,并且设置为了true.
Angular
在Angular中,通过@angular/common/http中的HttpClient来发送请求。你可以通过如下方式来指定 withCredentials
this.httpClient.post<any>(`http://yourdomain.com/api/account/login?username=theUsername&password=thePassword`, {}, { withCredentials: true }).subscribe(....
为了更加方便,你可以创建一个 HttpInterceptor来给每个请求都加上withCredentials标识。
import { Injectable } from '@angular/core'; import { HttpInterceptor, HttpEvent, HttpRequest, HttpHandler } from '@angular/common/http'; import { Observable } from 'rxjs/Observable'; @Injectable() export class AddWithCredentialsInterceptorService implements HttpInterceptor { intercept(req: HttpRequest<any>, next: HttpHandler): Observable<HttpEvent<any>> { return next.handle(req.clone({ withCredentials: true })); } }
Fetch Api
如果你使用的是更先进的 Fetch Api, 你需要给每个与cookie相关(请求携带cookie或者响应带有Set-Cookie header)的请求添加credentials属性,并把值设为 include.
下面是一个POST请求的例子
fetch('http://yourdomain.com/api/account/login?username=theUsername&password=thePassword', { method: 'POST', credentials: 'include' }).then...
.Net 客户
创建能发送请求的客户端,你需要用到 HttpClient
HttpClient在收到响应后,会自己管理cookie; 并且当你发送请求时,会自动带上cookie, 你只需要保证在后续的请求与登录的请求使用的是同一个HttpClient实例即可。
下面是一个使用 HttpClient 例子
var client = new HttpClient(); var loginResponse = await client.PostAsync("http://yourdomain.com/api/account/login?username=theUsername&password=thePassword", null); if (!loginResponse.IsSuccessStatusCode){ //handle unsuccessful login } var response = await client.GetAsync("http://yourdomain.com/api/anEndpointThatRequiresASignedInUser/");
你可能还需要保存验证的cookie,并且在随后的某个时间点恢复它。
想象一下,用户关闭了程序,在以后的某个时间又打开程序,你希望用户不用再登录。HttpClient是完全能够实现这个功能的,但它的初始化的方式有点不同:
CookieContainer cookieContainer = new CookieContainer(); HttpClientHandler handler = new HttpClientHandler { CookieContainer = cookieContainer }; handler.CookieContainer = cookieContainer; var client = new HttpClient(handler); var loginResponse = await client.PostAsync("http://yourdomain.com/api/account/login?username=theUsername&password=thePassword", null); if (!loginResponse.IsSuccessStatusCode){ //handle unsuccessful login } var authCookie = cookieContainer.GetCookies(new Uri("http://yourdomain.com")).Cast<Cookie>().Single(cookie => cookie.Name == "auth_cookie"); //Save authCookie.ToString() somewhere //authCookie.ToString() -> auth_cookie=CfDJ8J0_eoL4pK5Hq8bJZ8e1XIXFsDk7xDzvER3g70....
你可以通过调用CookieContainer的SetCookies方法来恢复cookie.
cookieContainer.SetCookies(new Uri("http://yourdomain.com"), "auth_cookie=CfDJ8J0_eoL4pK5Hq8bJZ8e1XIXFsDk7xDzvER3g70...");
结语
看完这个帖子,对你在Web Api中设置cookie可能会有所帮助。你只需要记住一些要点即可。即:你需要确保你产生的cookie中不带有samesite属性,通过检查你的登录方法的响应中的Set-Cookie header。
做这个检查时,最好使用FireFox的开发者工具,而不是Chrome。对于跨域的请求,Chrome(至少我的j版本67.0.3396.99)不显示Set-Cookie
header
另一个需要记住的是:你正确的设置了CORS, 或者说核心是你的CORS策略中含有AllowsCredentials
最后,对于客户端而言,要确保每次请求都带上了withCredentials标识,对Fetch Api而言是带上了credentials: 'include'