Модуль SSO

Приложение предусматривает два протокола OpenID и SAML для организации единого входа.

Со стороны приложения необходимо произвести следующие настройки в config.json:

В "modules" добавить новую секцию с названием модуля, который будет настроен, как модуль для SSO.

Примечание

Пример настроенного модуля с названием sso и значением "domain": "editboard.mycorp.com"

SAML

Пример и описание
{
  ...
    "modules": {
        "sso": {
            "module_type": "sso",
            "type": "saml",
            "entry_point": "https://adfs.mycorp.com/adfs/ls/",
            "issuer": "https://editboard.mycorp.com/sso/",
            "cert": "/conf/adfsmyadfsserver.cert",
            "callback_url": "https://editboard.mycorp.com/sso/callback",
            "field_id": "http://schemas.xmlsoap.org/claims/EmailAddress",
            "field_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",
            "exit_url": "https://editboard.mycorp.com",
            "whiteboard_api_partner": "sso",
            "whiteboard_api_key": "sso",
            "use_teams": true
        }
    },
    "recording": {
        ...
    }
}

Описание параметров модуля SSO (SAML)

Параметр Описание Тип данных
sso Название модуля. Произвольное значение (необязательно “sso”). Участвует в формировании URI Строка
module_type Задает тип модуля. Маркирует данную секцию как используемую для модуля SSO Строка
type Тип используемого протокола для SSO Строка
entry_point Адресом, по которому расположен сервис аутентификации Строка
issuer Уникальный идентификатор вашего сервиса SSO у провайдера. Это значение используется SSO провайдером для идентификации приложения, инициирующего запрос аутентификации Строка
cert Путь к сертификату безопасности, используемому для проверки подлинности сообщений SAML Строка
callback_url URL, на который SSO провайдер будет перенаправлять пользователя после успешной аутентификации, вместе с аутентификационным токеном или утверждениями Строка
field_id Указывает на поле в данных SAML Assertion, которое содержит уникальный идентификатор пользователя (в данном случае, адрес электронной почты) Строка
field_name Указывает на поле в данных SAML Assertion, содержащее имя пользователя. Это поле используется приложением для отображения имени или других данных пользователя Строка
exit_url URL, на который пользователь будет перенаправлен после выхода из системы или завершения сессии SSO Строка
whiteboard_api_partner Произвольное значение. Используется для разделения области видимости документов, если в системе используется несколько доменов Строка
whiteboard_api_key Произвольное значение. Ключ API для доступа к ресурсам определенного whiteboard_api_partner Строка
use_teams Определяет режим личного кабинета. Если true , то используется основная версия ЛК. Если false, то упрощенная Логический

OpenID

Пример и описание
{
  ...
    "modules": {
        "sso": {
            "module_type": "sso",
            "type": "auth2",
            "authorization_url": "https://oauth.server.ru/authorize",
            "token_url": "https://oauth.server.ru/token",
            "client_id": "e4eacca061db4c3487a1f75e********",
            "client_secret": "73bd19810cea4e169b2dee07********",
            "callback_url": "https://editboard.mycorp.com/sso/callback",
            "scope": "openid profile email",
            "info_url": "https://login.server.ru/info",
            "authorization_type": "Bearer",
            "field_id": "default_email",
            "field_name": "first_name",
            "whiteboard_api_partner": "OpenID_example_partner",
            "whiteboard_api_key": "OpenID_example_key",
            "exit_url": "https://editboard.mycorp.com/",
            "use_teams": true
        },
    },
    "recording": {
        ...
    }
}

Описание параметров модуля SSO (OpenID)

