Интеграция Spring Security OAuth2

Этот раздел перенесён из документации Camunda 7 и в дальнейшем будет доработан с учётом особенностей OpenBPM Engine

OpenBPM Engine предоставляет интеграцию Spring Security OAuth2 через библиотеку openbpm-engine-bpm-spring-boot-starter-security. Эта библиотека содержит зависимости Spring Security и Spring Security OAuth2, а также классы конфигурации, которые интегрируют Spring Security с аутентификацией веб‑приложений OpenBPM Engine.

Это доступно как для Spring Boot, так и для OpenBPM Engine Run.

Интеграция OpenBPM Engine включает несколько компонентов и конфигураций. В следующих разделах вы найдете подробности по каждому из них.

Активировать OAuth2

Spring Boot

Чтобы включить интеграцию Spring Security OAuth2 в Spring Boot, добавьте следующую зависимость в проект:

<dependency>
  <groupId>io.openbpm.bpm.springboot</groupId>
  <artifactId>openbpm-engine-bpm-spring-boot-starter-security</artifactId>
</dependency>

OpenBPM Engine Run

OpenBPM Engine Run уже содержит необходимые библиотеки, все, что нужно сделать — активировать их. Чтобы включить интеграцию Spring Security OAuth2 в OpenBPM Engine Run, запустите Run с дополнительным аргументом --oauth2:

./start.sh --webapps --rest --oauth2

Авто‑конфигурация

Интеграция OpenBPM Engine имеет две конфигурации авто‑настройки по умолчанию. В зависимости от регистрации OAuth2‑клиента в свойствах приложения (spring.security.oauth2.client.registration) будет активирована либо OperatonSpringSecurityOAuth2AutoConfiguration, либо OperatonBpmSpringSecurityDisableAutoConfiguration.

Конфигурация с включенным OAuth2

Конфигурация активируется, если настроена регистрация OAuth2‑клиента. Этот класс настраивает цепочку фильтров Spring Security для защиты веб‑приложений Camunda.

Класс авто‑конфигурации Spring: OperatonSpringSecurityOAuth2AutoConfiguration

Авто‑конфигурация с отключенной Spring Security

Конфигурация активируется, если нет настроенной регистрации OAuth2‑клиента. Этот класс настраивает цепочку фильтров Spring Security в режим разрешения всего (permit all).

Класс авто‑конфигурации Spring: OperatonBpmSpringSecurityDisableAutoConfiguration

Регистрация OAuth2‑клиента

Для регистрации клиента обратитесь к официальной документации Spring Security OAuth2 Core Configuration, чтобы настроить выбранного вами провайдера идентификации.

После настройки регистрации OAuth2‑клиента и включения интеграции Camunda Spring Security OAuth2 веб‑приложения будут использовать настроенного OAuth2‑провайдера для аутентификации.

Сопоставление имени пользователя

Интеграция Camunda использует поле name объекта principal из Spring Security как User ID в веб‑приложениях.

Spring Security по умолчанию использует claim subject (sub) как имя principal. Так как User ID в Camunda — важная часть авторизаций, важно, чтобы использовался правильный claim.

Spring Security предоставляет способ изменить атрибут по умолчанию, используемый для имени пользователя. Это свойство spring.security.oauth2.client.provider.[providerId].user-name-attribute из упомянутой выше OAuth2 Core Configuration.

Убедитесь, что корректно настроили, какой атрибут токена должен использоваться как User ID.

Настройка базовой авторизации

Для создания базовой авторизации в вашем приложении доступны следующие варианты:

Свойство openbpm.bpm.admin-user для создания пользователя‑администратора:
```
   openbpm.bpm:
     admin-user:
       id: demo
       password: demo
       firstName: Demo
       lastName: Demo
```
См. документацию OpenBPM Engine Properties для подробностей.
Administrator Authorization Plugin для выдачи админских прав конкретному OAuth2‑пользователю или группе.

OAuth2 Identity Provider

В дополнение к OAuth2‑логину OpenBPM Engine также поддерживает использование групп из OAuth2. Это достигается с помощью пользовательского сервиса идентификации, называемого OAuth2IdentityProvider.

