ASP.NET Core + OpenIddict 實作筆記：Password Flow 與 Refresh Token

結論#

這篇整理的是 OpenIddict 在 ASP.NET Core 專案中的最小可用建置流程，包含套件安裝、資料表建立、/connect/token 實作、Refresh Token 流程，以及 Azure 上常見的憑證權限坑。

適合用在哪裡#

要自己做登入授權中心的 .NET 專案
需要發 access token / refresh token 的 API 系統
已有 ASP.NET Core Identity，想接 OpenIddict
部署到 Azure App Service，遇到憑證或權限問題的人

流程步驟#

1. 先把資料層建起來#

先安裝需要的套件，最少會用到 Microsoft.EntityFrameworkCore.SqlServer、Microsoft.EntityFrameworkCore.Tools、OpenIddict.AspNetCore、OpenIddict.EntityFrameworkCore。接著用 Migration 產生 Schema，這一步的重點不是花俏，而是先讓 OpenIddict 需要的資料表真的落地，不然後面 Token 流程再漂亮也只是空中樓閣。實作上可直接跑 EF Migration，若想先看 SQL，也能先輸出 script 再交給 DBA 檢查。

1
# Visual Studio Package Manager Console
2
Add-Migration InitialCreate
3
Update-Database
4

5
# DotNet CLI
6
dotnet ef migrations add InitialCreate
7
dotnet ef database update
8

9
# 產生 SQL 腳本
10
dotnet ef migrations script InitialCreate --context DefaultDbContext

2. 在 Startup 註冊 OpenIddict 與 Identity#

