Single Sign-On (SSO)

OpenBPM Control поддерживает механизм Single Sign-On (SSO), позволяющий пользователям входить в систему с использованием внешнего поставщика аутентификации по протоколу OpenID Connect (OIDC). SSO обеспечивает централизованное управление пользователями и ролями, а также возможность единого входа для всех приложений в инфраструктуре организации.

В качестве примера настройки SSO ниже приведена интеграция с системой управления идентификацией Keycloak.

Настройка OpenBPM Control

Включение режима SSO

Чтобы заменить стандартную форму входа на авторизацию через SSO, необходимо включить использование OIDC и установить параметр Login Mode в значение oidc:

# Включаем поддержку OIDC
jmix.oidc.use-default-configuration=true

# Переключаем режим логина
openbpm.control.security.login-mode=oidc

Настройка клиента OIDC

Далее требуется настроить клиент для подключения к вашему поставщику SSO. Конфигурация выполняется стандартными средствами Spring Security через файл application.properties:

# Keycloak OIDC configuration
spring.security.oauth2.client.registration.keycloak.client-id=<client-id>
spring.security.oauth2.client.registration.keycloak.client-secret=<client_secret>
spring.security.oauth2.client.registration.keycloak.scope=openid, profile, roles

spring.security.oauth2.client.provider.keycloak.issuer-uri=http://localhost:8180/realms/<realm>
spring.security.oauth2.client.provider.keycloak.user-name-attribute=preferred_username

spring.security.oauth2.resourceserver.jwt.issuer-uri=http://localhost:8180/realms/<realm>

jmix.oidc.jwt-authentication-converter.username-claim=preferred_username

jmix.oidc.default-claims-roles-mapper.roles-claim-name=roles

Примечания:

  • keycloak — это идентификатор провайдера (можно заменить, например, на okta).

  • Параметры client-id и client-secret выдаются вашим поставщиком OpenID.

  • issuer-uri указывает на OpenID Configuration Endpoint, например: http://localhost:8180/realms/openbpm/.well-known/openid-configuration.

  • По умолчанию для имени пользователя используется claim sub. Чтобы изменить его, используйте:

    spring.security.oauth2.client.provider.keycloak.user-name-attribute=preferred_username

В OpenBPM Control настройка OIDC реализована с помощью Jmix дополнения OIDC Add-on. Более подробную информацию о конфигурации вы можете прочитать в официальной документации.

Настройка контейнера (Docker)

Если OpenBPM Control разворачивается в контейнере, параметры OIDC можно задать через переменные окружения в файле docker-compose.yml:

services:
  openbpm-control-app:
    image: registry.gitflic.ru/project/openbpm/openbpm-control-community/openbpm-control-community:latest
    container_name: openbpm-control-app
    restart: "no"
    environment:
      MAIN_DATASOURCE_URL: "jdbc:postgresql://openbpm-control-database/openbpm-control"
      MAIN_DATASOURCE_USERNAME: "root"
      MAIN_DATASOURCE_PASSWORD: "root"
      SERVER_PORT: "8081"
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_KEYCLOAK_CLIENTID: "<client-id>"
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_KEYCLOAK_CLIENTSECRET: "<client-secret>"
      SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_KEYCLOAK_ISSUERURI: "http://localhost:8180/realms/<realm>"
      SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUERURI: "http://localhost:8180/realms/<realm>"
      SPRING_SECURITY_OAUTH2_CLIENT_PROVIDER_KEYCLOAK_USERNAMEATTRIBUTE: "preferred_username"
      SPRING_SECURITY_OAUTH2_CLIENT_REGISTRATION_KEYCLOAK_SCOPE: "openid, profile, roles"
      JMIX_OIDC_JWTAUTHENTICATIONCONVERTER_USERNAMECLAIM: "preferred_username"
      JMIX_OIDC_DEFAULTCLAIMSROLESMAPPER_ROLESCLAIMNAME: "roles"
      JMIX_OIDC_USEDEFAULTCONFIGURATION: "true"
      OPENBPM_CONTROL_SECURITY_LOGINMODE: "oidc"
    ports:
      - "8081:8081"
    depends_on:
      openbpm-control-database:
        condition: service_started
    networks:
      - openbpm-control-net

  openbpm-control-database:
    image: postgres:16.3
    container_name: openbpm-control-database
    restart: "no"
    environment:
      POSTGRES_DB: "openbpm-control"
      POSTGRES_USER: "root"
      POSTGRES_PASSWORD: "root"
    volumes:
      - openbpm-control-database_data:/var/lib/postgresql/data
    networks:
      - openbpm-control-net

