From 7a40159d15c547f90e1d25fde58e970a6ac74195 Mon Sep 17 00:00:00 2001 From: "yadong.zhang" Date: Sat, 3 Aug 2019 14:28:31 +0800 Subject: [PATCH] =?UTF-8?q?:memo:=20=E5=B8=AE=E5=8A=A9=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/Q&A.md | 77 +++++++++++++++++++ docs/_coverpage.md | 16 ++++ docs/_sidebar.md | 12 +++ docs/supporting.md | 8 ++ docs/update.md | 183 +++++++++++++++++++++++++++++++++++++++++++++ docs/users.md | 11 +++ 6 files changed, 307 insertions(+) create mode 100644 docs/Q&A.md create mode 100644 docs/_coverpage.md create mode 100644 docs/_sidebar.md create mode 100644 docs/supporting.md create mode 100644 docs/update.md create mode 100644 docs/users.md diff --git a/docs/Q&A.md b/docs/Q&A.md new file mode 100644 index 0000000..4c5c428 --- /dev/null +++ b/docs/Q&A.md @@ -0,0 +1,77 @@ +## ~~升级到1.8.0后如何启用state？~~ + +~~在原api使用方法的基础上，为config追加一个state即可。~~ +``` +AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder() + .clientId("clientId") + .clientSecret("clientSecret") + .redirectUri("redirectUri") + .state("state") // 就是这儿 + .build()); +``` + +## ~~升级到1.8.0后login方法报错？~~ + +~~这是因为1.8.0版本中新增了[AuthCallback](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/model/AuthCallback.java)类，这个类封装了所有可能的回调参数。目前包含以下三个参数：~~ +- ~~`code`: 访问AuthorizeUrl后回调时带的参数code，用来换取token~~ +- ~~`auth_code`: 支付宝授权登陆时不会返回code而是返回`auth_code`参数~~ +- ~~`state`: 访问AuthorizeUrl后回调时带的参数state，用于和请求AuthorizeUrl前的state比较，防止CSRF攻击~~ + +~~1.8.0版本之后的api，可以直接用AuthCallback类作为回调方法的入参，比如：~~ +``` +@RequestMapping("/callback/{source}") +public Object login(@PathVariable("source") String source, AuthCallback callback) { + System.out.println("进入callback：" + source + " callback params：" + JSONObject.toJSONString(callback)); + AuthRequest authRequest = getAuthRequest(source); + AuthResponse response = authRequest.login(callback); + System.out.println(JSONObject.toJSONString(response)); + return response; +} +``` + ~~_代码截取自_ ：https://gitee.com/yadong.zhang/JustAuth-demo~~ + +## ~~升级到1.8.0后对于state参数有什么特殊要求吗？~~ + +~~理论上没有，stata只是用来保持会话状态，因为http协议的无状态性，从授权到回调，无法感知具体是哪个用户触发的。所以可以使用state作为校验。注：state参数每次完整的授权链中只可用一次！（也是为了防止不必要的危险）~~ + +~~作者建议state命名格式如下：~~ +- ~~授权登录：`{source}_{ip}_{random}`~~ +- ~~账号绑定：`{source}_{userId}_{ip}_{random}`~~ + +~~其中`source`表示授权平台，可以直接去JustAuth中的source，`ip`为当前用户的ip（部分情况可能不适用），`random`为随机字符串，`userId`为当前登录用户的id。~~ + +~~注：`authorize`和`login`（不是指回调传回的`state`，而是声明`request`时传入的`state`）中传的`state`务必保证一致~~ + +## 升级到1.9.3+版本后编译失败 + +主要明显的就是`IpUtils.getIp`和request的`.state`报错。 + +这是因为从`v1.9.3`版本开始，对项目进行了一些优化，具体优化内容参考：[v1.9.3](https://gitee.com/yadong.zhang/JustAuth/releases/v1.9.3)和[v1.9.4](https://gitee.com/yadong.zhang/JustAuth/releases/v1.9.4)。 + +新版本的使用方式，参考[JustAuth-demo](https://gitee.com/yadong.zhang/JustAuth-demo/blob/master/src/main/java/me/zhyd/justauth/RestAuthController.java) +``` +@RequestMapping("/render/{source}") +public void renderAuth(@PathVariable("source") String source, HttpServletResponse response) throws IOException { + AuthRequest authRequest = getAuthRequest(source); + String authorizeUrl = authRequest.authorize(AuthStateUtils.createState()); + response.sendRedirect(authorizeUrl); +} +@RequestMapping("/callback/{source}") +public Object login(@PathVariable("source") String source, AuthCallback callback) { + AuthRequest authRequest = getAuthRequest(source); + AuthResponse response = authRequest.login(callback); + return response; +} +``` + +## 升级到最新版本后为什么支付宝登录不能用了？ + +在升级到新版后，使用支付宝登录会提示`ClassNotFoundExcption`异常，这是因为从`1.9.4`版本开始，JustAuth将不在强依赖`alipay-sdk-java`，如果你需要用到Alipay的授权登陆，那么你还需要添加以下依赖： + +``` + + com.alipay.sdk + alipay-sdk-java + 3.7.4.ALL + +``` diff --git a/docs/_coverpage.md b/docs/_coverpage.md new file mode 100644 index 0000000..693b73e --- /dev/null +++ b/docs/_coverpage.md @@ -0,0 +1,16 @@ + +![](_media/logo.png) +# JustAuth 1.9.6 + +史上最全的整合第三方登录的开源库 + +Login, so easy + +

