diff --git a/docs/_images/basicAuthPostmanUse.png b/docs/_images/basicAuthPostmanUse.png new file mode 100644 index 0000000000000000000000000000000000000000..d79f6ef0f6594fa6ff9e754cb98df08406c970fa Binary files /dev/null and b/docs/_images/basicAuthPostmanUse.png differ diff --git a/docs/_images/jwtPostmanUse.png b/docs/_images/jwtPostmanUse.png new file mode 100644 index 0000000000000000000000000000000000000000..8ccfe0e76bedac97ef7dc5e345c0ea13113feacb Binary files /dev/null and b/docs/_images/jwtPostmanUse.png differ diff --git a/docs/_sidebar.md b/docs/_sidebar.md index 34ca8a72a91c30561349c5b76fb6da0801fe7826..82124412550c935b51be369956490edeca45e526 100644 --- a/docs/_sidebar.md +++ b/docs/_sidebar.md @@ -1,9 +1,12 @@ - 入门 - [介绍](README.md "introduce") - [快速开始](quickstart.md "quick start greatest") - -- 进阶扩展 + - [URI路径匹配](path-match.md) - [默认数据源](default-datasource.md) + - [默认认证方式](default-auth.md) + - [默认异常](default-exception.md) + +- 进阶扩展 - [扩展点](extend-point.md) - [自定义数据源](custom-datasource.md) - [自定义Subject](custom-subject.md) @@ -14,8 +17,6 @@ - [30分钟项目集成](sample-tom.md) - 其它 - - [url路径匹配](path-match.md) - - [sureness异常](exception.md) - [设计文档](design.md) - [参与贡献](contributing.md) - [Changelog](https://github.com/tomsun28/sureness/releases ':ignore') diff --git a/docs/custom-datasource.md b/docs/custom-datasource.md index 956ca59ce3b527cad68ab4da96dd0c6e6d59bc76..53e7086637dfdc79648f4e9b5109b97707d75d1b 100644 --- a/docs/custom-datasource.md +++ b/docs/custom-datasource.md @@ -1,6 +1,8 @@ ## 自定义数据源 +自定义前需要了解sureness提供的扩展接口,详见 [进阶扩展](extend-point.md) + 实现 `PathTreeProvider`的接口, 加载到`DefaultPathRoleMatcher`中. 实现 `SurenessAccountProvider`的接口,加载到需要的`processor`中. -具体扩展实践请参考 [使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness) +具体扩展实践请参考 [使用sureness30分钟项目集成案例](sample-tom.md) diff --git a/docs/custom-processor.md b/docs/custom-processor.md index 7b9db4dc6d3a7835a009c3ea13c178e32a7a8079..d4fe58632284b28bcc7b2791ac4fd8312a80bd67 100644 --- a/docs/custom-processor.md +++ b/docs/custom-processor.md @@ -1,6 +1,8 @@ ## 自定义processor +自定义前需要了解sureness提供的扩展接口,详见 [进阶扩展](extend-point.md) + 一个`subject`当然也可以被不同的`processor`处理,所以可以单独自定义`processor` 实现`Processor`接口,设置支持的`subject`,实现处理该`subject`的逻辑 -具体扩展实践请参考 [使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness) +具体扩展实践请参考 [使用sureness30分钟项目集成案例](sample-tom.md) \ No newline at end of file diff --git a/docs/custom-subject.md b/docs/custom-subject.md index 458403385b0162321ae9f53e9ebd6cace7ea9dc9..af38499a85e7b6cacdfe280f37057217d3a14879 100644 --- a/docs/custom-subject.md +++ b/docs/custom-subject.md @@ -1,7 +1,9 @@ ## 自定义subject +自定义前需要了解sureness提供的扩展接口,详见 [进阶扩展](extend-point.md) + 实现`Subject`接口,添加自定义的`subject`内容 实现`SubjectCreate`接口方法,创建出自定义的`subject` 实现`Processor`接口,支持处理自定义的`subject` -具体扩展实践请参考 [使用sureness30分钟搭建权限项目--sample-tom](https://github.com/tomsun28/sureness) +具体扩展实践请参考 [使用sureness30分钟项目集成案例](sample-tom.md) \ No newline at end of file diff --git a/docs/default-auth.md b/docs/default-auth.md new file mode 100644 index 0000000000000000000000000000000000000000..1ac8ffc8cdc59b88a3441738451ad5980df59ad9 --- /dev/null +++ b/docs/default-auth.md @@ -0,0 +1,38 @@ +## 默认支持的认证方式 + +`sureness`目前默认支持的认证方式有`bearer jwt`,`basic auth`, 当然用户可以通过扩展`Processor`,`Subject`和`SubjectCreate`接口实现自定义的认证方式 + +#### `bearer jwt` +`jwt`即`json web token`,是目前很流行的跨域,无状态,安全认证解决方案,介绍详见[网络](http://www.ruanyifeng.com/blog/2018/07/json_web_token-tutorial.html) +我们这里为啥叫`bearer jwt`是因为`jwt`是放入到http请求头的`bearer token`里面,即: `Authorization: Bearer jsonWebTokenValue` +eg: +``` +GET /api/v1/source1 HTTP/1.1 +Host: localhost:8088 +Content-Type: application/json +Authorization: Bearer eyJhbGciOiJIUzUxMiIsInppcCI6IkRFRiJ9.eNocjEEOwiAQRe8y65IwCBQ4hlvjotAhVqs1DBoT492l7F5e_vtfuNYFAliUPs3aCrIuCW1nFDHlUaBVqJOLJpkIA_ArtnHd7o0X5s43egim8qayy6lCQOOUd15JHIA-zy4OUo5dlG2lFp46KDjvR0fKhfgCIU8r0-8PAAD__w.f-3klWWDpEO3uDLlx2S53DV2cYernwVEDwcC6z1JexocbZoxRKmASTOuky1qMCxy_hV8-RbuMjDmI3ASa_FQOw +``` + +我们可以在`postman`如下使用它: 将`jwt`值塞入`Bearer Token`里. +![jwtPostmanUse](_images/jwtPostmanUse.png) + +#### `basic auth` +`basic auth`即`Basic access authentication`,经典的`http`基本认证方式,介绍详见[网络](https://www.jianshu.com/p/4cd42f7359f4) +这种认证方式是将账户密码组成的字符串`base64`加密,放入到请求头的 `Authorization`中, 即:`Authorization: Basic base64encode(username+":"+password)` +eg: +``` +GET /api/v1/source1 HTTP/1.1 +Host: localhost:8088 +Content-Type: application/json +Authorization: Basic dG9tOjMyMTEz +``` + +我们可以在`postman`如下使用它: 在`Basic Auth`类型的`Authorization`中输入账户密码即可,`postman`会自动对其`base64`加密. +![basicAuthPostmanUse](_images/basicAuthPostmanUse.png) + +#### 其他认证方式 +目前sureness暂支持这两种,之后会陆续扩展其他基本认证方式,当然你也可以很轻松的自定义认证方式,详见[自定义Subject](custom-subject.md) + +我们提供了默认认证方式的使用`DEMO`,请参考 [使用sureness10分钟项目集成案例](sample-bootstrap.md) +当然我们也提供了自定义认证方式的扩展`DEMO`,请参考 [使用sureness30分钟项目集成案例](sample-tom.md) + diff --git a/docs/default-datasource.md b/docs/default-datasource.md index f986e470e9b2d960eae149fdc2495f10128f3f0b..664ef9e1bdf42df4de63d5e6acee5093fe856848 100644 --- a/docs/default-datasource.md +++ b/docs/default-datasource.md @@ -1,4 +1,4 @@ -# 默认数据源 +## 默认数据源 `sureness`认证鉴权当然也需要我们自己的配置数据:账户数据,角色权限数据等 这些配置数据可能来自文本,关系数据库,非关系数据库 @@ -54,4 +54,5 @@ account: ``` -我们提供了默认文本数据源使用`DEMO`,默认文本数据源具体实现,请参考[使用sureness10分钟搭建权限项目--sample-bootstrap](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap) +我们提供了默认文本数据源使用`DEMO`,默认文本数据源具体实现,请参考 [使用sureness10分钟项目集成案例](sample-bootstrap.md) +当然数据源也可以来自数据库等存储,我们提供了接口让用户轻松的自定义数据源,详见[自定义数据源](custom-datasource.md) \ No newline at end of file diff --git a/docs/exception.md b/docs/default-exception.md similarity index 51% rename from docs/exception.md rename to docs/default-exception.md index b5fc64db56f2e9ce0b0e068ae4d9e864555f7928..2674997b34246db15bbb497baa2629582d90fcb7 100644 --- a/docs/exception.md +++ b/docs/default-exception.md @@ -1,4 +1,25 @@ -## sureness 异常 +## sureness 默认异常 + +`sureness`使用异常处理流程,我们需要对`checkIn`的认证鉴权流程中发生的认证失败或无权限访问等抛出的相应异常做自定义处理, +若认证鉴权成功,则直接通过,失败抛出特定异常,捕获异常,流程如下: + +``` + try { + SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest); + } catch (ProcessorNotFoundException | UnknownAccountException | UnsupportedSubjectException e4) { + // 账户创建相关异常 + } catch (DisabledAccountException | ExcessiveAttemptsException e2 ) { + // 账户禁用相关异常 + } catch (IncorrectCredentialsException | ExpiredCredentialsException e3) { + // 认证失败相关异常 + } catch (UnauthorizedException e5) { + // 鉴权失败相关异常 + } catch (RuntimeException e) { + // 其他自定义异常 + } +``` + +sureness 默认支持的异常处理流程中的异常如下: `sureness`异常 | 异常描述 --- | --- diff --git a/docs/extend-point.md b/docs/extend-point.md index 9c5fd89efd31d482f17e85c958e5038d19b3c3ae..f96ddafb17e744ed1c36558afc34345823325ea5 100644 --- a/docs/extend-point.md +++ b/docs/extend-point.md @@ -19,5 +19,4 @@ A(用户请求体进来) --> B(s) B(subjectCreate根据请求头内容创建不同的钥匙subject,每把钥匙都可以尝试) --> C(s) C(不同的钥匙认证方式即不同的锁processor来处理进来的钥匙subject) --> D(s) D(以上一次成功即成功并结束,失败即下一个钥匙锁尝试直到所有尝试结束) - -``` +``` \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index a9c839ceb2125852999c05f67c75b9ed3f95ddf5..999976249b9ee06e795e13225b6610df2c5e327a 100644 --- a/docs/index.html +++ b/docs/index.html @@ -10,10 +10,16 @@ + + +