🍻 文档

justauth · Sep 17, 2019 · fdc7821 · fdc7821
1 parent 5108765
commit fdc7821
Show file tree

Hide file tree

Showing 13 changed files with 298 additions and 41 deletions.
diff --git a/README.en-US.md b/README.en-US.md
@@ -170,6 +170,18 @@ authRequest.login(callback);
 
 I look forward to your joining us.
 
+
+## Contributors
+
+[contributors](https://docs.justauth.whnb.wang/#/contributors)
+
+## Recommend
+
+- `spring-boot-demo` In-depth study and actual combat of spring boot projects: [https://github.com/xkcoding/spring-boot-demo](https://github.com/xkcoding/spring-boot-demo)
+- `mica` Efficient Development of scaffolding by Spring Cloud: [https://github.com/lets-mica/mica](https://github.com/lets-mica/mica)
+- `pig` Cosmic strongest Micro Services Certified authorized scaffolding (essential for Architects): [https://gitee.com/log4j/pig](https://gitee.com/log4j/pig)
+- `SpringBlade` Complete online solution (necessary for enterprise development): https://gitee.com/smallc/SpringBlade
+
 ## References
 
 - [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)

diff --git a/README.md b/README.md
@@ -187,11 +187,17 @@ _请知悉：经咨询CSDN官方客服得知，CSDN的授权开放平台已经
 
 在项目立项初期，也对当前开源圈的一些相同类型的项目作过调研，同时本项目也参考过这些项目，再次感谢开源圈内的朋友。
 
-[YurunOAuthLogin](https://gitee.com/yurunsoft/YurunOAuthLogin): PHP 第三方登录授权 SDK
-
-[阿里妈妈MUX倾力打造的矢量图标库-iconfont](https://www.iconfont.cn/search/index): 本文档中的图标大部分取自该平台
-
-[mica](https://github.com/lets-mica/mica)：Spring Cloud 微服务开发核心包，支持 `web `和 `webflux`。注：JustAuth项目中的[UuidUtils](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/utils/UuidUtils.java)就是直接使用的mica提供的高性能的uuid创建工具类源码[StringUtil.java](https://github.com/lets-mica/mica/blob/master/mica-core/src/main/java/net/dreamlu/mica/core/utils/StringUtil.java#L335)
+- [YurunOAuthLogin](https://gitee.com/yurunsoft/YurunOAuthLogin): PHP 第三方登录授权 SDK
+- [阿里妈妈MUX倾力打造的矢量图标库-iconfont](https://www.iconfont.cn/search/index): 本文档中的图标大部分取自该平台
+- [mica](https://github.com/lets-mica/mica)：Spring Cloud 微服务开发核心包，支持 `web `和 `webflux`。注：JustAuth项目中的[UuidUtils](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/utils/UuidUtils.java)就是直接使用的mica提供的高性能的uuid创建工具类源码[StringUtil.java](https://github.com/lets-mica/mica/blob/master/mica-core/src/main/java/net/dreamlu/mica/core/utils/StringUtil.java#L335)
+- 感谢 JetBrains 提供的免费开源 License：
+<img src="https://github.com/lets-mica/mica/raw/c251e176b81518a6a570bf4eb21f525c4f582a81/docs/img/jetbrains.png" alt="图片引用自lets-mica" style="float:left;">
+
+## 开源推荐
+- `spring-boot-demo` 深度学习并实战 spring boot 的项目: [https://github.com/xkcoding/spring-boot-demo](https://github.com/xkcoding/spring-boot-demo)
+- `mica` SpringBoot 微服务高效开发工具集: [https://github.com/lets-mica/mica](https://github.com/lets-mica/mica)
+- `pig` 宇宙最强微服务认证授权脚手架(架构师必备): [https://gitee.com/log4j/pig](https://gitee.com/log4j/pig)
+- `SpringBlade` 完整的线上解决方案（企业开发必备）: https://gitee.com/smallc/SpringBlade
 
 ## 关于OAuth
 
@@ -210,7 +216,6 @@ _请知悉：经咨询CSDN官方客服得知，CSDN的授权开放平台已经
 
 - 开源总群 （190886500）：各个开源项目的都有，也有博客建设等方面的朋友。
 
-
 ## 请喝咖啡
 
 | 支付宝  | 微信  |

diff --git a/docs/README.md b/docs/README.md
@@ -155,6 +155,11 @@ JustAuth一共有两个主要分支：
 - 线上版分支（master）：稳定版，发布版就是这个分支的代码
 - 开发版分支（dev）：不保证稳定，新功能都会优先推送到该分支，对于想尝鲜的朋友，可以直接下载代码，然后源码编译dev分支
 
+## 开源推荐
+- `spring-boot-demo` 深度学习并实战 spring boot 的项目: [https://github.com/xkcoding/spring-boot-demo](https://github.com/xkcoding/spring-boot-demo)
+- `mica` SpringBoot 微服务高效开发工具集: [https://github.com/lets-mica/mica](https://github.com/lets-mica/mica)
+- `pig` 宇宙最强微服务认证授权脚手架(架构师必备): [https://gitee.com/log4j/pig](https://gitee.com/log4j/pig)
+- `SpringBlade` 完整的线上解决方案（企业开发必备）: https://gitee.com/smallc/SpringBlade
 
 ## 捐赠
 

diff --git a/docs/_sidebar.md b/docs/_sidebar.md
@@ -2,13 +2,13 @@
 - [贡献者名单](contributors.md)
 - 快速开始
   - [名词解释](explain.md)
+  - [OAuth流程](oauth.md)
   - [如何使用](how-to-use.md)
-  - [获取授权链接](authorize.md)
-  - [登录](login.md)
 - 其他特性
   - [使用State](using-state.md)
   - [自定义state缓存](customize-the-state-cache.md)
 - [配套项目](supporting.md)
 - [Q&A](Q&A.md)
 - [Who is using](users.md)
+- [致谢](thx.md)
 - [更新记录](update.md)
diff --git a/docs/authorize.md b/docs/authorize.md
diff --git a/docs/explain.md b/docs/explain.md
@@ -2,7 +2,7 @@
 
 ## 本文相关名词
 
-- `调用者` 指使用`JustAuth`的开发者
+- `开发者` 指使用`JustAuth`的开发者
 - `第三方` 指开发者对接的第三方网站，比如：QQ平台、微信平台、微博平台
 - `用户` 指最终服务的真实用户
 
@@ -12,9 +12,9 @@
 
 - `clientId` 客户端身份标识符（应用id），一般在申请完Oauth应用后，由**第三方平台颁发**，唯一
 - `clientSecret` 客户端密钥，一般在申请完Oauth应用后，由**第三方平台颁发**
-- `redirectUri` **调用者项目中的有效api地址**。用户在确认第三方平台授权（登录）后，第三方平台会重定向到该地址，并携带code等参数
-- `state` 用来保持授权会话流程完整性，防止CSRF攻击的安全的随机的参数，由**调用者生成**
-- `alipayPublicKey`  支付宝公钥。当选择支付宝登录时，必传该值，由**调用者生成**
+- `redirectUri` **开发者项目中的有效api地址**。用户在确认第三方平台授权（登录）后，第三方平台会重定向到该地址，并携带code等参数
+- `state` 用来保持授权会话流程完整性，防止CSRF攻击的安全的随机的参数，由**开发者生成**
+- `alipayPublicKey`  支付宝公钥。当选择支付宝登录时，必传该值，由**开发者生成**
 - `unionId`  是否需要申请unionid，目前只针对**qq登录**。注：qq授权登录时，获取unionid需要单独发送邮件申请权限。如果个人开发者账号中申请了该权限，可以将该值置为true，在获取openId时就会同步获取unionId。参考链接：[UnionID介绍](http://wiki.connect.qq.com/unionid%E4%BB%8B%E7%BB%8D)
 - `stackOverflowKey` Stack Overflow 登陆时需单独提供的key，由**第三方平台颁发**
 - `agentId`  企业微信登陆时需单独提供该值，由**第三方平台颁发**，为授权方的网页应用ID

diff --git a/docs/how-to-use.md b/docs/how-to-use.md
@@ -1,13 +1,18 @@
+# 如何使用
+
 在前面有介绍到，JustAuth的特点之一就是**简**，极简主义，不给使用者造成不必要的障碍。
 
 既然牛皮吹下了， 那么如何才能用JustAuth实现第三方登录呢？
 
+## 使用步骤
+
 使用JustAuth总共分三步（**这三步也适合于JustAuth支持的任何一个平台**）：
 
 1. 申请注册第三方平台的开发者账号
 2. 创建第三方平台的应用，获取配置信息(`accessKey`, `secretKey`, `redirectUri`)
 3. 使用该工具实现授权登陆
 
+## 使用方式
 
 - 引入依赖
 ```xml
@@ -30,4 +35,114 @@ authRequest.authorize("state");
 // 授权登录后会返回code（auth_code（仅限支付宝））、state，1.8.0版本后，可以用AuthCallback类作为回调接口的参数
 // 注：JustAuth默认保存state的时效为3分钟，3分钟内未使用则会自动清除过期的state
 authRequest.login(callback);
+```
+
+## API分解
+
+**JustAuth**的核心就是一个个的`request`，每个平台都对应一个具体的`request`类，所以在使用之前，需要就具体的授权平台创建响应的`request`
+
+```java
+// 创建授权request
+AuthRequest authRequest = new AuthGiteeRequest(AuthConfig.builder()
+        .clientId("clientId")
+        .clientSecret("clientSecret")
+        .redirectUri("redirectUri")
+        .build());
+```
+
+所有可用的`Request`列表请参考：[已集成的平台](https://docs.justauth.whnb.wang/#/README?id=已集成的平台)
+
+### 获取授权链接
+
+```java
+String authorizeUrl = authRequest.authorize("state");
+```
+获取到`authorizeUrl`后，可以手动实现redirect到`authorizeUrl`上
+
+**伪代码**
+
+```java
+/**
+ * 
+ * @param source 第三方授权平台，以本例为参考，该值为gitee（因为上面声明的AuthGiteeRequest）
+ */
+@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);
+}
+```
+
+注：`state`建议必传！`state`在`OAuth`的流程中的主要作用就是保证请求完整性，防止**CSRF**风险，此处传的`state`将在回调时传回
+
+### 登录(获取用户信息)
+
+```java
+AuthResponse response = authRequest.login(callback);
+```
+
+授权登录后会返回code（auth_code（仅限支付宝）、authorization_code（仅限华为））、state，1.8.0版本后，用`AuthCallback`类作为回调接口的入参
+
+**伪代码**
+
+```java
+/**
+ * 
+ * @param source 第三方授权平台，以本例为参考，该值为gitee（因为上面声明的AuthGiteeRequest）
+ */
+@RequestMapping("/callback/{source}")
+public Object login(@PathVariable("source") String source, AuthCallback callback) {
+    AuthRequest authRequest = getAuthRequest(source);
+    AuthResponse response = authRequest.login(callback);
+    return response;
+}
+```
+
+**注：第三方平台中配置的授权回调地址，以本文为例，在创建授权应用时的回调地址应为：`[host]/callback/gitee`**
+
+### 刷新token
+
+注：`refresh`功能，并不是每个平台都支持
+
+```java
+AuthResponse response = authRequest.refresh(AuthToken.builder().refreshToken(token).build());
+```
+
+**伪代码**
+
+```java
+/**
+ * 
+ * @param source 第三方授权平台，以本例为参考，该值为gitee（因为上面声明的AuthGiteeRequest）
+ * @param token  login成功后返回的refreshToken
+ */
+@RequestMapping("/refresh/{source}")
+public Object refreshAuth(@PathVariable("source") String source, String token){
+    AuthRequest authRequest = getAuthRequest(source);
+    return authRequest.refresh(AuthToken.builder().refreshToken(token).build());
+}
+```
+
+### 取消授权
+
+注：`revoke`功能，并不是每个平台都支持
+
+```java
+AuthResponse response = authRequest.revoke(AuthToken.builder().accessToken(token).build());
+```
+
+**伪代码**
+
+```java
+/**
+ * 
+ * @param source 第三方授权平台，以本例为参考，该值为gitee（因为上面声明的AuthGiteeRequest）
+ * @param token  login成功后返回的accessToken
+ */
+@RequestMapping("/revoke/{source}/{token}")
+public Object revokeAuth(@PathVariable("source") String source, @PathVariable("token") String token) throws IOException {
+    AuthRequest authRequest = getAuthRequest(source);
+    return authRequest.revoke(AuthToken.builder().accessToken(token).build());
+}
 ```
diff --git a/docs/login.md b/docs/login.md
diff --git a/docs/oauth.md b/docs/oauth.md
@@ -0,0 +1,61 @@
+# 关于OAuth
+
+请先查阅以下资料：
+
+- [The OAuth 2.0 Authorization Framework](https://tools.ietf.org/html/rfc6749)
+- [OAuth 2.0](https://oauth.net/2/)
+
+## OAuth 2的授权流程
+
+### 参与的角色
+
+- `Resource Owner` 资源所有者，即代表授权客户端访问本身资源信息的用户（User），也就是应用场景中的“**开发者A**”
+- `Resource Server` 资源服务器，托管受保护的**用户账号信息**，比如Github
+- `Authorization Server` 授权服务器，**验证用户身份**然后为客户端派发资源访问令牌，比如Github
+  - `Resource Server`和`Authorization Server` 可以是同一台服务器，也可以是不同的服务器，视具体的授权平台而有所差异
+- `Client` 客户端，即代表意图访问受限资源的**第三方应用**
+
+### 授权流程
+```html
+     +--------+                               +---------------+
+     |        |--(A)- Authorization Request ->|   Resource    |
+     |        |                               |     Owner     |
+     |        |<-(B)-- Authorization Grant ---|               |
+     |        |                               +---------------+
+     |        |
+     |        |                               +---------------+
+     |        |--(C)-- Authorization Grant -->| Authorization |
+     | Client |                               |     Server    |
+     |        |<-(D)----- Access Token -------|               |
+     |        |                               +---------------+
+     |        |
+     |        |                               +---------------+
+     |        |--(E)----- Access Token ------>|    Resource   |
+     |        |                               |     Server    |
+     |        |<-(F)--- Protected Resource ---|               |
+     +--------+                               +---------------+
+```
+
+上面的流程图取自[The OAuth 2.0 Authorization Framework#1.2](https://tools.ietf.org/html/rfc6749#section-1.2)
+
+- (A)  用户打开**客户端**以后，**客户端**要求**用户**给予授权。
+- (B)  **用户**同意给予**客户端**授权。
+- (C)  **客户端**使用上一步获得的授权，向**认证服务器**申请令牌。
+- (D)  **认证服务器**对**客户端**进行认证以后，确认无误，同意发放令牌
+- (E)  **客户端**使用令牌，向**资源服务器**申请获取资源。
+- (F)  **资源服务器**确认令牌无误，同意向**客户端**开放资源。
+
+### 授权许可 `Authorization Grant`
+
+- Authorization Code
+  - 结合普通服务器端应用使用(**web**端常用的授权方式)
+- Implicit
+  - 结合移动应用或 Web App 使用
+- Resource Owner Password Credentials
+  - 适用于受信任客户端应用，例如同个组织的内部或外部应用
+- Client Credentials
+  - 适用于客户端调用主服务API型应用（比如百度API Store）
+
+在`JustAuth`中是使用的`Authorization Code`授权方式，下面将主要讲解`Authorization Code`的授权流程
+
+（未完待续）
diff --git a/docs/thx.md b/docs/thx.md
@@ -0,0 +1,15 @@
+# 致谢
+
+在项目立项初期，也对当前开源圈的一些相同类型的项目作过调研，同时本项目也参考过这些项目，再次感谢开源圈内的朋友。
+
+- [YurunOAuthLogin](https://gitee.com/yurunsoft/YurunOAuthLogin): PHP 第三方登录授权 SDK
+- [阿里妈妈MUX倾力打造的矢量图标库-iconfont](https://www.iconfont.cn/search/index): 本文档中的图标大部分取自该平台
+- [mica](https://github.com/lets-mica/mica)：Spring Cloud 微服务开发核心包，支持 `web `和 `webflux`。注：JustAuth项目中的[UuidUtils](https://gitee.com/yadong.zhang/JustAuth/blob/master/src/main/java/me/zhyd/oauth/utils/UuidUtils.java)就是直接使用的mica提供的高性能的uuid创建工具类源码[StringUtil.java](https://github.com/lets-mica/mica/blob/master/mica-core/src/main/java/net/dreamlu/mica/core/utils/StringUtil.java#L335)
+
+
+**感谢 JetBrains 提供的免费开源 License**
+
+<img src="https://github.com/lets-mica/mica/raw/c251e176b81518a6a570bf4eb21f525c4f582a81/docs/img/jetbrains.png" alt="图片引用自lets-mica" style="float:left;">
+
+<div style="clear: both;"></div>
+
diff --git a/docs/using-state.md b/docs/using-state.md
@@ -1,3 +1,53 @@
 # 使用State
 
-待补充
+## state使用的流程
+
+在JustAuth中`state`参数的使用流程如下：
+
+1. 获取`authorizeUrl`时创建`state`(开发者创建，如果不创建则系统默认生成)
+2. 缓存`state`（JustAuth执行）
+3. 内置的缓存调度器自动清除已过期的`state`（JustAuth执行）
+
+## 创建state（开发者）
+`state`在OAuth授权流程中是一个**非必要但很重要**的参数，就如[名词解释](https://docs.justauth.whnb.wang/#/explain?id=justauth中的关键词)中描述的：`state`是用来保持授权会话流程完整性，防止CSRF攻击的安全的随机的参数，**由开发者生成**。
+
+在JustAuth中提供了一个默认的创建state的方法，使用方式：
+
+```java
+String state = AuthStateUtils.createState()
+```
+
+`createState`的内部实现其实就是生成了一个UUID（采用 jdk 9 的形式，优化性能），该工具是直接copy自[mica](https://github.com/lets-mica/mica/blob/master/mica-core/src/main/java/net/dreamlu/mica/core/utils/StringUtil.java)（`mica`是一个SpringBoot微服务高效开发工具集，开源地址：[https://github.com/lets-mica/mica](https://github.com/lets-mica/mica)），关于mica uuid生成方式的压测结果，可以参考：https://github.com/lets-mica/mica-jmh/wiki/uuid。
+
+除此之外，开发者还可以自己生成特定的`state`参数。
+
+## 缓存state（JustAuth）
+
+在JustAuth中，内置了一个基于map的state缓存器，默认缓存有效期为3分钟（缓存配置见`AuthCacheConfig.java`）。`AuthCacheConfig`中包含两个配置参数：
+
+- `timeout` 缓存过期时间，默认3分钟
+- `schedulePrune` 是否开启定时清理过期state的任务，默认开启。如果不开启，则需要开发者自己对state做处理，防止map存入过多内容
+
+缓存state的操作是在`getRealState`中触发的，不需要开发者自己处理
+```java
+/**
+ * 获取state，如果为空， 则默认取当前日期的时间戳
+ *
+ * @param state 原始的state
+ * @return 返回不为null的state
+ */
+protected String getRealState(String state) {
+    if (StringUtils.isEmpty(state)) {
+        state = UuidUtils.getUUID();
+    }
+    // 缓存state
+    authStateCache.cache(state, state);
+    return state;
+}
+```
+
+注：关于自定义缓存，请参考下节内容。
+
+## 清理state（JustAuth）
+
+JustAuth内置了一个缓存调度器，默认3分钟清理一次过期的`state`，缓存清理时间可以通过`AuthCacheConfig.timeout`进行修改，不建议修改太大。
diff --git a/src/main/java/me/zhyd/oauth/request/AuthQqRequest.java b/src/main/java/me/zhyd/oauth/request/AuthQqRequest.java
@@ -76,7 +76,7 @@ protected AuthUser getUserInfo(AuthToken authToken) {
 
     /**
      * 获取QQ用户的OpenId，支持自定义是否启用查询unionid的功能，如果启用查询unionid的功能，
-     * 那就需要调用者先通过邮件申请unionid功能，参考链接 {@see http://wiki.connect.qq.com/unionid%E4%BB%8B%E7%BB%8D}
+     * 那就需要开发者先通过邮件申请unionid功能，参考链接 {@see http://wiki.connect.qq.com/unionid%E4%BB%8B%E7%BB%8D}
      *
      * @param authToken 通过{@link AuthQqRequest#getAccessToken(AuthCallback)}获取到的{@code authToken}
      * @return openId