Настроить федерацию удостоверений

Вы можете настроить аутентификацию пользователей в облаке через федерацию удостоверений. Федерации удостоверений совместимы с любыми поставщиками удостоверений (IdP), которые поддерживают стандарт SAML 2.0.

Для настройки аутентификации через федерацию удостоверений, у вас должна быть минимальная роль organization-manager.federations.editor на организацию.

Чтобы настроить аутентификацию через федерацию удостоверений:

1. Создайте федерацию удостоверений.
2. Передайте сертификат IdP-сервера в федерацию.
3. Передайте сертификат федерации на IdP-сервер.
4. Настройте SAML-приложение на стороне IdP-сервера.
5. Настройте сопоставление атрибутов пользователей.
6. Проверьте работу аутентификации.

Примеры настройки аутентификации для отдельных поставщиков удостоверений приведены в практических руководствах:

• Active Directory.
• Google Workspace.
• Microsoft Entra ID.
• Keycloak.

Создать федерацию удостоверенийСоздать федерацию удостоверений

Передать сертификат IdP-сервера в федерациюПередать сертификат IdP-сервера в федерацию

Когда поставщик удостоверений (IdP) сообщает Yandex Identity Hub, что пользователь прошел аутентификацию, он подписывает сообщение своим сертификатом. Чтобы сервис Identity Hub мог проверить этот сертификат, добавьте его в созданную федерацию:

1. Получите сертификат вашего поставщика удостоверений.

   Чтобы узнать, как это сделать, обратитесь к документации или в службу технической поддержки используемого поставщика удостоверений.

   Имя субъекта в сертификате должно содержать FQDN сервера поставщика удостоверений, например fs.contoso.com, чтобы браузер не блокировал страницу аутентификации.

2. Приведите файл сертификата к PEM-формату:

   -----BEGIN CERTIFICATE-----
     <значение сертификата>
   -----END CERTIFICATE-----
   