Это провайдер идентификации только для чтения, который настраивает группы пользователя на основе выданных полномочий Spring Security. Этот провайдер идентификации также поддерживает стандартный OpenBPM Engine Database Identity Service в качестве резервного варианта для аутентификаций REST API.

Провайдер идентификации активирован по умолчанию. Вы можете переопределить это следующими свойствами:

openbpm.bpm.oauth2:
  identity-provider:
    enabled: false

См. раздел Configuration для дополнительной информации.

Mapper выданных полномочий

Мы также предоставляем mapper выданных полномочий по умолчанию, который может переопределить полномочия Spring Security, которые по умолчанию заполняются из claim scope (scp).

Этот mapper можно включить с помощью свойства group-name-attribute:

openbpm.bpm.oauth2:
  identity-provider:
    enabled: true
    group-name-attribute: cognito:groups

Mapper активируется только если свойство настроено. Он поддерживает claims типов коллекции String и String. Если claim — это String, он попытается разделить его по разделителю, которым по умолчанию является запятая. Вы можете переопределить разделитель по умолчанию через свойство group-name-delimiter.

См. раздел Configuration для дополнительной информации.

Пользовательский Granted Authorities Mapper

Как альтернативу вы также можете определить свой собственный GrantedAuthoritiesMapper, если нужна более тонкая настройка.

В Spring Boot это можно сделать, зарегистрировав собственный бин GrantedAuthoritiesMapper.

В Camunda Run нужно собрать JAR‑файл и скопировать его в папку userlib. Он должен содержать Spring auto configuration с бином кастомного granted authorities mapper.

Конфигурация

Все свойства конфигурации провайдера идентификации начинаются с префикса openbpm.bpm.oauth2.identity-provider. Доступны следующие свойства:

Имя свойства	Описание	Значение по умолчанию
enabled	Включает OAuth2 identity provider. Включен по умолчанию!	true
group-name-attribute	Включает и настраивает OAuth2 Granted Authorities Mapper.	-
group-name-delimiter	Настраивает разделитель, используемый в OAuth2 Granted Authorities Mapper. Используется только если настроенный group-name-attribute содержит значение типа String.	, (запятая)

Имя свойства

Описание

Значение по умолчанию

enabled

Включает OAuth2 identity provider. Включен по умолчанию!

true

group-name-attribute

Включает и настраивает OAuth2 Granted Authorities Mapper.

group-name-delimiter

Настраивает разделитель, используемый в OAuth2 Granted Authorities Mapper. Используется только если настроенный group-name-attribute содержит значение типа String.

, (запятая)

Ограничения

Как упоминалось ранее, этот провайдер является провайдером только для чтения, поэтому создание пользователей, групп или членств недоступно. Из‑за резервного использования DB Identity Service этот провайдер все еще определяется как writeable, что означает, что кнопки создания по‑прежнему видны на страницах Admin, но не работают.

OAuth2 не возвращает информацию о других пользователях или группах. Это означает, что пользователи и даже администраторы могут видеть на страницах Admin только своего пользователя и свои группы.

Кроме того, он показывает только группы из OAuth2 и не показывает группы, настроенные в базе данных OpenBPM Engine.

Отключение Identity Provider

С помощью упомянутого выше свойства Identity Provider можно деактивировать. Без провайдера идентификации OAuth2 используется только для аутентификации. Это означает, что пользователь также должен быть настроен с соответствующим User ID в базе данных OpenBPM Engine.

Если пользователь недоступен или у него недостаточно прав, он не сможет получить доступ к Webapps.

Выход

Мы также обеспечиваем поддержку локального выхода и client‑initiated SSO logout. Чтобы поддержать оба варианта выхода, интеграция OpenBPM Engine также содержит Frontend‑плагин, который переопределяет поведение выхода по умолчанию в Webapps. В результате, когда пользователь Webapp нажимает «выход», вызывается endpoint Spring /logout, а не endpoint OpenBPM Engine.

Client‑Initiated SSO Logout

Мы поддерживаем client‑initiated OIDC SSO logout. См. раздел Spring OpenID Connect 1.0 Client‑Initiated Logout для подробностей.

Чтобы настроить эту функцию, используйте следующие свойства:

openbpm.bpm.oauth2:
  sso-logout:
    enabled: true
    postLogoutRedirectUri: https://camunda.com/

