Browse Source

feat:update docs (#73)

master
vran 3 years ago
committed by GitHub
parent
commit
401f61b45c
No known key found for this signature in database GPG Key ID: 4AEE18F83AFDEB23
  1. 9
      docs/README/develop/login-and-auth/index.md
  2. BIN
      docs/README/develop/login-and-auth/username-and-password/img/1-filter.png
  3. BIN
      docs/README/develop/login-and-auth/username-and-password/img/2-username-and-password-filter.png
  4. BIN
      docs/README/develop/login-and-auth/username-and-password/img/3-token.png
  5. 161
      docs/README/develop/login-and-auth/username-and-password/index.md
  6. BIN
      docs/README/develop/module-and-package/img/module-relation.png
  7. 62
      docs/README/develop/module-and-package/index.md
  8. 2
      docs/_sidebar.md
  9. 1
      docs/index.html

9
docs/README/develop/login-and-auth/index.md

@ -0,0 +1,9 @@
# Databasir 登录授权流程
### [一、用户名密码登录认证流程](README/develop/login-and-auth/username-and-password/index.md)
### [二、OAuth2 登录认证流程](README/develop/login-and-auth/oauth2/index.md)

BIN
docs/README/develop/login-and-auth/username-and-password/img/1-filter.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 21 KiB

BIN
docs/README/develop/login-and-auth/username-and-password/img/2-username-and-password-filter.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 80 KiB

BIN
docs/README/develop/login-and-auth/username-and-password/img/3-token.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 70 KiB

161
docs/README/develop/login-and-auth/username-and-password/index.md

@ -0,0 +1,161 @@
# 用户名密码登录解析
## 相关代码位置
相关代码都位于 `API` 模块下的
- 【package】com.databasir.api.config.security.*
- 【class】com.databasir.api.config.SecurityConfig.java
## 登录认证过滤器
Databasir 的登录认证都是在 Filter 中实现的,目前有两个自定义的 Filter
- `DatabasirOauth2LoginFilter`:负责处理 OAuth2 登录的请求
- `DatabasirJwtTokenFilter`:负责验证登录凭证的有效性
用户名和密码的登录采用 Spring Security 自带的 Filter
- `UsernamePasswordAuthenticationFilter`:负责处理用户名密码登录的请求
用户登录请求都会经过这三个过滤器
![](img/1-filter.png)
由于本篇主要说明用户明密码登录这一流程,所以会重点专注于 `UsernamePasswordFilter` 这一过滤器。
## 登录认证相关类
用户名密码登录是基于 Spring Security 提供的 `UsernamePasswordAuthenticationFilter` 实现。
Databasir 根据该过滤器的扩展点自定义了以下类
- DatabasirAuthenticationFailureHandler:登录失败回调
- DatabasirAuthenticationSuccessHandler:登录成功回调
- DatabasirUserDetailService:获取用户登录信息的 service
- DatabasirUserDetails:用户的登录信息(扩展了角色信息)
这些类的装配都在 `com.databasir.api.config.SecurityConfig.java` 中,下面展示了一部分源码,重点关注 `configure(HttpSecurity)` 方法
```java
@Configuration
@RequiredArgsConstructor
@EnableGlobalMethodSecurity(prePostEnabled = true)
public class SecurityConfig extends WebSecurityConfigurerAdapter {
private final DatabasirUserDetailService databasirUserDetailService;
private final DatabasirAuthenticationEntryPoint databasirAuthenticationEntryPoint;
private final DatabasirJwtTokenFilter databasirJwtTokenFilter;
private final DatabasirAuthenticationFailureHandler databasirAuthenticationFailureHandler;
private final DatabasirAuthenticationSuccessHandler databasirAuthenticationSuccessHandler;
@Override
protected void configure(HttpSecurity http) throws Exception {
http.headers().frameOptions().disable();
http.csrf().disable();
http.cors();
http.sessionManagement().sessionCreationPolicy(SessionCreationPolicy.STATELESS)
.and()
// 启用 form 表单登录方式,配置登录地址为 /login,并制定成功和失败的回调处理类
.formLogin()
.loginProcessingUrl("/login")
.failureHandler(databasirAuthenticationFailureHandler)
.successHandler(databasirAuthenticationSuccessHandler)
.and()
.authorizeRequests()
// 登录和 Token 刷新无需授权
.antMatchers("/login", Routes.Login.REFRESH_ACCESS_TOKEN)
.permitAll()
// oauth 回调地址无需鉴权
.antMatchers("/oauth2/apps", "/oauth2/authorization/*", "/oauth2/login/*")
.permitAll()
// 静态资源无需鉴权
.antMatchers("/", "/*.html", "/js/**", "/css/**", "/img/**", "/*.ico")
.permitAll()
// api 请求需要授权
.antMatchers("/api/**").authenticated()
.and()
.exceptionHandling()
.authenticationEntryPoint(databasirAuthenticationEntryPoint);
http.addFilterBefore(
databasirJwtTokenFilter,
UsernamePasswordAuthenticationFilter.class
);
}
@Override
protected void configure(AuthenticationManagerBuilder auth) throws Exception {
// 这里指定了 userDetailService 为自定义的 DatabasirUserDetailService
auth.userDetailsService(databasirUserDetailService)
.passwordEncoder(bCryptPasswordEncoder());
}
}
```
## 登录认证过滤器处理流程
当请求经过 `UsernamePasswordAuthenticationFilter` 时,该过滤器会校验请求的路径是否是 `/login` ,如果不是的话就直接放行。
然后在从请求参数里面获取用户名和密码
- username
- password
再之后使用 `DatabasirUserDetailsService` 根据用户名获取实际的用户信息,将实际的密码和登录时传的参数做比较
- 如果不一致就登录失败,调用 `DatabasirAuthenticationFailureHandler`
- 如果一致就说明登录成功,调用 `DatabasirAuthenticationSuccessHandler`
下图展示了一个简化的代码调用时序
![](img/2-username-and-password-filter.png)
## 登录成功回调
当用户名密码认证通过以后就会触发**登录成功回调**(代码实现在`DatabasirAuthenticationSuccessHandler`),这里主要做一件事情
- 生成登录凭证:access_token、refresh_token
access_token 是请求接口的凭证,证明你是合法的登录用户,时效性是以分钟为单位,格式为 JWT。
refresh_token 是用于在 access_token 过期时,用于获取新的 access_token,时效性是以天为单位。
这些信息都存储在 login 表里,login 表与 user 表是一对一的关系
![](img/3-token.png)
access_token 和 refresh_token 最终都会返回给前端,前端拿到 token 以后调用业务接口都需在请求中加入 名为 Authorization 的 Header,值为 access_token
```http
POST /api/v1.0/groups
Authorization: {{ access_token }}
```
如果 access_token 过期,前端会拿 refresh_token 获取一个新的 access_token,然后再调用业务接口,这些过程对用户是透明的。
## 登录失败回调
当用户名密码认证没通过的时候机会触发登录失败回调,源码位于 `DatabasirAuthenticationFailureHandler` 中。
失败的回调会判断异常类型做出不同的响应
- BadCredentialsException:响应 200,用户名或密码错误
- DisabledException:响应 200,用户已禁用
- DatabasirAuthenticationException:响应 200,自定义登录异常
- 其他:响应 401

BIN
docs/README/develop/module-and-package/img/module-relation.png

Binary file not shown.

After

Width:  |  Height:  |  Size: 22 KiB

62
docs/README/develop/module-and-package/index.md

@ -1,6 +1,4 @@
# 模块和包
## 项目模块
# 项目模块
Databasir 基于 Gradle 进行模块管理,当前共有 5 个模块
@ -10,4 +8,60 @@ Databasir 基于 Gradle 进行模块管理,当前共有 5 个模块
| common | 定义了项目通用的类,比如加解密工具、业务异常、标准 HTTP 返回类型等 |
| core | 核心业务模块,包含了所有的业务逻辑 |
| dao | 数据访问层,包含了数据库的实体、数据访问对象以及项目模型的 SQL 文件 |
| plugin | jdbc 封装模块,将从 jdbc 获取的数据库元信息转换成 Databasir 的 Java 对象,文档信息的 DIFF 功能也是在该模块内实现 |
| plugin | jdbc 封装模块,将从 jdbc 获取的数据库元信息转换成 Databasir 的 Java 对象,文档信息的 DIFF 功能也是在该模块内实现 |
模块的依赖关系是一个简单的单向依赖
![](img/module-relation.png)
## API 模块介绍
- 代码目录
```java
api
└── src/main/java
└── com/databasir
├── api
│ ├── advice
│ │ ├── DatabasirExceptionAdvice.java /* 业务异常切面 */
│ │ └── OperationLogAspect.java /* 审计日志切面 */
│ ├── common
│ │ └── LoginUserContext.java 用户信息工具类
│ ├── config
│ │ ├── oauth2
│ │ │ ├── DatabasirOAuth2Authentication.java /* oauth2 登录信息实体 */
│ │ │ ├── DatabasirOauth2LoginFilter.java /* oauth2 登录过滤器 */
│ │ │ └── OAuth2AuthenticationSuccessHandler.java /* oauth2 登录成功回调类 */
│ │ ├── security
│ │ │ ├── DatabasirAuthenticationEntryPoint.java /* 授权失败回调类 */
│ │ │ ├── DatabasirAuthenticationFailureHandler.java /* 登录失败回调类 */
│ │ │ ├── DatabasirAuthenticationSuccessHandler.java /* 登录成功回调类 */
│ │ │ ├── DatabasirJwtTokenFilter.java /* jwt token 校验过滤器 */
│ │ │ ├── DatabasirUserDetails.java /* 已登录用户实体信息 */
│ │ │ └── DatabasirUserDetailService.java /* 加载 DatabasirUserDetails 的 service */
│ │ ├── SecurityConfig.java /* spring security 配置类 */
│ │ └── WebConfig.java /* web 配置类 */
│ ├── validator
│ │ └── XXXXXValidator.java /* 业务规则前置校验器 */
│ ├── XXXXXController.java /* 业务 HTTP 接口 */
│ └── Routes.java /* 业务 HTTP 接口路径常量 */
└── job
├── ProjectDocumentAutoSyncJob.java /* 文档自动同步任务 */
└── ProjectDocumentAutoSyncTriggerJob.java /* 文档自动同步任务启用任务 */
```
- 配置目录
```java
api
└── src/main/resources
├── static /* 静态资源目录 */
├── application.properties /* 生产环境配置文件 */
└── application-local.properties /* 本地开发配置文件 */
```

2
docs/_sidebar.md

@ -22,6 +22,8 @@
* 参与开发
* [构建指南](README/develop/build/index.md)
* [模块和包](README/develop/module-and-package/index.md)
* 登录授权流程
* [用户名密码登录流程](README/develop/login-and-auth/username-and-password/index.md)
* 捐赠

1
docs/index.html

@ -36,5 +36,6 @@
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-bash.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-sql.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-properties.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/prismjs@1/components/prism-java.min.js"></script>
</body>
</html>

Loading…
Cancel
Save