OIDC

Интеграция с OpenID Connect (OIDC) позволяет использовать внешнего провайдера аутентификации для входа пользователей в Astra Automation. OIDC упрощает интеграцию с современными провайдерами удостоверений за счет стандартизированного обмена данными через JSON, ID token и метаданные OpenID Connect.

Пример описывает настройку единого входа в Astra Automation через Keycloak с использованием метода Generic OIDC. В этом сценарии Keycloak проверяет учетные данные пользователя, а Astra Automation получает от него токены и сведения о пользователе для создания сессии и применения настроек сопоставления.

При аутентификации через OIDC Astra Automation выступает клиентским приложением, а внешний провайдер OIDC выполняет проверку учетных данных пользователя. Пользователь выбирает вход через OIDC в графической консоли Astra Automation, после чего Astra Automation перенаправляет его к провайдеру OIDC. Провайдер запрашивает учетные данные пользователя и после успешной аутентификации возвращает пользователя в Astra Automation с authorization code. Затем Astra Automation обращается к token endpoint провайдера и обменивает authorization code на ID token и access token. Если провайдер поддерживает обновление сессии, в ответе также может быть передан refresh token.

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

После получения токенов и сведений о пользователе Astra Automation выполняет внутреннюю обработку данных:

• проверяет ID token: подпись, срок действия, аудиторию, издателя и другие параметры;

• извлекает атрибуты пользователя по JSON-ключам, указанным в полях Ключ ID (ID Key), Ключ имени пользователя (Username Key) и Ключ групп (Groups Claim);

• сопоставляет внешнюю учетную запись с пользователем, организациями, командами и ролями;

• создает пользовательскую сессию, если проверка и сопоставление выполнены успешно.

Примечание

ID token обычно передается в формате JWT и используется для подтверждения личности пользователя. Access token используется для обращения к ресурсам или точкам доступа провайдера, если это требуется в процессе аутентификации.

Внимание

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

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

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

• Развернута и доступна платформа Astra Automation.

• Развернут и доступен сервис Keycloak. Инструкции по развертыванию см. в официальной документации.

• Имеется доступ к учетной записи администратора Keycloak.

• Определен realm Keycloak, используемый для аутентификации пользователей Astra Automation.

• Platform Gateway доступен пользователям по FQDN или IP-адресу.

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

Получение метаданных провайдера OIDC

Большинство провайдеров OIDC публикуют метаданные со списком точек доступа. Обычно они доступны по адресу:

https://<oidc_provider>/.well-known/openid-configuration

Для Keycloak метаданные realm доступны по адресу:

https://<keycloak_fqdn>/realms/<realm_name>/.well-known/openid-configuration

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

curl -s https://keycloak.example.com/realms/master/.well-known/openid-configuration | jq

Используйте параметры метаданных для заполнения полей Generic OIDC:

Поле Astra Automation	Параметр метаданных	Пример для Keycloak
URL провайдера OIDC (OIDC Provider URL)	issuer	https://keycloak.example.com/realms/master
URL-адрес авторизации (Authorization URL)	authorization_endpoint	https://keycloak.example.com/realms/master/protocol/openid-connect/auth
URL токена доступа (Access Token URL)	token_endpoint	https://keycloak.example.com/realms/master/protocol/openid-connect/token
URI JWKS (JWKS URI)	jwks_uri	https://keycloak.example.com/realms/master/protocol/openid-connect/certs
URL информации о пользователе (Userinfo URL)	userinfo_endpoint	https://keycloak.example.com/realms/master/protocol/openid-connect/userinfo
URL отзыва токена (Revoke Token URL)	revocation_endpoint	https://keycloak.example.com/realms/master/protocol/openid-connect/revoke

Примечание

Набор параметров в метаданных зависит от версии и настроек Keycloak. Если параметр revocation_endpoint отсутствует, оставьте поле URL отзыва токена (Revoke Token URL) пустым.

Важно

В поле URL провайдера OIDC (OIDC Provider URL) укажите realm URL без пути /.well-known/openid-configuration. Например: https://keycloak.example.com/realms/master.

Platform Gateway самостоятельно добавляет путь /.well-known/openid-configuration. Если указать полный URL метаданных, путь будет добавлен повторно и Platform Gateway обратится по некорректному адресу, что приведет к ошибке 404 Not Found.

URI перенаправления Astra Automation

URI перенаправления – это адрес, на который провайдер OIDC возвращает пользователя после успешной аутентификации. Этот адрес необходимо указать в Keycloak при создании клиента для Astra Automation.