已集成国内外十多家平台

+

极简的API设计

+ + +[Gitee](https://gitee.com/yadong.zhang/JustAuth) +[Github](https://github.com/zhangyd-c/JustAuth) +[Get Started](#简介) + diff --git a/docs/_sidebar.md b/docs/_sidebar.md new file mode 100644 index 0000000..85e99c6 --- /dev/null +++ b/docs/_sidebar.md @@ -0,0 +1,12 @@ +- [入门](README.md) +- [更新记录](update.md) +- 引导 + - [如何使用JustAuth集成一个平台](deploy.md) + - [获取授权链接](authorize.md) + - [登录](login.md) +- 其他特性 + - [使用State](useing-state.md) + - [自定义state缓存](custom-state-cache.md) +- [配套项目](supporting.md) +- [Q&A](Q&A.md) +- [Who is using](users.md) diff --git a/docs/supporting.md b/docs/supporting.md new file mode 100644 index 0000000..300a37b --- /dev/null +++ b/docs/supporting.md @@ -0,0 +1,8 @@ +## 配套demo +- [Springboot版](https://gitee.com/yadong.zhang/JustAuth-demo) ：JustAuth项目的demo（springboot项目） +- [jFinal版](https://github.com/xkcoding/jfinal-justauth-demo) ：Jfinal集成JustAuth的demo +- [ActFramework版](https://github.com/xkcoding/act-justauth-demo) ：ActFramework 集成 JustAuth 的 demo + +## 插件 +- [justauth-spring-boot-starter](https://github.com/xkcoding/justauth-spring-boot-starter) ：Spring Boot 集成 JustAuth 的最佳实践 + diff --git a/docs/update.md b/docs/update.md new file mode 100644 index 0000000..a274480 --- /dev/null +++ b/docs/update.md @@ -0,0 +1,183 @@ +## v1.9.6 +### 2019/08/03 + +- 增加`AuthCache`配置类`AuthCacheConfig.java`，可以自定义缓存有效期以及是否开启定时任务 +- 去掉`slf4j`依赖，封装`Log.java`工具类 +- 规范测试类 + +### 2019/08/02 + +- 增加`AuthCache`配置类`AuthCacheConfig.java`，可以自定义缓存有效期以及是否开启定时任务 +- 去掉`slf4j`依赖，封装`Log.java`工具类 +- 规范测试类 + +## v1.9.5 +### 2019/07/31 + +`v1.9.4`版本发布失败，请升级到`1.9.5`版本！ + +由此给您带来的不便，敬请谅解！ + +## v1.9.4 +### 2019/07/30 + +1. 升级`hutool-http`版本到`v4.6.1` +2. 去除`AuthCallback`中增加的默认的校验state的方法，挪到`AuthDefaultRequest`中做统一处理 +3. `alipay-sdk-java`依赖改为`provided`，如果需要使用支付宝登录，需要使用方手动引入相关依赖，具体操作方式，见项目WIKI； +4. 规范注释 + +## v1.9.3 +### 2019/07/30 + +1. 规范注释 +2. 增加State缓存，`AuthCallback`中增加默认的校验state的方法 +3. 增加默认的state生成方法，参考`AuthStateUtils.java`和`UuidUtils.java` +4. 升级`hutool-http`版本到`v4.6.0` +5. 修复其他一些问题 + +### 2019/07/27 + +1. `IpUtils.getIp`改名为`IpUtils.getLocalIp` +2. 规范注释 + +### 2019/07/25 + +1. `AuthConfig`类中去掉state参数 +2. 删除`AuthState`类 +3. 增加`authorize(String)`方法，并且使用`@Deprecated`标记`authorize()`方法 + +## v1.9.2 +### 2019/07/22 +1. 合并github上[xkcoding](https://github.com/xkcoding) 的[pr#26](https://github.com/zhangyd-c/JustAuth/pull/26)，AuthConfig类添加lombok注解，方便 [justauth-spring-boot-starter](https://github.com/xkcoding/justauth-spring-boot-starter) 直接使用 + +## v1.9.1 +### 2019/07/22 +1. 增加`stackoverflow`参数校验 +2. 解决`Pinterest`获取用户失败的问题 +3. 添加注释 + +## v1.9.0 +### 2019/07/19 + +1. 合并github上[@dyc12ii](https://github.com/dyc12ii) 的[pr#25](https://github.com/zhangyd-c/JustAuth/pull/25)，升级fastjson版本至1.2.58,避免安全漏洞 +2. `AuthUserGender`枚举类挪到`enums`包下 +3. 删除`AuthBaiduErrorCode`和`AuthDingTalkErrorCode`枚举类 +4. 优化百度授权流程，增加refresh token的方法 +5. 优化`AuthConfig`、`AuthResponse`类，去掉不必要的lombonk注解，减少编译后的代码量 +6. 使用lombok注解优化枚举类 +7. `AuthQqRequest`增加refresh方法 +8. 修复google登录无法获取用户信息的问题 +9. 优化代码 + +### 2019/07/18 + +1. 合并github上[@pengisgood](https://github.com/pengisgood) 的[pr#19](https://github.com/zhangyd-c/JustAuth/pull/19)，集成人人 +2. 合并github上[@pengisgood](https://github.com/pengisgood) 的[pr#20](https://github.com/zhangyd-c/JustAuth/pull/20)，集成Pinterest +3. 合并github上[@pengisgood](https://github.com/pengisgood) 的[pr#21](https://github.com/zhangyd-c/JustAuth/pull/21)，集成StackOverflow +4. 合并github上[@xkcoding](https://github.com/xkcoding) 的[pr#23](https://github.com/zhangyd-c/JustAuth/pull/23)，重构代码、新增编辑器规范，规范PR代码风格 + +### 2019/07/17 +1. 优化代码 +2. 集成Teambition登录 + +### 2019/07/16 +1. 重构UrlBuilder类 +2. 将CSDN相关的类置为`Deprecated`，后续可能会删除，也可能一直保留。毕竟CSDN的openAPI已经不对外开放了。 +3. `BaseAuthRequest` 改名为 `AuthDefaultRequest` +4. `ResponseStatus` 改名为 `AuthResponseStatus` 并且移动到 `me.zhyd.oauth.model` +5. 合并github上[@xkcoding](https://github.com/xkcoding) 的[pr#18](https://github.com/zhangyd-c/JustAuth/pull/18)，修复小米回调错误问题 同时 支持微信获取unionId + +## v1.8.1 +### 2019/07/15 +1. 新增 `AuthState` 类，内置默认的state生成规则和校验规则 + +### 2019/07/12 +1. 合并[Braavos96](https://github.com/Braavos96)提交的[PR#16](https://github.com/zhangyd-c/JustAuth/pull/16) + +## v1.8.0 +### 2019/06/28 +1. 修复百度登录获取不到token失效时间的问题 +2. 增加state参数校验，预防CSRF。**强烈建议启用state**！ + +### 2019/06/27 +1. 修复百度登录获取不到token失效时间的问题 +2. 增加state参数校验，预防CSRF。**强烈建议启用state**！ +3. 修改login方法的参数为AuthCallback，封装回调返回的参数 +4. 支持state参数 +5. 增加code和state参数校验 + +由于state安全问题，1.8.0以前的版本都有隐藏的CSRF漏洞问题，所以强烈建议正在使用JustAuth的朋友升级到1.8.0版本！ + +## v1.7.1 +### 2019/06/25 +qq授权登录时，需要获取`openId`作为`uuid`，在`1.6.1-beta`和`1.7.0`版本中，引入了`unionId`这一属性。获取`unionid`需要单独向qq团队**发送邮件**申请权限，鉴于这一申请权限的步骤比较麻烦（需要填写的内容比较多），所以在`AuthConfig`中增加了一个`unionId`属性，当为**true**时才会获取unionid，当为false时只获取openId。如果你需要该功能， 则在自行申请了相关权限后，将该属性置为true即可。关于unionId的参考链接：[UnionID介绍](http://wiki.connect.qq.com/unionid%E4%BB%8B%E7%BB%8D) + +## v1.7.0 +### 2019/06/19 +1. 合并[xkcoding](https://github.com/xkcoding)提交的[PR](https://github.com/zhangyd-c/JustAuth/pull/14)，重构了部分代码，jar包由原来的`130+kb`优化到现在的`110+kb` +2. 合并[skqing](https://gitee.com/skqing)提交的[PR](https://gitee.com/yadong.zhang/JustAuth/pulls/3)， 解决抖音登录失败问题 + +## v1.6.1-beta +### 2019/06/18 +1. 解决Issue [#IY2HW](https://gitee.com/yadong.zhang/JustAuth/issues/IY2HW) +2. 解决Issue [#IY2OH](https://gitee.com/yadong.zhang/JustAuth/issues/IY2OH) +3. 解决Issue [#IY2FV](https://gitee.com/yadong.zhang/JustAuth/issues/IY2FV) +4. 修复部分注释、拼写错误 +5. 解决Issue [#IY1QR](https://gitee.com/yadong.zhang/JustAuth/issues/IY1QR) 增加对Config属性的校验功能，主要校验redirect uri的合法性 +6. 合并[skqing](https://gitee.com/skqing)提交的[PR](https://gitee.com/yadong.zhang/JustAuth/pulls/2)，解决一些BUG + +## v1.6.0-beta +### 2019/06/06 +1. 增加今日头条的授权登陆 +2. 发布1.6.0-beta版本，今日头条开发者暂时不能认证， 所以无法做测试，等测试通过后，正式发布release版本 + +## v1.5.0 +### 2019/05/28 +1. 增加小米账号和微软的授权登陆 +2. 发布1.5.0版本 + +## v1.4.0 +### 2019/05/26 +1. 增加抖音和Linkedin的授权登陆 +2. 修改部分图片命名 +3. 优化部分代码 +4. 修复`AuthSource`中腾讯云开发平台的拼写错误：`TENCEN_CLOUD`->`TENCENT_CLOUD` +5. 修复支付宝登陆时用户名为空的问题 + +## v1.3.3 +### 2019/05/24 +1. 修复一些问题 +2. 升级api，在AuthUser中增加`uuid`属性，可以通过`uuid` + `source`唯一确定一个用户，此举解决了用户身份归属的问题。 +3. 发布1.3.3版本的jar包到公开仓库（1.3.2忘记发布了，( ╯□╰ )） +4. 重要：经咨询官方客服得知，CSDN的授权开放平台已经下线，如果以前申请过的应用，可以继续使用，但是不再支持申请新的应用。so, 本项目中的CSDN登录只能针对少部分用户使用了 + +## v1.3.1 +### 2019/05/23 +1. 修复QQ登录的问题 +2. 发布1.3.1版本的jar包到公开仓库 + +## v1.3.0 +### 2019/05/21 +1. 新增google授权登录 +2. 新增facebook授权登录 +3. 发布1.3.0版本的jar包到公开仓库 + +## v1.1.0 +### 2019/05/18 +1. 发布1.1.0版本的jar包到公开仓库（支持qq和微信登录） +2. 支持淘宝登录 +3. 修改`AuthUser.java`类中的`accessToken`属性，由原本的~~accessToken (String)~~改为`token (AuthToken)` +4. 修复一些bug +5. 发布1.2.0版本的jar包到公开仓库（支持淘宝登录） + +### 2019/05/17 +1. 增加qq和微信的授权登录 +2. 修改getAccessToken方法的返回值 + +## v1.0.1 +### 2019/03/27 +集成 支付宝授权登录 + +## v1.0.0 +### 2019/03/25 +史上最全的整合第三方登录的工具,目前已支持Github、Gitee、微博、钉钉和百度、Coding、腾讯云开发者平台和OSChina登录。 Login, so easy! diff --git a/docs/users.md b/docs/users.md new file mode 100644 index 0000000..7d08dc1 --- /dev/null +++ b/docs/users.md @@ -0,0 +1,11 @@ +# Who is using? + +- [spring-boot-demo](https://github.com/xkcoding/spring-boot-demo): spring boot demo 是一个用来学习 spring boot 的项目，总共包含 55 个集成demo，已经完成 46 个。（注：[spring-boot-demo-social](https://github.com/xkcoding/spring-boot-demo/tree/master/spring-boot-demo-social)模块中集成了JustAuth）注：该作者是JustAuth的开发者之一，负责开发QQ登录、微信登录、小米登录、微软登录、谷歌登录。 +- [Guns](https://gitee.com/stylefeng/guns): Guns基于Spring Boot2，致力于做更简洁的后台管理系统。（注：Guns企业版中使用到了JustAuth实现第三方OAuth登录） + +- [Shiro-Action](https://github.com/zhaojun1998/Shiro-Action): 基于 Shiro 的权限管理系统，支持 restful url 授权 +- [project-template](https://github.com/HobbyBear/project-template): 作为前后端分离项目的后端模板整个项目基于springboot2.1.3，集jsr303框架做参数校验，spring security 做权限管理，并实现限制同一账号登陆会话数量功能，spring mail 发送邮件，justAuth做的第三方登陆， spring session做session共享，orm框架采用jpa,集成七牛云实现图片上传，redis实现分布式锁 +- [mica](https://github.com/lets-mica/mica/tree/master/mica-social)：mica是Spring Cloud 微服务开发核心包。采用源码形式（保留了作者名）另加改了一些代码。 +... + +我在这儿等你 >>> :alien: -- GitLab