大树快速开发平台 - 中文文档

Appearance

Oauth2 模块使用说明 ​

1. 什么是Oauth 2.0 ​

什么是Oauth 2.0？
大神阮一峰的一篇文章介绍的比较详细，点此查看：《理解OAuth 2.0》

2. 服务端 ​

服务端

本框架作为 Oauth2 的服务器，给其他业务系统做统一认证服务。

使用说明：

  1. 开启Oauth2服务
  2. 注册应用
  3. 客户端集成

- 2.1 开启Oauth2服务 ​

  • 在配置文件 application.yml 中，自定义配置，代码如下：
yaml
com.kg:
  #oauth2配置
  oauth2:
    #服务端，是否启动(true/false)
    server.enable: true

通过com.kg.oauth2.server.enable配置，是否开启Oauth2统一认证服务。
开启后，相关代码启用，即可对外提供标准的Oauth 2.0服务了。

- 2.2 注册应用 ​

  • 第三方应用，想要使用本系统的Oauth2服务，还需要在本系统内注册应用。
    在 管理后台 - 系统配置 - 应用商店 中，可以对Oauth2的客户端应用进行管理。
    如下图所示：

应用商店

  • 点击新增按钮，可以注册一个新的第三方应用，如下图所示：

应用商店-新增

说明：

  • 回调地址：认证成功后，带着一次性Code回调该地址，是第三方应用的地址
  • 应用ID和应用Secret配置后，交付给第三方应用（客户端）集成开发时使用
  • 其他参数，参考标准的Oauth2协议规范

- 2.3 客户端集成 ​

  • 第三方应用自行集成。

  • 如果第三方应用，也是使用本框架，作为客户端
    集成操作详见下文: 3. 客户端

3. 客户端（第三方应用） ​

客户端

本框架作为 Oauth2 的客户端，集成他方的统一认证，登录本系统。

使用说明：

  1. 配置Oauth2 客户端信息
  2. 给登录页加Oauth2 登录链接

- 3.1 配置Oauth2 客户端信息 ​

  • 在配置文件 application.yml 中，自定义配置，代码如下：
yaml
com.kg:
  #oauth2配置
  oauth2:
    #客户端信息配置（作为Oauth2的客户端，集成第三方Oauth2统一认证登录时使用）
    client:
      clientId: dev
      clientSecret: dev
      #回调地址
      redirectUri: http://xxxxxx/oauth2/client/login/code
      #第三方Oauth2服务端地址
      oauthServerUri: http://yyyyyy/
      #回调登录错误时，跳转前端错误页
      errorRouter: http://zzzzzz/#/oauth2/error
      #回调登录成功时，跳转前端成功页（处理本系统登录逻辑）
      successRouter: http://zzzzzz/#/oauth2/success
      #回调登录成功，但首次登录时，跳转到绑定用户界面
      userBindRouter: http://zzzzzz/#/oauth2/bind

配置说明

  1. clientId 和 clientSecret 是第三方Oauth 2.0服务端提供的（需要在服务端注册应用）
  2. redirectUri： 是回调地址，服务端认证通过后，会带着一次性code回调该地址
    其中 xxxxxx 是本地后端接口的项目地址（域名/IP+端口+上下文）
    而 /oauth2/client/login/code 是本项目的固定api地址（代码在：Oauth2ClientController.java）
  3. oauthServerUri： 是 Oauth 2.0 服务端的项目地址（域名/IP+端口+上下文）
  4. errorRouter： 是回调本地登录，发生错误时的错误提示页
    其中 zzzzzz 时本地前端项目地址（域名/IP+端口）
  5. successRouter： 是回调本地登录成功后，处理前端登录逻辑的页面，处理成功后跳转后台首页
  6. userBindRouter： 认证登录成功后，若是首次进入本应用，需要绑定本应用的用户，跳转该页面进行绑定
  • Oauth2ClientController.java 的代码路径：

- 3.2 给登录页加Oauth2 登录链接 ​

  • 登录页面代码，所在路径：
    web-vue2/src/views/login/index.vue

集成第三方Oauth2服务端登录

链接说明

  1. http://yyyyyy/oauth/authorize 是 Oauth 2.0 服务端的项目地址（域名/IP+端口+上下文）
    其中 yyyyyy 和上面配置中 oauthServerUri 保持一致
  2. response_type=code 固定参数（授权码模式）
  3. client_id=xxx 应用ID
  4. redirect_uri=xxxxxx 回调地址（建议encodeURI编码），必须和 redirectUri 配置保持一致
  5. state=zzzzzz 服务端认证成功后，会在回调时带着state参数原样返回

- 3.3 客户端登录操作过程如下 ​

  1. 服务器端未登录状态，用户跳转到登录页，如下图：

客户端登录流程

  1. 登录成功后，跳转到中间页，如下图：

客户端登录成功

  1. 若登录过程出现错误，跳转到错误提示页，如下图：

客户端登录错误

  1. 若登录成功，且用户首次登录客户端系统，未绑定用户，则跳转到绑定用户界面，如下图：

客户端登录绑定用户

  1. 输入客户端应用的用户名和密码，点击绑定按钮，跳转到绑定成功界面，如下图：

客户端登录绑定成功

  1. 登录成功后，跳转到后台首页，如下图：

客户端登录成功跳转后台首页

  1. 绑定成功后，想要解绑用户，则在后台 -> 个人中心 界面，点击解绑，如下图：

客户端登录解绑用户