ASP.NET Core + OpenIddict Implementation Notes: Password Flow and Refresh Token

Conclusion#

This post summarizes the minimum viable build process for OpenIddict in an ASP.NET Core project, including package installation, database table creation, /connect/token implementation, Refresh Token flow, and common certificate permission pitfalls on Azure.

Use Cases#

.NET projects that need to build their own login authorization center
API systems that need to issue access token / refresh token
Existing ASP.NET Core Identity projects that want to integrate OpenIddict
Anyone deploying to Azure App Service and encountering certificate or permission issues

Workflow Steps#

1. Set up the Data Layer First#

First, install the necessary packages. At a minimum, you’ll need Microsoft.EntityFrameworkCore.SqlServer, Microsoft.EntityFrameworkCore.Tools, OpenIddict.AspNetCore, and OpenIddict.EntityFrameworkCore. Then, use Migration to generate the schema. The key point here isn’t fancy features, but ensuring that the database tables required by OpenIddict are actually created. Otherwise, no matter how elegant your Token flow is, it will just be a castle in the air. In practice, you can directly run EF Migration, or if you want to see the SQL first, you can output a script and hand it over to your DBA for review.

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. Register OpenIddict and Identity in Startup#

This step involves connecting DbContext, Identity, and OpenIddict Core / Server / Validation. There are three key points: first, options.UseOpenIddict() must be hooked into DbContext; second, the Server-side needs to enable /connect/token and allow PasswordFlow and RefreshTokenFlow; third, the Token’s lifetime, Scope, and signing certificate must be clearly defined. If you’re just testing the flow on a development machine, you can use AddDevelopmentEncryptionCertificate() and AddDevelopmentSigningCertificate(). However, don’t be lazy in a production environment; if you gloss over these things, they will come back to haunt you later (´-ω-`).

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
    });

Automatically creating a client and an administrator account in the development environment can significantly reduce manual operations during initialization. The purpose of this section is simple: to confirm that your database tables, Identity, and OpenIddict are truly connected, rather than constantly wondering during testing if it’s an incorrect account, a missing client, or a flaw in the authorization configuration. Here, a default-client will be created, and an admin user will be generated, with the password first hashed using PasswordHasher before being stored.

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. Implement /connect/token, Connecting Both Password and Refresh Tokens#

/connect/token is the core entry point for the entire flow. Upon receiving a request, it first determines the Grant Type and then dispatches to different handling methods. The approach for Password Grant is: find the user, validate the password, create a ClaimsIdentity, add roles and necessary Scopes, and finally return SignIn(...) to let OpenIddict issue the token for you. Refresh Token is much simpler: just retrieve the ClaimsPrincipal from the current authentication context and re-issue the token. In plain terms, the former is “exchanging credentials for a ticket,” while the latter is “exchanging an old ticket for a new one.”

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
}

Additional Notes#

If you encounter WindowsCryptographicException: Access is denied. on Azure App Service, you can first add WEBSITE_LOAD_USER_PROFILE=1. This is a common pitfall when loading development certificates.
UseReferenceAccessTokens() / UseReferenceRefreshTokens() means the actual token content is stored in the database, and external parties receive a reference value. This facilitates management but also increases reliance on database stability.
While Password Flow is quick to implement, it’s generally only suitable for controlled systems or internal integrations. For external-facing products, the authorization flow requires more thought than just getting it to run.

Commands / Examples Summary#

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

Wrapping Up#

OpenIddict isn’t really difficult; the challenge lies in correctly connecting the database tables, authorization settings, and token flow all at once from the beginning. Aim for minimum viability first, then gradually add security and production environment configurations – that’s the normal path forward.

References#

OpenIddict Official Documentation https://github.com/openiddict/openiddict-core
Setting up Token Authentication with OpenIddict in .NET 5 https://nwb.one/blog/openid-connect-dotnet-5
Building an Authentication Server with OpenIddict to Protect Your Web API with Client Credentials Grant https://wezmag.github.io/posts/protect-api-with-client-credentials-grant-using-openiddict-part-1/
Setting up an Authorization Server with OpenIddict - Part VI - Refresh Tokens https://dev.to/robinvanderknaap/setting-up-an-authorization-server-with-openiddict-part-vi-refresh-tokens-5669
Detailed OpenIddict Flow https://www.cnblogs.com/liyouming/p/15772403.html