Настройка SSO

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

Модуль SSO в values.yaml

Пример настройки полей modules.sso в файле values.yaml из установочного пакета Helm:

sso:
    enabled: true
    module_type: "sso"
    type: "saml"
    entry_point: "https://<ДОМЕН_СЕРВЕРА_AD_FS>/adfs/ls"
    issuer: "https://<ВАШ_ДОМЕН>/sso/"
    cert: "adfs/cert.crt"
    callback_url: "https://<ВАШ_ДОМЕН>/sso/callback" 
    field_id: "nameID"
    field_name: "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
    exit_url: "https://<ВАШ_ДОМЕН>"
    whiteboard_api_partner: "sso"
    whiteboard_api_key: "sso"
    x509:
        create_secret: true
        certificate: |
            -----BEGIN CERTIFICATE-----
            MII***==
            -----END CERTIFICATE-----
    admins:
        - "admin@domain.ru"
sso:
    enabled: true
    module_type: "sso"
    type: "auth2"
    callback_url: "https://<ВАШ_ДОМЕН>/sso/callback"
    authorization_url: "https://<ДОМЕН_СЕРВЕРА_KEYCLOAK>/realms/[realm_ID]/protocol/openid-connect/auth"
    token_url: "https://<ДОМЕН_СЕРВЕРА_KEYCLOAK>/realms/[realm_ID]/protocol/openid-connect/token"
    info_url: "https://<ДОМЕН_СЕРВЕРА_KEYCLOAK>/realms/[realm_ID]/protocol/openid-connect/userinfo"
    scope: "openid profile email"
    authorization_type: "Bearer"
    field_id: "email"
    field_name: "name"
    client_id: "[client_id]"
    client_secret: "[client_secret]"
    whiteboard_api_partner: "kc"
    whiteboard_api_key: "kc_key"
    admins:
        - "admin@domain.ru" 

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

Параметр

Описание

Тип данных

sso

Название модуля. Произвольное значение (необязательно “sso”). Участвует в формировании URI

Строка

enabled

Статус активации группы параметров: true — включено; false — выключено

Логический

module_type

Тип модуля. Маркирует данную секцию как используемую для модуля SSO

Строка

type

Тип используемого протокола для SSO, в данном случае saml

Строка

entry_point

Адрес, по которому расположен сервис аутентификации, например AD FS

Строка

issuer

Уникальный идентификатор вашего сервиса 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 для доступа к ресурсам определенного apiPartner

Строка

x509.create_secret

Признак того, что для аутентификации используется сертификат в формате X.509

Логический

x509.certificate

Данные сертификата X.509

Строка

admins

Адреса администраторов вашей организации, которые получат доступ к администрированию Досок

Массив

use_teams

Необязательный параметр. Определяет режим личного кабинета: true — основная версия ЛК; false — упрощенная версия

Логический

Параметр

Описание

Тип данных

sso

Название модуля. Произвольное значение (необязательно “sso”). Участвует в формировании URI

Строка

enabled

Статус активации группы параметров: true — включено; false — выключено

Логический

module_type

Задает тип модуля. Маркирует данную секцию как используемую для модуля SSO

Строка

type

Тип используемого протокола для SSO, в данном случае auth2

Строка

callback_url

URL, на который SSO-провайдер перенаправит пользователя после успешной аутентификации. Вместо <ВАШ_ДОМЕН> укажите адрес вашего домена

Строка

authorization_url

URL, на который необходимо перенаправить пользователя для начала процесса аутентификации через OAuth 2.0. Подставьте в это поле значение authorization_endpoint, которое вы сохранили на шаге 1.4 при получении параметров SSO из Keycloak

Строка

token_url

URL, который используется для обмена авторизационного кода на токен, обеспечивающий доступ к защищенным ресурсам пользователя. Подставьте в это поле значение token_endpoint, которое вы сохранили на шаге 1.4 при получении параметров SSO из Keycloak

Строка

info_url

URL, по которому приложение может запросить данные о пользователе, используя полученный токен доступа. Это позволяет извлечь информацию о пользователе после аутентификации/ Подставьте в это поле значение userinfo_endpoint, которое вы сохранили на шаге 1.4 при получении параметров SSO из Keycloak

Строка

scope

Указывает область действия запрашиваемых разрешений. Значение null означает, что конкретные разрешения не указаны или используются значения по умолчанию. При работе с openid для корректной работы приложения заполняется следующим образом "scope" : "openid profile email"