Для Platform Gateway URI перенаправления имеет следующий формат:

https://<gateway_fqdn>/api/gateway/social/complete/<slug>/

Здесь:

• <gateway_fqdn> – FQDN или IP-адрес Platform Gateway;

• <slug> – slug метода аутентификации.

При создании метода аутентификации через графическую консоль Astra Automation slug обычно формируется из значения поля Название (Name).

Пример:

https://gateway.example.com/api/gateway/social/complete/keycloak-oidc/

Важно

Не указывайте в Keycloak значение поля URL-адрес авторизации (Authorization URL) в качестве URI перенаправления. URL-адрес авторизации (Authorization URL) указывает, куда Astra Automation перенаправляет пользователя для входа. URI перенаправления указывает, куда провайдер OIDC возвращает пользователя после успешной аутентификации.

Проверка фактического URI перенаправления

Перед настройкой производственной среды рекомендуется проверить фактическое значение redirect_uri, которое Astra Automation передает провайдеру OIDC.

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

1. Создайте метод аутентификации Generic OIDC в Astra Automation.

2. Включите метод аутентификации.

3. Откройте страницу входа Platform Gateway.

4. Откройте инструменты разработчика браузера и перейдите на вкладку сетевых запросов.

5. Нажмите кнопку входа через OIDC.

6. Найдите перенаправление к провайдеру OIDC.

7. Проверьте значение параметра redirect_uri в URL запроса.

Полученное значение добавьте в Keycloak в поле Valid redirect URIs.

Настройка клиента в Keycloak

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

1. Авторизуйтесь в графической консоли Keycloak с привилегиями администратора.

2. Выберите realm, в рамках которого будет выполняться аутентификация пользователей.

3. В боковом меню выберите Clients.

4. Нажмите Create client.

5. В поле Client type выберите OpenID Connect.

6. В поле Client ID укажите идентификатор клиента.

   Например:

   aa-gateway-oidc
   

7. В поле Name укажите отображаемое название клиента.

   Например:

   Astra Automation
   

8. Нажмите Next.

9. Включите параметр Client authentication.

   Этот параметр нужен, чтобы Keycloak сформировал секрет клиента. Секрет будет использоваться в поле Секрет OIDC (OIDC Secret) в Astra Automation.

10. Отключите параметр Authorization, если он не используется в вашей схеме.

11. Включите параметр Standard flow.

    Standard flow используется для Authorization Code Flow: пользователь проходит аутентификацию в Keycloak, после чего Astra Automation получает authorization code и обменивает его на токены.

12. Для обычного browser SSO оставьте параметр Direct access grants выключенным.

    Если планируется использовать OIDC для CLI, API, registry или других сценариев без браузерного входа, необходимость включения Direct access grants проверьте отдельно в целевой конфигурации.

13. Нажмите Next.

14. В форме Login settings заполните поля:

    Поле Keycloak	Значение
    Root URL	Адрес Platform Gateway, например https://gateway.example.com
    Home URL	Адрес Platform Gateway, например https://gateway.example.com
    Valid redirect URIs	Точный URI перенаправления Astra Automation, например https://gateway.example.com/api/gateway/social/complete/keycloak-oidc/
    Valid post logout redirect URIs	Разрешенный адрес возврата после выхода, например https://gateway.example.com/*
    Web origins	Origin Platform Gateway, например https://gateway.example.com

    Для тестовых стендов допустимо временно использовать wildcard-значения, например https://<gateway_fqdn>/* в Valid redirect URIs или * в Web origins. Для производственной среды не рекомендуется использовать wildcard redirect URI и wildcard Web origins.

    Примечание

    В URL не должно быть пробелов в начале или конце строки. Лишние пробелы часто приводят к ошибке redirect_uri_mismatch.

15. Нажмите Save.

Получение Client ID и Client Secret

После создания клиента получите значения, которые нужно указать в Astra Automation.

1. В Keycloak откройте созданный клиент.

2. Скопируйте значение Client ID.

   Это значение нужно указать в поле Ключ OIDC (OIDC Key) в Astra Automation.

3. Откройте вкладку Credentials.

4. Скопируйте значение Client Secret.

   Это значение нужно указать в поле Секрет OIDC (OIDC Secret) в Astra Automation.

Настройка claims mappers в Keycloak

Для корректного создания пользователей рекомендуется передавать стандартные JSON-ключи пользователя в ID token, access token и userinfo.

