Настройка 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