這一步要做的是把 DbContext、Identity、OpenIddict Core / Server / Validation 串起來。重點有三個：一是 options.UseOpenIddict() 要掛進 DbContext；二是 Server 端要開 /connect/token 並允許 PasswordFlow、RefreshTokenFlow；三是 Token 的壽命、Scope、簽章憑證要先定清楚。若你只是先在開發機測通流程，可以先用 AddDevelopmentEncryptionCertificate() 與 AddDevelopmentSigningCertificate()，但正式環境別偷懶，這種東西混過去，日後都會回來找你 (´-ω-`)。

1
services.AddDbContext<DefaultDbContext>(options =>
2
{
3
    options.UseSqlServer(Configuration.GetConnectionString("DefaultConnection"));
4
    options.UseOpenIddict(); // 讓 OpenIddict 使用 EF Core
5
});
6

7
services.AddOpenIddict()
8
    .AddCore(options =>
9
    {
10
        options.UseEntityFrameworkCore()
11
            .UseDbContext<DefaultDbContext>();
12
    })
13
    .AddServer(options =>
14
    {
15
        options.SetTokenEndpointUris("/connect/token");
16
        options.SetUserinfoEndpointUris("/connect/userinfo");
17

18
        options.AllowPasswordFlow();
19
        options.AllowRefreshTokenFlow();
20
        options.AllowCustomFlow("custom_flow_name");
21

22
        options.UseReferenceAccessTokens();
23
        options.UseReferenceRefreshTokens();
24

25
        options.RegisterScopes(
26
            OpenIddictConstants.Permissions.Scopes.Email,
27
            OpenIddictConstants.Permissions.Scopes.Profile,
28
            OpenIddictConstants.Permissions.Scopes.Roles);
29

30
        options.SetAccessTokenLifetime(TimeSpan.FromMinutes(30));
31
        options.SetRefreshTokenLifetime(TimeSpan.FromDays(7));
32

33
        options.AddDevelopmentEncryptionCertificate()
34
               .AddDevelopmentSigningCertificate();
35

36
        options.UseAspNetCore()
37
               .EnableTokenEndpointPassthrough();
38
    })
39
    .AddValidation(options =>
40
    {
41
        options.UseLocalServer();
42
        options.UseAspNetCore();
43
    });

3. 建立測試 Client 與使用者，先把登入鏈路打通#

在開發環境先自動建立一組 Client 與管理者帳號，能大幅減少初始化時的手工操作。這段的目的很單純：確認你的資料表、Identity、OpenIddict 三者真的接起來，而不是每次測試都在懷疑到底是帳號錯、Client 沒建、還是授權配置有洞。這裡會建立 default-client，並產出一個 admin 使用者，密碼先用 PasswordHasher 轉成雜湊後存入。

1
#if DEBUG
2
CreateCientAndUser(app);
3
#endif
4

5
private static void CreateCientAndUser(IApplicationBuilder app)
6
{
7
    using var scope = app.ApplicationServices
8
        .GetRequiredService<IServiceScopeFactory>()
9
        .CreateScope();
10

11
    var context = scope.ServiceProvider.GetRequiredService<DefaultDbContext>();
12
    context.Database.EnsureCreated();
13

14
    var manager = scope.ServiceProvider.GetRequiredService<IOpenIddictApplicationManager>();
15
    var existingClientApp = manager.FindByClientIdAsync("default-client").GetAwaiter().GetResult();
16

17
    if (existingClientApp == null)
18
    {
19
        manager.CreateAsync(new OpenIddictApplicationDescriptor
20
        {
21
            ClientId = "default-client",
22
            ClientSecret = "your-client-secret",
23
            DisplayName = "Default client application",
24
            Permissions =
25
            {
26
                OpenIddictConstants.Permissions.Endpoints.Token,
27
                OpenIddictConstants.Permissions.GrantTypes.Password,
28
                OpenIddictConstants.Permissions.GrantTypes.RefreshToken
29
            }
30
        }).GetAwaiter().GetResult();
31
    }
32
}

4. 實作 `/connect/token`，把 Password 與 Refresh Token 都接上#

/connect/token 是整個流程的核心入口，收到請求後先判斷 Grant Type，再分流到不同處理方法。Password Grant 的做法是：找到使用者、驗證密碼、建立 ClaimsIdentity、加上角色與必要 Scope，最後回傳 SignIn(...) 讓 OpenIddict 幫你發 Token。Refresh Token 則簡單很多，直接從目前驗證內容取出 ClaimsPrincipal 再重新簽發即可。白話講，前者是「靠帳密換票」，後者是「拿舊票換新票」。

1
[HttpPost("~/connect/token")]
2
[AllowAnonymous]
3
public async Task<IActionResult> Exchange()
4
{
5
    var oidcRequest = HttpContext.GetOpenIddictServerRequest();
6

7
    if (oidcRequest.IsPasswordGrantType())
8
        return await TokensForPasswordGrantType(oidcRequest);
9

10
    if (oidcRequest.IsRefreshTokenGrantType())
11
        return await TokenForRefreshGrantType();
12

13
    return BadRequest(new OpenIddictResponse
14
    {
15
        Error = OpenIddictConstants.Errors.UnsupportedGrantType
16
    });
17
}
18

19
private async Task<IActionResult> TokensForPasswordGrantType(OpenIddictRequest request)
20
{
21
    var user = await _userManager.FindByNameAsync(request.Username);
22
    if (user == null)
23
        return Unauthorized();
24

25
    var signInResult = await _signInManager.CheckPasswordSignInAsync(user, request.Password, false);
26
    if (!signInResult.Succeeded)
27
        return Unauthorized();
28

29
    var identity = new ClaimsIdentity(
30
        TokenValidationParameters.DefaultAuthenticationType,
31
        OpenIddictConstants.Claims.Name,
32
        OpenIddictConstants.Claims.Role);
33

34
    identity.AddClaim(OpenIddictConstants.Claims.Subject, user.Id.ToString(), OpenIddictConstants.Destinations.AccessToken);
35
    identity.AddClaim(OpenIddictConstants.Claims.Username, user.Username, OpenIddictConstants.Destinations.AccessToken);
36

37
    foreach (var userRole in user.UserRoles)
38
    {
39
        identity.AddClaim(OpenIddictConstants.Claims.Role, userRole.Role.NormalizedName, OpenIddictConstants.Destinations.AccessToken);
40
    }
41

42
    var principal = new ClaimsPrincipal(identity);
43
    principal.SetScopes(new[]
44
    {
45
        OpenIddictConstants.Scopes.Roles,
46
        OpenIddictConstants.Scopes.OfflineAccess,
47
        OpenIddictConstants.Scopes.Email,
48
        OpenIddictConstants.Scopes.Profile
49
    });
50

51
    return SignIn(principal, OpenIddictServerAspNetCoreDefaults.AuthenticationScheme);
52
}
53

54
private async Task<IActionResult> TokenForRefreshGrantType()
55
{
56
    var principal = (await HttpContext.AuthenticateAsync(
57
        OpenIddictServerAspNetCoreDefaults.AuthenticationScheme)).Principal;
58

59
    return SignIn(principal, OpenIddictServerAspNetCoreDefaults.AuthenticationScheme);
60
}

補充#

Azure App Service 若遇到 WindowsCryptographicException: Access is denied.，可先補上 WEBSITE_LOAD_USER_PROFILE=1，這通常是在載入開發憑證時踩到的坑。
UseReferenceAccessTokens() / UseReferenceRefreshTokens() 代表實際 Token 內容存在資料庫，外部拿到的是參照值，方便控管，但也更依賴資料庫穩定性。
Password Flow 雖然實作快，但通常只適合受控系統或內部整合；若是對外產品，授權流程要再多想一步，別只求先能跑。

指令 / 範例整理#

Click to expand

1
# 安裝後執行 Migration
2
Add-Migration InitialCreate
3
Update-Database
4

5
dotnet ef migrations add InitialCreate
6
dotnet ef database update
7
dotnet ef migrations script InitialCreate --context DefaultDbContext

1
POST /connect/token
2
Content-Type: application/x-www-form-urlencoded
3

4
grant_type=password
5
client_id=default-client
6
client_secret=your-client-secret
7
username=admin
8
password=your-password
9
scope=offline_access profile email roles

1
POST /connect/token
2
Content-Type: application/x-www-form-urlencoded
3

4
grant_type=refresh_token
5
client_id=default-client
6
client_secret=your-client-secret
7
refresh_token=your-refresh-token

收尾#

OpenIddict 真的不難，難的是一開始把資料表、授權設定、Token 流程一次接對；先求最小可用，再慢慢補安全與正式環境配置，這才是正常活路。

參考來源#

OpenIddict官方文件 https://github.com/openiddict/openiddict-core
在 .NET 5 中使用 OpenIddict 設置令牌身份驗證 https://nwb.one/blog/openid-connect-dotnet-5
使用 OpenIddict 建立一個支援 Client Credentials Grant 的 Authentication Server 來保護你的 Web API https://wezmag.github.io/posts/protect-api-with-client-credentials-grant-using-openiddict-part-1/
使用 OpenIddict 設置授權服務器 - 第 VI 部分 - 刷新令牌 https://dev.to/robinvanderknaap/setting-up-an-authorization-server-with-openiddict-part-vi-refresh-tokens-5669
OpenIddict詳細流程 https://www.cnblogs.com/liyouming/p/15772403.html

結論#