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

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

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

Политики аутентификации — это инструмент Yandex Identity Hub, позволяющий гибко настраивать доступ к приложениям, запрещая или разрешая аутентификацию определенным пользователям в определенных приложениях и/или с определенных IP-адресов. Подробнее читайте в разделе Политики аутентификации в Yandex Identity Hub.

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

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

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

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

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

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

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

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

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

• ACS URL — URL-адрес, на который Yandex 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-приложения на стороне Yandex Identity Hub, должен соответствовать режиму подписи, заданному на стороне поставщика услуг.

• Принимать только подписанные запросы — позволяет проверять подпись SAML-запросов от поставщика услуг и не начинать аутентификацию, если подписи в запросе нет или она невалидна.

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

• Шифровать assertion в ответе — позволяет включить шифрование SAML-ответов, чтобы добавить дополнительный слой защиты данных. По умолчанию SAML-ответы только подписываются.

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

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

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

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

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

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

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

Возможные форматы и значения атрибута:

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

  • SubjectClaims.preferred_username — значение по умолчанию при переключении на этот формат.

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

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

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

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

  • SubjectClaims.sub — значение по умолчанию при переключении на этот формат.
  • SubjectClaims.external_id — внешний идентификатор пользователя.
  • SubjectClaims.employee_id — табельный номер сотрудника.

• urn:oasis:names:tc:SAML:2.0:nameid-format:transient — идентификатор пользователя передается в значении идентификатора текущей сессии пользователя. Значение этого идентификатора изменяется в зависимости от используемой сессии и не может применяться для однозначной идентификации пользователя.

  Формат urn:oasis:names:tc:SAML:2.0:nameid-format:transient нельзя задать в настройках атрибута NameID явно: идентификатор пользователя в этом формате передается в SAML-ответе только в том случае, если этот формат был явно запрошен в SAML-запросе.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Полезные ссылкиПолезные ссылки

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