ASP.NET 中 OAuth 2.0/OpenID Connect 深度集成指南

核心配置

1. 安装必要 NuGet 包

Install-Package Microsoft.AspNetCore.Authentication.OpenIdConnect
Install-Package Microsoft.IdentityModel.Protocols.OpenIdConnect

2. Startup 配置 (ASP.NET Core 3.1+/6.0/7.0/8.0)

public void ConfigureServices(IServiceCollection services)
{
    services.AddAuthentication(options =>
    {
        options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
    })
    .AddCookie()
    .AddOpenIdConnect(options =>
    {
        // 基本配置
        options.Authority = "https://your-identity-provider.com";
        options.ClientId = "your-client-id";
        options.ClientSecret = "your-client-secret";
        options.ResponseType = OpenIdConnectResponseType.Code;
        
        // 作用域配置
        options.Scope.Clear();
        options.Scope.Add("openid");
        options.Scope.Add("profile");
        options.Scope.Add("email");
        options.Scope.Add("offline_access"); // 用于获取刷新令牌
        
        // 安全配置
        options.UsePkce = true; // 启用PKCE
        options.SaveTokens = true; // 保存令牌到Cookie
        options.GetClaimsFromUserInfoEndpoint = true;
        
        // 令牌验证配置
        options.TokenValidationParameters = new TokenValidationParameters
        {
            NameClaimType = "name",
            RoleClaimType = "role",
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ClockSkew = TimeSpan.FromMinutes(1)
        };
        
        // 事件处理
        options.Events = new OpenIdConnectEvents
        {
            OnAuthorizationCodeReceived = OnAuthorizationCodeReceivedAsync,
            OnTokenResponseReceived = OnTokenResponseReceivedAsync,
            OnUserInformationReceived = OnUserInformationReceivedAsync,
            OnTokenValidated = OnTokenValidatedAsync,
            OnAuthenticationFailed = OnAuthenticationFailedAsync
        };
    });
}

高级配置

1. 令牌管理

// 存储令牌到数据库示例
private async Task OnTokenResponseReceivedAsync(TokenResponseReceivedContext context)
{
    var userId = context.Principal.FindFirstValue(ClaimTypes.NameIdentifier);
    var tokens = new
    {
        context.TokenEndpointResponse.AccessToken,
        context.TokenEndpointResponse.RefreshToken,
        context.TokenEndpointResponse.ExpiresIn
    };
    
    // 存储或更新用户令牌
    await _tokenService.StoreTokensAsync(userId, tokens);
}

2. 令牌刷新机制

public async Task<string> RefreshAccessTokenAsync(string refreshToken)
{
    var client = _httpClientFactory.CreateClient();
    
    var response = await client.RequestRefreshTokenAsync(new RefreshTokenRequest
    {
        Address = "https://your-identity-provider.com/connect/token",
        ClientId = "your-client-id",
        ClientSecret = "your-client-secret",
        RefreshToken = refreshToken
    });
    
    if (response.IsError)
    {
        throw new Exception("刷新令牌失败: " + response.Error);
    }
    
    return response.AccessToken;
}

3. 安全增强配置

services.AddOpenIdConnect(options =>
{
    // ...其他配置
    
    // 防止CSRF攻击
    options.NonceCookie.SameSite = SameSiteMode.Strict;
    options.CorrelationCookie.SameSite = SameSiteMode.Strict;
    
    // 严格的重定向URI验证
    options.RequireHttpsMetadata = true;
    options.Events.OnRedirectToIdentityProvider = context =>
    {
        context.ProtocolMessage.RedirectUri = "https://yourapp.com/signin-oidc";
        return Task.CompletedTask;
    };
    
    // 自定义令牌验证
    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidIssuer = "https://your-identity-provider.com",
        ValidAudience = "your-client-id",
        ValidateIssuerSigningKey = true,
        ValidateLifetime = true,
        ClockSkew = TimeSpan.Zero // 严格验证过期时间
    };
});

实际应用场景

1. API 保护

// 在Program.cs或Startup.cs中
services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.Authority = "https://your-identity-provider.com";
        options.Audience = "your-api-resource";
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true
        };
    });

// 在控制器上
[Authorize(AuthenticationSchemes = JwtBearerDefaults.AuthenticationScheme)]
[ApiController]
public class SecureApiController : ControllerBase
{
    // 受保护的API端点
}

2. 混合流（前端+后端）

// 配置混合流
services.AddOpenIdConnect(options =>
{
    options.ResponseType = OpenIdConnectResponseType.CodeIdToken;
    options.ResponseMode = OpenIdConnectResponseMode.FormPost;
    options.SaveTokens = true;
    
    // 前端可以访问的令牌
    options.Events.OnTicketReceived = context =>
    {
        var tokens = context.Properties.GetTokens();
        context.HttpContext.Response.Cookies.Append(
            "frontend_access_token",
            tokens.First(t => t.Name == "access_token").Value,
            new CookieOptions { HttpOnly = false, Secure = true, SameSite = SameSiteMode.Strict }
        );
        return Task.CompletedTask;
    };
});

故障排除

常见问题解决方案

1. 令牌验证失败

   • 检查颁发者(issuer)和受众(audience)配置

   • 验证签名密钥是否正确加载

   • 检查系统时钟同步

2. 重定向URI不匹配

   • 确保在身份提供者和应用中配置完全相同的URI

   • 注意大小写和尾部斜杠

3. CORS问题

   • 确保正确配置CORS策略

   • 检查预检请求(OPTIONS)是否被正确处理

4. 令牌过期问题

   • 实现自动刷新机制

   • 考虑使用滑动过期策略

性能优化

1.配置缓存​​​​​​​

services.AddOpenIdConnect(options =>
{
    options.ConfigurationManager = new ConfigurationManager<OpenIdConnectConfiguration>(
        "https://your-identity-provider.com/.well-known/openid-configuration",
        new OpenIdConnectConfigurationRetriever(),
        new HttpDocumentRetriever { RequireHttps = true }
    )
    {
        AutomaticRefreshInterval = TimeSpan.FromDays(1),
        RefreshInterval = TimeSpan.FromHours(12)
    };
});

 2.令牌缓存

services.AddDistributedMemoryCache(); // 或使用Redis等分布式缓存

services.AddOpenIdConnect(options =>
{
    options.BackchannelHttpHandler = new HttpClientHandler
    {
        ServerCertificateCustomValidationCallback = HttpClientHandler.DangerousAcceptAnyServerCertificateValidator
    };
    options.BackchannelTimeout = TimeSpan.FromSeconds(30);
});

3.优化令牌验证

services.AddSingleton<ISecurityTokenValidator, CustomTokenValidator>();

services.AddAuthentication()
    .AddJwtBearer(options =>
    {
        options.SecurityTokenValidators.Clear();
        options.SecurityTokenValidators.Add(services.BuildServiceProvider().GetService<ISecurityTokenValidator>());
    });