Внешние системы авторизации

По умолчанию в модуле авторизации и аутентификации пользователей ORBISmap 3 используется авторизация с использованием внутренних пользователей. Внутренние пользователи хранятся в системной базе данных и имеют заданные учётные данные, которые используются при авторизации.

Данная статья рассматривает другой вариант работы с системой авторизации и аутентификации — конфигурация работы с использованием внешних провайдеров идентификации (IdP).

При входе через внешние сервисы программа перенаправляет пользователя на страницу входа внешнего сервиса, а после успешной проверки возвращает обратно с подтверждением учетной записи. В этом случае проверку логина и пароля выполняет внешний сервис, а приложение ORBISmap 3 создает свою собственную сессию и выдает пользователю токен для работы.

ORBISmap 3 поддерживает внешние провайдеры авторизации стандартов OpenID Connect (OIDC) и Единой системы идентификации и аутентификации (ЕСИА).

Настройки внешних систем идентификации задаются в конфигурационных файлах двумя вариантами — переменными окружения модуля авторизации и аутентификации и глобальным конфигурационным YAML-файлом.

OpenID Connect

OpenID Connect (OIDC) — это современный стандарт аутентификации, построенный поверх протокола OAuth 2.0. Он позволяет приложениям проверять личность пользователей на основе данных, полученных от доверенного провайдера идентификации (Identity Provider, IdP). В отличие от простой авторизации через OAuth, OIDC добавляет слой идентификации, предоставляя приложению защищенную информацию о пользователе в формате JWT-токенов.

Использование внешних провайдеров идентификации OIDC возможно в двух вариантах: ROP (Resource Owner Password) и Authorization Code Flow (перенаправление на страницу внешнего провайдера). Подробнее о вариантах взаимодействия можно прочитать в документации API модуля аутентификации.

Конфигурация OIDC-интеграции может размещается в глобальном YAML-файле приложения. Ниже приведен пример настройки интеграции с OIDC-провайдером через конфигурационный файл, а также назначение каждого параметра:

modules: # секция работы с конфигурациями модулей
  auth:  # секция модуля авторизации и аутентификации пользователей
    oidc:  # секция настройки внешних систем
      oidc-external-system:  # имя внешней системы, отображаемое в списке доступных систем при запросе конфигурации клиентом
        default_url: https://gis.local/admin
        default_role: postgres
        issuer: https://auth.example.com/realms/my-realm
        client_id: oms3-client-id
        client_secret: s3cr3t_k3y_v4lu3_f0r_0idc
        login_callback_url: https://app.example.com/auth/oidc/callback
        logout_callback_url: https://app.example.com/auth/oidc/logout
        scopes: openid profile email groups
        timeout: 30  # можно не задавать, имеет значение по умолчанию

Подробнее о назначении атрибутов:

default_url — URL по умолчанию для перенаправления после успешной аутентификации;
default_role — код роли, присваиваемой пользователю при отсутствии данных о привязанной;
issuer — URL эмитента (IdP), выдающего токены, должен точно совпадать с настройками провайдера;
client_id — идентификатор клиента, зарегистрированный в провайдере;
client_secret — секретный ключ клиента для аутентификации в провайдере;
login_callback_url — URL, на который провайдер перенаправит пользователя после входа;
logout_callback_url — URL для обработки выхода из системы;
scopes — список OIDC-областей, обязательно должен включать openid (области разделяются пробелом);
timeout — предельное время ожидания ответа от провайдера.

Для конфигурации с использованием переменных окружения модуля требуется задать переменную GIS_MOD_AUTH_OIDC в формате, который соответствует уровню oidc в yaml-файле конфигурации и представлен строкой с записанным в неё JSON объектом следующего вида:

{
    "oidc-external-system": {
        "default_url": "https://gis.local/admin",
        "default_role": "postgres",
        "issuer": "https://auth.example.com/realms/my-realm",
        "client_id": "oms3-client-id",
        "client_secret": "s3cr3t_k3y_v4lu3_f0r_0idc",
        "login_callback_url": "https://app.example.com/auth/oidc/callback",
        "logout_callback_url": "https://app.example.com/auth/oidc/logout",
        "scopes": "openid profile email groups",
        "timeout": 30
    }
}

Единая система идентификации и аутентификации

Примечание: Для работы интеграции с ЕСИА требуется соответствующий вариант установки модуля авторизации и аутентификации.

ЕСИА (Единая система идентификации и аутентификации) — государственная система аутентификации и авторизации, разработанная Министерством цифрового развития Российской Федерации. Она обеспечивает единый вход в информационные системы и сервисы органов власти, внебюджетных фондов и других организаций, оказывающих государственные услуги.

Использование внешнего провайдера идентификации ЕСИА возможно в варианте Authorization Code Flow (перенаправление на страницу внешнего провайдера).

