Home

Awesome

<p align="center"> <a href="https://github.com/usthe/sureness"> <img alt="sureness" src="./docs/_media/brand128.svg"> </a> </p>

<font size="14p">Sureness</font> <font size="5p"> | 中文文档</font>

A efficient security framework that focus on the protection of REST API.

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

<a href="https://www.producthunt.com/posts/sureness?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-sureness" target="_blank"><img src="https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=287707&theme=light" alt="sureness - Jvm security framework that focus on protection of rest api | Product Hunt"/></a>

Home Page: usthe.com/sureness | su.usthe.com

Code Hosting

| <a href="https://gitcode.com/dromara/sureness/overview" target="_blank"><b>GitCode</b></a> | <a href="https://gitee.com/dromara/sureness" target="_blank"><b>Gitee</b></a> |<a href="https://github.com/dromara/sureness" target="_blank"><b>GitHub</b></a> |

<font color="green">Introduction</font>

Sureness is a efficient open-source security framework that focus on the protection of REST API.

Why Is High Performance

pathRoleMatcher

Framework Sample Support

Security Framework Compare

Sureness VS Shiro VS Spring Security
~SurenessShiroSpring Security
Multi Framework Supportsupportsupport need modifynot support
REST APIsupportsupport need modifysupport
Websocketsupportnot supportnot support
Path Matchdictionary matching treeant matchant match
Annotation Supportsupportsupportsupport
Servletsupportsupportsupport
JAX-RSsupportnot supportnot support
Dynamic Permissionssupportsupport need modifysupport need modify
Performancefastslowerslower
Learning Curvesimplesimplesteep
Benchmark

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

Quick Start

<font color="red">Some Conventions</font>

Resource path matching see: URI Match

Add Sureness In Your Project

When use maven or gradle build project, add coordinate

<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'

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.

Default Document DataSource Config - sureness.yml, see: Default Document DataSource
Annotation DataSource Config Detail - AnnotationLoader, see: Annotation DataSource

If the configuration resource data comes from text, please refer to Sureness integration Spring Boot sample(configuration file scheme)
If the configuration resource data comes from dataBase, please refer to Sureness integration Spring Boot sample(database scheme)

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:

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

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

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:

Refer to Extension 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

  1. Custom SubjectCreator

Implment SubjectCreate to create your custom subject

See Custom SubjectCreator

  1. 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

  1. Custom Datasource

Implment PathTreeProvider, load in DefaultPathRoleMatcher
Implment SurenessAccountProvide, load in processor

See Custom Datasource

Detail please refer to Sureness integration Spring Boot sample(database scheme)

Contributing

Very welcome to Contribute this project, go further and better with Sureness.

Components of Repository:

See CONTRIBUTING

Friend's Links

Join discussion

QQ Group: 390083213
Github Discussion
Gitter Channel

<img alt="tan-cloud" src="https://cdn.jsdelivr.net/gh/dromara/hertzbeat/home/static/img/wechat.png" width="400"/> <br/> <img alt="planet" src="https://cdn.jsdelivr.net/gh/dromara/hertzbeat@gh-pages/img/planet.jpg" width="400"/>

License

Apache License, Version 2.0

Thanks

JetBrains