上一篇文章(http://www.javashuo.com/article/p-ktmtutos-kr.html)再次把Swagger的使用進行了講解,完成了對Swagger的分組、描述和開啓小綠鎖以進行身份的認證受權,那麼本篇就來講說身份認證受權。html
開始以前先搞清楚幾個概念,請注意認證與受權是不一樣的意思,簡單理解:認證,是證實你的身份,你有帳號密碼,你能夠登陸進咱們的系統,說明你認證成功了;受權,即權限,分配給用戶某一權限標識,用戶獲得什麼什麼權限,才能使用系統的某一功能,就是受權。git
身份認證能夠有不少種方式,能夠建立一個用戶表,使用帳號密碼,也能夠接入第三方平臺,在這裏我接入GitHub進行身份認證。固然你能夠選擇其餘方式(如:QQ、微信、微博等),能夠本身擴展。github
打開GitHub,進入開發者設置界面(https://github.com/settings/developers),咱們新建一個 oAuth App。web
如圖所示,咱們將要用到敏感數據放在appsettings.json
中json
{ ... "Github": { "UserId": 13010050, "ClientID": "5956811a5d04337ec2ca", "ClientSecret": "8fc1062c39728a8c2a47ba445dd45165063edd92", "RedirectUri": "https://localhost:44388/account/auth", "ApplicationName": "阿星Plus" } }
ClientID
和ClientSecret
是GitHub爲咱們生成的,請注意保管好你的ClientID
和ClientSecret
。我這裏直接給出了明文,我將在本篇結束後刪掉此 oAuth App 😝。請本身建立噢!api
RedirectUri
是咱們本身添加的回調地址。ApplicationName
是咱們應用的名稱,所有都要和GitHub對應。安全
相應的在AppSettings.cs
中讀取服務器
... /// <summary> /// GitHub /// </summary> public static class GitHub { public static int UserId => Convert.ToInt32(_config["Github:UserId"]); public static string Client_ID => _config["Github:ClientID"]; public static string Client_Secret => _config["Github:ClientSecret"]; public static string Redirect_Uri => _config["Github:RedirectUri"]; public static string ApplicationName => _config["Github:ApplicationName"]; } ...
接下來,咱們你們自行去GitHub的OAuth官方文檔看看,https://developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/微信
分析一下,咱們接入GitHub身份認證受權整個流程下來分如下幾步app
code
參數開始以前,先將GitHub的API簡單處理一下。
在.Domain
層中Configurations文件夾下新建GitHubConfig.cs
配置類,將所須要的API以及appsettings.json
的內容讀取出來。
//GitHubConfig.cs namespace Meowv.Blog.Domain.Configurations { public class GitHubConfig { /// <summary> /// GET請求,跳轉GitHub登陸界面,獲取用戶受權,獲得code /// </summary> public static string API_Authorize = "https://github.com/login/oauth/authorize"; /// <summary> /// POST請求,根據code獲得access_token /// </summary> public static string API_AccessToken = "https://github.com/login/oauth/access_token"; /// <summary> /// GET請求,根據access_token獲得用戶信息 /// </summary> public static string API_User = "https://api.github.com/user"; /// <summary> /// Github UserId /// </summary> public static int UserId = AppSettings.GitHub.UserId; /// <summary> /// Client ID /// </summary> public static string Client_ID = AppSettings.GitHub.Client_ID; /// <summary> /// Client Secret /// </summary> public static string Client_Secret = AppSettings.GitHub.Client_Secret; /// <summary> /// Authorization callback URL /// </summary> public static string Redirect_Uri = AppSettings.GitHub.Redirect_Uri; /// <summary> /// Application name /// </summary> public static string ApplicationName = AppSettings.GitHub.ApplicationName; } }
細心的同窗可能以及看到了,咱們在配置的時候多了一個UserId
。在這裏使用一個策略,由於我是博客系統,管理員用戶就只有我一我的,GitHub的用戶Id是惟一的,我將本身的UserId
配置進去,當咱們經過api獲取到UserId
和本身配置的UserId
一致時,就爲其受權,你就是我,我承認你,你能夠進入後臺隨意玩耍了。
在開始寫接口以前,還有一些工做要作,就是在 .net core 中開啓使用咱們的身份認證和受權,由於.HttpApi.Hosting
層引用了項目.Application
,.Application
層自己也須要添加Microsoft.AspNetCore.Authentication.JwtBearer
,因此在.Application
添加包:Microsoft.AspNetCore.Authentication.JwtBearer
,打開程序包管理器控制檯用命令Install-Package Microsoft.AspNetCore.Authentication.JwtBearer
安裝,這樣就不須要重複添加引用了。
在.HttpApi.Hosting
模塊類MeowvBlogHttpApiHostingModule
,ConfigureServices
中添加
public override void ConfigureServices(ServiceConfigurationContext context) { // 身份驗證 context.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme) .AddJwtBearer(options => { options.TokenValidationParameters = new TokenValidationParameters { ValidateIssuer = true, ValidateAudience = true, ValidateLifetime = true, ClockSkew = TimeSpan.FromSeconds(30), ValidateIssuerSigningKey = true, ValidAudience = AppSettings.JWT.Domain, ValidIssuer = AppSettings.JWT.Domain, IssuerSigningKey = new SymmetricSecurityKey(AppSettings.JWT.SecurityKey.GetBytes()) }; }); // 認證受權 context.Services.AddAuthorization(); // Http請求 context.Services.AddHttpClient(); }
由於待會咱們要在代碼中調用GitHub的api,因此這裏提早將System.Net.Http.IHttpClientFactory
和相關服務添加到IServiceCollection中。
解釋一下TokenValidationParameters
參數的含義:
ValidateIssuer
:是否驗證頒發者。ValidateAudience
:是否驗證訪問羣體。ValidateLifetime
:是否驗證生存期。ClockSkew
:驗證Token的時間偏移量。ValidateIssuerSigningKey
:是否驗證安全密鑰。ValidAudience
:訪問羣體。ValidIssuer
:頒發者。IssuerSigningKey
:安全密鑰。
GetBytes()
是abp的一個擴展方法,能夠直接使用。
設置值所有爲true,時間偏移量爲30秒,而後將ValidAudience
、ValidIssuer
、IssuerSigningKey
的值配置在appsettings.json
中,這些值都是能夠自定義的,不必定按照我填的來。
//appsettings.json { ... "JWT": { "Domain": "https://localhost:44388", "SecurityKey": "H4sIAAAAAAAAA3N0cnZxdXP38PTy9vH18w8I9AkOCQ0Lj4iMAgDB4fXPGgAAAA==", "Expires": 30 } } //AppSettings.cs ... public static class JWT { public static string Domain => _config["JWT:Domain"]; public static string SecurityKey => _config["JWT:SecurityKey"]; public static int Expires => Convert.ToInt32(_config["JWT:Expires"]); } ...
Expires
是咱們的token過時時間,這裏也給個30。至於它是30分鐘仍是30秒,由你本身決定。
SecurityKey
是我隨便用編碼工具進行生成的。
同時在OnApplicationInitialization(ApplicationInitializationContext context)
中使用它。
... public override void OnApplicationInitialization(ApplicationInitializationContext context) { ... // 身份驗證 app.UseAuthentication(); // 認證受權 app.UseAuthorization(); ... } ...
此時配置就完成了,接下來去寫接口生成Token並在Swagger中運用起來。
在.Application
層以前已經添加了包:Microsoft.AspNetCore.Authentication.JwtBearer
,直接新建Authorize文件夾,添加接口IAuthorizeService
以及實現類AuthorizeService
。
//IAuthorizeService.cs using Meowv.Blog.ToolKits.Base; using System.Threading.Tasks; namespace Meowv.Blog.Application.Authorize { public interface IAuthorizeService { /// <summary> /// 獲取登陸地址(GitHub) /// </summary> /// <returns></returns> Task<ServiceResult<string>> GetLoginAddressAsync(); /// <summary> /// 獲取AccessToken /// </summary> /// <param name="code"></param> /// <returns></returns> Task<ServiceResult<string>> GetAccessTokenAsync(string code); /// <summary> /// 登陸成功,生成Token /// </summary> /// <param name="access_token"></param> /// <returns></returns> Task<ServiceResult<string>> GenerateTokenAsync(string access_token); } }
添加三個接口成員方法,所有爲異步的方式,同時注意咱們是用以前編寫的返回模型接收噢,而後一一去實現他們。
先實現GetLoginAddressAsync()
,我們構建一個AuthorizeRequest
對象,用來填充生成GitHub登陸地址,在.ToolKits
層新建GitHub文件夾,引用.Domain
項目,添加類:AuthorizeRequest.cs
。
//AuthorizeRequest.cs using Meowv.Blog.Domain.Configurations; using System; namespace Meowv.Blog.ToolKits.GitHub { public class AuthorizeRequest { /// <summary> /// Client ID /// </summary> public string Client_ID = GitHubConfig.Client_ID; /// <summary> /// Authorization callback URL /// </summary> public string Redirect_Uri = GitHubConfig.Redirect_Uri; /// <summary> /// State /// </summary> public string State { get; set; } = Guid.NewGuid().ToString("N"); /// <summary> /// 該參數可選,須要調用Github哪些信息,能夠填寫多個,以逗號分割,好比:scope=user,public_repo。 /// 若是不填寫,那麼你的應用程序將只能讀取Github公開的信息,好比公開的用戶信息,公開的庫(repository)信息以及gists信息 /// </summary> public string Scope { get; set; } = "user,public_repo"; } }
實現方法以下,拼接參數,輸出GitHub重定向的地址。
... /// <summary> /// 獲取登陸地址(GitHub) /// </summary> /// <returns></returns> public async Task<ServiceResult<string>> GetLoginAddressAsync() { var result = new ServiceResult<string>(); var request = new AuthorizeRequest(); var address = string.Concat(new string[] { GitHubConfig.API_Authorize, "?client_id=", request.Client_ID, "&scope=", request.Scope, "&state=", request.State, "&redirect_uri=", request.Redirect_Uri }); result.IsSuccess(address); return await Task.FromResult(result); } ...
一樣的,實現GetAccessTokenAsync(string code)
,構建AccessTokenRequest
對象,在.ToolKits
GitHub文件夾添加類:AccessTokenRequest.cs
。
//AccessTokenRequest.cs using Meowv.Blog.Domain.Configurations; namespace Meowv.Blog.ToolKits.GitHub { public class AccessTokenRequest { /// <summary> /// Client ID /// </summary> public string Client_ID = GitHubConfig.Client_ID; /// <summary> /// Client Secret /// </summary> public string Client_Secret = GitHubConfig.Client_Secret; /// <summary> /// 調用API_Authorize獲取到的Code值 /// </summary> public string Code { get; set; } /// <summary> /// Authorization callback URL /// </summary> public string Redirect_Uri = GitHubConfig.Redirect_Uri; /// <summary> /// State /// </summary> public string State { get; set; } } }
根據登陸成功獲得的code來獲取AccessToken,由於涉及到HTTP請求,在這以前咱們須要在構造函數中依賴注入IHttpClientFactory
,使用IHttpClientFactory
建立HttpClient
。
... private readonly IHttpClientFactory _httpClient; public AuthorizeService(IHttpClientFactory httpClient) { _httpClient = httpClient; } ...
... /// <summary> /// 獲取AccessToken /// </summary> /// <param name="code"></param> /// <returns></returns> public async Task<ServiceResult<string>> GetAccessTokenAsync(string code) { var result = new ServiceResult<string>(); if (string.IsNullOrEmpty(code)) { result.IsFailed("code爲空"); return result; } var request = new AccessTokenRequest(); var content = new StringContent($"code={code}&client_id={request.Client_ID}&redirect_uri={request.Redirect_Uri}&client_secret={request.Client_Secret}"); content.Headers.ContentType = new MediaTypeHeaderValue("application/x-www-form-urlencoded"); using var client = _httpClient.CreateClient(); var httpResponse = await client.PostAsync(GitHubConfig.API_AccessToken, content); var response = await httpResponse.Content.ReadAsStringAsync(); if (response.StartsWith("access_token")) result.IsSuccess(response.Split("=")[1].Split("&").First()); else result.IsFailed("code不正確"); return result; } ...
使用IHttpClientFactory
建立HttpClient
能夠自動釋放對象,用HttpClient
發送一個POST請求,若是GitHub服務器給咱們返回了帶access_token的字符串便表示成功了,將其處理一下輸出access_token。若是沒有,就表明參數code有誤。
在.HttpApi
層新建一個AuthController
控制器,注入咱們的IAuthorizeService
Service,試試咱們的接口。
//AuthController.cs using Meowv.Blog.Application.Authorize; using Meowv.Blog.ToolKits.Base; using Microsoft.AspNetCore.Authorization; using Microsoft.AspNetCore.Mvc; using System.Threading.Tasks; using Volo.Abp.AspNetCore.Mvc; using static Meowv.Blog.Domain.Shared.MeowvBlogConsts; namespace Meowv.Blog.HttpApi.Controllers { [ApiController] [AllowAnonymous] [Route("[controller]")] [ApiExplorerSettings(GroupName = Grouping.GroupName_v4)] public class AuthController : AbpController { private readonly IAuthorizeService _authorizeService; public AuthController(IAuthorizeService authorizeService) { _authorizeService = authorizeService; } /// <summary> /// 獲取登陸地址(GitHub) /// </summary> /// <returns></returns> [HttpGet] [Route("url")] public async Task<ServiceResult<string>> GetLoginAddressAsync() { return await _authorizeService.GetLoginAddressAsync(); } /// <summary> /// 獲取AccessToken /// </summary> /// <param name="code"></param> /// <returns></returns> [HttpGet] [Route("access_token")] public async Task<ServiceResult<string>> GetAccessTokenAsync(string code) { return await _authorizeService.GetAccessTokenAsync(code); } } }
注意這裏咱們添加了兩個Attribute:[AllowAnonymous]、[ApiExplorerSettings(GroupName = Grouping.GroupName_v4)],在.Swagger
層中爲AuthController
添加描述信息
... new OpenApiTag { Name = "Auth", Description = "JWT模式認證受權", ExternalDocs = new OpenApiExternalDocs { Description = "JSON Web Token" } } ...
打開Swagger文檔,調用一下咱們兩個接口看看效果。
而後打開咱們生成的重定向地址,會跳轉到登陸頁面,以下:
點擊Authorize按鈕,登陸成功後會跳轉至咱們配置的回調頁面,.../account/auth?code=10b7a58c7ba2e4414a14&state=a1ef05212c3b4a2cb2bbd87846dd4a8e
而後拿到code(10b7a58c7ba2e4414a14),在去調用一下獲取AccessToken接口,成功返回咱們的access_token(97eeafd5ca01b3719f74fc928440c89d59f2eeag)。
拿到access_token,就能夠去調用獲取用戶信息API了。在這以前咱們先來寫幾個擴展方法,待會和之後都用得着,在.ToolKits
層新建文件夾Extensions,添加幾個比較經常使用的擴展類(...)。
擴展類的代碼我就不貼出來了。你們能夠去GitHub(https://github.com/Meowv/Blog/tree/blog_tutorial/src/Meowv.Blog.ToolKits/Extensions)自行下載,每一個擴展方法都有具體的註釋。
接下來實現GenerateTokenAsync(string access_token)
,生成Token。
有了access_token,能夠直接調用獲取用戶信息的接口:https://api.github.com/user?access_token=97eeafd5ca01b3719f74fc928440c89d59f2eeag ,會獲得一個json,將這個json包裝成一個模型類UserResponse.cs
。
在這裏教你們一個小技巧,若是你須要將json或者xml轉換成模型類,可使用Visual Studio的一個快捷功能,點擊左上角菜單:編輯 => 選擇性粘貼 => 將JSON粘貼爲類/將XML粘貼爲類,是否是很方便,快去試試吧。
//UserResponse.cs namespace Meowv.Blog.ToolKits.GitHub { public class UserResponse { public string Login { get; set; } public int Id { get; set; } public string Avatar_url { get; set; } public string Html_url { get; set; } public string Repos_url { get; set; } public string Name { get; set; } public string Company { get; set; } public string Blog { get; set; } public string Location { get; set; } public string Email { get; set; } public string Bio { get; set; } public int Public_repos { get; set; } } }
而後看一下具體生成token的方法吧。
... /// <summary> /// 登陸成功,生成Token /// </summary> /// <param name="access_token"></param> /// <returns></returns> public async Task<ServiceResult<string>> GenerateTokenAsync(string access_token) { var result = new ServiceResult<string>(); if (string.IsNullOrEmpty(access_token)) { result.IsFailed("access_token爲空"); return result; } var url = $"{GitHubConfig.API_User}?access_token={access_token}"; using var client = _httpClient.CreateClient(); client.DefaultRequestHeaders.Add("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/83.0.4103.14 Safari/537.36 Edg/83.0.478.13"); var httpResponse = await client.GetAsync(url); if (httpResponse.StatusCode != HttpStatusCode.OK) { result.IsFailed("access_token不正確"); return result; } var content = await httpResponse.Content.ReadAsStringAsync(); var user = content.FromJson<UserResponse>(); if (user.IsNull()) { result.IsFailed("未獲取到用戶數據"); return result; } if (user.Id != GitHubConfig.UserId) { result.IsFailed("當前帳號未受權"); return result; } var claims = new[] { new Claim(ClaimTypes.Name, user.Name), new Claim(ClaimTypes.Email, user.Email), new Claim(JwtRegisteredClaimNames.Exp, $"{new DateTimeOffset(DateTime.Now.AddMinutes(AppSettings.JWT.Expires)).ToUnixTimeSeconds()}"), new Claim(JwtRegisteredClaimNames.Nbf, $"{new DateTimeOffset(DateTime.Now).ToUnixTimeSeconds()}") }; var key = new SymmetricSecurityKey(AppSettings.JWT.SecurityKey.SerializeUtf8()); var creds = new SigningCredentials(key, SecurityAlgorithms.HmacSha256); var securityToken = new JwtSecurityToken( issuer: AppSettings.JWT.Domain, audience: AppSettings.JWT.Domain, claims: claims, expires: DateTime.Now.AddMinutes(AppSettings.JWT.Expires), signingCredentials: creds); var token = new JwtSecurityTokenHandler().WriteToken(securityToken); result.IsSuccess(token); return await Task.FromResult(result); } ...
GitHub的這個API作了相應的安全機制,有一點要注意一下,當咱們用代碼去模擬請求的時候,須要給他加上User-Agent
,否則是不會成功返回結果的。
FromJson<T>
是以前咱們添加的擴展方法,將JSON字符串轉爲實體對象。
SymmetricSecurityKey(byte[] key)
接收一個byte[]
參數,這裏也用到一個擴展方法SerializeUtf8()
字符串序列化成字節序列。
咱們判斷返回的Id是否爲咱們配置的用戶Id,若是是的話,就驗證成功,進行受權,生成Token。
生成Token的代碼也很簡單,指定了 Name,Email,過時時間爲30分鐘。具體各項含義能夠去這裏看看:https://tools.ietf.org/html/rfc7519。
最後調用new JwtSecurityTokenHandler().WriteToken(SecurityToken token)
即可成功生成Token,在Controller添加好,去試試吧。
... /// <summary> /// 登陸成功,生成Token /// </summary> /// <param name="access_token"></param> /// <returns></returns> [HttpGet] [Route("token")] public async Task<ServiceResult<string>> GenerateTokenAsync(string access_token) { return await _authorizeService.GenerateTokenAsync(access_token); } ...
將以前拿到的access_token傳進去,調用接口能夠看到已經成功生成了token。
前面爲AuthController
添加了一個Attribute:[AllowAnonymous]
,表明這個Controller下的接口都不須要受權,就能夠訪問,固然你不添加的話默認也是開放的。能夠爲整個Controller指定,同時也能夠爲具體的接口指定。
當想要保護某個接口時,只須要加上Attribute:[Authorize]
就能夠了。如今來保護咱們的BlogController
下非查詢接口,給增刪改添加上[Authorize]
,注意引用命名空間Microsoft.AspNetCore.Authorization
。
... ... /// <summary> /// 添加博客 /// </summary> /// <param name="dto"></param> /// <returns></returns> [HttpPost] [Authorize] public async Task<ServiceResult<string>> InsertPostAsync([FromBody] PostDto dto) ... /// <summary> /// 刪除博客 /// </summary> /// <param name="id"></param> /// <returns></returns> [HttpDelete] [Authorize] public async Task<ServiceResult> DeletePostAsync([Required] int id) ... /// <summary> /// 更新博客 /// </summary> /// <param name="id"></param> /// <param name="dto"></param> /// <returns></returns> [HttpPut] [Authorize] public async Task<ServiceResult<string>> UpdatePostAsync([Required] int id, [FromBody] PostDto dto) ... /// <summary> /// 查詢博客 /// </summary> /// <param name="id"></param> /// <returns></returns> [HttpGet] public async Task<ServiceResult<PostDto>> GetPostAsync([Required] int id) ... ...
如今編譯運行一下,調用上面的增刪改看看能不能成功?
這時接口就會直接給咱們返回一個狀態碼爲401的錯誤,爲了不這種不友好的錯誤,咱們能夠添加一箇中間件來處理咱們的管道請求或者在AddJwtBearer()
中處理咱們的身份驗證事件機制,當遇到錯誤的狀態碼時,咱們仍是返回咱們以前的建立的模型,定義友好的返回錯誤,將在後面篇章中給出具體方法。
能夠看到公開的API和須要受權的API小綠鎖是不同的,公開的顯示爲黑色,須要受權的顯示爲灰色。
若是須要在Swagger中調用咱們的非公開API,要怎麼作呢?點擊咱們的小綠鎖將生成的token按照Bearer {Token}
的方式填進去便可。
注意不要點Logout,不然就退出了。
能夠看到當咱們請求的時候,請求頭上多了一個authorization: Bearer {token}
,此時便大功告成了。當咱們在web中調用的時候,也遵循這個規則便可。
特別提示
在我作受權的時候,token也生成成功了,也在Swagger中正確填寫Bearer {token}了。調用接口的時候始終仍是返回401,最終發現致使這個問題的緣由是在配置Swagger小綠鎖時一個錯誤名稱致使的。
看他的描述爲:A unique name for the scheme, as per the Swagger spec.(根據Swagger規範,該方案的惟一名稱)
如圖,將其名稱改成 "oauth2" ,即可以成功受權。本篇接入了GitHub,實現了認證和受權,用JWT的方式保護咱們寫的API,你學會了嗎?😁😁😁