Настройка OIDC-провайдера аутентификации

Конфигурация OIDC-провайдера

Чтобы настроить OIDC-провайдер (OpenID Connect), создайте конфигурацию с необходимыми параметрами для подключения к OIDC-серверу и маппинга пользовательских атрибутов.

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

  1. Пользователь выбирает OIDC-провайдер на странице входа.
  2. Система перенаправляет пользователя на страницу аутентификации OIDC-провайдера.
  3. После успешной аутентификации OIDC-провайдер перенаправляет пользователя обратно в систему с кодом авторизации. В endpoint {UI_APP_ENDPOINT}/auth/callback/oidc.
  4. Система обменивает код авторизации на токены доступа и ID-токен.
  5. Система запрашивает дополнительную информацию через userinfo endpoint.
  6. Система создает или обновляет пользователя в базе данных, назначает роли и группы на основе информации из userinfo.
  7. Система создает сессию для пользователя и перенаправляет его на главную страницу.

Основные параметры конфигурации

{
            slug: 'keycloak',                  // Уникальный идентификатор провайдера
            title: 'Keycloak',                 // Отображаемое название провайдера
            type: 'oidc',                      // Тип провайдера (должен быть 'oidc')
            defaultRole: 'datalens.visitor',   // Роль по умолчанию для новых пользователей
            config: {
                // Параметры подключения к OIDC-серверу
                issuer: 'https://keycloak.example.org/realms/datalens-enterprise/.well-known/openid-configuration',  // URL OIDC-сервера
                clientId: 'datalens',          // Идентификатор клиента
                clientSecret: 'password',      // Секрет клиента
                codeChallengeMethod: 'S256',   // Метод PKCE (Proof Key for Code Exchange)
                scope: ['openid', 'profile', 'email', 'roles', 'groups'],  // Запрашиваемые области доступа
                
                // Маппинг атрибутов пользователя (опционально)
                userAttributes: {
                    userId: 'sub',             // Атрибут для идентификатора пользователя (по умолчанию 'sub')
                    login: 'preferred_username', // Атрибут для логина пользователя (по умолчанию 'preferred_username')
                    email: 'email',            // Атрибут для адреса электронной почты пользователя (по умолчанию 'email')
                    firstName: 'given_name',   // Атрибут для имени пользователя (по умолчанию 'given_name')
                    lastName: 'family_name',   // Атрибут для фамилии пользователя (по умолчанию 'family_name')
                },
                
                // Настройка ролей (опционально)
                roles: {
                    path: 'resource_access.datalens.roles',  // Путь к ролям в userinfo
                    targetType: 'array-of-strings',          // Тип данных ролей
                    mapping: {
                        'datalens.admin': 'client.datalens.admin',     // Маппинг ролей
                        'datalens.creator': 'client.datalens.creator', // Маппинг ролей
                        'datalens.visitor': 'client.datalens.visitor', // Маппинг ролей
                    },
                },
                syncUserRoles: true,           // Синхронизировать роли пользователя при каждом входе
                
                // Настройка групп (опционально)
                groups: {
                    path: 'groups',            // Путь к группам в userinfo
                    targetType: 'array-of-objects',  // Тип данных групп
                    mapping: {                 // Маппинг атрибутов группы (только для 'array-of-objects')
                        groupId: 'id',         // Атрибут для идентификатора группы
                        title: 'name',         // Атрибут для названия группы
                    },
                },
                syncUserGroups: true,          // Синхронизировать группы пользователя при каждом входе
            }
        }

Детальное описание параметров

Основные параметры

  • slug — уникальный идентификатор провайдера, используется в URL и внутренних идентификаторах.
  • title — название провайдера, отображаемое в интерфейсе.
  • type — тип провайдера, для OIDC должно быть значение oidc.
  • defaultRole — роль, назначаемая пользователю, если не удалось определить роль из userinfo.

Параметры подключения к OIDC-серверу

  • issuer — URL OIDC-сервера, который предоставляет метаданные OpenID Connect. Обычно это URL с путем к .well-known/openid-configuration.
  • clientId — Идентификатор клиента, полученный при регистрации приложения в OIDC-провайдере.
  • clientSecret — Секрет клиента, полученный при регистрации приложения в OIDC-провайдере.
  • codeChallengeMethod — Метод PKCE (Proof Key for Code Exchange) для защиты от атак перехвата кода авторизации. По умолчанию S256. Если передать null, то авторизация будет выполняться с state и nonce без PKCE.
  • scope — Массив запрашиваемых областей доступа. По умолчанию: ['openid', 'profile', 'email'].

Маппинг атрибутов пользователя

Позволяет настроить соответствие между атрибутами пользователя OIDC и полями пользователя в системе:

  • userId — атрибут для идентификатора пользователя (по умолчанию sub).
  • login — атрибут для логина пользователя (по умолчанию preferred_username).
  • email — атрибут для адреса электронной почты пользователя (по умолчанию email).
  • firstName — атрибут для имени пользователя (по умолчанию given_name).
  • lastName — атрибут для фамилии пользователя (по умолчанию family_name).

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

Позволяет настроить получение и маппинг ролей пользователя из userinfo:

  • path — путь к ролям в userinfo. Например, resource_access.datalens.roles или realm_access.roles.

  • targetType — тип данных ролей. Возможные значения:

    • array-of-strings — массив строк.
    • stringified-array-of-strings — строка, содержащая сериализованный JSON-массив строк.

  • mapping — объект, сопоставляющий роли в системе с ролями в userinfo.

Настройка групп

