SAML

Содержание

SAML#

Интеграция по протоколу SAML 2.0 позволяет использовать внешнего поставщика удостоверений (Identity Provider, IdP) для входа пользователей в Astra Automation. В Astra Automation аутентификация пользователей централизована и выполняется через шлюз (Platform Gateway), который выступает единой точкой входа в платформу. Все остальные компоненты используют результаты аутентификации, выполненной через шлюз. Настройку SSO необходимо выполнять через графическую консоль после установки платформы.

Пример описывает настройку единого входа в Astra Automation через Keycloak с использованием метода аутентификации SAML. В этом сценарии Keycloak выступает поставщиком удостоверений и проверяет учетные данные пользователя, а шлюз играет роль поставщика услуг (Service Provider, SP) и получает подписанное SAML-утверждение (assertion) с атрибутами пользователя для создания сессии и применения настроек сопоставления.

Пользователь выбирает вход через SAML на странице входа Astra Automation, после чего шлюз формирует запрос аутентификации (AuthnRequest) и перенаправляет пользователя к поставщику удостоверений. Keycloak запрашивает учетные данные пользователя и после успешной аутентификации возвращает браузер пользователя с ответом SAMLResponse на URL сервиса потребления утверждений (Assertion Consumer Service, ACS) шлюза. Шлюз проверяет подпись ответа, расшифровывает утверждение, извлекает атрибуты пользователя, сопоставляет или создает учетную запись и создает пользовательскую сессию.

На схеме показан общий порядок взаимодействия между пользователем, Astra Automation и поставщиком удостоверений.

@startuml
title AA user authentication with SAML
actor User as U
participant "AA (Platform Gateway)" as G
participant "IdP (SAML)" as I
U -> G: Open AA URL
G --> U: Return login page\n(with SAML sign-in button)
U -> G: Click SAML sign-in button
G --> U: HTTP 302 redirect to IdP SSO URL\nwith AuthnRequest, RelayState
U -> I: Follow redirect\nwith AuthnRequest
I --> U: Prompt for credentials
U -> I: Submit credentials
I --> U: Return auto-submit form\nwith SAMLResponse, RelayState
U -> G: HTTP POST SAMLResponse\nto ACS URL
G -> G: Validate response signature,\ndecrypt assertion,\nmap or create user
G --> U: Set AA session cookie\nand redirect to dashboard
U -> G: Subsequent requests\nwith AA session
G -> G: Authorize actions\nbased on RBAC
G --> U: Return HTML page / UI data
@enduml

Примечание

Инструкция протестирована с Keycloak версии 26.5.1. В других версиях Keycloak отдельные параметры и поведение интерфейса (в частности, настройки SAML-подписи и шифрования) могут отличаться.

Предварительные требования#

Перед настройкой убедитесь, что выполнены следующие условия:

Развернута и доступна платформа Astra Automation.
Развернут и доступен сервис Keycloak. Инструкции по развертыванию см. в официальной документации.
Имеется доступ к учетной записи администратора Keycloak.
Определен realm Keycloak, используемый для аутентификации пользователей Astra Automation.
Platform Gateway доступен пользователям по FQDN или IP-адресу.
Подготовлены публичный сертификат (saml-encryption.crt) и приватный ключ (saml-encryption.key) шифрования для SAML-аутентификации. Ключ должен быть незашифрованным ключом RSA в контейнере PKCS#8 или PKCS#1; полные требования и команды генерации и проверки см. в описании метода аутентификации SAML.
Подготовлены публичный сертификат (saml-signing.crt) и приватный ключ (saml-signing.key) для подписи запросов поставщика услуг. Эта пара используется, только если в клиенте Keycloak включена проверка подписи клиента (атрибут saml.client.signature); в конфигурации клиента из данного примера проверка отключена.

Для производственной среды рекомендуется использовать FQDN, HTTPS и доверенный сертификат TLS. Для тестового стенда допустимо использовать IP-адрес и самоподписанный сертификат, если это соответствует требованиям среды.

Получение метаданных поставщика удостоверений#

Keycloak публикует SAML-метаданные (дескриптор) каждого realm по адресу:

https://<keycloak_fqdn>/realms/<realm_name>/protocol/saml/descriptor

Чтобы получить метаданные, откройте URL в браузере или выполните запрос с помощью curl, например:

curl -s https://keycloak.example.com/realms/master/protocol/saml/descriptor

Используйте значения из метаданных для заполнения полей метода аутентификации SAML в Astra Automation:

