Dromara Sureness | Documentation in English

Высокопроизводительный фреймворк аутентификации и авторизации для REST API

Официальный сайт: sureness.dromara.org

Репозиторий кода

| GitCode | Gitee |GitHub |

Описание

Dromara Sureness — это новый фреймворк аутентификации и авторизации, который предоставляет высокопроизводительный и гибкий способ управления доступом к REST API. Он позволяет динамически менять права доступа, использовать различные стратегии аутентификации и обеспечивает быстрое выполнение запросов.- Поддержка аутентификации и авторизации для REST API, основанной на модели RBAC (пользователи-роли-ресурсы), с акцентом на безопасность API.

• Независимость от конкретного веб-фреймворка (уже есть примеры интеграции с Spring Boot, Quarkus, Javalin, Ktor, Micronaut, JFinal, Solon и другими).
• Возможность динамического изменения конфигураций прав доступа для каждого API.
• Поддержка протокола WebSocket, основных контейнеров HTTP (Servlet и JAX-RS).
• Поддержка различных стратегий аутентификации, таких как JWT, Basic Auth, Digest Auth, а также возможность расширения для создания собственных методов аутентификации.
• Высокие производственные характеристики благодаря улучшенной структуре дерева словарей.
• Открытый API для расширения, примеры использования и подробная документация помогают быстро понять и внедрить расширения.

Высокопроизводительная система соответствия

Примеры поддерживаемых фреймворков- [x] Пример интеграции Sureness с Spring Boot (конфигурационный файловый подход) sample-bootstrap

• Пример интеграции Sureness с Spring Boot (подход с использованием базы данных) sample-tom
• Пример интеграции Sureness с Quarkus sample-quarkus
• Пример интеграции Sureness с Javalin sample-javalin
• Пример интеграции Sureness с Ktor sample-ktor
• Пример интеграции Sureness с Spring WebFlux sample-spring-webflux
• Пример интеграции Sureness с Micronaut sample-micronaut
• Пример интеграции Sureness с JFinal sample-jfinal
• Пример интеграции Sureness с Solon sample-solon
• Пример интеграции Sureness с Spring Gateway sample-spring-gateway
• Пример интеграции Sureness с Zuul sample-zuul
• Пример использования Session в Sureness sureness-session
• Пример распределённого кэширования Session в Sureness sureness-redis-session
• Больше примеров в процессе подготовки## Сравнение систем аутентификации

Sureness VS Shiro VS Spring Security

Базовая тестовая проверка производительности

Базовая проверка показывает, что Sureness при сравнении с системами без управления правами доступа теряет всего 0,026 мс производительности, тогда как Shiro теряет 0,088 мс, а Spring Security — 0,116 мс. В сравнении с этим Sureness демонстрирует производительность, которая в три раза выше, чем у Shiro, и в четыре раза выше, чем у Spring Security (по TPS). Разница в производительности будет увеличиваться с увеличением количества цепочек запросов, подробнее см. базовую проверку## Быстрый старт#### Перед началом некоторых соглашений

• Sureness основан на RBAC, то есть пользователи-роли-ресурсы: пользователь принадлежит роли — роль имеет доступ к ресурсу (API) — пользователь может получить доступ к ресурсу (API)
• Мы рассматриваем запросы REST API как ресурс, формат которого выглядит так: requestUri===httpMethod То есть путь запроса вместе с методом запроса (post, get, put, delete...) рассматриваются как единый ресурс для назначения прав доступа например: /api/v2/book===get запрос типа get к интерфейсу /api/v2/book

Дополнительно о пути ресурса см. URI пути совпадения

Включение Sureness в проект

Проект использует сборку через maven или gradle. Добавьте координаты:

<dependency>
    <groupId>com.usthe.sureness</groupId>
    <artifactId>sureness-core</artifactId>
    <version>1.1.0</version>
</dependency>

implementation 'com.usthe.sureness:sureness-core:1.1.0'

Настройка Sureness с использованием конфигурации по умолчанию

Конфигурация по умолчанию использует файловый источник данных sureness.yml как источник данных учетных записей и прав доступа По умолчанию поддерживаются аутентификационные механизмы JWT, Basic auth, Digest auth

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

