Аутентификация с помощью 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. При включении этой опции поставщик удостоверений (Identity Provider, 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"
Совет
Не забывайте своевременно перевыпускать сертификаты и добавлять их в федерацию.
Чтобы не пропустить момент окончания срока действия сертификата, подпишитесь на уведомления от организации. Уведомления направляются подписанным пользователям за 60, 30 и 5 дней до момента прекращения действия сертификата, а также после того, как сертификат становится недействительным.
Настройка системы единого входа (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
) организации. О том, как назначить пользователю роль, читайте в разделе Роли.
Примечание
Для доступа пользователя к консоли управленияresource-manager.clouds.member
, но также можно назначить и другие роли, если вы знаете, какие права вы хотите предоставить приглашенным пользователям.
Чтобы дать эти права сразу всем пользователям в организации, назначьте роль системной группе All users in organization X
. При работе с CLI или API назначение дополнительных ролей не требуется.
-
Перейдите в сервис 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.
- Войдите в сервис Yandex Cloud Organization
-
Введите данные для аутентификации и нажмите кнопку Далее.
После успешной аутентификации IdP-сервер перенаправит вас по ACS URL, который вы указали в настройках Entra ID, а после — на главную страницу консоли управления