Приложения в Yandex Identity Hub

Пользователи вашей организации могут аутентифицироваться во внешних приложениях с помощью технологии единого входа (SSO). Для этого Identity Hub позволяет создавать приложения — ресурсы Yandex Cloud, которые содержат настройки интеграции Yandex Identity Hub как поставщика удостоверений (Identity Provider, IdP) с одной стороны и стороннего поставщика услуг (Service Provider, SP) — с другой.

Identity Hub поддерживает стандарты технологии единого входа SAML и OpenID Connect (OIDC).

В качестве поставщика услуг могут выступать различные сервисы, поддерживающие технологию единого входа, которые могут работать как по модели SaaS, так и по модели on-premise. Например: Яндекс 360, GitHub, GitLab, Jenkins, Jira и множество других.

SAML-приложенияSAML-приложения

В Identity Hub вы можете создавать SAML-приложения, которые позволяют настроить единый вход по стандарту SAML на стороне Identity Hub, а также предоставляют необходимые значения для настройки интеграции на стороне поставщика услуг.

Доступ к внешнему приложению разрешен только тем пользователям организации Yandex Cloud, которые явно добавлены в соответствующее SAML-приложение или входят в группы пользователей, явно добавленные в это SAML-приложение.

Управлять SAML-приложениями может пользователь, которому назначена роль organization-manager.samlApplications.admin или выше.

Схема взаимодействия сторон по стандарту SAMLСхема взаимодействия сторон по стандарту SAML

В базовом представлении аутентификация пользователя с использованием механизма единого входа по стандарту SAML происходит по следующей схеме:

1. На странице аутентификации внешнего приложения (поставщика услуг) пользователь Yandex Cloud выбирает аутентификацию с помощью единого входа.
2. Поставщик услуг направляет SAML-запрос в Identity Hub (поставщик удостоверений) и перенаправляет пользователя на URL входа Identity Hub.
3. Пользователь аутентифицируется в Identity Hub, используя свои учетные данные.
4. Если в Identity Hub существует SAML-приложение, соответствующее данному внешнему приложению, аутентифицировавшийся пользователь добавлен в это SAML-приложение, а полученный SAML-запрос корректен, то Identity Hub направляет поставщику услуг подписанный SAML-ответ, содержащий атрибуты пользователя.
5. Поставщик услуг проверяет корректность SAML-ответа и его подписи и в случае успеха предоставляет пользователю доступ к внешнему приложению.
6. При выходе пользователя из внешнего приложения поставщик услуг направляет SAML-запрос в Identity Hub и перенаправляет пользователя на URL выхода Identity Hub.

Обмен данными между сторонами по стандарту SAML происходит в формате XML.

Настройка на стороне поставщика удостоверений (Identity Hub)Настройка на стороне поставщика удостоверений (Identity Hub)

Для корректной работы интеграции на стороне Identity Hub необходимо настроить ряд параметров интеграции в SAML-приложении. Получите необходимые значения этих параметров у вашего поставщика услуг:

• SP EntityID — уникальный идентификатор поставщика услуг (Service Provider).

  Значение должно совпадать на стороне поставщика услуг и на стороне Identity Hub.