Конфигурация

Все свойства конфигурации провайдера идентификации начинаются с префикса openbpm.bpm.oauth2.sso-logout. Доступны следующие свойства:

Имя свойства	Описание	Значение по умолчанию
enabled	Активирует функцию client‑initiated OIDC logout.	false
post-logout-redirect-uri	Настраивает URI, на который пользователь перенаправляется после SSO logout у провайдера.	{baseUrl}

Имя свойства

Описание

Значение по умолчанию

enabled

Активирует функцию client‑initiated OIDC logout.

false

post-logout-redirect-uri

Настраивает URI, на который пользователь перенаправляется после SSO logout у провайдера.

{baseUrl}

Ограничения

В настоящее время невозможно изменить endpoint выхода Spring по умолчанию, которым является /logout.

Логирование

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

logging:
  level:
    io.openbpm.bpm.spring.boot.starter.security.oauth2: DEBUG

Пример

В этом разделе мы приводим пример конфигурации с OKTA в качестве OIDC‑провайдера. Также мы отмечаем и поясняем несколько строк:

openbpm.bpm.oauth2:
 sso-logout: # 1
   enabled: true
   postLogoutRedirectUri: https://camunda.com/
 identity-provider:
   group-name-attribute: okta-groups # 2

spring.security: # 3
 oauth2:
   client:
     registration:
       okta:
         clientId: <clientId>
         clientSecret: <clientSecret>
         scope: openid,profile,email,offline_access # 4
     provider:
       okta:
         issuerUri: <issuerUri>
         user-name-attribute: preferred_username # 5

Активирован client‑initiated SSO, переопределен redirect uri.
Группы провайдера идентификации загружаются из пользовательского claim okta-groups.
- Это также нужно настроить на стороне провайдера, чтобы id token содержал этот claim.
Используются традиционные свойства Spring Security.
- Альтернативно можно использовать библиотеку okta-spring-security-oauth2 и ее свойства.
Определяет scopes openid,profile,email,offline_access.
- Scopes зависят от провайдера. Обычно требуется openid.
- В случае OKTA profile и email полезны для доступа к имени, фамилии и email в Camunda, но не обязательны.
- offline_access активирует grant refresh_token, не обязательно.
Настраивает preferred_username как атрибут имени пользователя, который также используется как Camunda User ID.

Отключение авто‑конфигурации

Если вы хотите использовать Spring Security, но без интеграционных классов Camunda, вы можете сделать это, исключив две авто‑конфигурации:

Либо с аннотацией @EnableAutoConfiguration:

@EnableAutoConfiguration(exclude={
    OperatonSpringSecurityOAuth2AutoConfiguration.class,
    OperatonBpmSpringSecurityDisableAutoConfiguration.class
});

Или в свойствах приложения:

spring:
  autoconfigure:
    exclude:
      - io.openbpm.bpm.spring.boot.starter.security.oauth2.OperatonSpringSecurityOAuth2AutoConfiguration
      - io.openbpm.bpm.spring.boot.starter.security.oauth2.OperatonBpmSpringSecurityDisableAutoConfiguration

Для дополнительной информации см. документацию Spring Disabling Specific Auto-configuration Classes.

Лицензия и атрибуция

Эта документация была создана на базе материала "Camunda 7 Docs" от Camunda, находится под лицензией Creative Commons Attribution-ShareAlike 3.0 Unported License .

Оригинал документации: https://docs.camunda.org

Интеграция Spring Security OAuth2

Активировать OAuth2

Spring Boot

OpenBPM Engine Run

Авто‑конфигурация

Конфигурация с включенным OAuth2

Авто‑конфигурация с отключенной Spring Security

Регистрация OAuth2‑клиента

Сопоставление имени пользователя

Настройка базовой авторизации

OAuth2 Identity Provider

Mapper выданных полномочий

Пользовательский Granted Authorities Mapper

Конфигурация

Ограничения

Отключение Identity Provider

Выход

Client‑Initiated SSO Logout

Конфигурация

Ограничения

Рекомендации по безопасности

Время жизни токена

Логирование

Пример

Отключение авто‑конфигурации

Лицензия и атрибуция