# sureness | [中文文档](README_CN.md)
> A simple and efficient jvm security framework that focus on the protection of REST API.
[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)
[![Maven](https://img.shields.io/badge/Maven%20Central-1.0.3-blue.svg)](https://search.maven.org/artifact/com.usthe.sureness/sureness-core)
![GitHub pull request check contexts](https://img.shields.io/github/status/contexts/pulls/dromara/sureness/8?label=pull%20checks)
[![Gitter](https://img.shields.io/gitter/room/usthe/sureness?label=sureness&color=orange&logo=gitter&logoColor=red)](https://gitter.im/usthe/sureness)
![GitHub Release Date](https://img.shields.io/github/release-date/dromara/sureness?color=blue&logo=figshare&logoColor=red)
[![star](https://gitee.com/dromara/sureness/badge/star.svg?theme=gray)](https://gitee.com/dromara/sureness/stargazers)
[![star](https://img.shields.io/github/stars/dromara/sureness?style=social)](https://github.com/dromara/sureness)
**Home Page: [dromara.org/sureness](https://dromara.org/sureness) or [su.usthe.com](https://su.usthe.com/)**
## 🎡 Introduction
> [Sureness](https://github.com/dromara/sureness) is a simple and efficient open-source security framework that focus on the protection of REST API.
> Provide authentication and authorization, based on RBAC.
> No specific framework dependency (supports Javalin, Spring Boot, Quarkus, Ktor, Micronaut and more).
> Supports dynamic modification of permissions.
> Supports WebSockets and mainstream HTTP containers (Servlet and JAX-RS).
> Supports JWT, Basic Auth, Digest Auth, and can be extended to support custom authentication methods.
> High performance due to dictionary matching tree.
> Good extension interface, demos and documentation.
> Sureness has a sensible default configuration, is easy to customize, and is not couple to any one framework, which enables developers to quickly and safely protect their projects in multiple scenarios.
##### 🔍 Compare
| ~ | sureness | shiro | spring security |
| --- | --- | --- | --- |
| **Multi Framework Support** | support | support need modify | not support |
| **REST API** | support | support need modify | support |
| **Websocket** | support | not support | not support |
| **Path Match** | dictionary matching tree | ant match | ant match |
| **Annotation Support** | support | support | support |
| **Servlet** | support | support | support |
| **JAX-RS** | support | not support | not support |
| **Dynamic Modification of Permissions** | support | support need modify | support need modify |
| **Performance** | fast | slower | slower|
| **Learning Curve** | simple | simple | steep|
##### 📈 Benchmark
![benchmark](docs/_images/benchmark_en.png)
**Benchmark test shows sureness to lose 0.026ms performance compared to frameless application, shiro lose 0.088ms, spring security lose 0.116ms.**
**In contrast, sureness basically does not consume performance, and the performance (TPS loss) is 3 times that of shiro and 4 times that of spring security.**
**The performance gap will be further widened as the api matching chain increases.**
Detail see [Benchmark Test](https://github.com/tomsun28/sureness-shiro-spring-security-benchmark)
##### ✌ Framework Sample Support
- [x] sureness integration springboot sample(configuration file scheme) [sample-bootstrap](sample-bootstrap)
- [x] sureness integration springboot sample(database scheme) [sample-tom](sample-tom)
- [x] sureness integration quarkus sample [sample-quarkus](samples/quarkus-sureness)
- [x] sureness integration javalin sample [sample-javalin](samples/javalin-sureness)
- [x] sureness integration ktor sample [sample-ktor](samples/ktor-sureness)
- [x] sureness integration spring webflux sample [sample-spring-webflux](samples/spring-webflux-sureness)
- [x] sureness integration micronaut sample [sample-micronaut](samples/micronaut-sureness)
- [x] sureness integration micronaut sample [sample-jfinal](samples/jfinal-sureness)
- [x] sureness integration solon sample [sample-solon](samples/solon-sureness)
- [x] sureness integration session sample [sureness-session](samples/sureness-session)
- [x] sureness integration redis cache session sample [sureness-redis-session](samples/sureness-redis-session)
- [x] more samples todo
## 🔨 Quick Start
#### 🐕 Some Conventions
- Based RBAC, User-Role-Resource.
- We treat API requests as a resource, resource format like `requestUri===httpMethod`.
That is the request uri + request method(`post,get,put,delete...`) is considered as a resource as a whole.
`eg: /api/v2/book===get`
- User belongs some Role -- Role owns Resource -- User can access the resource.
Resource path matching see: [URI Match](docs/path-match.md)
#### 🐖 Add Sureness In Your Project
When use maven or gradle build project, add coordinate
```
com.usthe.sureness
sureness-core
1.0.3
```
```
compile group: 'com.usthe.sureness', name: 'sureness-core', version: '1.0.3'
```
#### 🐵 Use the Default Configuration to Configure Sureness
The default configuration -`DefaultSurenessConfig` uses the document datasource `sureness.yml` as the auth datasource.
It supports JWT auth, Basic auth, Digest authentication.
```
@Bean
public DefaultSurenessConfig surenessConfig() {
return new DefaultSurenessConfig();
}
```
#### 🐮 Load Auth Config DataSource
Sureness authentication requires us to provide our own account data, role permission data, etc. These data may come from text, relational databases, non-relational databases, annotations, etc.
We provide interfaces `SurenessAccountProvider`, `PathTreeProvider` for user implement to load data from the dataSource where they want.
- `SurenessAccountProvider` - Account datasource provider interface.
- `PathTreeProvider` - Resource uri-role datasource provider interface.
Default Document DataSource Config - `sureness.yml`, see: [Default Document DataSource](docs/default-datasource.md)
Annotation DataSource Config Detail - `AnnotationLoader`, see: [Annotation DataSource](docs/annotation-datasource.md)
If the configuration resource data comes from text, please refer to [Sureness integration springboot sample(configuration file scheme)](https://github.com/tomsun28/sureness/tree/master/sample-bootstrap)
If the configuration resource data comes from dataBase, please refer to [Sureness integration springboot sample(database scheme)](https://github.com/tomsun28/sureness/tree/master/sample-tom)
#### 🐐 Add an Interceptor Intercepting All Requests
The essence of sureness is to intercept all rest requests for authenticating and Authorizing.
The interceptor can be a filter or a spring interceptor, it intercepts all request to check them.
```
SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest)
```
#### 🐰 Implement Auth Exception Handling Process
Sureness uses exception handling process:
- If auth success, method - `checkIn` will return a `SubjectSum` object containing user information.
- If auth failure, method - `checkIn` will throw different types of auth exceptions.
Users need to continue the subsequent process based on these exceptions.(eg: return the request response)
Here we need to customize the exceptions thrown by `checkIn`, passed directly when auth success, catch exception when auth failure and do something:
```
try {
SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest);
} catch (ProcessorNotFoundException | UnknownAccountException | UnsupportedSubjectException e4) {
// Create subject error related execption
} catch (DisabledAccountException | ExcessiveAttemptsException e2 ) {
// Account disable related exception
} catch (IncorrectCredentialsException | ExpiredCredentialsException e3) {
// Authentication failure related exception
} catch (UnauthorizedException e5) {
// Authorization failure related exception
} catch (SurenessAuthenticationException | SurenessAuthorizationException e) {
// other sureness exception
}
```
Detail sureness auth exception see: [Default Sureness Auth Exception](docs/default-exception.md)
**Have Fun**
## 🥐 Advanced Use
Sureness supports custom subject, custom subjectCreator, custom processor and more.
Before advanced custom extension, let's first understand the general process of sureness:
![flow](/docs/_images/flow-en.png)
As in the above process, Subject is created by SubjectCreate according to the request body, and different authentication processors process the supported Subjects.
Sureness provides the following common interfaces as extension points:
- `Subject`: Authenticated authorized user's account interface, provide the account's username,password, request resources, roles, etc.
- `SubjectCreate`: Create subject interface, provider create method.
- `Processor`: Process subject interface, where happen authentication and authorization.
- `PathTreeProvider`: Resource data provider, it can load data from txt or database,etc.
- `SurenessAccountProvider`: Account data provider, it can load data from txt or database,etc.
Refer to [Extension Point](https://usthe.com/sureness/#/extend-point) for the extended documentation.
1. 🥊 **Custom Subject**
`Implment Subject, add custom subject content`
`Implment SubjectCreate to create custom subject`
`Implment Processor to support custom subject`
See [Custom Subject](docs/custom-subject.md)
2. 🔫 **Custom SubjectCreator**
`Implment SubjectCreate to create your custom subject`
See [Custom SubjectCreator](docs/custom-subject-creator.md)
3. 🪓 **Custom Processor**
`A subject also can support by different processor, so we can custom processor to support custom subject`
`Implment Processor, set which subject can support and implment processing details`
See [Custom Processor](docs/custom-processor.md)
4. 🏹 **Custom Datasource**
`Implment PathTreeProvider, load in DefaultPathRoleMatcher`
`Implment SurenessAccountProvide, load in processor`
See [Custom Datasource](docs/custom-datasource.md)
Detail please refer to [Sureness integration springboot sample(database scheme)](sample-tom)
## 🙋 Contributing
Very welcome to Contribute this project, go further and better with sureness.
Components of Repository:
- [sureness's kernel code--sureness-core](core)
- [sureness integration springboot sample(configuration file scheme)--sample-bootstrap](sample-bootstrap)
- [sureness integration springboot sample(database scheme)-sample-tom](sample-tom)
- [sample projects using sureness in each framework(javalin,ktor,quarkus)--samples](samples)
See [CONTRIBUTING](CONTRIBUTING.md)
#### 💪 Why Is High Performance
![pathRoleMatcher](docs/_images/PathRoleMatcher.svg)
## 🌞 Friend's Links
* **```JustAuth```** A Java library of third-party authorized login: [Github](https://github.com/justauth/JustAuth)
* **```MaxKey```** Leading-Edge Enterprise-Class open source IAM Identity and Access management product: [Github](https://github.com/dromara/MaxKey)
* **```PhalApi```** PHP Api Framework: [Website](https://www.phalapi.net/)
## Join discussion
[Github Discussion](https://github.com/usthe/sureness/discussions)
[Gitter Channel](https://gitter.im/usthe/sureness)
QQ Group:390083213
Dromara社区微信公众号: gh_7eeb0b1b7476
Sureness微信公众号:sureness
## 🛡️ License
[`Apache License, Version 2.0`](https://www.apache.org/licenses/LICENSE-2.0.html)