Позволяет настроить получение и маппинг групп пользователя из userinfo:

  • path — путь к группам в userinfo. Например, groups.

  • targetType — тип данных групп. Возможные значения:

    • array-of-strings — массив строк, где каждая строка — идентификатор группы.
    • array-of-strings-with-id — массив строк, где каждая строка имеет формат id:title.
    • array-of-objects — массив объектов, содержащих идентификатор и название группы.
    • stringified-array-of-strings — строка, содержащая сериализованный JSON-массив строк.
    • stringified-array-of-strings-with-id — строка, содержащая сериализованный JSON-массив строк с форматом id:title.
    • stringified-array-of-objects — строка, содержащая сериализованный JSON-массив объектов.

  • mapping — объект, определяющий, какие поля объекта группы использовать для идентификатора и названия группы. Обязателен для типов array-of-objects и stringified-array-of-objects.

    • groupId — поле объекта группы, используемое как идентификатор.
    • title — поле объекта группы, используемое как название.

Дополнительные настройки

  • syncUserRoles — при значении true (по умолчанию) роли пользователя будут синхронизироваться при каждом входе.
  • syncUserGroups — при значении true (по умолчанию false) группы пользователя будут синхронизироваться при каждом входе.

Особенности синхронизации ролей и групп

Синхронизация групп и ролей пользователя происходит в момент входа пользователя в систему. Если в userinfo присутствуют роли или группы, указанные в конфигурации, они будут назначены пользователю. Если роли не найдены, пользователю будет назначена роль по умолчанию.

Пример конфигурации для Keycloak

const keycloakConfig = {
            slug: 'keycloak',
            title: 'Keycloak',
            type: 'oidc',
            defaultRole: 'datalens.visitor',
            config: {
                issuer: 'https://keycloak.example.org/realms/datalens-enterprise/.well-known/openid-configuration',
                clientId: 'datalens',
                clientSecret: 'password',
                codeChallengeMethod: 'S256',
                scope: ['openid', 'profile', 'email', 'roles', 'groups'],
                
                roles: {
                    path: 'resource_access.datalens.roles',
                    targetType: 'array-of-strings',
                    mapping: {
                        'datalens.admin': 'client.datalens.admin',
                        'datalens.creator': 'client.datalens.creator',
                    },
                },
                syncUserRoles: true,
                
                groups: {
                    path: 'groups',
                    targetType: 'array-of-strings', // Рекомендуем настроить Script Mapper и использовать array-of-objects для указания идентификатора и названия группы
                },
                syncUserGroups: true,
            },
        };

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

Для примера задайте конфигурацию клиента Keycloak:

  1. Укажите настройки клиента, для этого нажмите Clients → ваш клиент (datalens) → Settings:

    • Valid redirect URIs: {UI_APP_ENDPOINT}/auth/callback/oidc. Замените UI_APP_ENDPOINT на URL вашего приложения, например http://example.com:8080/auth/callback/oidc.

    • Client authentication — on.

    • Authentication flow — Standard flow.

  2. Чтобы создать роли, нажмите Clients → ваш клиент (datalens) → Roles:

    • client.datalens.admin
    • client.datalens.creator

  3. Чтобы создать группу, нажмите Groups → Create group.

  4. Чтобы назначить группу и роли пользователю, нажмите Users → пользователь:

    • Назначьте роли на вкладке Role mapping.
    • Назначьте группу на вкладке Groups.

  5. Чтобы настроить scope клиента, нажмите Client scopes → Create client scope:

    • Создайте scope groups и mapper type Group Membership. Включите Add to userinfo в настройках Keycloak.
    • Создайте scope roles или predefined mapper client roles. Включите Add to userinfo в настройках Keycloak.

Пример userinfo для Keycloak

{
          "sub": "4d2b6d80-49cf-44fb-94c6-946393dea8c7",
          "resource_access": {
            "datalens": {
              "roles": [
                "client.datalens.creator"
              ]
            },
          },
          "email_verified": true,
          "name": "Bob Smith",
          "groups": [
            "datalens-admin"
          ],
          "preferred_username": "bob",
          "given_name": "Bob",
          "family_name": "Smith",
          "email": "bob@example.org"
        }

Использование конфигурации

Настройка через переменную окружения AUTH_PROVIDERS_CONFIG

Для настройки провайдеров аутентификации в приложении используется переменная окружения AUTH_PROVIDERS_CONFIG. Эта переменная содержит JSON-строку с массивом конфигураций всех провайдеров аутентификации.

Пример значения переменной окружения AUTH_PROVIDERS_CONFIG:

[
          {
            "slug": "keycloak",
            "title": "Keycloak",
            "type": "oidc",
            "defaultRole": "datalens.visitor",
            "config": {
              "issuer": "https://keycloak.example.org/realms/datalens-enterprise/.well-known/openid-configuration",
              "clientId": "datalens",
              "clientSecret": "password",
              "codeChallengeMethod": "S256",
              "scope": ["openid", "profile", "email", "roles", "groups"],
              "roles": {
                "path": "resource_access.datalens.roles",
                "targetType": "array-of-strings",
                "mapping": {
                  "datalens.admin": "client.datalens.admin",
                  "datalens.creator": "client.datalens.creator"
                }
              },
              "syncUserRoles": true,
              "groups": {
                "path": "groups",
                "targetType": "array-of-strings"
              },
              "syncUserGroups": true
            }
          }
        ]
Предыдущая
Настройка LDAP-провайдера аутентификации
Следующая
Синхронизация с внешним IdP