Параметр Описание Тип данных
sso Название модуля. Произвольное значение (необязательно “sso”). Участвует в формировании URI Строка
module_type Задает тип модуля. Маркирует данную секцию как используемую для модуля SSO Строка
type Тип используемого протокола для SSO Строка
authorization_url URL, на который необходимо перенаправить пользователя для начала процесса аутентификации через OAuth 2.0 Строка
token_url URL, используемый для обмена авторизационного кода на токен доступа. Этот токен затем используется для доступа к защищенным ресурсам пользователя Строка
client_id Уникальный идентификатор клиента, выданный OAuth-провайдером при регистрации приложения Строка
client_secret Секретный ключ, выданный вместе с client_id, необходимый для обеспечения безопасности при обмене данными между приложением и OAuth-сервером Строка
callback_url URL, на который SSO провайдер будет перенаправлять пользователя после успешной аутентификации, вместе с аутентификационным токеном или утверждениями Строка
scope Указывает область действия запрашиваемых разрешений. Значение null означает, что не указаны конкретные разрешения или используются значения по умолчанию. При необходимости может быть заполнено следующим образом "scope" : "openid profile email" Строка
info_url URL, по которому приложение может запросить данные о пользователе, используя полученный токен доступа. Это позволяет извлечь информацию о пользователе после аутентификации Строка
authorization_type Указывает на тип используемой аутентификации. Возможны значения Bearer, token, в зависимости от необходимости Строка
field_id Поле указывающие на идентификатор пользователя получаемый от OAuth-провайдера. Это значение используются для идентификации пользователя в приложении Строка
field_name Поле указывающие на имя пользователя получаемое от OAuth-провайдера. Это значение используются для представления пользователя в приложении Строка
exit_url URL, на который пользователь будет перенаправлен после выхода из системы или завершения сессии SSO Строка
whiteboard_api_partner Произвольное значение. Используется для разделения области видимости документов, если в системе используется несколько доменов Строка
whiteboard_api_key Произвольное значение. ключ API для доступа к ресурсам определенного whiteboard_api_partner Строка
use_teams Определяет режим личного кабинета. Если true , то используется основная версия ЛК. Если false, то упрощенная Логический

LDAPS

Пример и описание
{
  ...
    "modules": {
        "sso": {
        "module_type": "sso",
        "type": "ldap",
        "ldap": {
            "url": "ldap://111.11.111.11",
            "bindDN": "CN=user_example,CN=users,dc=mycorp,dc=com",
            "bindCredentials": "password_example",
            "searchBase": "dc=mycorp,dc=com",
            "searchFilter": "(samAccountName={{username}})",
            "tlsOptions": {
                "ca": [
                    "-----BEGIN CERTIFICATE-----
                    -----END CERTIFICATE-----"
                    ],
                "rejectUnauthorized": true
            }
        },
        "callback_url": "https://editboard.mycorp.com/sso/callback",
        "whiteboard_api_partner": "test",
        "whiteboard_api_key": "1234567890abcdefgh1234567890abcd",
        "field_id": "userPrincipalName",
        "field_name": "displayName",
        "admins": [
             "login1@example.com"
            ]
        },
    },
    "recording": {
        ...
    }
}

Описание параметров модуля SSO (LDAP)

Параметр Описание Тип данных
sso Название модуля. Произвольное значение (необязательно “sso”). Участвует в формировании URI Строка
module_type Задает тип модуля. Маркирует данную секцию как используемую для модуля SSO Строка
type Тип используемого протокола для SSO Строка
ldap Секция с настройками подключения к LDAP-серверу Объект
url URL LDAP-сервера, к которому будет производиться подключение Строка
bindDN DN учетной записи, с которой происходит подключение к LDAP для выполнения операций поиска Строка
bindCredentials Пароль для учетной записи, указанной в bindDN Строка
searchBase Базовая DN, с которой начинается поиск пользователей в иерархии LDAP Строка
searchFilter Фильтр поиска пользователей в LDAP Строка
tlsOptions Настройки для TLS Объект
ca Список доверенных сертификатов Certification Authority, которые используются для верификации сертификата сервера Массив(Строка)
rejectUnauthorized Отклонение соединения, если серверный сертификат не прошел проверку Логический
callback_url URL, на который SSO провайдер будет перенаправлять пользователя после успешной аутентификации, вместе с аутентификационным токеном или утверждениями Строка
whiteboard_api_partner Произвольное значение. Используется для разделения области видимости документов, если в системе используется несколько доменов Строка
whiteboard_api_key Произвольное значение. ключ API для доступа к ресурсам определенного whiteboard_api_partner Строка
field_id Атрибут LDAP, который используется в качестве идентификатора пользователя (email) Строка
field_name Атрибут LDAP, который используется в качестве имени пользователя Строка
admins Позволяет задать начальный список авторизованных администраторов (userPrincipalName) Массив(Строка)