• ACS URL — URL-адрес, на который Identity Hub будет отправлять SAML-ответ.

  ACS URL должен соответствовать схеме https. Использовать протокол без шифрования допускается только в целях тестирования на локальном хосте (значения http://127.0.0.1 и http://localhost).

  Если ваш поставщик услуг вместо ACS URL использует ACS-индексы, в дополнение к ACS URL вы можете задать полученное на стороне поставщика услуг значение индекса.

  Вы можете указать одновременно несколько URL/индексов ACS.

  Примечание

  Если в настройках поля ACS URL для одного из URL-адресов вы указали индекс, то индексы также должны быть указаны и для всех остальных URL-адресов.

• Режим подписи — элементы SAML-ответа, которые будут подписываться электронной подписью:

  • Assertions — будут подписываться только передаваемые атрибуты. Значение по умолчанию.
  • Response — будет подписываться весь SAML-ответ целиком.
  • Assertions and Response — будут подписываться как целиком весь SAML-ответ, так и (отдельно) передаваемые атрибуты.

  Важно

  Режим подписи, заданный для SAML-приложения на стороне Identity Hub, должен соответствовать режиму подписи, заданному на стороне поставщика услуг.

Атрибуты пользователя и группАтрибуты пользователя и групп

Новое SAML-приложение по умолчанию создается с определенным набором относящихся к пользователю атрибутов, которые будут передаваться из Identity Hub поставщику услуг. Этот набор включает в себя:

Имя атрибута	Значение атрибута	Передаваемое значение
NameID	SubjectClaims.preferred_username	идентификатор пользователя
givenname	SubjectClaims.given_name	полное имя пользователя
fullname	SubjectClaims.name	имя пользователя
surname	SubjectClaims.family_name	фамилия пользователя
emailaddress	SubjectClaims.email	адрес электронной почты пользователя

После создания SAML-приложения вы можете добавлять, изменять и удалять следующие атрибуты пользователя:

• SubjectClaims.sub — идентификатор пользователя. Значение поля соответствует значению, отображаемому в поле Идентификатор в списке пользователей организации в интерфейсе Identity Hub в Cloud Center. Например: aje0fapf84ofj57q1r0b.
• SubjectClaims.preferred_username — уникальный логин пользователя. Значение поля соответствует значению, отображаемому в поле Имя пользователя в списке пользователей организации в интерфейсе Identity Hub в Cloud Center. Например: ivanov@example-federation.ru.
• SubjectClaims.name — полное имя пользователя. Значение поля соответствует значению, отображаемому в поле Пользователь в списке пользователей организации в интерфейсе Identity Hub в Cloud Center. Например: Иванов Иван.
• SubjectClaims.given_name — имя. Значение поля соответствует значению, отображаемому в поле Имя в разделе Персональная информация на странице с информацией о пользователе в интерфейсе Identity Hub в Cloud Center. Например: Иван.
• SubjectClaims.family_name — фамилия. Значение поля соответствует значению, отображаемому в поле Фамилия в разделе Персональная информация на странице с информацией о пользователе в интерфейсе Identity Hub в Cloud Center. Например: Иванов.
• SubjectClaims.email — адрес электронной почты. Значение поля соответствует значению, отображаемому в поле Электронная почта на странице с информацией о пользователе в интерфейсе Identity Hub в Cloud Center. Например: ivanov@example-company.ru.
• SubjectClaims.phone_number — номер телефона. Значение поля соответствует значению, отображаемому в поле Номер телефона в разделе Персональная информация на странице с информацией о пользователе в интерфейсе Identity Hub в Cloud Center. Например: +74951234567.

Имя атрибута NameID, в котором передается идентификатор пользователя, изменить нельзя. Для этого атрибута можно изменить формат, в котором будет отправляться идентификатор, если в SAML-запросе со стороны поставщика услуг формат атрибута не указан явно. При изменении формата значение атрибута изменяется автоматически. Возможные форматы и значения атрибута:

• urn: oasis: names: tc: SAML: 1.1:nameid-format: emailAddress — идентификатор пользователя передается в формате адреса электронной почты в атрибуте SubjectClaims.preferred_username. Формат по умолчанию.

  Уникальность и неизменяемость передаваемого идентификатора не гарантируется: в одной организации могут быть два пользователя с одинаковым идентификатором preferred_username. Например: федеративный пользователь и локальный пользователь могут иметь одинаковое значение этого атрибута.

  Если идентификатор preferred_username федеративного пользователя задан не в формате адреса электронной почты, к передаваемому идентификатору будет автоматически добавлен суффикс @<идентификатор_федерации_удостоверений>, чтобы привести его к такому формату.

• urn: oasis: names: tc: SAML: 2.0:nameid-format: persistent — идентификатор пользователя передается в атрибуте SubjectClaims.sub в формате идентификатора пользователя организации. При этом передаваемое значение гарантированно уникальное и неизменяемое.

В дополнение к указанным выше атрибутам пользователя в SAML-ответе может быть передан атрибут групп, значением которого является список групп, в которые входит пользователь. Для этого атрибута вы можете задать произвольное имя и одно из значений:

• Все группы — в SAML-ответе в значение данного поля будут включены все группы, в которые входит пользователь.

  Максимальное количество передаваемых в этом поле групп — 1 000. Если количество групп, в которые входит пользователь, превышает это число, на сторону поставщика услуг будет передана только первая тысяча групп.

• Только назначенные группы — в SAML-ответе в значение данного поля из всех групп, в которые входит пользователь, будут включены только те группы, которые явно заданы на вкладке Пользователи и группы SAML-приложения.

Настройка на стороне поставщика услуг (внешнее приложение)Настройка на стороне поставщика услуг (внешнее приложение)

Для корректной работы интеграции на стороне поставщика услуг также необходимо настроить ряд параметров интеграции. В зависимости от возможностей вашего поставщика услуг вы можете выполнить эти настройки как вручную, так и автоматически, загрузив XML-файл с метаданными или указав URL с метаданными.

Ссылка на скачивание XML-файла с метаданными и URL с метаданными доступны на странице с информацией о SAML-приложении в интерфейсе Cloud Center. Там же доступны значения параметров интеграции для настройки вручную:

• Issuer / IdP EntityID — уникальный идентификатор, используемый для приложения. Значение должно совпадать на стороне поставщика услуг и на стороне Identity Hub.
• Login URL — адрес, на который поставщик услуг будет отправлять запросы для аутентификации пользователя.
• Logout URL — адрес, на который поставщик услуг будет отправлять SAML-запрос при выходе пользователя из системы.

Кроме того, на стороне поставщика услуг должны быть настроены и корректно обрабатываться атрибуты пользователя, настроенные на стороне Identity Hub.

Сертификат ключа проверки электронной подписиСертификат ключа проверки электронной подписи

В дополнение к настройке указанных выше параметров в конфигурацию поставщика услуг необходимо также добавить сертификат, с помощью которого поставщик услуг сможет верифицировать электронную подпись, которой Identity Hub подписывает SAML-ответы.

Сертификат ключа проверки электронной подписи для SAML-приложения автоматически выпускается при создании приложения сроком на пять лет.

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

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

Дополнительно на стороне поставщика услуг необходимо указать, какие данные в SAML-ответах поставщика удостоверений будут подписываться:

• только передаваемые атрибуты пользователя;
• весь SAML-ответ целиком;
• целиком весь SAML-ответ и (отдельно) передаваемые атрибуты.

Заданный режим подписи на стороне поставщика услуг должен соответствовать режиму подписи, заданному на стороне Identity Hub.

OIDC-приложенияOIDC-приложения

В Identity Hub вы можете создавать OIDC-приложения, которые позволяют настроить единый вход по стандарту OpenID Connect (OIDC) на стороне Identity Hub, а также предоставляют необходимые значения для настройки интеграции на стороне поставщика услуг.

Доступ к внешнему приложению разрешен только тем пользователям организации Yandex Cloud, которые явно добавлены в соответствующее OIDC-приложение или входят в группы пользователей, явно добавленные в это OIDC-приложение.

Управлять OIDC-приложениями может пользователь, которому назначена роль organization-manager.oauthApplications.admin или выше.

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

Схема взаимодействия сторон по стандарту OIDCСхема взаимодействия сторон по стандарту OIDC

В базовом представлении аутентификация пользователя с использованием механизма единого входа по стандарту OpenID Connect происходит по следующей схеме:

1. На странице аутентификации внешнего приложения (поставщика услуг) пользователь Yandex Cloud выбирает аутентификацию с помощью единого входа.
2. Поставщик услуг направляет запрос аутентификации в Identity Hub (поставщик удостоверений) и перенаправляет пользователя на URL входа Identity Hub, указанный в поле Authorization endpoint.
3. Пользователь аутентифицируется в Identity Hub, используя свои учетные данные.
4. Если в Identity Hub существует OIDC-приложение, соответствующее данному внешнему приложению, аутентифицировавшийся пользователь добавлен в это OIDC-приложение, а полученный запрос аутентификации корректен, то Identity Hub направляет поставщику услуг код авторизации и перенаправляет пользователя обратно во внешнее приложение.
5. По адресу, заданному в поле Token endpoint, поставщик услуг запрашивает в Identity Hub ID-токен и токен доступа. В запросе указывается секрет приложения, по которому Identity Hub проверяет подлинность запроса.
6. Если переданный поставщиком услуг секрет действителен, Identity Hub направляет поставщику услуг ID-токен и токен доступа.
7. Поставщик услуг проверяет переданный ID-токен с помощью публичного ключа, получив его в Yandex Cloud по идентификатору, указанному в поле kid заголовка ID-токена. В случае успеха поставщик услуг предоставляет пользователю доступ к внешнему приложению.

Обмен данными между сторонами по стандарту OIDC происходит в формате JSON.

Секрет OIDC-приложенияСекрет OIDC-приложения

Секрет приложения генерируется пользователем на стороне OIDC-приложения в Identity Hub и представляет собой случайную строку определенной длины, начинающуюся с префикса yccs__.

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

Срок жизни секрета OIDC-приложения не ограничен. При этом вы в любой момент можете сгенерировать в приложении любое количество новых секретов, а также удалить их.

Секреты OIDC-приложений не сохраняются на стороне Yandex Cloud и отображаются пользователю только в момент создания. После обновления или закрытия страницы браузера, на которой был сгенерирован секрет, содержимое секрета становится недоступно.

Настройка на стороне поставщика удостоверений (Identity Hub)Настройка на стороне поставщика удостоверений (Identity Hub)

Для корректной работы интеграции на стороне Identity Hub в OIDC-приложении необходимо указать адрес (адреса) Redirect URI, выбрать набор атрибутов пользователя, которые будут передаваться поставщику услуг, а также сгенерировать секрет приложения. Прежде чем настраивать OIDC-приложение на стороне Identity Hub, получите адрес (адреса) Redirect URI у вашего поставщика услуг.

Redirect URIRedirect URI

Redirect URI — адрес на стороне внешнего приложения, куда пользователь будет перенаправляться в результате успешного прохождения аутентификации в Identity Hub.

Redirect URI должен соответствовать схеме https. Использовать протокол без шифрования допускается только в целях тестирования на локальном хосте (значения http://127.0.0.1 и http://localhost).

В OIDC-приложении вы можете задать одновременно несколько адресов Redirect URI.

Атрибуты пользователяАтрибуты пользователя

В настройках OIDC-приложения вы можете задать состав атрибутов пользователя, которые определяются выбранными в поле Scopes значениями и будут передаваться поставщику услуг в ID-токене:

• openid (идентификатор пользователя) — идентификатор пользователя. Обязательный параметр.

• email (адрес электронной почты) — адрес электронной почты пользователя.

• profile (полное имя, имя, фамилия, аватар и др.) — дополнительная информация о пользователе.

• groups (группы пользователя в организации) — группы пользователей организации, участником которых является аутентифицирующийся пользователь. Возможные значения:

  • Все группы — поставщику услуг будут переданы все группы, в которые входит пользователь.

    Максимальное количество передаваемых групп — 1 000. Если количество групп, в которые входит пользователь, превышает это число, на сторону поставщика услуг будет передана только первая тысяча групп.

  • Только назначенные группы — из всех групп, в которые входит пользователь, поставщику услуг будут переданы только те группы, которые явно заданы на вкладке Пользователи и группы OIDC-приложения.

В новом OIDC-приложении по умолчанию выбраны все атрибуты, за исключением groups.

Настройка на стороне поставщика услуг (внешнее приложение)Настройка на стороне поставщика услуг (внешнее приложение)

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

URL с конфигурацией предоставляет поставщику услуг значения всех необходимых для настройки интеграции параметров и доступен в поле OpenID Configuration в блоке Конфигурация поставщика услуг (SP) на странице с информацией об OIDC-приложении в интерфейсе Cloud Center. На этой же странице доступны значения параметров интеграции для настройки вручную:

• ClientID — уникальный идентификатор приложения.
• Authorization endpoint — адрес в Yandex Cloud, на который поставщик услуг будет перенаправлять пользователя для прохождения аутентификации.
• Token endpoint — адрес, на который от внешнего приложения поступает запрос на получение ID-токена и токена доступа.
• Userinfo endpoint — адрес, по которому внешнее приложение может получить атрибуты пользователя.

В дополнение к указанным выше настройкам на стороне поставщика услуг также необходимо указать секрет приложения.

См. такжеСм. также

• Создать SAML-приложение в Yandex Identity Hub
• Изменить SAML-приложение в Yandex Identity Hub
• Деактивировать и удалить SAML-приложение в Yandex Identity Hub
• Создать OIDC-приложение в Yandex Identity Hub
• Изменить OIDC-приложение в Yandex Identity Hub
• Деактивировать и удалить OIDC-приложение в Yandex Identity Hub