3. Добавьте сертификат в федерацию:

   Интерфейс Cloud Center

   CLI

   API

   1. Войдите в сервис Yandex Identity Hub с учетной записью администратора или владельца организации.

   2. На панели слева выберите Федерации.

   3. Нажмите на строку с федерацией, для которой нужно добавить сертификат.

   4. Внизу страницы в блоке Сертификаты нажмите кнопку Добавить сертификат.

   5. Введите название и описание сертификата.

   6. Выберите способ добавления сертификата:

      • Чтобы добавить сертификат в виде файла, нажмите Выбрать файл и укажите путь к нему.
      • Чтобы вставить скопированное содержимое сертификата, выберите способ Текст.

   7. Нажмите кнопку Добавить.

   Если у вас еще нет интерфейса командной строки Yandex Cloud (CLI), установите и инициализируйте его.

   По умолчанию используется каталог, указанный при создании профиля CLI. Чтобы изменить каталог по умолчанию, используйте команду yc config set folder-id <идентификатор_каталога>. Также для любой команды вы можете указать другой каталог с помощью параметров --folder-name или --folder-id.

   1. Посмотрите описание команды добавления сертификата:

      yc organization-manager federation saml certificate create --help
      

   2. Добавьте сертификат для федерации, указав путь к файлу сертификата:

      yc organization-manager federation saml certificate create --federation-name <имя_федерации> \
        --name "<имя_сертификата>" \
        --certificate-file <путь_к_файлу_сертификата>
      

   1. Сформируйте файл с телом запроса body.json, указав содержимое сертификата в свойстве data:

      {
        "federationId": "<идентификатор_федерации>",
        "description": "<описание_сертификата>",
        "name": "<имя_сертификата>",
        "data": "<содержимое_сертификата>"
      }
      

   2. Воспользуйтесь методом REST API create для ресурса Certificate или вызовом gRPC API CertificateService/Create и передайте в запросе файл с параметрами запроса.

   Пример cURL-запроса:

   export IAM_TOKEN=CggaATEVAgA...
   curl \
     --request POST \
     --header "Content-Type: application/json" \
     --header "Authorization: Bearer ${IAM_TOKEN}" \
     --data '@body.json' \
     "https://organization-manager.api.yandexcloud.kz/organization-manager/v1/saml/certificates"
   

   Совет

   Не забывайте своевременно перевыпускать сертификаты и добавлять их в федерацию.

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

   Передать сертификат федерации на IdP-серверПередать сертификат федерации на IdP-сервер

   Если при создании федерации вы включили опцию Подписывать запросы аутентификации, запросы аутентификации от Yandex Cloud будут содержать цифровую подпись. Чтобы IdP-сервер мог проверить эту подпись, добавьте сертификат Yandex Cloud на IdP-сервер:

   1. Если вы не скачивали SAML-сертификат Yandex Cloud при создании федерации удостоверений, скачайте его сейчас:

      Интерфейс Cloud Center

      1. Войдите в сервис Yandex Identity Hub с учетной записью администратора или владельца организации.

      2. На панели слева выберите Федерации.

      3. В открывшемся списке выберите нужную федерацию удостоверений и в поле Подписывать запросы аутентификации нажмите Скачать сертификат.

         Если слева от кнопки Скачать сертификат отображается значок , значит срок действия текущего SAML-сертификата Yandex Cloud закончился или вот-вот закончится.

         Скачайте и установите перевыпущенный SAML-сертификат Yandex Cloud в вашей федерации удостоверений.

         Совет

         Чтобы узнать дату истечения срока действия текущего SAML-сертификата, в правом верхнем углу нажмите Изменить. Нужная дата будет указана в блоке Дополнительно в секции Сертификат SAML.

         Сохраните дату истечения срока действия SAML-сертификата в свой календарь. За несколько месяцев до указанной даты вам будет необходимо скачать и установить в вашей федерации и на IdP-сервере перевыпущенный SAML-сертификат Yandex Cloud.

   2. Передайте скачанный SAML-сертификат Yandex Cloud на IdP-сервер. Чтобы узнать, как это сделать, обратитесь к документации или в службу технической поддержки используемого поставщика удостоверений.

   Настроить SAML-приложение на стороне IdP-сервераНастроить SAML-приложение на стороне IdP-сервера

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

   Пример SAML-сообщения

   <samlp:Response ID="_bcdf7b6b-ea42-4191-8d5e-ebd4274acec6" Version="2.0" IssueInstant="2019-07-30T13:24:25.488Z"
    Destination="https://kz.console.yandex.cloud/federations/bfbrotp6l1b2avhe1spu" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
     InResponseTo="19fb953133b313a86a001f2d387160e47f3e7aa0" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
     <Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://example.org/auth</Issuer>
     <samlp:Status>
       <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
     </samlp:Status>
     <Assertion ID="_90cd8dcc-6105-4300-9ae4-f2c8c5aeb1e5" IssueInstant="2019-07-30T13:24:25.488Z"
      Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
       <Issuer>http://example.org/auth</Issuer>
       <ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
         <ds:SignedInfo>
           <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
           <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
           <ds:Reference URI="#_90cd8dcc-6105-4300-9ae4-f2c8c5aeb1e5">
             <ds:Transforms>
               <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
               <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
             </ds:Transforms>
             <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
             <ds:DigestValue>phUQR...</ds:DigestValue>
           </ds:Reference>
         </ds:SignedInfo>
         <ds:SignatureValue>VACd7O...</ds:SignatureValue>
         <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
           <ds:X509Data>
             <ds:X509Certificate>MIIC7j...</ds:X509Certificate>
           </ds:X509Data>
         </KeyInfo>
       </ds:Signature>
       <Subject>
         <NameID>user@example.org</NameID>
         <SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
           <SubjectConfirmationData InResponseTo="19fb953133b313a86a001f2d387160e47f3e7aa0" NotOnOrAfter="2019-07-30T13:29:25.488Z" Recipient="https://kz.console.yandex.cloud/federations/bfbrotp6l1b2avhe1spu" />
         </SubjectConfirmation>
       </Subject>
       <Conditions NotBefore="2019-07-30T13:24:25.482Z" NotOnOrAfter="2019-07-30T14:24:25.482Z">
         <AudienceRestriction>
           <Audience>https://kz.console.yandex.cloud/federations/bfbrotp6l1b2avhe1spu</Audience>
         </AudienceRestriction>
       </Conditions>
       <AttributeStatement>
         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
           <AttributeValue>user@example.org</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
           <AttributeValue>First Name</AttributeValue>
         </Attribute>
         <Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
           <AttributeValue>Last Name</AttributeValue>
         </Attribute>
       </AttributeStatement>
     </Assertion>
   </samlp:Response>
   

   Настройте SAML-приложение таким образом, чтобы при формировании сообщения:

   • В элементах Response и SubjectConfirmationData в атрибуте InResponseTo был передан идентификатор из SAML-запроса на аутентификацию, отправленного Yandex Cloud.

   • URL вида https://kz.auth.yandex.cloud/federations/<идентификатор_федерации> был передан в следующих элементах:

     • Response в атрибуте Destination;
     • SubjectConfirmationData в атрибуте Recipient;
     • Audience.
     Как получить идентификатор федерации

     1. Войдите в сервис Yandex Identity Hub.
     2. На панели слева выберите Федерации.
     3. Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля Идентификатор.

   • В элементе NameID был указан уникальный идентификатор пользователя. В качестве идентификатора рекомендуется использовать User Principal Name (UPN) или адрес электронной почты.

   • В элементе Issuer была указана ссылка на страницу поставщика удостоверений, куда перенаправлялся пользователь для прохождения аутентификации.

   • В элементе SignatureValue было указано подписанное сообщение, а в элементе KeyInfo — сертификат, которым оно было подписано.

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

   • Active Directory.
   • Google Workspace.
   • Microsoft Entra ID.
   • Keycloak.

   Настроить сопоставление атрибутов пользователейНастроить сопоставление атрибутов пользователей

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

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

   Данные пользователя	Комментарий	Элементы SAML-сообщения
   Уникальный идентификатор пользователя	Обязательный атрибут. Рекомендуется использовать User Principal Name (UPN) или адрес электронной почты.	<NameID>
   Фамилия	Отображается в сервисах Yandex Cloud. Ограничение значения по длине: 64 символа.	<Attribute> с параметром Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
   Имя	Отображается в сервисах Yandex Cloud. Ограничение значения по длине: 64 символа.	<Attribute> с параметром Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
   Полное имя	Отображается в сервисах Yandex Cloud. Пример: Иван Иванов. Ограничение значения по длине: 64 символа.	<Attribute> с параметром Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
   Почта	Используется для отправки уведомлений из сервисов Yandex Cloud. Пример: ivanov@example.com. Ограничение по длине: 256 символов.	<Attribute> с параметром Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
   Телефон	Используется для отправки уведомлений из сервисов Yandex Cloud. Пример: +71234567890. Ограничение по длине: 64 символа.	<Attribute> с параметром Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone"
   Аватар	Отображается в сервисах Yandex Cloud. Изображение передается в кодировке Base64. Ограничение по длине: 204800 символов.	<Attribute> с параметром Name="thumbnailPhoto"
   Членство в группах	Используется для функционала динамического сопоставления членства в группах.	<Attribute> с параметром Name="member"

   Примечание

   Если значение атрибута thumbnailPhoto превышает ограничение по длине, атрибут игнорируется. Если значение другого атрибута превышает ограничение, такое значение обрезается.

   Проверить работу аутентификацииПроверить работу аутентификации

   Чтобы проверить работу аутентификации федеративных пользователей:

   1. Если в федерации не включена опция Автоматически создавать пользователей, добавьте федеративных пользователей вручную.

   2. Откройте браузер в гостевом режиме или режиме инкогнито для чистой симуляции нового пользователя.

   3. Перейдите по URL для входа в консоль управления:

      https://kz.console.yandex.cloud/federations/<идентификатор_федерации>
      

      Как получить идентификатор федерации

      1. Войдите в сервис Yandex Identity Hub.
      2. На панели слева выберите Федерации.
      3. Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля Идентификатор.

      Браузер перенаправит вас на страницу аутентификации поставщика удостоверений.

   4. Введите ваши аутентификационные данные. По умолчанию необходимо ввести UPN и пароль.

   5. Нажмите кнопку Sign in.

   6. После успешной аутентификации IdP-сервер перенаправит вас по URL https://kz.auth.yandex.cloud/federations/<ID_федерации>, который вы указали в настройках сервера, а после этого — на главную страницу консоли управления.

   Убедитесь, что вошли в консоль от имени федеративного пользователя.