Настройка источника данных учетных записей и ролейДля аутентификации и авторизации Sureness также требуются наши данные учетных записей, ролей и других сведений. Эти данные могут быть получены из текстовых файлов, баз данных, нереляционных баз данных или аннотаций.Мы предоставляем интерфейсы источников данных: SurenessAccountProvider, PathTreeProvider, которые можно реализовать для создания собственного источника данных.

• PathTreeProvider: интерфейс источника данных ресурсов, который позволяет загружать данные из баз данных, текстовых файлов и т.д., загружая их в соответствующий проверяющий ресурс DefaultPathRoleMatcher.
• SurenessAccountProvider: интерфейс источника данных учетных записей, который позволяет загружать данные из баз данных, текстовых файлов и т.д., загружая их в процессоры, требующие учетных данных.

При использовании конфигурации по умолчанию DefaultSurenessConfig используются текстовый и аннотационный источники данных.

• Текстовый источник данных использует конфигурацию sureness.yml, подробнее см. документацию текстовый источник данных по умолчанию
• Аннотационный источник данных использует аннотации @RequiresRoles, @WithoutAuth, подробнее см. документацию аннотационный источник данных

Мы предоставили примеры кодовой реализации:

Для конкретной реализации по умолчанию используйте Пример интеграции Spring Boot Sureness (конфигурационный файловый подход) -- sample-bootstrap.

Если данные правил доступа берутся из базы данных, обратитесь к Пример интеграции Spring Boot Sureness (подход с использованием базы данных) -- sample-tom.### Добавление фильтров для перехвата всех запросов

Основная идея Sureness заключается в перехвате всех запросов API для проверки аутентификации и авторизации.

При входе можно использовать фильтры или интерцепторы Spring. В фильтре следует добавить безопасность Sureness, как показано ниже:

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

Реализация процесса обработки ошибок при аутентификации и авторизации

Sureness использует следующий процесс обработки ошибок:

1. Если аутентификация и авторизация успешны, метод checkIn вернёт объект SubjectSum со всеми данными пользователя.
2. Если аутентификация или авторизация провалились, метод checkIn выбросит различные типы исключений, требуя от пользователя продолжить выполнение последующих шагов (ответить соответствующими ответами).

