115 Star 899 Fork 234

dromara / sureness

加入 Gitee
与超过 1200万 开发者一起发现、参与优秀开源项目,私有仓库也完全免费 :)
免费加入
克隆/下载
贡献代码
同步代码
取消
提示: 由于 Git 不支持空文件夾,创建文件夹后会生成空的 .keep 文件
Loading...
README_CN.md
Apache-2.0

sureness

Sureness | English Documentation

面向REST API的高性能认证鉴权框架

License Maven GitHub pull request check contexts Gitter GitHub Release Date star star

sureness - Jvm security framework that focus on protection of rest api | Product Hunt

官网: usthe.com/sureness | su.usthe.com

📫 背景

在主流的前后端分离架构中,如何通过有效快速的认证鉴权来保护后端提供的REST API变得尤为重要。对现存框架,不原生支持RESTfulApache Shiro, 还是深度绑定SpringSpring Security,或多或少都不是我们的理想型。
于是乎Sureness诞生了,我们希望能解决这些,提供一个面向REST API无框架依赖,可以动态修改权限多认证策略更快速度易用易扩展的认证鉴权框架。

🎡 介绍

Sureness 是我们在深度使用 Apache Shiro 之后,吸取其优点全新设计开发的一个认证鉴权框架
面向 REST API 的认证鉴权,基于 RBAC (用户-角色-资源)主要关注于对 API 的安全保护
无特定Web框架依赖(已有 Spring Boot,Quarkus,Javalin,Ktor,Micronaut,Jfinal,Solon 等集成样例)
支持动态修改权限配置(动态修改配置每个 API 谁有权访问)
支持 Websocket ,主流 HTTP 容器 ServletJAX-RS
支持多种认证策略, JWT, Basic Auth, Digest Auth ... 可扩展自定义认证方式
基于改进的字典匹配树拥有的高性能
良好的扩展接口, 样例和文档助急速理解扩展使用

Sureness的低配置,易扩展,不耦合其他框架,希望能对系统多场景快速安全的保护

🔍 对比
~ Sureness Shiro Spring Security
多框架支持 支持 需改动支持 不支持
REST API 支持 需改动支持 支持
Websocket 支持 不支持 不支持
过滤链匹配 优化的字典匹配树 ant匹配 ant匹配
注解支持 支持 支持 支持
Servlet 支持 支持 支持
JAX-RS 支持 不支持 不支持
权限动态修改 支持 需改动支持 需改动支持
性能速度 较快 较慢 较慢
学习曲线 简单 简单 陡峭
📈 基准性能测试

benchmark

基准测试显示Sureness对比无权限框架应用损耗0.026ms性能,Shiro损耗0.088ms,Spring Security损耗0.116ms, 相比之下Sureness性能(参考TPS损耗)是Shiro的3倍,Spring Security的4倍
性能差距会随着api匹配链的增加而进一步拉大
详见基准测试

✌ 框架支持样例

🔨 快速开始

🐕 使用前一些约定

  • Sureness基于RBAC,即用户-角色-资源: 用户所属角色--角色拥有资源(API)--用户就能访问资源(API)
  • 我们将REST API请求视作一个资源,资源格式为: requestUri===httpMethod
    即请求的路径加上其请求方式(post,get,put,delete...)作为一个整体被视作资源来赋权配置
    eg: /api/v2/book===get get方式请求/api/v2/book接口数据

资源路径匹配详见 URI路径匹配

🐖 项目中加入Sureness

项目使用mavengradle构建,加入坐标

<dependency>
    <groupId>com.usthe.sureness</groupId>
    <artifactId>sureness-core</artifactId>
    <version>1.1.0</version>
</dependency>
compile group: 'com.usthe.sureness', name: 'sureness-core', version: '1.1.0'

🐵 使用默认配置来配置Sureness

默认配置使用了文件数据源sureness.yml作为账户权限数据源
默认配置支持了JWT, Basic auth, Digest auth认证

@Bean
public DefaultSurenessConfig surenessConfig() {
    return new DefaultSurenessConfig();
}

🐮 配置权限账户数据源

Sureness认证鉴权,当然也需要我们提供自己的账户数据,角色权限数据等,这些数据可能来自文本,关系数据库,非关系数据库,注解等。
我们提供了数据源接口:SurenessAccountProvider, PathTreeProvider,用户可以实现此接口实现自定义数据源。

  • PathTreeProvider: 资源的数据源接口,实现从数据库,文本等加载数据,加载到对应的资源权限匹配器DefaultPathRoleMatcher
  • SurenessAccountProvider: 用户的账户密钥信息接口,实现从数据库,文本等加载数据,加载到需要账户数据的processor

当使用的是上方默认配置DefaultSurenessConfig时,则默认使用文本数据源和注解数据源作为数据提供者。