Поле Astra Automation	Параметр метаданных	Пример для Keycloak
Идентификатор объекта (Entity ID)	`entityID` элемента `EntityDescriptor` – URL realm	`https://keycloak.example.com/realms/master`
URL входа поставщика удостоверений (IdP Login URL)	`Location` элемента `SingleSignOnService` – URL сервиса SSO	`https://keycloak.example.com/realms/master/protocol/saml`
Публичный сертификат поставщика удостоверений (IdP Public Cert)	содержимое элемента `X509Certificate` ключа подписи (`use="signing"`)	сертификат подписи realm (см. Получение сертификата подписи realm)

Получение сертификата подписи realm#

При настройке метода аутентификации SAML в поле Публичный сертификат поставщика удостоверений (IdP Public Cert) вносится сертификат подписи realm Keycloak, с помощью которого шлюз проверяет подпись ответов поставщика удостоверений. Получить этот сертификат можно одним из двух способов:

в графической консоли Keycloak перейдите в Realm Settings ‣ Keys, в строке активного ключа подписи (использование SIG, алгоритм RS256) нажмите кнопку Certificate и скопируйте содержимое;
в SAML-метаданных realm найдите элемент KeyDescriptor с атрибутом use="signing" и скопируйте содержимое вложенного элемента X509Certificate.

Примечание

По умолчанию realm содержит два ключа RSA: ключ подписи (использование SIG, алгоритм RS256) и ключ шифрования (использование ENC, алгоритм RSA-OAEP). Для поля Публичный сертификат поставщика удостоверений (IdP Public Cert) необходим именно ключ подписи.

Скопированное значение представляет собой содержимое сертификата без маркеров, закодированное в формате Base64. Перед вставкой в поле Публичный сертификат поставщика удостоверений (IdP Public Cert) значение необходимо дополнить маркерами начала и конца:

-----BEGIN CERTIFICATE-----
<содержимое сертификата>
-----END CERTIFICATE-----

Значение без маркеров платформа отклоняет с ошибкой Unable to load as PEM data ... MalformedFraming.

Настройка Keycloak#

Для подготовки сервиса Keycloak к использованию выполните следующие действия:

Авторизуйтесь в графической консоли Keycloak с привилегиями администратора.
Выберите realm, в рамках которого будет выполняться аутентификация пользователей.
Настройте client scope для передачи ролей пользователей:
1. Перейдите в меню Client scopes.
2. Откройте client scope role_list.
3. Перейдите на вкладку Mappers.
4. Откройте mapper role list.
5. Включите параметр Single Role Attribute.
6. Сохраните изменения.
Убедитесь, что в Keycloak присутствуют учетные записи пользователей, используемые для аутентификации.

Примечание

В корпоративной инфраструктуре учетные записи пользователей, как правило, поступают в Keycloak из внешнего источника идентификации (LDAP/Active Directory).

При необходимости для тестирования SSO можно создать учетную запись вручную:
1. Перейдите в Users ‣ Create user.
2. Заполните информацию о создаваемом пользователе:
  - Username – название учетной записи пользователя;
  - Email – электронная почта пользователя;
  - Email verified – переведите переключатель в состояние Yes, чтобы отметить адрес электронной почты как подтвержденный;
  - First name – имя пользователя;
  - Last name – фамилия пользователя.
3. Нажмите кнопку Create.
4. Добавьте пароль для учетной записи пользователя:
  1. Перейдите в Users ‣ <New_user> ‣ Credentials ‣ Set password.
  2. Введите пароль и подтвердите его.
  3. Переведите переключатель Temporary в состояние Off.
  4. Сохраните изменения.
Загрузите и откройте в текстовом редакторе файл keycloak_gateway_client.json на своей рабочей станции.
Введите соответствующие данные вместо временных заменителей.

Здесь:
- <gateway_fqdn> – доменное имя шлюза;
- <saml_signing_certificate> – публичный сертификат подписи поставщика услуг SAML, значение которого должно соответствовать содержимому файла saml-signing.crt;
- <saml_signing_private_key> – приватный ключ подписи поставщика услуг SAML, значение которого должно соответствовать содержимому файла saml-signing.key;
- <saml_encryption_certificate> – публичный сертификат шифрования поставщика услуг SAML, значение которого должно соответствовать содержимому файла saml-encryption.crt;
- <saml_encryption_private_key> – приватный ключ шифрования поставщика услуг SAML, значение которого должно соответствовать содержимому файла saml-encryption.key.
Сохраните изменения.
Импортируйте измененный файл в Keycloak:
1. В графической консоли перейдите в Clients ‣ Import client.
2. В поле Resource file нажмите кнопку Browse….
3. Выберите измененный файл keycloak_gateway_client.json.
4. Нажмите кнопку Save.
В меню Clients откройте настройки импортированного клиента.

Примечание

Импортированный клиент отображается в списке клиентов под идентификатором (Client ID), совпадающим с URL шлюза, например, https://<gateway_fqdn>/.
Убедитесь, что в поле Encryption algorithm выбрано значение AES_256_CBC, а в поле Key transport algorithm – значение RSA1_5.

