Создать SAML-приложение в Yandex Identity Hub для интеграции с OpenCode Console
Важно
Часть ресурсов, необходимых для прохождения практического руководства, доступны только в регионе Россия.
OpenCode Console
Руководство описывает настройку доступа к рабочему пространству в OpenCode Console. Настройка доступа к экземпляру OpenCode, запущенному локально или на сервере, не рассматривается.
Примечание
Управлять SAML-приложениями может пользователь, которому назначена роль organization-manager.samlApplications.admin или выше.
Чтобы настроить единый вход:
- Подготовьтесь к работе.
- Получите параметры OpenCode Console.
- Создайте и настройте SAML-приложение.
- Активируйте SAML в OpenCode Console.
- Предоставьте пользователям доступ к приложению.
- Привяжите и подтвердите почтовый домен.
- Проверьте вход в рабочее пространство.
Перед началом работы
- Подготовьте организацию в Yandex Identity Hub. Если у вас еще нет организации, создайте ее.
- Убедитесь, что у вас есть рабочее пространство в OpenCode Console и роль Owner в нем. Настраивать SSO может только владелец рабочего пространства.
- Подготовьте почтовый домен вашей организации и убедитесь, что можете добавлять TXT-записи в его DNS-зону. Домен потребуется привязать к рабочему пространству и подтвердить в OpenCode Console.
- Убедитесь, что у пользователей, которые будут входить через SSO, в Yandex Identity Hub указан адрес электронной почты в этом домене.
Важно
После активации SSO администраторы и участники рабочего пространства должны входить через настроенного поставщика удостоверений. Владелец сохраняет возможность входа без SSO. Не закрывайте сессию владельца до завершения настройки и проверки входа.
Получите параметры OpenCode Console
-
Войдите в OpenCode Console
как владелец рабочего пространства и выберите нужное рабочее пространство. -
Откройте Settings → Security и нажмите Configure SSO.
-
Выберите SAML 2.0 и вариант настройки произвольного поставщика удостоверений Custom SAML.
-
На шаге Set up your provider скопируйте значения ACS URL (Callback) и SP Entity ID. Они понадобятся для настройки приложения в Yandex Identity Hub.
Используйте значения из вашего подключения. Адреса содержат уникальный идентификатор подключения SSO и имеют вид:
- ACS URL (Callback) —
https://opencode.ai/console/auth/sso/<идентификатор_подключения>/callback. - SP Entity ID —
https://opencode.ai/console/auth/sso/<идентификатор_подключения>/metadata.
- ACS URL (Callback) —
Создайте и настройте SAML-приложение
-
В другой вкладке браузера откройте сервис Yandex Identity Hub
. -
На панели слева выберите
Приложения. -
Нажмите
Создать приложение и в открывшемся окне:- Выберите метод единого входа SAML (Security Assertion Markup Language).
- В поле Имя укажите имя приложения, например
opencode-saml. - (Опционально) Добавьте описание и метки приложения.
- Нажмите Создать приложение.
-
На странице созданного приложения нажмите
Редактировать и задайте настройки:- SP EntityID — значение SP Entity ID из OpenCode Console.
- ACS URL — значение ACS URL (Callback) из OpenCode Console.
- Режим подписи — Assertions.
Поле SP Logout URL оставьте пустым.
-
Нажмите Сохранить.
-
Настройте передачу адреса электронной почты пользователя:
- Перейдите на вкладку Атрибуты.
- Нажмите
Добавить атрибут. - В поле Имя атрибута укажите
email. - В поле Значение выберите
SubjectClaims.email. - Нажмите Добавить.
Если атрибут
emailуже есть, проверьте его значение вместо создания нового атрибута. -
Перейдите на вкладку Обзор и в блоке Конфигурация поставщика удостоверений (IdP) скопируйте значение поля Metadata URL.
Примечание
OpenCode Console требует, чтобы поставщик удостоверений подписывал SAML-ответ или содержащиеся в нем утверждения. Также поставщик должен передавать адрес электронной почты пользователя в атрибуте email или в NameID. В этом руководстве используются подпись утверждений и отдельный атрибут email.
Активируйте SAML в OpenCode Console
-
Вернитесь к настройке Custom SAML в OpenCode Console и нажмите Next.
-
На шаге Add provider details в поле IdP Metadata вставьте URL метаданных приложения, скопированный из Yandex Identity Hub.
-
Нажмите Fetch. Проверьте, что заполнились поля IdP Entity ID, IdP SSO URL и IdP Certificate.
Вместо загрузки по URL можно использовать Upload XML и загрузить файл метаданных, скачанный со страницы SAML-приложения в Yandex Identity Hub.
-
В поле Display Name укажите имя поставщика удостоверений, например
Identity Hub SAML. -
Нажмите Next.
-
На шаге Review проверьте параметры и нажмите Activate SSO.
Предоставьте пользователям доступ к приложению
Пользователей или группы пользователей нужно явно добавить в созданное SAML-приложение Yandex Identity Hub:
Примечание
Управлять пользователями и группами, добавленными в SAML-приложение, может пользователь, которому назначена роль organization-manager.samlApplications.userAdmin или выше.
- В сервисе Yandex Identity Hub
откройте Приложения и выберите созданное приложение. - Перейдите на вкладку Пользователи и группы.
- Нажмите
Добавить пользователей. - Выберите нужного пользователя или группу пользователей и нажмите Добавить.
Совет
Если вы хотите более тонко настроить аутентификацию пользователей в приложениях, в том числе разрешить аутентификацию только с определенных IP-адресов, используйте политики аутентификации.
Политики аутентификации — это инструмент Yandex Identity Hub, позволяющий гибко настраивать доступ к приложениям, запрещая или разрешая аутентификацию определенным пользователям в определенных приложениях и/или с определенных IP-адресов. Подробнее читайте в разделе Политики аутентификации в Yandex Identity Hub.
Привяжите и подтвердите почтовый домен
Домен нужно добавить и подтвердить именно в OpenCode Console. Подтверждение домена в Yandex Identity Hub не заменяет эту настройку.
-
В OpenCode Console откройте Settings → Security нужного рабочего пространства.
-
После активации SSO в блоке Email domains нажмите Add domain.
-
Укажите домен адресов электронной почты пользователей, например
example.com. -
В DNS-зоне домена создайте TXT-запись с именем и значением, которые покажет OpenCode Console. Запись имеет вид:
Параметр
Пример
Имя
_opencode-console-challenge.example.comТип
TXTЗначение
oc-verify=<код_подтверждения>Используйте код подтверждения из OpenCode Console, а не значение из примера.
-
Дождитесь обновления DNS-записей и нажмите Verify Domain в OpenCode Console. Если проверка не прошла, убедитесь, что запись корректна, и повторите попытку позже.
-
Убедитесь, что домен подтвержден. Если пользователи используют несколько почтовых доменов, повторите эти действия для каждого домена.
Примечание
К одному рабочему пространству можно привязать несколько доменов. Один и тот же домен нельзя привязать к нескольким рабочим пространствам.
Проверьте вход в рабочее пространство
- Откройте OpenCode Console
в приватном окне браузера, чтобы не использовать сессию владельца. - Начните вход с адресом электронной почты пользователя из подтвержденного домена. Пользователь должен быть добавлен в приложение Yandex Identity Hub напрямую или через группу.
- После перенаправления в Yandex Identity Hub выполните аутентификацию этого пользователя.
- Если учетная запись с таким адресом уже существует в OpenCode Console, подтвердите ее связывание кнопкой Link account, когда появится соответствующий запрос.
- Убедитесь, что пользователю доступно нужное рабочее пространство.
При первом входе через SSO пользователи из подтвержденного домена автоматически присоединяются к рабочему пространству с ролью Member. Исключения:
- у пользователя есть ожидающее приглашение;
- в рабочем пространстве настроена синхронизация каталога SCIM
; - используется подписка OpenCode Go
.
В этих случаях членство определяется приглашением, синхронизацией или условиями подписки. Подробнее в документации OpenCode
Полезные ссылки
Организация — это высший ресурс в иерархии ресурсной модели Yandex Cloud, который объединяет ресурсы всех остальных сервисов, а также используется для управления пользователями и параметрами их аутентификации и авторизации. Подробнее читайте в разделе Организация.
Пользователей Yandex Identity Hub можно объединять в группы, что упрощает управление доступом в Yandex Cloud. Подробнее читайте в разделе Группы пользователей.