{"id":13458788,"url":"https://github.com/dromara/sureness","last_synced_at":"2025-05-14T12:13:19.228Z","repository":{"id":37324677,"uuid":"166837677","full_name":"dromara/sureness","owner":"dromara","description":"Dromara Sureness A efficient security framework focus on protection of API. ","archived":false,"fork":false,"pushed_at":"2024-12-26T14:25:50.000Z","size":8668,"stargazers_count":874,"open_issues_count":21,"forks_count":157,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-04-11T05:59:52.237Z","etag":null,"topics":["authentication","authorization","basic-auth","digest","framework","javalin","jwt","ktor","library","quarkus","restful-api","shiro","spring","spring-security","springboot"],"latest_commit_sha":null,"homepage":"https://sureness.dromara.org","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dromara.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support/pom.xml","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://www.paypal.me/tomsun28","https://su.usthe.com/#/cn/sponsor"]}},"created_at":"2019-01-21T15:35:21.000Z","updated_at":"2025-04-07T14:04:17.000Z","dependencies_parsed_at":"2024-01-13T17:49:21.588Z","dependency_job_id":"29251a36-5db3-4027-b716-2d9bb18119b2","html_url":"https://github.com/dromara/sureness","commit_stats":{"total_commits":544,"total_committers":18,"mean_commits":30.22222222222222,"dds":"0.12867647058823528","last_synced_commit":"c0d93b9f53bf93e6a8f8f3cf962bc48ff06b099d"},"previous_names":[],"tags_count":30,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dromara%2Fsureness","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dromara%2Fsureness/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dromara%2Fsureness/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dromara%2Fsureness/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dromara","download_url":"https://codeload.github.com/dromara/sureness/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254140770,"owners_count":22021220,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","authorization","basic-auth","digest","framework","javalin","jwt","ktor","library","quarkus","restful-api","shiro","spring","spring-security","springboot"],"created_at":"2024-07-31T09:00:57.349Z","updated_at":"2025-05-14T12:13:14.215Z","avatar_url":"https://github.com/dromara.png","language":"Java","funding_links":["https://www.paypal.me/tomsun28","https://su.usthe.com/#/cn/sponsor"],"categories":["Java"],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/usthe/sureness\"\u003e\n    \u003cimg alt=\"sureness\" src=\"./docs/_media/brand128.svg\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n# \u003cfont size=\"14p\"\u003eDromara Sureness\u003c/font\u003e \u003cfont size=\"5p\"\u003e  | [中文文档](README_CN.md)\u003c/font\u003e\n\n\u003e A efficient security framework that focus on the protection of REST API.\n\n[![License](https://img.shields.io/badge/license-Apache%202-4EB1BA.svg)](https://www.apache.org/licenses/LICENSE-2.0.html)\n[![Maven](https://img.shields.io/badge/Maven%20Central-1.0.5-blue.svg)](https://search.maven.org/artifact/com.usthe.sureness/sureness-core)\n![GitHub pull request check contexts](https://img.shields.io/github/status/contexts/pulls/dromara/sureness/8?label=pull%20checks)\n[![Gitter](https://img.shields.io/gitter/room/usthe/sureness?label=sureness\u0026color=orange\u0026logo=gitter\u0026logoColor=red)](https://gitter.im/usthe/sureness)\n![GitHub Release Date](https://img.shields.io/github/release-date/dromara/sureness?color=blue\u0026logo=figshare\u0026logoColor=red)\n[![star](https://gitee.com/dromara/sureness/badge/star.svg?theme=gray)](https://gitee.com/dromara/sureness/stargazers)\n[![star](https://img.shields.io/github/stars/dromara/sureness?style=social)](https://github.com/dromara/sureness)\n\n**Home Page: [sureness.dromara.org](https://sureness.dromara.org)**\n\n**Code Hosting**\n\n|  \u003ca href=\"https://gitcode.com/dromara/sureness/overview\" target=\"_blank\"\u003e\u003cb\u003eGitCode\u003c/b\u003e\u003c/a\u003e        |  \u003ca href=\"https://gitee.com/dromara/sureness\" target=\"_blank\"\u003e\u003cb\u003eGitee\u003c/b\u003e\u003c/a\u003e  |\u003ca href=\"https://github.com/dromara/sureness\" target=\"_blank\"\u003e\u003cb\u003eGitHub\u003c/b\u003e\u003c/a\u003e  |\n\n\n## \u003cfont color=\"green\"\u003eIntroduction\u003c/font\u003e\n\n**Dromara Sureness** is a efficient open-source security framework that focus on the protection of REST API.  \n- Provide authentication and authorization, based on RBAC.   \n- No specific framework dependency (supports Javalin, Spring Boot, Quarkus, Ktor, Micronaut and more).    \n- Supports dynamic modification of permissions.   \n- Supports WebSockets and HTTP containers (Servlet and JAX-RS).    \n- Supports JWT, Basic Auth, Digest Auth, and can custom auth methods.    \n- High performance with Dictionary Matching Tree.      \n- Good extension interface, demos and documentation.\n\n#####  Why Is High Performance  \n\n![pathRoleMatcher](docs/_images/PathRoleMatcher.svg)  \n\n##### Framework Sample Support  \n\n- [x] Sureness integration **Spring Boot** sample(configuration file scheme) [sample-bootstrap](sample-bootstrap)   \n- [x] Sureness integration **Spring Boot** sample(database scheme) [sample-tom](sample-tom)  \n- [x] Sureness integration **Quarkus** sample [sample-quarkus](samples/quarkus-sureness)  \n- [x] Sureness integration **Javalin** sample [sample-javalin](samples/javalin-sureness)    \n- [x] Sureness integration **Ktor** sample [sample-ktor](samples/ktor-sureness)   \n- [x] Sureness integration **Spring Webflux** sample [sample-spring-webflux](samples/spring-webflux-sureness)\n- [x] Sureness integration **Micronaut** sample [sample-micronaut](samples/micronaut-sureness)\n- [x] Sureness integration **Jfinal** sample [sample-jfinal](samples/jfinal-sureness)\n- [x] Sureness integration **Solon** sample [sample-solon](samples/solon-sureness)\n- [x] Sureness integration **Spring Gateway** sample [sample-spring-gateway](samples/spring-gateway-sureness)  \n- [x] Sureness integration **Zuul** sample [sample-zuul](samples/zuul-sureness)    \n- [x] Sureness integration Session sample [sureness-session](samples/sureness-session)    \n- [x] Sureness integration Redis Session cache sample [sureness-redis-session](samples/sureness-redis-session)  \n- [x] More samples todo  \n\n##  Security Framework Compare \n##### Sureness VS Shiro VS Spring Security   \n\n| ~         | Sureness | Shiro | Spring Security |\n| ---       | ---      | ---   | --- |\n| **Multi Framework Support**  | support      | support need modify   | not support |\n| **REST API** | support | support need modify   | support |\n| **Websocket** | support | not support   | not support |\n| **Path Match**  | dictionary matching tree | ant match | ant match |\n| **Annotation Support**    | support      | support      | support |\n| **Servlet**    | support      | support      | support |\n| **JAX-RS**     | support      | not support    | not support |\n| **Dynamic Permissions** | support | support need modify | support need modify |\n| **Performance** | fast | slower | slower|\n| **Learning Curve** | simple | simple | steep|\n\n##### Benchmark  \n\n![benchmark](docs/_images/benchmark_en.png)  \n\n**Benchmark test shows Sureness to lose 0.026ms performance compared to frameless application, Shiro lose 0.088ms, Spring Security lose 0.116ms.**    \n**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.**      \n**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)       \n\n##  Quick Start \n\n####  \u003cfont color=\"red\"\u003eSome Conventions\u003c/font\u003e  \n\n- Based RBAC, User-Role-Resource.    \n- We treat API requests as a resource, resource format like `requestUri===httpMethod`.   \n  That is the request uri + request method(`post,get,put,delete...`) is considered as a resource as a whole.  \n  `eg: /api/v2/book===get`    \n- User belongs some Role -- Role owns Resource -- User can access the resource.  \n\nResource path matching see: [URI Match](docs/path-match.md)  \n\n####  Add Sureness In Your Project  \n\nWhen use maven or gradle build project, add coordinate  \n```\n\u003cdependency\u003e\n    \u003cgroupId\u003ecom.usthe.sureness\u003c/groupId\u003e\n    \u003cartifactId\u003esureness-core\u003c/artifactId\u003e\n    \u003cversion\u003e1.1.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n```\ncompile group: 'com.usthe.sureness', name: 'sureness-core', version: '1.1.0'\n```\n\n####  Use the Default Configuration to Configure Sureness  \n\nThe default configuration -`DefaultSurenessConfig` uses the document datasource `sureness.yml` as the auth datasource.  \nIt supports JWT auth, Basic auth, Digest authentication.  \n```\n@Bean\npublic DefaultSurenessConfig surenessConfig() {\n    return new DefaultSurenessConfig();\n}\n```\n\n####  Load Auth Config DataSource   \n\nSureness 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.   \nWe provide interfaces `SurenessAccountProvider`, `PathTreeProvider` for user implement to load data from the dataSource where they want.  \n\n- `SurenessAccountProvider` - Account datasource provider interface.    \n- `PathTreeProvider` - Resource uri-role datasource provider interface.     \n\nDefault Document DataSource Config - `sureness.yml`, see: [Default Document DataSource](docs/default-datasource.md)   \nAnnotation DataSource Config Detail - `AnnotationLoader`, see: [Annotation DataSource](docs/annotation-datasource.md)  \n\nIf 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)   \nIf 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)   \n\n\n####  Add an Interceptor Intercepting All Requests  \n\nThe essence of Sureness is to intercept all rest requests for authenticating and authorizing.        \nThe interceptor can be a filter or a Spring interceptor, it intercepts all request to check them.  \n```\nSubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest)\n```\n\n####  Implement Auth Exception Handling Process    \n\nSureness uses exception handling process:  \n\n- If auth success, method - `checkIn` will return a `SubjectSum` object containing user information.    \n- If auth failure, method - `checkIn` will throw different types of auth exceptions.   \n\nUsers need to continue the subsequent process based on these exceptions.(eg: return the request response)  \n\nHere we need to customize the exceptions thrown by `checkIn`, passed directly when auth success, catch exception when auth failure and do something:    \n\n```\ntry {\n    SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest);\n} catch (ProcessorNotFoundException | UnknownAccountException | UnsupportedSubjectException e4) {\n    // Create subject error related execption \n} catch (DisabledAccountException | ExcessiveAttemptsException e2 ) {\n    // Account disable related exception\n} catch (IncorrectCredentialsException | ExpiredCredentialsException e3) {\n    // Authentication failure related exception\n} catch (UnauthorizedException e5) {\n    // Authorization failure related exception\n} catch (SurenessAuthenticationException | SurenessAuthorizationException e) {\n    // other sureness exception\n}\n```\n\nDetail see: [Default Sureness Auth Exception](docs/default-exception.md)   \n\n**Have Fun**      \n\n##  Advanced Use\n\nSureness supports custom subject, custom subjectCreator, custom processor and more.  \n\nBefore advanced custom extension, let's first understand the general process of Sureness:  \n\n![flow](/docs/_images/flow-en.png)  \n\nAs in the above process, Subject is created by SubjectCreate according to the request body, and different authentication processors process the supported Subjects.  \n\nSureness provides the following common interfaces as extension points:  \n\n- `Subject`:  Authenticated authorized  user's account interface, provide the account's username,password, request resources, roles, etc.  \n- `SubjectCreate`: Create subject interface, provider create method.   \n- `Processor`:  Process subject interface, where happen authentication and authorization. \n- `PathTreeProvider`: Resource data provider, it can load data from txt or database,etc.\n- `SurenessAccountProvider`: Account data provider, it can load data from txt or database,etc.   \n\nRefer to [Extension Point](https://usthe.com/sureness/#/extend-point) for the extended documentation.   \n\n1.  **Custom Subject**\n\n`Implment Subject, add custom subject content`  \n`Implment SubjectCreate to create custom subject`  \n`Implment Processor to support custom subject`\n\nSee [Custom Subject](docs/custom-subject.md)  \n\n2. **Custom SubjectCreator**\n\n`Implment SubjectCreate to create your custom subject`   \n\nSee [Custom SubjectCreator](docs/custom-subject-creator.md)  \n\n3.  **Custom Processor**\n\n`A subject also can support by different processor, so we can custom processor to support custom subject`\n`Implment Processor, set which subject can support and implment processing details`\n\nSee [Custom Processor](docs/custom-processor.md)  \n\n4.  **Custom Datasource**  \n\n`Implment PathTreeProvider, load in DefaultPathRoleMatcher`   \n`Implment SurenessAccountProvide, load in processor`  \n\nSee [Custom Datasource](docs/custom-datasource.md)  \n\nDetail please refer to  [Sureness integration Spring Boot sample(database scheme)](sample-tom)   \n\n##  Contributing  \n\nVery welcome to Contribute this project, go further and better with Sureness. \n\nComponents of Repository:  \n- [Sureness's kernel code--Sureness-core](core)  \n- [Sureness integration Spring Boot sample(configuration file scheme)--sample-bootstrap](sample-bootstrap)  \n- [Sureness integration Spring Boot sample(database scheme)-sample-tom](sample-tom)  \n- [Sample projects using Sureness in each framework(Javalin,Ktor,Quarkus)--samples](samples)  \n\nSee [CONTRIBUTING](CONTRIBUTING.md)    \n\n\n\n## Friend's Links   \n\n* **```HertzBeat```** An open-source, real-time monitoring system with custom-monitor and agentLess: [Github](https://github.com/dromara/hertzbeat)   \n* **```JustAuth```** A Java library of third-party authorized login: [Github](https://github.com/justauth/JustAuth)    \n* **```MaxKey```** Leading-Edge Enterprise-Class open source IAM Identity and Access management product: [Github](https://github.com/dromara/MaxKey)   \n* **```PhalApi```** PHP Api Framework: [Website](https://www.phalapi.net/)    \n\n##  Join discussion    \n\nQQ Group: 390083213   \n[Github Discussion](https://github.com/dromara/sureness/discussions)          \n[Gitter Channel](https://gitter.im/dromara/sureness)   \n\n\u003cimg alt=\"tan-cloud\" src=\"https://cdn.jsdelivr.net/gh/dromara/hertzbeat/home/static/img/wechat.png\" width=\"400\"/\u003e       \n\n\u003cbr/\u003e\n\n\u003cimg alt=\"planet\" src=\"https://cdn.jsdelivr.net/gh/dromara/hertzbeat@gh-pages/img/planet.jpg\" width=\"400\"/\u003e    \n\n\n\n##  License  \n[`Apache License, Version 2.0`](https://www.apache.org/licenses/LICENSE-2.0.html)\n\n##  Thanks   \n\n[![JetBrains](home/static/img/jb_beam.svg)](https://www.jetbrains.com/community/opensource/#support)   \n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdromara%2Fsureness","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdromara%2Fsureness","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdromara%2Fsureness/lists"}