# CollectiveOAuth **Repository Path**: izory/CollectiveOAuth ## Basic Information - **Project Name**: CollectiveOAuth - **Description**: .Net平台(C#) 史上最全的整合第三方登录的开源库 => 环境支持 .NET Framework 4.5 ~ 4.6.2 和 .N。目前已包含Github、Gitee、钉钉、百度、支付宝、微信、企业微信、腾讯云开发者平台(Coding)、OSChina、微博、QQ、Google、Facebook、等第三方平台的授权登录 - **Primary Language**: C# - **License**: AGPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 23 - **Forks**: 319 - **Created**: 2022-06-21 - **Last Updated**: 2026-07-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

Login-OAuth2, so easy.

查看更多
------------------------------------------------------------------------------- ## 版本更新 - 2026-7-30 现支持 **.Net10.0** ## 特别感谢 **JustAuth**：这里特别感谢JustAuth开源项目作者提供架构思路 .Net平台下 **CollectiveOAuth**，它仅仅是一个 **第三方授权登录**的**工具类库**，它可以让我们脱离繁琐的第三方登录SDK，让登录变得**So easy!** - 项目开源地址：[Gitee(https://gitee.com/izory/CollectiveOAuth)](https://gitee.com/izory/CollectiveOAuth) ## 特点 废话不多说，就俩字： 1. **全**：已集成二十多家第三方平台（国内外常用的基本都已包含），仍然还在持续扩展中! 2. **简**：API就是奔着最简单去设计的（见后面`快速开始`），尽量让您用起来没有障碍感！ ## 快速开始 - 引入依赖 - 配置授权信息(默认配置在`appsettings.json`中, 可以改造存储数据库或者其它任意地方) ```C# "OAuthConfig": { "WECHAT_ENTERPRISE_SCAN": { "ClientId": "xxxxxxxxxxxxxxxxx", "AgentId": "xxxxxx", "ClientSecret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", "RedirectUri": "https://yours.domain.com/oauth2/callback?authSource=WECHAT_ENTERPRISE_SCAN" } } ``` - 调用api ```C# // 创建授权request var clientConfig = configuration.GetSection("OAuthConfig:GITEE").Get(); var state = AuthStateUtils.createState(); var authRequest = new GiteeAuthRequest(clientConfig); // 生成授权页面 var authorize = authRequest.authorize(state); //authRequest.login(authCallback); // 授权登录后会返回code（auth_code（仅限支付宝））、state，可以用AuthCallback类作为回调接口的参数 // 注：CollectiveOAuth默认保存state的时效为5分钟，5分钟内未使用则会自动清除过期的state ``` #### API列表 | :computer: 平台 | :coffee: API类 | :page_facing_up: SDK | |:------:|:-------:|:-------:| | | [GiteeAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/GiteeAuthRequest.cs) | 参考文档 | | | [GithubAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/GithubAuthRequest.cs) | 参考文档 | | | [WeiboAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/WeiboAuthRequest.cs) | 参考文档 | | | [DingTalkScanAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/DingTalkScanAuthRequest.cs) | 参考文档 | | | [BaiduAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/BaiduAuthRequest.cs) | 参考文档 | | | [CodingAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/CodingAuthRequest.cs) | 参考文档 | | | [OschinaAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/OschinaAuthRequest.cs) | 参考文档 | | | [AlipayMPAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/AlipayMpAuthRequest.cs) | 参考文档 | | | [QQAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/QQAuthRequest.cs) | 参考文档 | | | [WeChatOpenAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/WeChatOpenAuthRequest.cs) | 参考文档 | | | [WeChatMPAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/WeChatMpAuthRequest.cs) | 参考文档 | | | [WeChatEnterpriseAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/WeChatEnterpriseAuthRequest.cs) | 参考文档 | | | [WeChatEnterpriseScanAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/WeChatEnterpriseScanAuthRequest.cs) | 参考文档 | | | [TaobaoAuthRequest] | 参考文档 | | | [GoogleAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/GoogleAuthRequest.cs) | 参考文档 | | | [FacebookAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/FacebookAuthRequest.cs) | 参考文档 | | | [DouYinAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/DouYinAuthRequest.cs) | 参考文档 | | | [LinkedInAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/LinkedinAuthRequest.cs) | 参考文档 | | | [MicrosoftAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/MicrosoftAuthRequest.cs) | 参考文档 | | | [XiaoMiAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/XiaoMiAuthRequest.cs) | 参考文档 | | | [ToutiaoAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/ToutiaoAuthRequest.cs) | 参考文档 | | | [TeambitionAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/TeambitionAuthRequest.cs) | 参考文档 | | | [RenrenAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/RenrenAuthRequest.cs) | 参考文档 | | | [PinterestAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/PinterestAuthRequest.cs) | 参考文档 | | | [StackOverflowAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/StackOverflowAuthRequest.cs) | 参考文档 | | | [HuaweiAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/HuaweiAuthRequest.cs) | 参考文档 | | | [KujialeAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/KujialeAuthRequest.cs) | 参考文档 | | | [GitlabAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/GitlabAuthRequest.cs) | 参考文档 | | | [MeituanAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/MeituanAuthRequest.cs) | 参考文档 | | | [ElemeAuthRequest](https://gitee.com/rthinking/CollectiveOAuth/blob/master/Come.CollectiveOAuth/Request/AuthRequests/ElemeAuthRequest.cs) | 参考文档 | | | [TwitterAuthRequest] | 参考文档 | _请知悉：经咨询CSDN官方客服得知，CSDN的授权开放平台已经下线。如果以前申请过的应用，可以继续使用，但是不再支持申请新的应用。 ## 后续开发计划 正在筹备中 另外，期待有兴趣的你和我一起完善和优化这个项目！ ## 贡献代码 1. fork本项目到自己的repo 2. 把fork过去的项目也就是你仓库中的项目clone到你的本地 3. 修改代码 4. commit后push到自己的库 5. 发起PR（pull request） 请求，提交到`dev`分支 6. 等待作者合并 ------------------------------------------------------------------------------- ## 使用文档（详细） > 下列各章节与 `CollectiveOAuthCore/使用文档.md`（中文）、`CollectiveOAuthCore/使用文档.en.md`（英文）保持一致。 ### 一、支持的平台 通过 `DefaultAuthSourceEnum` 枚举区分，配置节点名即枚举名大写。已支持： | 枚举（authSource） | 平台 | 说明 | |---|---|---| | `GITHUB` | GitHub | 默认 scope `user:email` | | `GOOGLE` | Google | OIDC，token 端点 `oauth2.googleapis.com/token` | | `MICROSOFT` | Microsoft | `login.microsoftonline.com` / Graph | | `LINKEDIN` | LinkedIn | OpenID Connect（`openid profile email`） | | `FACEBOOK` | Facebook | 需申请敏感字段权限 | | `WEIBO` | 微博 | — | | `QQ` | QQ | 支持 `unionId`（需平台单独申请） | | `WECHAT_OPEN` | 微信开放平台 | 网站应用 | | `WECHAT_MP` | 微信公众平台 | 公众号 | | `WECHAT_ENTERPRISE` / `WECHAT_ENTERPRISE_SCAN` | 企业微信 | — | | `ALIPAY_MP` | 支付宝小程序 | 需 `alipayPublicKey` | | `GITEE` / `OSCHINA` / `CODING` / `GITLAB` | 代码托管平台 | — | | `BAIDU` / `XIAOMI` / `HUAWEI` / `KUJIALE` | 国内厂商 | — | | `DOUYIN` / `TOUTIAO` | 字节系 | — | | `MEITUAN` / `ELEME` | 美团 / 饿了么 | — | | `STACK_OVERFLOW` / `PINTEREST` / `RENREN` / `TEAMBITION` | 其他 | — | > 钉钉扫码（`DINGTALK_SCAN`）当前为未启用状态（相关实现被注释）。 ### 二、引入库 ```xml ``` ```csharp using Come.CollectiveOAuth.Config; using Come.CollectiveOAuth.Models; using Come.CollectiveOAuth.Request; using Come.CollectiveOAuth.Utils; using Come.CollectiveOAuth.Cache; ``` ### 三、快速上手 #### 1. 准备配置 ```csharp var config = new ClientConfig { clientId = "你的 ClientId / AppKey", clientSecret = "你的 ClientSecret / AppSecret", redirectUri = "https://your-domain.com/callback/github", scope = "user:email" }; ``` `ClientConfig` 字段： | 字段 | 类型 | 说明 | |---|---|---| | `clientId` | string | 平台分配的 AppKey / Client ID（必填） | | `clientSecret` | string | AppSecret（必填） | | `redirectUri` | string | 回调地址，须 `http(s)`（Facebook 必须 https，支付宝禁止 localhost），会做合法性校验（必填） | | `scope` | string | 授权范围，可不填（使用各平台默认） | | `alipayPublicKey` | string | 支付宝专用 | | `unionId` | bool | 仅 QQ，开启后在获取 openId 时同步请求 unionId（需平台单独权限） | | `stackOverflowKey` | string | Stack Overflow 专用 | | `agentId` | string | 企业微信专用 | #### 2. 生成授权地址并重定向 ```csharp var request = new GithubAuthRequest(config); string state = AuthStateUtils.createState(); string authorizeUrl = request.authorize(state); return Redirect(authorizeUrl); ``` #### 3. 处理回调 ```csharp public IActionResult Callback(AuthCallback callback) { var request = new GithubAuthRequest(config); // 与第 2 步用同一缓存实例 AuthResponse response = request.login(callback); if (response.ok()) // code == 2000 成功 { AuthUser user = (AuthUser)response.data; // user.uuid / user.nickname / user.avatar / user.email / user.source / user.token } } ``` > **要点**：`authorize` 与 `login` 必须使用**同一个 `IAuthStateCache` 实例**，否则回调 state 校验失败。默认 `DefaultAuthStateCache` 基于进程内 `IMemoryCache`，单实例可直接用；多实例部署请注入共享缓存。 ### 四、核心 API - 创建请求：`new GithubAuthRequest(config)` 或 `new GithubAuthRequest(config, authStateCache)` - 生成授权 URL：`request.authorize(state)` - 登录换用户信息：`request.login(callback)` / `await request.loginAsync(callback)` - `AuthResponse`：`code`（2000 成功）、`msg`、`data`（`AuthUser`）、`ok()` - `AuthUser`：`uuid` / `username` / `nickname` / `avatar` / `email` / `location` / `gender` / `source` / `token` / `originalUser` - 刷新 / 撤销：`request.refresh(token)` / `request.revoke(token)`（未实现返回 `NOT_IMPLEMENTED`，不抛异常） ### 五、State 防重放 `authorize(state)` 时 `getRealState` 把 state 写入 `IAuthStateCache`；回调时 `checkState` 校验存在后立即删除（一次性）。自定义缓存（如 Redis）实现 `IAuthStateCache` 接口：`cache(key, value)` / `containsKey(key)` / `remove(key)`。 ### 六、日志 ```csharp AuthLog.Writer = msg => _logger.LogDebug("[CollectiveOAuth] {Msg}", msg); // 默认 no-op ``` ### 七、异步与 HttpClient 注入 - 提供 `loginAsync` / `refreshAsync` / `revokeAsync`；默认以 `Task.Run` 包裹同步逻辑，可在子类覆写 `getAccessTokenAsync` / `getUserInfoAsync` 实现真正异步 IO。 - 注入统一 `HttpClient`：`HttpUtils.Client = httpClient;` ### 八、各平台注意事项 - **GitHub**：默认 `user:email`，私有邮箱可能为 null。 - **Google**：OIDC，userinfo 通过 `Authorization: Bearer` 获取；token 端点 `oauth2.googleapis.com/token`。 - **LinkedIn**：已切 OpenID Connect，scope 须 `openid profile email`，userinfo 取自 `https://api.linkedin.com/v2/userinfo`（旧 `r_liteprofile` / `emailAddress` 新应用已不可用）。 - **Microsoft**：端点仍有效；需 `offline_access` 才拿到 `refresh_token`。 - **Facebook**：`gender` / `birthday` 等敏感字段需 App Review。 - **QQ**：`unionId` 为 `bool`，仅平台已授权时生效。 - **微信系列**：端点与字段均现行有效。 - **微博**：回调需带 `code` 与 `state`。 ### 九、示例工程 `Come.AspNetCore.Sample` 提供 ASP.NET Core 完整示例：`AuthRequestFactory` 按 `authSource` 从 `appsettings.json` 的 `OAuthConfig:{SOURCE}` 读取 `ClientConfig` 并创建 `AuthRequest`；`OAuth2Controller` 含 `Authorization`（跳转）与 `Callback`（调用 `login`）。 `appsettings.json` 示例： ```json { "OAuthConfig": { "GITHUB": { "clientId": "xxxx", "clientSecret": "xxxx", "redirectUri": "https://localhost:5001/callback/github", "scope": "user:email" } } } ``` ### 十、常见问题 **Q：login 失败，msg 提示 state 非法？** A：授权与回调使用不同的 `IAuthStateCache` 实例，或 state 已被消费。确保共用同一缓存；多实例部署请用共享缓存（如 Redis）。 **Q：邮箱 / 性别等字段为空？** A：多数平台默认不返回敏感字段，需在 `scope` 显式申请并在平台后台完成权限申请（如 Facebook App Review、GitHub `user:email`）。 **Q：回调地址校验失败？** A：库会校验 `redirectUri`（须 http/https；Facebook 必须 https；支付宝禁止 localhost）。请确保与平台后台登记一致。 **Q：如何排查网络 / 接口错误？** A：异常已透明化，`response.msg` 含真实原因；也可通过 `AuthLog.Writer` 挂接日志查看详细过程。