Здесь требуется обрабатывать выбрасываемые исключения методом checkIn. Успешная аутентификация пропускается, а проваленная аутентификация выбрасывает специальное исключение для дальнейшей обработки, как показано ниже:```java try { SubjectSum subject = SurenessSecurityManager.getInstance().checkIn(servletRequest); } catch (ProcessorNotFoundException | UnknownAccountException | UnsupportedSubjectException e4) { // Exceptions related to account creation } catch (DisabledAccountException | ExcessiveAttemptsException e2) { // Exceptions related to disabled account } catch (IncorrectCredentialsException | ExpiredCredentialsException e3) { // Exceptions related to failed authentication } catch (UnauthorizedException e5) { // Exceptions related to failed authorization } catch (SurenessAuthenticationException | SurenessAuthorizationException e) { // Other user exceptions }

**НАСЛАЖДАЙТЕСЬ!**

> Если этот [быстрый старт] вам кажется сложным, вы можете воспользоваться этим [шаг за шагом руководством], которое подробно объясняет все этапы создания проекта с полной функциональностью аутентификации и авторизации с помощью Sureness.

## Расширенные возможности

`Sureness` поддерживает пользовательскую настройку `subject`, регистрацию пользовательского `subjectCreator`, а также использование пользовательских `processors`. Перед созданием продвинутых пользовательских расширений стоит ознакомиться с основной логикой Sureness:

![flow](docs/_images/flow-cn.png)

Как показано на приведенной выше схеме, объект `Subject` создается на основе запроса при помощи `SubjectCreate`, а различные модули проверки (`Processors`) выполняют проверку доступа для каждого типа объекта `Subject`.

Sureness предоставляет следующие часто используемые интерфейсы в качестве точек расширения:- `Subject`: Интерфейс объекта проверки, предоставляющий информацию о ключах аккаунта, запрашиваемых ресурсах, роли пользователя и т.д.
- `SubjectCreate`: Интерфейс создания объекта Subject, который позволяет создавать различные типы объектов Subject на основе входящих данных запроса.
- `Processor`: Интерфейс процессора, который выполняет проверку доступа на основе информации, содержащейся в объекте Subject.
- `PathTreeProvider`: Интерфейс источника данных для ресурсов, позволяющий загружать данные из базы данных, текстовых файлов и т.д.
- `SurenessAccountProvider`: Интерфейс источника данных для аккаунтов, позволяющий загружать данные ключей аккаунта из базы данных, текстовых файлов и т.д.Дополнительная информация о расширении доступна по ссылке [расширенные точки](docs/cn/extend-point.md).

1. **Пользовательский объект Subject**

Реализуйте интерфейс `Subject`, чтобы добавить пользовательский контент в объект Subject.
Реализуйте методы интерфейса `SubjectCreate`, чтобы создать пользовательский creator объекта Subject.
Реализуйте интерфейс `BaseProcessor`, чтобы добавить пользовательский processor, поддерживающий обработку пользовательского объекта Subject.
Подробнее см. [пользовательский объект Subject](docs/cn/custom-subject.md).

2. **Пользовательский creator объекта Subject**

Реализуйте методы интерфейса `SubjectCreate`, чтобы создавать объект Subject на основе входящего запроса.
Подробнее см. [пользовательский creator объекта Subject](docs/cn/custom-subject-creator.md).

3. **Пользовательский Processor**

Реализуйте интерфейс `BaseProcessor`, чтобы указать поддерживаемый объект Subject и реализовать логику проверки доступа для этого объекта.
Подробнее см. [пользовательский Processor](docs/cn/custom-processor.md).

4. **Пользовательский источник данных**

Реализуйте интерфейс `PathTreeProvider`, чтобы загружать данные в соответствующий matcher прав доступа `DefaultPathRoleMatcher`.
Реализуйте интерфейс `SurenessAccountProvider`, чтобы загружать данные ключей аккаунта в нужный processor.
Подробнее см. [пользовательский источник данных](docs/cn/custom-datasource.md).

Подробные примеры расширения можно найти в разделе [Sureness интегрированный с Spring Boot (схема с использованием базы данных)](sample-sureness-integration-with-spring-boot).## Участие в проекте

Мы рады видеть новых участников проекта, стремящихся сделать нашу общую работу лучше!

Компоненты репозитория:

- [Основной код Sureness -- sureness-core](core)
- [Пример использования Sureness для интеграции с Spring Boot (схема конфигурационных файлов)](sample-bootstrap)
- [Пример использования Sureness для интеграции с Spring Boot (схема с использованием базы данных)](sample-tom)
- [Примеры использования Sureness в различных фреймворках (Javalin, Ktor, Quarkus)](samples) См. [CONTRIBUTING](CONTRIBUTING.md)

## Дополнительно

Статьи:
[Проектирование прав доступа в REST API — часть 1](https://segmentfault.com/a/1190000038360856)
[Проектирование прав доступа в REST API — быстрое создание проекта с использованием конфигурационных файлов](https://segmentfault.com/a/1190000039075245)
[Проектирование прав доступа в REST API — пример интеграции Spring Boot с использованием базы данных](https://segmentfault.com/a/1190000039191172)

<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"/>

Группа QQ: 390083213  
[Github Discussion](https://github.com/dromara/sureness/discussions)  
[Gitter Channel](https://gitter.im/dromara/sureness)

## О Recommended Open Source Projects* **```HertzBeat```** Лёгкий и удобный системный мониторинг реального времени, который не требует агента и имеет мощные возможности настройки мониторинга: [Github](https://github.com/dromara/hertzbeat)
* **```JustAuth```** Маленькая, но полная и красивая открытая библиотека для работы с авторизацией третьих сторон: [Gitee](https://gitee.com/yadong.zhang/JustAuth)
* **```MaxKey```** Ведущий отраслевой продукт для управления и проверки идентификации, который является открытым источником IAM: [Gitee](https://gitee.com/dromara/MaxKey)
* **```PhalApi```** Лёгковесный PHP-фреймворк для создания API: [Официальный сайт](https://www.phalapi.net/)## Лицензия  
[`Apache License, Version 2.0`](https://www.apache.org/licenses/LICENSE-2.0.html)

## Благодарность

[![JetBrains](home/static/img/jb_beam.svg)](https://www.jetbrains.com/community/opensource/#поддержка)