Настройка 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 |
Статус активации группы параметров: |
Логический |
module_type |
Тип модуля. Маркирует данную секцию как используемую для модуля SSO |
Строка |
type |
Тип используемого протокола для SSO, в данном случае |
Строка |
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 |
Необязательный параметр. Определяет режим личного кабинета: |
Логический |
Параметр |
Описание |
Тип данных |
sso |
Название модуля. Произвольное значение (необязательно “sso”). Участвует в формировании URI |
Строка |
enabled |
Статус активации группы параметров: |
Логический |
module_type |
Задает тип модуля. Маркирует данную секцию как используемую для модуля SSO |
Строка |
type |
Тип используемого протокола для SSO, в данном случае |
Строка |
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 |
Указывает область действия запрашиваемых разрешений. Значение |
Строка |
authorization_type |
Указывает на тип используемой аутентификации. Возможны значения: |
Строка |
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 |
Необязательный параметр. Определяет режим личного кабинета: |
Логический |
Дополнительные поля
"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 в 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. Тип, использованный в токене и ожидаемый приложением, должны иметь полное соответствие.