Эти значения уже заданы в импортируемом файле атрибутами saml.encryption.algorithm и saml.encryption.keyAlgorithm; при создании клиента вручную их необходимо выбрать в перечисленных полях.

Примечание

Алгоритм RSA1_5 требуется текущей реализацией поставщика услуг SAML в Astra Automation. Варианты RSA-OAEP не поддерживаются: шлюз не сможет расшифровать утверждение, и вход завершится ошибкой failed to decrypt.

Настройка шлюза#

Для настройки SSO в Astra Automation выполните следующие действия:

Войдите в графическую консоль Astra Automation с правами администратора.
На панели навигации выберите Управление доступом ‣ Методы аутентификации (Access Management ‣ Authentication Methods).
В окне Методы аутентификации (Authentication Methods) нажмите кнопку Создать метод аутентификации (Create authentication).
В открывшемся окне выберите тип метода аутентификации SAML в поле Тип аутентификации (Authentication type) и нажмите кнопку Далее (Next).
Задайте следующие параметры:
- Название (Name) – название метода аутентификации, например, keycloak-saml. Значение этого поля определяет подпись кнопки входа через SSO на странице входа Astra Automation.
- Идентификатор поставщика услуг SAML (SP) (SAML Service Provider Entity ID) – URL шлюза, например, https://<gateway_fqdn>/. Значение должно точно совпадать с идентификатором (Client ID) импортированного клиента Keycloak, включая завершающую косую черту.
- Публичный сертификат поставщика услуг SAML (SAML Service Provider Public Certificate) – содержимое файла saml-encryption.crt.
- Публичный сертификат поставщика удостоверений (IdP Public Cert) – сертификат подписи realm Keycloak, дополненный маркерами начала и конца (см. Получение сертификата подписи realm).
- URL входа поставщика удостоверений (IdP Login URL) – URL сервиса SSO в Keycloak, например, https://<keycloak_fqdn>/realms/master/protocol/saml.
- Идентификатор объекта (Entity ID) – URL нужного realm Keycloak, например, https://<keycloak_fqdn>/realms/master.
- Атрибуты пользователя – имена SAML-атрибутов утверждения, из которых Astra Automation получает данные пользователя. Значения должны соответствовать именам атрибутов, настроенным в mappers клиента Keycloak. Mappers импортированного клиента можно проверить на вкладке Client scopes клиента в выделенном client scope с суффиксом -dedicated. Дополнительные атрибуты можно передавать и через отдельный client scope с произвольным названием: создайте client scope с протоколом SAML, добавьте в него mappers и привяжите его к клиенту на вкладке Client scopes кнопкой Add client scope:
  - Электронная почта пользователя (User Email) – email;
  - Имя пользователя (Username) – username;
  - Фамилия пользователя (User Last Name) – last_name;
  - Имя пользователя (User First Name) – first_name;
  - Постоянный ID пользователя (User Permanent ID) – email.
  Примечание
  
  Поля Имя пользователя (Username) и Имя пользователя (User First Name) отображаются в графической консоли с одинаковой русской подписью и различаются только английскими подписями в скобках.
  
  Предупреждение
  
  Значение email в поле Постоянный ID пользователя (User Permanent ID) – имя SAML-атрибута, содержащего адрес электронной почты пользователя. Адрес электронной почты не является стабильным идентификатором: при смене адреса платформа создаст отдельную учетную запись, а при миграции на другой метод аутентификации может создать дублирующуюся учетную запись вместо повторного использования существующей. При наличии в утверждении стабильного уникального атрибута, например идентификатора пользователя из LDAP или внутреннего идентификатора пользователя Keycloak, рекомендуется указать его имя вместо email. Настройка передачи внутреннего идентификатора Keycloak и порядок перехода на OIDC приведены в разделе Миграция с SAML на OIDC.
- URL сервиса потребления утверждений SAML (ACS) (SAML Assertion Consumer Service (ACS) URL) – при первичном сохранении оставьте поле пустым. После сохранения платформа автоматически сгенерирует ACS URL в следующем формате:
```
<FRONT_END_URL>/api/gateway/social/complete/<slug>/
```
  Здесь:
  - <FRONT_END_URL> – внешний URL шлюза из настроек платформы;
  - <slug> – случайный идентификатор, который платформа генерирует при создании метода аутентификации. Предугадать значение заранее нельзя, поэтому сгенерированный ACS URL необходимо скопировать после сохранения метода аутентификации.
- Закрытый ключ поставщика услуг SAML (SAML Service Provider Private Key) – содержимое файла saml-encryption.key.
- Информация об организации поставщика услуг SAML (SAML Service Provider Organization Info).
  
  Пример заполнения:
```
{
   "en-US": {
         "url": "https://example.com/",
         "name": "example",
         "displayname": "example"
   }
}
```
- Технический контакт поставщика услуг SAML (SAML Service Provider Technical Contact).
  
  Пример заполнения:
```
{
   "givenName": "admin",
   "emailAddress": "admin@example.com"
}
```
- Контакт службы поддержки поставщика услуг SAML (SAML Service Provider Support Contact).
  
  Пример заполнения:
```
{
   "givenName": "admin",
   "emailAddress": "admin@example.com"
}
```
Включите параметр Включенный (Enabled).
Завершите создание, следуя инструкции по созданию метода аутентификации.
После сохранения изменений скопируйте сгенерированное значение поля URL сервиса потребления утверждений SAML (ACS) (SAML Assertion Consumer Service (ACS) URL).
Войдите в графическую консоль Keycloak и в меню Clients откройте настройки импортированного клиента.
Вставьте скопированное значение в поле Valid redirect URIs и сохраните изменения.

Проверка работоспособности SSO#

Для проверки работоспособности выполните следующие действия:

Выполните выход из учетной записи администратора Keycloak.
Откройте страницу входа в графическую консоль Astra Automation.
Нажмите кнопку keycloak-saml.

Подпись кнопки соответствует значению поля Название (Name) метода аутентификации.
Выполните вход с помощью обычного пользователя Keycloak.
Проверьте, что пользователь вернулся в графическую консоль Astra Automation.
Проверьте данные пользователя в Astra Automation:
- username;
- email;
- first name;
- last name;
- членство в организациях и командах;
- назначенные роли.

Для диагностики можно получить SP-метаданные метода аутентификации – XML-документ с фактическими значениями Entity ID, ACS URL и сертификатами поставщика услуг. Метаданные доступны по адресу:

https://<gateway_fqdn>/api/gateway/v1/authenticators/<id>/metadata/

Здесь:

<id> – идентификатор метода аутентификации в Astra Automation.

Типичные проблемы#

Проблема	Возможная причина	Решение
Ошибка входа `AuthFailed` с текстом `The response was received at http://... instead of https://...`	Известная проблема сборки: TLS-соединение терминируется на прокси перед шлюзом, и шлюз обрабатывает запрос по схеме `http`, которая не совпадает со схемой `https` в адресе ACS	Проверьте настройку внешнего URL и схемы шлюза; при необходимости обратитесь к администратору платформы
Ошибка входа `AuthFailed: failed to decrypt`	В клиенте Keycloak выбран неподдерживаемый алгоритм в поле Key transport algorithm (вариант RSA-OAEP)	В настройках клиента Keycloak выберите значение RSA1_5
Ошибка входа после возврата из Keycloak с текстом `Found an Attribute element with duplicated Name`	Keycloak передает несколько атрибутов SAML с одинаковым названием; как правило, это атрибуты ролей, если в client scope `role_list` не включен параметр Single Role Attribute	Включите параметр Single Role Attribute в mapper role list client scope `role_list`
После перенаправления к поставщику удостоверений Keycloak отображает страницу с описанием ошибки, а в журнале событий Keycloak регистрируется `invalid_redirect_uri`	Сгенерированный платформой URL сервиса потребления утверждений (ACS) не входит в список Valid redirect URIs клиента Keycloak, например, не совпадает схема `http`/`https`	Сравните значение поля URL сервиса потребления утверждений SAML (ACS) (SAML Assertion Consumer Service (ACS) URL) со списком Valid redirect URIs клиента Keycloak и приведите их в соответствие
После перенаправления Keycloak сообщает, что клиент не найден	Значение поля Идентификатор поставщика услуг SAML (SP) (SAML Service Provider Entity ID) не совпадает с идентификатором клиента Keycloak	Проверьте, что значение поля точно совпадает с Client ID импортированного клиента, включая завершающую косую черту
Ошибка `Unable to load as PEM data` при создании метода аутентификации, в деталях – `Could not deserialize key data` или ошибка разбора ASN.1	Закрытый ключ не соответствует требованиям: ключ зашифрован, использует ECDSA или его маркеры `BEGIN`/`END` не соответствуют фактическому формату данных	Проверьте требования к закрытому ключу; преобразуйте ключ в формат PKCS#8 командой `openssl pkcs8 -topk8` или сгенерируйте новую пару

Миграция пользователей#

Поле Автоматически мигрировать пользователей из (Auto migrate users from) для SAML работает так же, как и для других методов аутентификации. Особенности миграции и проверенные сценарии, включая случай использования идентификатора email в методе SAML, описаны в секции о миграции пользователей на странице OIDC. Пошаговый порядок перевода единого входа с SAML на OIDC приведен в разделе Миграция с SAML на OIDC.