volumes:
  openbpm-control-database_data:

networks:
  openbpm-control-net:
    driver: bridge

Настройка локального экземпляра Keycloak

Один из самых популярных поставщиков OpenID - Keycloak. Для ознакомления с дополнением Jmix OIDC вы можете запустить Keycloak локально с помощью Docker.

Запуск Keycloak с использованием Docker

Используйте следующую команду для запуска экземпляра Keycloak с помощью Docker на порту 8180:

docker run -p 8180:8080 \
    -e KEYCLOAK_ADMIN=admin \
    -e KEYCLOAK_ADMIN_PASSWORD=admin \
    --name keycloak \
    quay.io/keycloak/keycloak:22.0 start-dev

См. документацию Keycloak для получения дополнительной информации.

URL Keycloak: http://localhost:8180

Административные учетные данные:

Имя пользователя: admin
Пароль: admin

Вы можете прочитать о настройке экземпляра Keycloak в Руководстве администратора сервера.

Настройка Keycloak для OpenBPM Control

Создание Realm

Войдите в консоль администратора Keycloak и выполните следующие шаги:

  1. В левой панели нажмите Add Realm.

    create realm 1

  2. Введите имя области, например openbpm.

  3. Нажмите Create.

    create realm 2

Создание клиента

Клиент представляет приложение OpenBPM Control, которое будет использовать Keycloak для аутентификации.

  1. Перейдите в раздел Clients и нажмите Create.

  2. Укажите параметры:

    Параметр Значение

    Client ID

    openbpm-control

    Client Protocol

    openid-connect
    create client 1

  3. В разделе Capability config:

    Параметр Значение

    Client authentication

    ON
    create client 2

  4. В разделе Login Settings установите:

    Параметр Значение

    Valid Redirect URIs

    * (только для разработки)

    Valid post logout redirect URIs

    * (только для разработки)

    Web Origins

    * (только для разработки)
    create client 3

    После сохранения клиента перейдите на вкладку Credentials и скопируйте Client Secret. Этот секрет будет использоваться в настройках OpenBPM Control.

    client credentials

Создание ролей

Роли в Keycloak должны совпадать с кодами ролей, используемыми в Jmix/OpenBPM Control.

  1. Перейдите в раздел Realm roles → Add Role.

  2. Укажите имя роли, например system-full-access.

  3. Сохраните изменения.

    create role

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

  1. Перейдите в раздел Users → Add User.

  2. Укажите имя пользователя, например johndoe.

  3. Сохраните.

    create user

    После сохранения:

    • На вкладке Credentials задайте пароль пользователю.

    • На вкладке Role Mappings назначьте роль system-full-access.

      create user credentials
      assign role

Настройка маппера ролей

Чтобы роли передавались в ID Token, создайте маппер:

  1. Перейдите в раздел Client scopes → roles → Mappers → realm roles.

  2. Нажмите Create и заполните поля:

    Поле Значение

    Mapper Type

    User Realm Role

    Token Claim Name

    realm roles

    Claim JSON Type

    String

    Add to ID token

    ON

    Add to access token

    ON

    Add to userinfo

    ON
    create mapper 1
    create mapper 2

Проверка аутентификации

После успешной настройки Keycloak и OpenBPM Control, стандартная форма логина будем заменена на форму логина от Keycloak:

keycloak login