Для версии приложения от 1.6.0 и выше, параметр use_teams не является обязательным

Дополнительные поля для модуля SSO

   "sso":{
        "module_type":"sso",
        .
        .
        .
        "db_users_only":true,
        "admins":[
            "login1@example.com","login2@example.com"
        ]
    }
Параметр Описание Тип данных
db_users_only Если параметр включен, то в кабинет могут попасть только те пользователи, что уже есть в базе данных. До версии 1.7.0 В базу данных добавлялись автоматически все пользователи прошедшие авторизацию Логический
admins Позволяет задать начальный список авторизованных администраторов Массив(Строка)

Работа с несколькими модулями SSO (версия 1.8.0 и выше)

В случае, если необходимо обеспечить несколько точек для аутентификации пользователей, можно добавить необходимое количество конфигураций SSO в раздел modules файла config.json.

В таком случае при переходе на ресурс приложения пользователям будет предоставлен выбор куда будет произведено перенаправление для аутентификации.

sso_select

Возможные ошибки при настройке

Проблемы связанные с ключами

8|whiteboard | /sso/callback SAML endpoint hit
8|whiteboard | Ошибка аутентификации: Error: Failed to read asymmetric key

или

8|whiteboard | /sso/callback SAML endpoint hit
8|whiteboard | Ошибка аутентификации: Error: Invalid signature

Свидетельствует о несовпадении ключей между сервером и приложением.
Если в метадате содержится несколько ключей, то необходимо проверить их все.

Проблемы связанные с токенами при использовании OpenID

editboard  | 0|whiteboard  | /sso/callback endpoint hit
editboard  | 0|whiteboard  | 2024-02-16 18:10:37)accessToken: {содержимое токена}
editboard  | 0|whiteboard  | Ошибка аутентификации: [AxiosError: Request failed with status code 401] {
editboard  | 0|whiteboard  |   code: 'ERR_BAD_REQUEST',

Может возникать в случаях, когда выбран неверный "authorization_type" в секции SSO. Тип использованный в токене и ожидаемый приложением должны иметь полное соответствие.

Проблемы связанные с SAML

Если при использовании модуля SSO браузер возвращает следующую ошибку:

{error: -1}

0|whiteboard  | /sso/callback SAML endpoint hit
0|whiteboard  | User authenticated {
0|whiteboard  | issuer: 'http://adfs.mycorp.com/adfs/services/trust',

В данном случае следует проверить правильность заполнения следующих полей:

"field_id": "http://schemas.xmlsoap.org/claims/EmailAddress",
"field_name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name",

Проблемы связанные с LDAP

При запуске в веб инсталлере проверка соединения (/sso/check) приводит к ошибке nginx 502 Bad Gateway на /sso.
Рекомендуется проверить error_log nginx на предмет ошибок вида upstream sent too big header while reading response header from upstream.
В случае наличия данной ошибки, убедитесь, что размеры буферов в nginx соответствуют потребностям выполняемых запросов.

proxy_buffer_size
proxy_buffers
proxy_busy_buffers_size
large_client_header_buffers

При необходимости увеличьте их.
Кроме этого можно сократить количество атрибутов, которые возвращаются в приложение. Например, не передавать thumbnailPhoto.

Предыдущая
Настройка Object Storage
Следующая
Настройка AD FS