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; // 启用PKCEoptions.SaveTokens = true; // 保存令牌到Cookieoptions.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>());});