ASP.NET Core 集成 Facebook OAuth2 登录Microsoft.AspNetCore.Authentication.Facebook 配置与源码解析【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore本文围绕 ASP.NET Core 开源仓库中Microsoft.AspNetCore.Authentication.Facebook中间件展开它是 ASP.NET Core 内置社交登录体系中对 Facebook OAuth2 认证协议的官方实现。读者读完本文后将掌握如何通过AddFacebook快速接入 Facebook 登录、理解AppId/AppSecret/Fields/Scope等关键配置项的默认值与作用、弄清appsecret_proof、PKCE、逗号分隔 Scope 等 Facebook 特有协议细节的实现原理并学会从源码构建与测试该项目。项目定位OAuth2 Facebook 认证的官方实现src/Security/Authentication/Facebook/目录下的项目实现了基于 OAuth2 的 Facebook 登录认证包名为Microsoft.AspNetCore.Authentication.Facebook。从项目文件Microsoft.AspNetCore.Authentication.Facebook.csproj的描述可见其定位ASP.NET Core middleware that enables an application to support Facebooks OAuth 2.0 authentication workflow使应用支持 Facebook OAuth 2.0 认证工作流的中间件。它并非从零实现 OAuth2而是建立在通用 OAuth 基础设施之上。扩展方法 FacebookExtensions.cs 中AddFacebook最终调用AddOAuthFacebookOptions, FacebookHandler(...)因此它天然复用Microsoft.AspNetCore.Authentication.OAuth的 Challenge、Token 交换、票据生成等通用流程仅针对 Facebook 的协议差异做定制。核心类型与默认端点整个组件由四个核心类型构成类型职责FacebookDefaults定义默认认证方案名、显示名与三个 Facebook 端点常量FacebookOptions继承自OAuthOptions封装 Facebook 特有的配置项FacebookHandler认证处理器负责发起登录、换取令牌、拉取用户信息FacebookExtensions提供AddFacebook系列 DI 扩展方法默认端点与方案名FacebookDefaults.cs 定义了组件默认值认证方案名AuthenticationScheme Facebook显示名DisplayName Facebook授权端点https://www.facebook.com/v22.0/dialog/oauth登录对话框令牌端点https://graph.facebook.com/v22.0/oauth/access_token换取访问令牌用户信息端点https://graph.facebook.com/v22.0/meGraph API 拉取用户资料。需要说明的是端点中带有明确的 Graph API 版本号v22.0这意味着该组件当前以 Facebook v22.0 API 为对齐目标若 Facebook 后续弃用该版本可通过自定义AuthorizationEndpoint、TokenEndpoint、UserInformationEndpoint指向新端点。FacebookOptions 的默认行为FacebookOptions.cs 的构造函数设置了大量默认值理解这些默认值对实际配置至关重要CallbackPath /signin-facebookFacebook 授权后回跳的本地回调路径SendAppSecretProof true默认向 Graph API 请求附加appsecret_proof参数UsePkce true默认启用 PKCERFC 7636 证明密钥交换默认Scope含email默认Fields含name、email、first_name、last_name内置一批ClaimActions映射将 Graph API 返回的 JSON 字段映射为ClaimTypes标准声明如id→NameIdentifier、email→Email、first_name→GivenName、last_name→Surname、birthday→DateOfBirthFacebook 特有字段则使用urn:facebook:*形式命名空间如urn:facebook:age_range_min、urn:facebook:location、urn:facebook:link、urn:facebook:timezone等。Validate()方法要求AppId与AppSecret均非空否则抛出ArgumentException。快速上手安装与配置安装包在应用项目中执行dotnet add package Microsoft.AspNetCore.Authentication.Facebook基础配置Program.cs参考仓库内 PACKAGE.md 的示例最简配置如下var builder WebApplication.CreateBuilder(args); builder.Services.AddAuthentication() .AddFacebook(options { options.AppId Configuration[Authentication:Facebook:AppId]; options.AppSecret Configuration[Authentication:Facebook:AppSecret]; });前置准备接入前需要完成两件事在 Facebook 开发者平台创建应用拿到 App ID 与 App Secret并把应用的合法回调地址登记为https://你的域名/signin-facebook与默认CallbackPath对应通过用户机密dotnet user-secrets、环境变量或配置提供程序安全存储 App ID 与 App Secret切忌硬编码进源码或提交到版本库。从源码结构看FacebookOptions中AppId/AppSecret只是ClientId/ClientSecret的别名属性见 FacebookOptions.cs源码注释明确指出Facebook uses a non-standard term for this fieldFacebook 对该字段使用非标准术语因此两者完全等价可按习惯任选其一。配置项详解AppId / AppSecretFacebook 分配给应用的 ID 与密钥。二者为必填项缺失时会在认证流程中抛出ArgumentNullException验证逻辑见 FacebookOptions.cs测试用例见 FacebookTests.cs 中的ThrowsIfAppIdMissing与ThrowsIfAppSecretMissing。Scope权限范围OAuth Scope 用于声明需要授权的数据权限默认已包含email。可用options.Scope.Add(...)追加权限。与标准 OAuth 规范RFC 6749 §3.3空格分隔不同Facebook 要求逗号分隔因此 FacebookHandler.cs 重写了FormatScopeprotected override string FormatScope(IEnumerablestring scopes) { // Facebook deviates from the OAuth spec here. // They require comma separated instead of space separated. return string.Join(,, scopes); }测试用例 ChallengeWillIncludeScopeAsConfigured 验证了重定向地址中包含scopefoo,bar的逗号分隔形式ChallengeWillIncludeScopeAsOverwritten 则验证可通过OAuthChallengeProperties.SetScope(baz, qux)在单次 Challenge 中覆盖 Scope。Fields用户信息字段Fields集合决定调用https://graph.facebook.com/v22.0/me时请求哪些用户字段默认包含name、email、first_name、last_name。在 FacebookHandler.CreateTicketAsync 中Fields会被拼接为逗号分隔的fields查询参数附加到用户信息端点。SendAppSecretProofFacebook 特有的安全机制为每次 Graph API 调用附加一个appsecret_proof参数其值为以 App Secret 为密钥对访问令牌计算出的 HMAC-SHA256 十六进制摘要。默认开启true。实现见 FacebookHandler.csprivate string GenerateAppSecretProof(string accessToken) { var key Encoding.ASCII.GetBytes(Options.AppSecret); var tokenBytes Encoding.ASCII.GetBytes(accessToken); var hash HMACSHA256.HashData(key, tokenBytes); return Convert.ToHexStringLower(hash); }测试 CustomUserInfoEndpointHasValidGraphQuery 断言了用户信息请求中确实携带appsecret_proof...参数。UsePkce 与 CallbackPathUsePkce true表示默认启用 PKCEChallenge 阶段会生成code_challenge与code_challenge_methodS256参数见测试 ChallengeWillTriggerRedirection 与 PkceSentToTokenEndpoint后者进一步验证令牌端点请求表单中携带非空的code_verifierCallbackPath /signin-facebook是授权码回跳地址若应用部署在子路径下重定向地址会自动拼接前缀测试 NestedMapWillNotAffectRedirect 验证了http://example.com/base/signin-facebook的场景。认证流程与底层原理结合 FacebookHandler.cs 与测试用例可还原完整登录时序发起 Challenge应用调用ChallengeAsync(Facebook)处理器将浏览器重定向到 Facebook 授权对话框地址含response_typecode、client_id、redirect_uri、scope、state以及 PKCE 的code_challenge与code_challenge_methodS256参见 ChallengeWillTriggerRedirection用户授权回跳Facebook 将用户重定向回redirect_uri默认/signin-facebook携带授权码code与state换取令牌处理器用授权码向令牌端点 POST 表单client_id、redirect_uri、client_secret、code、grant_typeauthorization_code、code_verifier见测试 PkceSentToTokenEndpoint拉取用户信息CreateTicketAsync构造用户信息端点查询——追加access_token若SendAppSecretProof为真则再追加appsecret_proof最后追加逗号拼接的fields见 FacebookHandler.cs构建票据解析 Graph API 返回的 JSON通过context.RunClaimActions()执行FacebookOptions中预置的声明映射触发Events.CreatingTicket事件最终生成AuthenticationTicket交由SignInScheme处理通常为 Cookie 认证。若用户信息端点请求失败处理器会抛出HttpRequestException提示检查认证信息是否正确以及对应 Facebook Graph API 是否已启用FacebookHandler.cs。另外值得注意的是FacebookHandler仅支持 Challenge 与回调处理不支持 SignIn/SignOut 语义——测试基类中SupportsSignIn、SupportsSignOut均为falseFacebookTests.cs实际登录状态由外部 Cookie 方案承担这也是社交登录的标准协作模式。从源码构建与测试关联文档Facebook 模块 README给出了本项目的构建与测试方式。构建构建整个仓库的某个子集可参考 构建文档其中的Building a subset of the code小节。最简做法是在src/Security父目录下执行 ./build.cmdLinux/macOS 环境对应使用build.sh仓库中 build.sh 与 build.cmd 并存。测试运行本项目相关测试同样参考 构建文档 中Running tests on command line小节或在src/Security目录下执行 ./build.cmd -t也可以进入项目src目录旁的test目录即src/Security/Authentication/test直接运行dotnet test该测试目录中的 FacebookTests.cs 覆盖了上文提到的默认值校验、Scope 格式、PKCE、appsecret_proof、回调重定向等关键行为可作为理解组件行为的可执行参考。补充说明该包标记为IsTrimmabletrue支持 AOT/裁剪场景见 csproj包还提供AddFacebook(string authenticationScheme, ...)、AddFacebook(string authenticationScheme, string displayName, ...)等多个重载FacebookExtensions.cs便于注册多个自定义方案或调整显示名更多安全认证体系概览可参考 Security 模块总 README仓库整体信息见 ASP.NET Core 根 README。【免费下载链接】aspnetcoreASP.NET Core is a cross-platform .NET framework for building modern cloud-based web applications on Windows, Mac, or Linux.项目地址: https://gitcode.com/GitHub_Trending/as/aspnetcore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