В Keycloak можно использовать dedicated client scope созданного клиента, например aa-gateway-oidc-dedicated.

Рекомендуемые mappers:

Mapper name	User attribute	Token claim
username	username	preferred_username
email	email	email
first name	firstName	given_name
last name	lastName	family_name

Для каждого mapper включите передачу в:

• ID token;

• access token;

• userinfo.

Для Generic OIDC дополнительно настройте передачу claim aud:

1. В dedicated client scope клиента откройте вкладку Mappers.

2. Нажмите Add mapper и выберите создание mapper по конфигурации.

3. Выберите mapper типа Audience.

4. В качестве аудитории укажите клиент Astra Automation, например aa-gateway-oidc.

5. Включите передачу claim в ID token.

6. Сохраните mapper и убедитесь, что значение aud присутствует в ID token.

Отсутствие claim aud может привести к ошибке:

jwt.exceptions.MissingRequiredClaimError: Token is missing the "aud" claim

Для проверки сопоставления групп создайте mapper групп. Обычно для Keycloak используется token claim groups.

Mapper name	Token claim
groups	groups

Если в Astra Automation в поле Ключ групп (Groups Claim) оставлено значение Group, настройте Keycloak так, чтобы группы передавались в JSON-ключе Group. Значение поля Ключ групп (Groups Claim) в Astra Automation должно совпадать с именем JSON-ключа, который провайдер OIDC передает в ID token или userinfo.

Проверка JSON-ключей в токене

Перед настройкой Astra Automation рекомендуется проверить, что ID token или userinfo содержит необходимые JSON-ключи:

• sub;

• preferred_username;

• email;

• given_name;

• family_name.

Если планируется сопоставление групп, также проверьте наличие JSON-ключа с группами, например groups или Group. Проверить содержимое ID token можно через инструменты разработчика браузера или локальные средства декодирования JWT.

Предупреждение

Не передавайте реальные токены из производственной среды во внешние онлайн-сервисы декодирования JWT. Для проверки используйте локальные средства декодирования или отдельного тестового пользователя и тестовый стенд.

Создание тестового пользователя в Keycloak

Убедитесь, что в 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. Сохраните изменения.

Примечание

Для проверки не рекомендуется использовать учетную запись admin, если такая учетная запись уже существует в Astra Automation как локальный пользователь. В этом случае Astra Automation может создать отдельную учетную запись с автоматически сформированным суффиксом.

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

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

1. Войдите в графическую консоль Astra Automation с правами администратора.

2. Выберите Управление доступом ‣ Методы аутентификации (Access Management ‣ Authentication Methods).

3. В окне Методы аутентификации (Authentication Methods) нажмите кнопку Создать метод аутентификации (Create authentication).

4. В поле Тип аутентификации (Authentication type) выберите Generic OIDC и нажмите кнопку Далее (Next).

5. Заполните основные параметры метода.

   Поле Astra Automation	Значение
   Название (Name)	Произвольное название метода, например keycloak-oidc
   Автоматически мигрировать пользователей из (Auto migrate users from)	Используйте при переходе с другого метода аутентификации. Миграция может завершиться без ошибки, но при использовании имени учетной записи или адреса электронной почты платформа может создать отдельную учетную запись или добавить к имени префикс. Для использования существующей учетной записи следует применять один и тот же стабильный уникальный идентификатор пользователя в старом и новом методах
   URL провайдера OIDC (OIDC Provider URL)	Realm URL без пути /.well-known/openid-configuration, например https://keycloak.example.com/realms/master. Platform Gateway самостоятельно получает метаданные OpenID Connect
   Ключ OIDC (OIDC Key)	Client ID из настроек клиента Keycloak
   Секрет OIDC (OIDC Secret)	Client Secret из настроек клиента Keycloak
   URL токена доступа (Access Token URL)	Значение token_endpoint из метаданных провайдера OIDC
   Метод токена доступа (Access Token Method)	POST
   URL-адрес авторизации (Authorization URL)	Значение authorization_endpoint из метаданных провайдера OIDC
   Ключ ID (ID Key)	Введите sub
   ID токена источника (ID Token Issuer)	Значение issuer из метаданных провайдера OIDC
   URI JWKS (JWKS URI)	Значение jwks_uri из метаданных провайдера OIDC
   Тип ответа (Response Type)	Введите code
   Метод аутентификации конечной точки токена (Token Endpoint Auth Method)	client_secret_post или client_secret_basic в зависимости от настроек провайдера
   URL информации о пользователе (Userinfo URL)	Значение userinfo_endpoint из метаданных провайдера OIDC
   Ключ имени пользователя (Username Key)	JSON-ключ, из которого Astra Automation получает имя пользователя. Для новых настроек Keycloak обычно используется preferred_username. Не используйте имя учетной записи или адрес электронной почты как единственное условие повторного использования существующей учетной записи при миграции: в проверенных сценариях такие значения привели к созданию отдельной учетной записи или имени с префиксом
   Ключ групп (Groups Claim)	JSON-ключ, из которого Astra Automation получает список групп пользователя. Для Keycloak обычно используется groups, если в Keycloak настроен mapper групп с token claim groups. Если в поле указано Group, провайдер OIDC должен передавать группы в JSON-ключе Group
   Алгоритмы OIDC JWT (OIDC JWT Algorithm(s))	Для Keycloak обычно используется RS256
   Опции декодирования OIDC JWT (OIDC JWT Decode Options)	Оставьте пустым при корректной синхронизации времени между платформой Astra Automation и Keycloak. Для диагностики ошибки The token is not yet valid (iat) на тестовом стенде можно временно указать {"verify_iat": false}

