Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/dromara/sureness
Dromara Sureness A efficient security framework focus on protection of API.
https://github.com/dromara/sureness
authentication authorization basic-auth digest framework javalin jwt ktor library quarkus restful-api shiro spring spring-security springboot
Last synced: 3 days ago
JSON representation
Dromara Sureness A efficient security framework focus on protection of API.
- Host: GitHub
- URL: https://github.com/dromara/sureness
- Owner: dromara
- License: apache-2.0
- Created: 2019-01-21T15:35:21.000Z (almost 6 years ago)
- Default Branch: master
- Last Pushed: 2024-12-08T01:17:55.000Z (14 days ago)
- Last Synced: 2024-12-12T07:05:09.900Z (10 days ago)
- Topics: authentication, authorization, basic-auth, digest, framework, javalin, jwt, ktor, library, quarkus, restful-api, shiro, spring, spring-security, springboot
- Language: Java
- Homepage: https://usthe.com/sureness
- Size: 8.27 MB
- Stars: 870
- Watchers: 31
- Forks: 159
- Open Issues: 21
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Support: support/pom.xml
Awesome Lists containing this project
- awesome - dromara/sureness - A simple and efficient security framework that focus on protection of API. (Java)
README
# Sureness | [中文文档](README_CN.md)
> A efficient security framework that focus on the protection of REST API.
[](https://www.apache.org/licenses/LICENSE-2.0.html)
[](https://search.maven.org/artifact/com.usthe.sureness/sureness-core)
[](https://gitter.im/usthe/sureness)
[](https://gitee.com/dromara/sureness/stargazers)
[](https://github.com/dromara/sureness)
**Home Page: [usthe.com/sureness](https://usthe.com/sureness) | [su.usthe.com](https://su.usthe.com/)**
**Code Hosting**
## Introduction
**Sureness** is a 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 HTTP containers (Servlet and JAX-RS).
- Supports JWT, Basic Auth, Digest Auth, and can custom auth methods.
- High performance with Dictionary Matching Tree.
- Good extension interface, demos and documentation.
##### Why Is High Performance
##### Framework Sample Support
- [x] Sureness integration **Spring Boot** sample(configuration file scheme) [sample-bootstrap](sample-bootstrap)
- [x] Sureness integration **Spring Boot** 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 **Jfinal** sample [sample-jfinal](samples/jfinal-sureness)
- [x] Sureness integration **Solon** sample [sample-solon](samples/solon-sureness)
- [x] Sureness integration **Spring Gateway** sample [sample-spring-gateway](samples/spring-gateway-sureness)
- [x] Sureness integration **Zuul** sample [sample-zuul](samples/zuul-sureness)
- [x] Sureness integration Session sample [sureness-session](samples/sureness-session)
- [x] Sureness integration Redis Session cache sample [sureness-redis-session](samples/sureness-redis-session)
- [x] More samples todo
## Security Framework Compare
##### Sureness VS Shiro VS Spring Security
| ~ | 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 Permissions** | support | support need modify | support need modify |
| **Performance** | fast | slower | slower|
| **Learning Curve** | simple | simple | steep|
##### Benchmark
**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)
## 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.1.0
```
```
compile group: 'com.usthe.sureness', name: 'sureness-core', version: '1.1.0'
```
#### 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 Spring Boot 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 Spring Boot 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 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:
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 Spring Boot 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 Spring Boot sample(configuration file scheme)--sample-bootstrap](sample-bootstrap)
- [Sureness integration Spring Boot sample(database scheme)-sample-tom](sample-tom)
- [Sample projects using Sureness in each framework(Javalin,Ktor,Quarkus)--samples](samples)
See [CONTRIBUTING](CONTRIBUTING.md)
## Friend's Links
* **```HertzBeat```** An open-source, real-time monitoring system with custom-monitor and agentLess: [Github](https://github.com/dromara/hertzbeat)
* **```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
QQ Group: 390083213
[Github Discussion](https://github.com/dromara/sureness/discussions)
[Gitter Channel](https://gitter.im/dromara/sureness)
## License
[`Apache License, Version 2.0`](https://www.apache.org/licenses/LICENSE-2.0.html)
## Thanks
[](https://www.jetbrains.com/community/opensource/#support)