Строка

authorization_type

Указывает на тип используемой аутентификации. Возможны значения: Bearer, token

Строка

field_id

Наименование поля, которое содержит идентификатор пользователя, получаемый от OAuth-провайдера. Это значение используется для идентификации пользователя в приложении

Строка

field_name

Наименование поля, которое содержит имя пользователя, получаемое от OAuth-провайдера. Это значение используется для представления пользователя в приложении

Строка

client_id

Уникальный идентификатор клиента, выданный OAuth-провайдером при регистрации приложения. Укажите значение Client ID, которое вы ввели на шаге 2.2 при конфигурировании Keycloak

Строка

client_secret

Секретный ключ, выданный вместе с client_id, необходимый для обеспечения безопасности при обмене данными между приложением и OAuth-сервером. Укажите значение Client Secret, которое вы сохранили на шаге 2.2 при получении параметров SSO из Keycloak

Строка

whiteboard_api_partner

Произвольное значение. Используется для разделения области видимости документов, если в системе используется несколько доменов

Строка

whiteboard_api_key

Произвольное значение. Ключ API для доступа к ресурсам определенного whiteboard_api_partner

Строка

admins

Адреса администраторов вашей организации, которые получат доступ к администрированию Досок

Массив

use_teams

Необязательный параметр. Определяет режим личного кабинета: true — основная версия ЛК, false — упрощенная версия

Логический

Дополнительные поля

   "sso":{
        "module_type":"sso",
        .
        .
        .
        "db_users_only":true,
        "admins":[
            "login1@example.com","login2@example.com"
        ]
    }

Параметр

Описание

Тип данных

db_users_only

Если параметр включен, то в кабинет могут попасть только те пользователи, что уже есть в базе данных. До версии 1.7.0 В базу данных добавлялись автоматически все пользователи прошедшие авторизацию

Логический

admins

Позволяет задать начальный список авторизованных администраторов

Массив(Строка)

Работа с несколькими модулями

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

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

sso_select

Модуль SSO в configmap-config.yaml

Помимо описания параметров SSO в файле values.yaml необходимо переопределить параметры SSO в файле, который используется для создания ConfigMap в Kubernetes. Откройте файл configmap-config.yaml и замените код, содержащий параметры SSO, на блок следующего содержания:

"sso": {
    "module_type": "{{ .Values.modules.sso.module_type }}",
    "type": "{{ .Values.modules.sso.type }}",
    "entry_point": "{{ .Values.modules.sso.entry_point }}",
    "issuer": "{{ .Values.modules.sso.issuer }}",
    "cert": "{{ .Values.modules.sso.cert }}",
    "callback_url": "{{ .Values.modules.sso.callback_url }}",
    "field_id": "{{ .Values.modules.sso.field_id }}",
    "field_name": "{{ .Values.modules.sso.field_name }}",
    "exit_url": "{{ .Values.modules.sso.exit_url }}",
    "whiteboard_api_partner": "{{ .Values.modules.sso.api_partner }}",
    "whiteboard_api_key": "{{ .Values.modules.sso.api_key }}"
},
"sso": {
    "module_type": "{{ .Values.modules.sso.module_type }}",
    "type": "{{ .Values.modules.sso.type }}",
    "callback_url": "{{ .Values.modules.sso.callback_url }}",
    "authorization_url": "{{ .Values.modules.sso.authorization_url }}",
    "token_url": "{{ .Values.modules.sso.token_url }}",
    "info_url": "{{ .Values.modules.sso.info_url }}",
    "scope": "{{ .Values.modules.sso.scope }}",
    "authorization_type": "{{ .Values.modules.sso.authorization_type }}",
    "field_id": "{{ .Values.modules.sso.field_id }}",
    "field_name": "{{ .Values.modules.sso.field_name }}",
    "client_id": "{{ .Values.modules.sso.client_id }}",
    "client_secret": "{{ .Values.modules.sso.client_secret }}",
    "whiteboard_api_partner": "{{ .Values.modules.sso.whiteboard_api_partner }}",
    "whiteboard_api_key": "{{ .Values.modules.sso.whiteboard_api_key }}",
    "admins":{{ .Values.modules.sso.admins | toJson }}
},

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

Несовпадение ключей

Ошибки вида:

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

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

Другие ошибки протоколов

Если при использовании модуля 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",

Ошибка, связанная с токеном:

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. Тип, использованный в токене и ожидаемый приложением, должны иметь полное соответствие.