6. Включите параметр Проверить сертификат провайдера OIDC (Verify OIDC Provider Certificate), если Keycloak использует доверенный сертификат.

7. Включите параметр Состояние перенаправления (Redirect State), чтобы Astra Automation сохраняла и проверяла параметр state при перенаправлении пользователя.

8. В поле Список областей OAuth2 (List of OAuth2 Scope(s)) укажите scopes, которые Astra Automation будет запрашивать у Keycloak.

   Минимальный набор:

   - openid
   - email
   - profile
   

9. Включите параметр Включенный (Enabled).

10. При необходимости включите параметр Создавать объекты (Create objects), чтобы Astra Automation могла создавать пользователей, команды и организации по правилам сопоставления.

11. Нажмите кнопку Далее (Next).

12. Настройте правила сопоставления пользователей, организаций и команд.

13. Сохраните метод аутентификации.

Миграция пользователей с другого метода аутентификации

Поле Автоматически мигрировать пользователей из (Auto migrate users from) предназначено для перехода с ранее использовавшегося метода аутентификации.

При оценке результата миграции различайте:

• техническое выполнение миграции – процесс завершается без ошибки;

• повторное использование существующей учетной записи – платформа не создает дубликат и не изменяет имя пользователя с помощью префикса.

В проверенных сценариях миграция завершилась без ошибки, но существующая учетная запись не была повторно использована:

SAML: email
OIDC: email
Результат: создана дублирующаяся учетная запись

SAML: email
OIDC: preferred_username
Результат: создана отдельная учетная запись

При использовании имени учетной записи или адреса электронной почты в качестве идентификатора результатом миграции могут быть дублирующиеся учетные записи или имена с автоматически добавленным префиксом.

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

Перед массовым переходом:

• определите, какой стабильный идентификатор пользователя передают старый и новый методы;

• убедитесь, что оба метода передают одно и то же значение стабильного идентификатора;

• выполните проверку на отдельном тестовом пользователе;

• убедитесь, что платформа повторно использовала существующую учетную запись;

• проверьте сохранение ролей, членства в организациях и командах, а также владения объектами;

• предусмотрите способ возврата к предыдущему методу аутентификации.

Предупреждение

Не считайте отсутствие ошибки признаком того, что существующая учетная запись была повторно использована.

Перед отключением старого метода аутентификации проверьте, что Astra Automation не создала дублирующуюся учетную запись и не изменила имя пользователя с помощью префикса.

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

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

1. Выполните выход из учетной записи администратора Keycloak.

2. Откройте страницу входа в графическую консоль Astra Automation.

3. Нажмите кнопку Keycloak OIDC.

4. Выполните вход с помощью обычного пользователя Keycloak.

5. Проверьте, что пользователь вернулся в графическую консоль Astra Automation.

6. Проверьте данные пользователя в Astra Automation:

   • username;

   • email;

   • first name;

   • last name;

   • членство в организациях и командах;

   • назначенные роли.

Проверка сопоставления групп

Параметр Ключ групп (Groups Claim) позволяет Astra Automation прочитать группы пользователя из ID token или userinfo, но сам по себе не назначает права.

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

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

1. После заполнения данных метода аутентификации нажмите кнопку Далее (Next).

