基於 abp vNext 和 .NET Core 開發博客項目 – 接入GitHub，用JWT保護你的API
上一篇文章(//www.cnblogs.com/meowv/p/12924859.html)再次把Swagger的使用進行了講解，完成了對Swagger的分組、描述和開啟小綠鎖以進行身份的認證授權，那麼本篇就來說說身份認證授權。
開始之前先搞清楚幾個概念，請注意認證與授權是不同的意思，簡單理解：認證，是證明你的身份，你有賬號密碼，你可以登錄進我們的系統，說明你認證成功了；授權，即權限，分配給用戶某一權限標識，用戶得到什麼什麼權限，才能使用系統的某一功能，就是授權。
身份認證可以有很多種方式，可以創建一個用戶表，使用賬號密碼，也可以接入第三方平台，在這裡我接入GitHub進行身份認證。當然你可以選擇其他方式(如：QQ、微信、微博等)，可以自己擴展。
打開GitHub，進入開發者設置界面(//github.com/settings/developers)，我們新建一個 oAuth App。
如圖所示，我們將要用到敏感數據放在appsettings.json中
{
...
"Github": {
"UserId": 13010050,
"ClientID": "5956811a5d04337ec2ca",
"ClientSecret": "8fc1062c39728a8c2a47ba445dd45165063edd92",
"RedirectUri": "//localhost:44388/account/auth",
"ApplicationName": "阿星Plus"
}
}
ClientID和ClientSecret是GitHub為我們生成的，請注意保管好你的ClientID和ClientSecret。我這裡直接給出了明文，我將在本篇結束後刪掉此 oAuth App 😝。請自己創建噢！
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官方文檔看看，//developer.github.com/apps/building-oauth-apps/authorizing-oauth-apps/
分析一下，我們接入GitHub身份認證授權整個流程下來分以下幾步
- 根據參數生成GitHub重定向的地址，跳轉到GitHub登錄頁，進行登錄
- 登錄成功之後會跳轉到我們的回調地址，回調地址會攜帶
code參數 - 拿到code參數，就可以換取到access_token
- 有了access_token，可以調用GitHub獲取用戶信息的接口，得到當前登錄成功的用戶信息
開始之前，先將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 = "//github.com/login/oauth/authorize";
/// <summary>
/// POST請求，根據code得到access_token
/// </summary>
public static string API_AccessToken = "//github.com/login/oauth/access_token";
/// <summary>
/// GET請求，根據access_token得到用戶信息
/// </summary>
public static string API_User = "//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": "//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對象，在.ToolKitsGitHub文件夾添加類：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控制器，注入我們的IAuthorizeServiceService，試試我們的接口。
//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(//github.com/Meowv/Blog/tree/blog_tutorial/src/Meowv.Blog.ToolKits/Extensions)自行下載，每個擴展方法都有具體的注釋。
接下來實現GenerateTokenAsync(string access_token)，生成Token。
有了access_token，可以直接調用獲取用戶信息的接口：//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分鐘。具體各項含義可以去這裡看看：//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，你學會了嗎？😁😁😁
開源地址：//github.com/Meowv/Blog/tree/blog_tutorial