我们提供了代码工程样例:
默认文本数据源具体实现,请参考Sureness集成Spring Boot样例(配置文件方案)--sample-bootstrap
若权限配置数据来自数据库,请参考Sureness集成Spring Boot样例(数据库方案)--sample-tom

🐐 添加过滤器拦截所有请求

Sureness的本质就拦截所有API请求对其认证鉴权判断。
入口拦截器器实现一般可以是 filter or spring interceptor
在拦截器中加入Sureness的安全过滤器,如下:

SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest)

🐰 实现认证鉴权相关异常处理流程

Sureness使用异常处理流程:

  1. 若认证鉴权成功,checkIn会返回包含用户信息的SubjectSum对象
  2. 若中间认证鉴权失败,checkIn会抛出不同类型的认证鉴权异常,用户需根据这些异常来继续后面的流程(返回相应的请求响应)

这里我们就需要对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 (SurenessAuthenticationException | SurenessAuthorizationException e) {
    // 其他自定义异常
}

异常详见 默认异常类型

HAVE FUN

如果这个[快速开始]对您不是很友好,可以参考这篇一步一步搭建,里面一步一步详细介绍了使用Sureness搭建一个完整功能认证鉴权项目的步骤。

🥐 进阶扩展

Sureness支持自定义subject,自定义subjectCreator注册,自定义processor处理器等

进阶自定义扩展之前我们先来了解下Sureness的大致流程:

flow

如上面流程,Subject被SubjectCreate根据request请求体所创造,不同的认证鉴权处理器Processor来处理所支持的Subject。

Sureness提供了下面这些常用接口作为扩展点:

  • Subject: 认证鉴权对象接口,提供访问对象的账户密钥,请求资源,角色等信息
  • SubjectCreate: 创建Subject接口,根据请求内容创建不同类型的Subject对象
  • Processor: Subject处理接口,根据Subject信息,进行认证鉴权
  • PathTreeProvider: 资源的数据源接口,实现从数据库,文本等加载数据
  • SurenessAccountProvider: 用户的账户密钥信息接口,实现从数据库,文本等加载数据

扩展文档详见 扩展点

  1. 🥊 自定义subject

实现Subject接口,添加自定义的subject内容
实现SubjectCreate接口方法,自定义subjectCreator创建出自定义的subject
实现BaseProcessor接口,自定义processor支持处理自定义的subject
详见 自定义Subject

  1. 🔫 自定义subjectCreator

实现SubjectCreate接口方法,根据request请求的内容创建出对应需要的的subject
详见 自定义SubjectCreate

  1. 🪓 自定义processor

实现BaseProcessor接口,设置支持的subject,实现处理该subject的认证鉴权逻辑
详见 自定义Processor

  1. 🏹 自定义数据源

实现 PathTreeProvider的接口, 加载到对应的资源权限匹配器DefaultPathRoleMatcher
实现 SurenessAccountProvider的接口,加载到需要账户数据的processor
详见 自定义数据源

具体扩展实践请参考 Sureness集成Spring Boot样例(数据库方案)--sample-tom

🙋 参与贡献

非常欢迎参与项目贡献,我们致力于维护一个互相帮助的快乐社区。

仓库的组成部分:

详见 CONTRIBUTING

💪 高性能匹配

pathRoleMatcher

💡 更多相关

相关文章:
REST API 权限设计 - 初探一
REST API 权限设计 - 快速搭建权限项目-配置文件方案
REST API 权限设计 - Sureness集成Spring Boot样例-数据库方案

tan-cloud
planet

QQ Group: 390083213
Github Discussion
Gitter Channel

🌞 开源推荐

  • HertzBeat 易用友好的实时监控系统,无需Agent,强大自定义监控能力: Github
  • JustAuth 小而全而美的第三方登录开源组件: Gitee
  • MaxKey 业界领先的企业级开源IAM身份管理和身份认证产品: Gitee
  • PhalApi 一个轻量级PHP开源接口框架: 官网

🛡️ License

Apache License, Version 2.0

🎟️ Thanks

JetBrains

Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: 1. You must give any other recipients of the Work or Derivative Works a copy of this License; and 2. You must cause any modified files to carry prominent notices stating that You changed the files; and 3. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and 4. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright tomsun28 usthe.com. Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

简介

面向REST API的高性能认证鉴权框架,致力于管理保护API安全 展开 收起
Java 等 3 种语言
Apache-2.0
取消

发行版 (11)

全部

贡献者

全部

近期动态

加载更多
不能加载更多了
Java
1
https://gitee.com/dromara/sureness.git
git@gitee.com:dromara/sureness.git
dromara
sureness
sureness
master

搜索帮助

F2647f8d 8189591 Bbdfb06e 8189591