Конфигурация ЕСИА-интеграции может размещается в глобальном YAML-файле приложения. Вот пример типичной структуры:

modules: # секция работы с конфигурациями модулей
  auth:  # секция модуля авторизации и аутентификации пользователей
    oidc:  # секция настройки внешних систем
      "ЕСИА":  # имя внешней системы, отображаемое в списке доступных систем при запросе конфигурации клиентом
        default_url: https://gis.local/admin
        default_role: postgres
        client_id: oms3-client-id
        client_secret: s3cr3t_k3y_v4lu3_f0r_0idc
        login_callback_url: https://app.example.com/auth/oidc/callback
        logout_callback_url: https://app.example.com/auth/oidc/logout
        service_url: https://esia.gosuslugi.ru/
        scopes: openid profile email groups
        crypto_cn: "CN=MyPortal,O=Federal Service,C=RU"
        crypto_pin: ""
        only_trusted: true
        crypto_path: "/etc/ssl/esia/certs/"
        timeout: 30  # имеет значение по умолчанию — 30

Подробнее о назначении атрибутов, не совпадающих с OIDC-провайдерами:

service_url — базовый URL сервиса ЕСИА;
crypto_cn — Common Name (CN) сертификата для подписания запросов;
crypto_pin — PIN-код для доступа к закрытому ключу;
only_trusted — флаг, отвечающий за принятие только запросов с валидной подписью от ЕСИА;
crypto_path — путь к файлам сертификата.

Для конфигурации с использованием переменных окружения модуля требуется задать переменную GIS_MOD_AUTH_OIDC в формате словаря, который соответствует уровню oidc в yaml-файле конфигурации и представлен строкой с записанным в неё JSON объектом конфигурации внешних систем. При подключении нескольких систем внешней авторизации в переменую окружения следует передать конфигурации внешних систем под заданными ключами, соответствующими их именам.

Пример настройки нескольких систем внешней авторизации через переменную окружения:

{
    "oidc-external-system": {
        "default_url": "https://gis.local/admin",
        "default_role": "postgres",
        "issuer": "https://auth.example.com/realms/my-realm",
        "client_id": "oms3-client-id",
        "client_secret": "s3cr3t_k3y_v4lu3_f0r_0idc",
        "login_callback_url": "https://app.example.com/auth/oidc/callback",
        "logout_callback_url": "https://app.example.com/auth/oidc/logout",
        "scopes": "openid profile email groups",
        "timeout": 30
    },
    "ЕСИА": {
        "default_url": "https://gis.local/admin",
        "default_role": "postgres",
        "client_id": "oms3-client-id",
        "client_secret": "s3cr3t_k3y_v4lu3_f0r_0idc",
        "login_callback_url": "https://app.example.com/auth/oidc/callback",
        "logout_callback_url": "https://app.example.com/auth/oidc/logout",
        "service_url": "https://esia.gosuslugi.ru/",
        "scopes": "openid profile email groups",
        "crypto_cn": "CN=MyPortal,O=Federal Service,C=RU",
        "crypto_pin": "",
        "only_trusted": true,
        "crypto_path": "/etc/ssl/esia/certs/",
        "timeout": 30
    }
}

Для того, чтобы модуль авторизации мог работать с ЕСИА, необходимо положить дистрибутив КриптоПро под именем linux-amd64_deb.tgz в папку модуля auth/cryptopro, а также папку с сертификатами с именем certs в папку модуля auth/extern.

Также в конфигурацию в поле gis_mod_auth_cryptopro_license необходимо ввести лицензионный ключ КриптоПро. Модуль поддерживает работу КриптоПро как 4 версии, так и 5.

Для конфигурации установки КриптоПро в модуле требуется указать следующие переменные окружения:

GIS_MOD_AUTH_CRYPTO_PATH - путь для установки КриптоПро;
GIS_MOD_AUTH_CRYPTOPRO_LICENSE - лицензионный ключ КриптоПро;
GIS_MOD_AUTH_CRYPTO_PIN - PIN-код для доступа к закрытому ключу.

Чтобы Nginx позволял совершать запросы с подписанными электронной подписью данными в ЕСИА, необходимо увеличить размер буфера, поскольку они имеют объём, превышающий стандартный. Далее представлен пример настройки размера буфера в конфигурационном файле Nginx:

/* Настройки проксирования запросов к модулю аутентификации и авторизации */
location ~ ^{{http_root}}api/v\d+/auth {
  resolver 127.0.0.11 valid=5s;
  set $service auth;

  /* Конфигурация размера буфера */
  proxy_buffer_size 128k;
  proxy_buffers 8 128k;
  proxy_busy_buffers_size 256k;
  /* Конец конфигурации размера буфера */

  rewrite ^{{http_root}}api/v(\d+)/auth/(users|auth|tokens)(/?)(.*) /v$1/$2$3$4 break;
  proxy_pass http://$service;
}