Аутентификация с помощью Microsoft Entra ID
С помощью федерации удостоверений вы можете использовать Microsoft Entra ID
Настройка аутентификации состоит из следующих этапов:
Перед началом работы
Чтобы воспользоваться инструкциями в этом разделе, вам понадобится учетная запись Azure с активной подпиской.
Создание и настройка SAML-приложения в Azure
Создайте SAML-приложение и скачайте сертификат
В роли поставщика удостоверений (IdP) выступает SAML-приложение в Microsoft Azure. Начните создавать приложение и скачайте сертификат:
-
Перейдите на портал Azure
. -
В разделе Службы Azure выберите Microsoft Entra ID.
-
На панели слева выберите Корпоративные приложения.
-
Нажмите Новое приложение.
-
На странице Обзор коллекции Microsoft Entra нажмите Создайте собственное приложение.
-
В открывшемся окне:
-
Введите название приложения.
-
Выберите вариант Integrate any other application you don't find in the gallery (Non-gallery).
-
Нажмите кнопку Создать.
-
-
На открывшейся странице Обзор на панели слева выберите Единый вход.
-
Выберите метод единого входа SAML.
-
На странице Вход на основе SAML в разделе 3. Сертификат подписи SAML скачайте сертификат (Base64). С помощью него поставщик удостоверений подписывает сообщение о том, что пользователь прошел аутентификацию.
Не закрывайте страницу: данные IdP-сервера понадобятся при создании и настройке федерации.
Добавьте пользователей
Добавьте пользователей на IdP-сервер:
-
Перейдите на страницу Корпоративные приложения
. -
Выберите созданное SAML-приложение.
-
На панели слева выберите Пользователи и группы.
-
Нажмите Добавить пользователя или группу.
-
В поле Пользователи нажмите Не выбрано.
-
В открывшемся окне отметьте пользователей и нажмите кнопку Выбрать.
-
Нажмите кнопку Назначить.
Создание и настройка федерации в Yandex Cloud Organization
Создайте федерацию
-
Перейдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
В правом верхнем углу страницы нажмите кнопку
Создать федерацию. В открывшемся окне:-
Задайте имя федерации. Имя должно быть уникальным в каталоге.
-
При необходимости добавьте описание.
-
В поле Время жизни cookie укажите время, в течение которого браузер не будет требовать у пользователя повторной аутентификации.
-
В поле IdP Issuer вставьте ссылку, которая указана в поле Идентификатор Microsoft Entra на странице Вход на основе SAML в Entra ID. Формат ссылки:
https://sts.windows.net/<идентификатор_SAML-приложения>/
-
В поле Ссылка на страницу для входа в IdP вставьте ссылку, которая указана в поле URL-адрес входа на странице Вход на основе SAML в Entra ID. Формат ссылки:
https://login.microsoftonline.com/<идентификатор_SAML-приложения>/saml2
В ссылке допустимо использовать только протоколы HTTP и HTTPS.
-
Включите опцию Автоматически создавать пользователей, чтобы пользователь после аутентификации автоматически добавлялся в организацию. Если опция отключена, федеративных пользователей потребуется добавить вручную.
Автоматически федеративный пользователь создается только при первом входе пользователя в облако. Если вы исключили пользователя из федерации, вернуть его туда можно будет только вручную.
-
Включите опцию Принудительная повторная аутентификация (ForceAuthn) в IdP, чтобы задать значение
true
для параметра ForceAuthn в запросе аутентификации SAML. При включении этой опции IdP-провайдер запрашивает у пользователя аутентификацию по истечении сессии в Yandex Cloud. -
Нажмите кнопку Создать федерацию.
-
Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.
По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name
или --folder-id
.
-
Посмотрите описание команды создания федерации:
yc organization-manager federation saml create --help
-
Создайте федерацию:
yc organization-manager federation saml create --name my-federation \ --organization-id <идентификатор_организации> \ --auto-create-account-on-login \ --cookie-max-age 12h \ --issuer "https://sts.windows.net/<идентификатор_SAML-приложения>/" \ --sso-url "https://login.microsoftonline.com/<идентификатор_SAML-приложения>/saml2" \ --sso-binding POST \ --force-authn
Где:
-
--name
— имя федерации. Имя должно быть уникальным в каталоге. -
--organization-id
— идентификатор организации. -
--auto-create-account-on-login
— флаг, который активирует автоматическое создание новых пользователей в облаке после аутентификации на IdP-сервере.
Опция упрощает процесс заведения пользователей, но созданный таким образом пользователь не сможет выполнять никаких операций с ресурсами в облаке. Исключение — те ресурсы, на которые назначены роли публичной группеAll users
илиAll authenticated users
.Если опцию не включать, то пользователь, которого не добавили в организацию, не сможет войти в консоль управления, даже если пройдет аутентификацию на вашем IdP-сервере. В этом случае вы можете управлять списком пользователей, которым разрешено пользоваться ресурсами Yandex Cloud.
-
--cookie-max-age
— время, в течение которого браузер не должен требовать у пользователя повторной аутентификации. -
--issuer
— идентификатор IdP-сервера, на котором должна происходить аутентификация.Используйте ссылку, которая указана в поле Идентификатор Microsoft Entra на странице Вход на основе SAML в Entra ID. Формат ссылки:
https://sts.windows.net/<идентификатор_SAML-приложения>/
-
--sso-url
— URL-адрес страницы, на которую браузер должен перенаправить пользователя для аутентификации.Используйте ссылку, которая указана в поле URL-адрес входа на странице Вход на основе SAML в Entra ID. Формат ссылки:
https://login.microsoftonline.com/<идентификатор_SAML-приложения>/saml2
В ссылке допустимо использовать только протоколы HTTP и HTTPS.
-
--sso-binding
— укажите тип привязки для Single Sign-on. Большинство поставщиков поддерживают тип привязкиPOST
. -
(Опционально)
force-authn
— при истечении сессии в Yandex Cloud поставщик удостоверений запросит у пользователя повторную аутентификацию.
-
Если у вас еще нет Terraform, установите его и настройте провайдер Yandex Cloud.
-
В конфигурационном файле опишите параметры федерации:
-
name
— имя федерации. Имя должно быть уникальным в каталоге. -
description
— описание федерации. -
organization_id
— идентификатор организации. -
labels
— набор пар меток ключ/значение, которые присвоены федерации. -
issuer
— идентификатор IdP-сервера, на котором должна происходить аутентификация.Используйте ссылку, которая указана в поле Идентификатор Microsoft Entra на странице Вход на основе SAML в Entra ID. Формат ссылки:
https://sts.windows.net/<идентификатор_SAML-приложения>/
-
sso_binding
— укажите тип привязки для Single Sign-on. Большинство поставщиков поддерживают тип привязкиPOST
. -
sso_url
— URL-адрес страницы, на которую браузер должен перенаправить пользователя для аутентификации.Используйте ссылку, которая указана в поле URL-адрес входа на странице Вход на основе SAML в Entra ID. Формат ссылки:
https://login.microsoftonline.com/<идентификатор_SAML-приложения>/saml2
В ссылке допустимо использовать только протоколы HTTP и HTTPS.
-
cookie_max_age
— время в секундах, в течение которого браузер не должен требовать у пользователя повторной аутентификации. Значение по умолчанию8 часов
. -
auto_create_account_on_login
— флаг, который активирует автоматическое создание новых пользователей в облаке после аутентификации на IdP-сервере.
Опция упрощает процесс заведения пользователей, но созданный таким образом пользователь не сможет выполнять никаких операций с ресурсами в облаке. Исключение — те ресурсы, на которые назначены роли публичной группеAll users
илиAll authenticated users
.Если опцию не включать, то пользователь, которого не добавили в организацию, не сможет войти в консоль управления, даже если пройдет аутентификацию на вашем сервере. В этом случае вы можете управлять списком пользователей, которым разрешено пользоваться ресурсами Yandex Cloud.
-
case_insensitive_name_ids
— зависимость имен пользователей от регистра.
Если опция включена, идентификаторы имен федеративных пользователей будут нечувствительны к регистру. -
security_settings
— настройки безопасности федерации:encrypted_assertions
— подписывать запросы аутентификации.
Если включить опцию, то все запросы аутентификации от Yandex Cloud будут содержать цифровую подпись. Вам потребуется скачать и установить сертификат Yandex Cloud.
Пример структуры конфигурационного файла:
resource "yandex_organizationmanager_saml_federation" federation { name = "my-federation" organization_id = "<идентификатор_организации>" auto_create_account_on_login = "true" issuer = "https://sts.windows.net/<идентификатор_SAML-приложения>/" sso_url = "https://login.microsoftonline.com/<идентификатор_SAML-приложения>/saml2" sso_binding = "POST" security_settings { encrypted_assertions = "true" } }
-
-
Проверьте корректность конфигурационных файлов.
-
В командной строке перейдите в папку, где вы создали конфигурационный файл.
-
Выполните проверку с помощью команды:
terraform plan
Если конфигурация описана верно, в терминале отобразятся параметры федерации. Если в конфигурации есть ошибки, Terraform на них укажет.
-
-
Создайте федерацию.
-
Если в конфигурации нет ошибок, выполните команду:
terraform apply
-
Подтвердите создание федерации.
После этого в указанной организации будет создана федерация. Проверить появление федерации и ее настроек можно в организации в разделе Федерации
. -
-
Создайте файл с телом запроса, например
body.json
:{ "name": "my-federation", "organizationId": "<идентификатор_организации>", "autoCreateAccountOnLogin": true, "cookieMaxAge":"43200s", "issuer": "https://sts.windows.net/<идентификатор_SAML-приложения>/", "ssoUrl": "https://login.microsoftonline.com/<идентификатор_SAML-приложения>/saml2", "ssoBinding": "POST", "securitySettings": { "forceAuthn": true } }
Где:
-
name
— имя федерации. Имя должно быть уникальным в каталоге. -
organizationId
— идентификатор организации. -
autoCreateAccountOnLogin
— флаг, который активирует автоматическое создание новых пользователей в облаке после аутентификации на IdP-сервере.
Опция упрощает процесс заведения пользователей, но созданный таким образом пользователь не сможет выполнять никаких операций с ресурсами в облаке. Исключение — те ресурсы, на которые назначены роли публичной группеAll users
илиAll authenticated users
.Если опцию не включать, то пользователь, которого не добавили в организацию, не сможет войти в консоль управления, даже если пройдет аутентификацию на вашем IdP-сервере. В этом случае вы можете управлять списком пользователей, которым разрешено пользоваться ресурсами Yandex Cloud.
-
cookieMaxAge
— время, в течение которого браузер не должен требовать у пользователя повторной аутентификации. -
issuer
— идентификатор IdP-сервера, на котором должна происходить аутентификация.Используйте ссылку, которая указана в поле Идентификатор Microsoft Entra на странице Вход на основе SAML в Entra ID. Формат ссылки:
https://sts.windows.net/<идентификатор_SAML-приложения>/
-
ssoUrl
— URL-адрес страницы, на которую браузер должен перенаправить пользователя для аутентификации.Используйте ссылку, которая указана в поле URL-адрес входа на странице Вход на основе SAML в Entra ID. Формат ссылки:
https://login.microsoftonline.com/<идентификатор_SAML-приложения>/saml2
В ссылке допустимо использовать только протоколы HTTP и HTTPS.
-
ssoBinding
— укажите тип привязки для Single Sign-on. Большинство поставщиков поддерживают тип привязкиPOST
. -
forceAuthn
— параметр, который включает принудительную повторную аутентификацию пользователя по истечении сессии в Yandex Cloud.
-
-
Чтобы создать федерацию, воспользуйтесь методом REST API create для ресурса Federation или вызовом gRPC API FederationService/Create и передайте в запросе файл с параметрами запроса.
Пример запроса:
curl \ --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Bearer <IAM-токен>" \ --data '@body.json' \ https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/federations
Пример ответа:
{ "done": true, "metadata": { "@type": "type.googleapis.com/yandex.cloud.organization-manager.v1.saml.CreateFederationMetadata", "federationId": "ajeobmje4dgj********" }
В свойстве
federationId
указан идентификатор созданной федерации: сохраните его, он понадобится в дальнейшем.
Добавьте сертификаты
При аутентификации у сервиса Cloud Organization должна быть возможность проверить сертификат IdP-сервера. Для этого добавьте скачанный ранее сертификат в федерацию:
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Нажмите на строку с федерацией, для которой нужно добавить сертификат.
-
Внизу страницы в блоке Сертификаты нажмите кнопку Добавить сертификат.
-
Введите название и описание сертификата.
-
Выберите способ добавления сертификата:
- Чтобы добавить сертификат в виде файла, нажмите Выбрать файл и укажите путь к нему.
- Чтобы вставить скопированное содержимое сертификата, выберите способ Текст и вставьте содержимое.
-
Нажмите кнопку Добавить.
Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.
По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name
или --folder-id
.
-
Посмотрите описание команды добавления сертификата:
yc organization-manager federation saml certificate create --help
-
Добавьте сертификат для федерации, указав путь к файлу сертификата:
yc organization-manager federation saml certificate create \ --federation-id <ID_федерации> \ --name "my-certificate" \ --certificate-file certificate.cer
Воспользуйтесь методом create для ресурса Certificate:
-
Сформируйте тело запроса. В свойстве
data
укажите содержимое сертификата:{ "federationId": "<ID_федерации>", "name": "my-certificate", "data": "-----BEGIN CERTIFICATE..." }
-
Отправьте запрос на добавление сертификата:
export IAM_TOKEN=CggaAT******** curl \ --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Bearer ${IAM_TOKEN}" \ --data '@body.json' \ "https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/certificates"
Совет
Чтобы аутентификация не прерывалась в тот момент, когда у очередного сертификата закончился срок действия, рекомендуется добавлять в федерацию несколько сертификатов — текущий и те, которые будут использоваться после текущего. Если один сертификат окажется недействительным, Yandex Cloud попробует проверить подпись другим сертификатом.
Настройка системы единого входа (SSO)
Укажите URL для перенаправления
Когда вы создали федерацию, завершите создание SAML-приложения в Azure:
-
Откройте страницу настроек SAML-приложения Вход на основе SAML.
-
В разделе 1. Базовая конфигурация SAML укажите сведения о Yandex Cloud, выступающем в роли поставщика услуг. Для этого в полях Идентификатор (сущности) и URL-адрес ответа (URL-адрес службы обработчика утверждений) укажите ACS URL, на который пользователи будут перенаправляться после аутентификации.
Как получить ACS URL федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля ACS URL.
-
-
Нажмите Сохранить.
Настройте сопоставление атрибутов пользователей
Важно
Настройка сопоставления атрибутов обязательна.
После аутентификации пользователя IdP-сервер отправит в Yandex Cloud SAML-сообщение, которое будет содержать:
-
информацию об успешной аутентификации;
-
атрибуты пользователя, такие как идентификатор Name ID, имя и адрес электронной почты.
Чтобы настроить сопоставление между атрибутами SAML-сообщения и персональными данными, на странице Вход на основе SAML в разделе 2. Утверждения и атрибуты пользователя нажмите Изменить.
Типы персональных данных, которые поддерживает Yandex Cloud Organization для Entra ID, приведены ниже.
Данные пользователя | Комментарий | Атрибуты приложений |
---|---|---|
Уникальный идентификатор пользователя (Name ID) | Обязательный атрибут. По умолчанию в Entra ID в качестве источника атрибута используется User Principal Name (UPN) в формате <логин>_<домен>#EXT#@<поставщик>.onmicrosoft.com . При добавлении пользователей в федерацию вручную такой формат Name ID не поддерживается. Рекомендуется в Entra ID изменить источник атрибута: вместо UPN user.userprincipalname выбрать адрес электронной почты user.mail . |
Утверждение Уникальный идентификатор пользователя (ID) |
Фамилия | Отображается в сервисах Yandex Cloud. Ограничение значения по длине: 64 символа. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname |
Имя | Отображается в сервисах Yandex Cloud. Ограничение значения по длине: 64 символа. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname |
Полное имя | Отображается в сервисах Yandex Cloud. Пример: Иван Иванов .Ограничение значения по длине: 64 символа. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name |
Почта | Используется для отправки уведомлений из сервисов Yandex Cloud. Пример: ivanov@example.com .Ограничение значения по длине: 256 символов. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
Важно
Если значение атрибута превышает ограничение по длине, то часть значения, выходящая за пределы ограничения, отбрасывается.
Добавьте пользователей в организацию
Если при создании федерации вы не включили опцию Автоматически создавать пользователей, федеративных пользователей нужно добавить в организацию вручную.
Для этого вам понадобятся пользовательские Name ID. Их возвращает IdP-сервер вместе с ответом об успешной аутентификации.
При включенной опции Автоматически создавать пользователей в федерацию будут добавлены только пользователи, которые впервые авторизуются в облаке. Если федеративный пользователь был исключен, добавить его повторно можно только вручную.
Добавить пользователя может администратор (роль organization-manager.admin
) или владелец (роль organization-manager.organizations.owner
) организации. О том, как назначить пользователю роль, читайте в разделе Роли.
-
Перейдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Пользователи. -
В правом верхнем углу экрана нажмите Ещё
и выберите Добавить федеративных пользователей. -
Выберите федерацию, из которой необходимо добавить пользователей.
-
Перечислите Name ID пользователей, разделяя их пробелами или переносами строк.
-
Нажмите Добавить. Пользователи будут подключены к организации.
Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.
По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name
или --folder-id
.
-
Посмотрите описание команды добавления пользователей:
yc organization-manager federation saml add-user-accounts --help
-
Добавьте пользователей, перечислив их Name ID через запятую:
yc organization-manager federation saml add-user-accounts --id <ID_федерации> \ --name-ids=alice@example.com,bob@example.com,charlie@example.com
Где:
-
--id
— идентификатор федерации. -
--name-ids
— Name ID пользователей.
-
Чтобы добавить пользователей федерации в облако:
-
Сформируйте файл с телом запроса, например
body.json
. В теле запроса укажите массив Name ID пользователей, которых необходимо добавить:{ "nameIds": [ "alice@example.com", "bob@example.com", "charlie@example.com" ] }
-
Отправьте запрос, указав в параметрах идентификатор федерации:
curl \ --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Bearer <IAM-токен>" \ --data '@body.json' \ https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/federations/<ID_федерации>:addUserAccounts
Проверка аутентификации
Когда вы закончили настройку SSO, протестируйте, что все работает:
-
Откройте браузер в гостевом режиме или режиме инкогнито.
-
Перейдите по URL для входа в консоль:
https://console.yandex.cloud/federations/<ID_федерации>
Как получить ID федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля Идентификатор.
Браузер должен перенаправить вас на страницу аутентификации в Microsoft.
-
-
Введите данные для аутентификации и нажмите кнопку Далее.
После успешной аутентификации IdP-сервер перенаправит вас по ACS URL, который вы указали в настройках Entra ID, а после — на главную страницу консоли управления