2. На шаге Сопоставление (Mapping) нажмите кнопку Добавить сопоставление аутентификации (Add authentication mapping).

3. Выберите требуемый тип сопоставления.

Примечание

Подробную информацию о полях шага Сопоставление (Mapping) см. в описании графического интерфейса платформы

1. Для сопоставления по группам выберите Группы (Groups) в поле Триггер (Trigger), укажите требуемую Операцию (Operation) и выберите группы в поле Группы (Groups).

2. Заполните остальные поля, отображаемые для выбранного типа сопоставления.

3. При необходимости добавьте другие правила сопоставления.

4. Нажмите кнопку Далее (Next), проверьте настройки на шаге Обзор (Review) и завершите создание метода аутентификации.

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

• провайдер OIDC передает группы пользователя в ID token или userinfo;

• значение поля Ключ групп (Groups Claim) совпадает с именем JSON-ключа групп;

• для нужной группы создано правило на шаге Сопоставление (Mapping);

• пользователь входит в нужную группу на стороне провайдера OIDC.

После изменения членства пользователя в группах провайдера OIDC выполните повторный вход пользователя в Astra Automation и проверьте, что права изменились в соответствии с правилами сопоставления.

Внимание

Назначайте сопоставление типа Суперпользователь (Superuser) только при необходимости. Для производственной среды рекомендуется использовать сопоставление с организациями, командами или ограниченными ролями.

Проверка API, ansible-galaxy и registry flows

Успешный вход через Web UI не гарантирует работоспособность других сценариев аутентификации. Если OIDC должен использоваться не только для графической консоли, отдельно проверьте:

• доступ к API;

• установку коллекций через ansible-galaxy;

• доступ к Private Automation Hub;

• podman login и docker login;

• загрузку образов сред выполнения через podman pull или docker pull;

• доступность Registry API, например:

  curl -v https://gateway.example.com/v2/
  

Эти проверки зависят от версии Platform Gateway, настроек registry и поддерживаемых non-browser authentication flows.

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

Проблема	Возможная причина	Решение
redirect_uri_mismatch	Неверный URI перенаправления	Проверьте фактическое значение redirect_uri в инструментах разработчика браузера и добавьте его в Valid redirect URIs в Keycloak
Ошибка входа после возврата из Keycloak	Неверный Client Secret или неподходящий метод аутентификации token endpoint	Проверьте Секрет OIDC (OIDC Secret) и значение Метод аутентификации конечной точки токена (Token Endpoint Auth Method)
Ошибка проверки токена	Неверный issuer или алгоритм подписи	Проверьте ID токена источника (ID Token Issuer) и Алгоритмы OIDC JWT (OIDC JWT Algorithm(s))
Token is missing the "aud" claim	В ID token отсутствует claim aud	Настройте в Keycloak mapper типа Audience, добавьте клиент Astra Automation в аудиторию и проверьте содержимое ID token
The token is not yet valid (iat)	Время на узле Astra Automation и узле провайдера OIDC не синхронизировано	Включите синхронизацию времени на узлах. В тестовой среде можно временно использовать Опции декодирования OIDC JWT (OIDC JWT Decode Options) со значением {"verify_iat": false}
Пользователь создан без email, имени или фамилии	Провайдер OIDC не передает нужные JSON-ключи	Проверьте claims mappers в Keycloak и содержимое ID token или userinfo
Группы не применяются	Неверное значение Ключ групп (Groups Claim) или отсутствует правило сопоставления	Проверьте JSON-ключ групп и настройте правило сопоставления
Создается дублирующийся пользователь или к имени добавляется префикс	В старом и новом методах в качестве идентификатора используется имя учетной записи или адрес электронной почты	Используйте один и тот же стабильный уникальный идентификатор пользователя в обоих методах. Перед массовым переходом проверьте результат на отдельном тестовом пользователе

Рекомендации для производственной среды

Для производственной среды рекомендуется:

• использовать HTTPS;

• использовать FQDN вместо IP-адреса;

• использовать отдельный realm для Astra Automation;

• указывать точный URI перенаправления без wildcard;

• не использовать wildcard Web origins;

• запрашивать только необходимые scopes;

• использовать стабильный JSON-ключ sub в поле Ключ ID (ID Key);

• проверять JSON-ключи в ID token или userinfo до включения метода для пользователей;

• управлять RBAC через группы провайдера OIDC, если это предусмотрено архитектурой;

• документировать фактический URI перенаправления для каждого метода аутентификации.