Аутентификация с помощью Keycloak
С помощью федерации удостоверений вы можете использовать Keycloak
Настройка аутентификации состоит из следующих этапов:
Подготовка к работе
Чтобы воспользоваться инструкциями в этом разделе, вам понадобятся:
-
Платформа Docker. Если у вас не установлен Docker, установите его
. Убедитесь, что Docker Engine запущен. -
Локальный IdP-сервер Keycloak
. Чтобы установить и запустить Keycloak, выполните команды:Keycloak 20 в режиме разработчикаKeycloak 19docker run -p 8080:8080 -e KEYCLOAK_ADMIN=admin -e KEYCLOAK_ADMIN_PASSWORD=Pa55w0rd quay.io/keycloak/keycloak:latest start-dev
git clone https://github.com/keycloak/keycloak-containers.git cd ./keycloak-containers/docker-compose-examples docker-compose -f keycloak-postgres.yml up
Примечание
Чтобы сотрудники в корпоративной сети или интернете могли использовать Keycloak для аутентификации в вашем приложении, разверните IdP-сервер Keycloak в сети и настройте публичный адрес. Подробнее читайте в документации Keycloak
. -
Действующий сертификат, который используется для подписи в службе Keycloak. Чтобы его получить:
-
Войдите в аккаунт администратора Keycloak по адресу:
Keycloak 17 или новееKeycloak 16 и предшествующих версийhttp://keycloak.example.com:8080/admin
. Вместоkeycloak.example.com
должен быть указан адрес вашего локального сервера, например:http://localhost:8080/admin
.http://keycloak.example.com:8080/auth/admin
. Вместоkeycloak.example.com
должен быть указан адрес вашего локального сервера, например:http://localhost:8080/auth/admin
.Параметры входа по умолчанию:
- User name or email :
admin
. - Password :
Pa55w0rd
.
- User name or email :
-
В разделе Realm Settings выберите вкладку Keys.
-
В строке RS256 нажмите Certificate и скопируйте значение сертификата.
-
Сохраните сертификат в текстовом файле с расширением
.cer
в следующем формате:-----BEGIN CERTIFICATE----- <значение_сертификата> -----END CERTIFICATE-----
Вы также можете получить сертификат по прямой ссылке:
Keycloak 17 или новееKeycloak 16 и предшествующих версийhttp://keycloak.example.com:8080/realms/master/protocol/saml/descriptor
. Значение сертификата хранится в теге<ds:X509Certificate>...</ds:X509Certificate>
.http://keycloak.example.com:8080/auth/realms/master/protocol/saml/descriptor
. Значение сертификата хранится в теге<ds:X509Certificate>...</ds:X509Certificate>
. -
Создание и настройка федерации в Yandex Cloud Organization
Создайте федерацию
-
Перейдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
В правом верхнем углу страницы нажмите кнопку
Создать федерацию. В открывшемся окне:-
Задайте имя федерации. Имя должно быть уникальным в каталоге.
-
При необходимости добавьте описание.
-
В поле Время жизни cookie укажите время, в течение которого браузер не будет требовать у пользователя повторной аутентификации.
-
В поле IdP Issuer вставьте ссылку вида:
-
Keycloak 17 или новее
http://<хост>:8080/realms/master
Если для IdP-сервера настроен публичный адрес
, укажите его URL. Например:http://keycloak.example.com:8080/realms/master
-
Keycloak 16 и предшествующих версий
http://<хост>:8080/auth/realms/master
Если для IdP-сервера настроен публичный адрес
, укажите его URL. Например:http://keycloak.example.com:8080/auth/realms/master
-
-
В поле Ссылка на страницу для входа в IdP вставьте ссылку вида:
-
Keycloak 17 или новее
http://<хост>:8080/realms/master/protocol/saml
Если для IdP-сервера настроен публичный адрес
, укажите его URL. Например:http://keycloak.example.com:8080/realms/master/protocol/saml
-
Keycloak 16 и предшествующих версий
http://<хост>:8080/auth/realms/master/protocol/saml
Если для IdP-сервера настроен публичный адрес
, укажите его URL. Например:http://keycloak.example.com:8080/auth/realms/master/protocol/saml
В ссылке допустимо использовать только протоколы HTTP и HTTPS.
-
-
Включите опцию Автоматически создавать пользователей, чтобы автоматически добавлять пользователя в организацию после аутентификации. Если опция отключена, федеративных пользователей потребуется добавить вручную.
Автоматически федеративный пользователь создается только при первом входе пользователя в облако. Если вы исключили пользователя из федерации, вернуть его туда можно будет только вручную.
-
Чтобы все запросы аутентификации от Yandex Cloud содержали цифровую подпись, включите опцию Подписывать запросы аутентификации. Для завершения настройки потребуется скачать и установить сертификат Yandex Cloud. Скачать сертификат можно в поле Подписывать запросы аутентификации сразу после сохранения федерации.
-
Включите опцию Принудительная повторная аутентификация (ForceAuthn) в IdP, чтобы задать значение
true
для параметра ForceAuthn в запросе аутентификации SAML. При включении этой опции IdP-провайдер запрашивает у пользователя аутентификацию по истечении сессии в Yandex Cloud. -
Нажмите кнопку Создать федерацию.
-
Если у вас еще нет интерфейса командной строки Yandex Cloud, установите и инициализируйте его.
По умолчанию используется каталог, указанный в профиле CLI. Вы можете указать другой каталог с помощью параметра --folder-name
или --folder-id
.
-
Посмотрите описание команды создания федерации:
yc organization-manager federation saml create --help
-
Создайте федерацию:
-
Keycloak 17 или новее
yc organization-manager federation saml create --name my-federation \ --organization-id <идентификатор_организации> \ --auto-create-account-on-login \ --encrypted-assertions \ --cookie-max-age 12h \ --issuer "http://<хост>:8080/realms/master" \ --sso-binding POST \ --sso-url "http://<хост>:8080/realms/master/protocol/saml" \ --force-authn
-
Keycloak 16 и предшествующих версий
yc organization-manager federation saml create --name my-federation \ --organization-id <идентификатор_организации> \ --auto-create-account-on-login \ --encrypted-assertions \ --cookie-max-age 12h \ --issuer "http://<хост>:8080/auth/realms/master" \ --sso-url "http://<хост>:8080/auth/realms/master/protocol/saml" \ --sso-binding POST \ --force-authn
Где:
-
--name
— имя федерации. Имя должно быть уникальным в каталоге. -
--organization-id
— идентификатор организации. -
--auto-create-account-on-login
— флаг, который активирует автоматическое создание новых пользователей в облаке после аутентификации на IdP-сервере.
Опция упрощает процесс заведения пользователей, но созданный таким образом пользователь не сможет выполнять никаких операций с ресурсами в облаке. Исключение — те ресурсы, на которые назначены роли публичной группеAll users
илиAll authenticated users
.Если опцию не включать, то пользователь, которого не добавили в организацию, не сможет войти в консоль управления, даже если пройдет аутентификацию на вашем IdP-сервере. В этом случае вы можете управлять списком пользователей, которым разрешено пользоваться ресурсами Yandex Cloud.
-
--encrypted-assertions
— флаг, который включает цифровую подпись запросов аутентификации. Для завершения настройки потребуется скачать и установить сертификат Yandex Cloud. -
--cookie-max-age
— время, в течение которого браузер не должен требовать у пользователя повторной аутентификации. -
--issuer
— идентификатор IdP-сервера, на котором должна происходить аутентификация:-
Keycloak 17 или новее
http://<хост>:8080/realms/master
Если для IdP-сервера настроен публичный адрес
, укажите его URL. Например:http://keycloak.example.com:8080/realms/master
-
Keycloak 16 и предшествующих версий
http://<хост>:8080/auth/realms/master
Если для IdP-сервера настроен публичный адрес
, укажите его URL. Например:http://keycloak.example.com:8080/auth/realms/master
-
-
--sso-url
— URL-адрес страницы, на которую браузер должен перенаправить пользователя для аутентификации:-
Keycloak 17 или новее
http://<хост>:8080/realms/master/protocol/saml
Если для IdP-сервера настроен публичный адрес
, укажите его URL. Например:http://keycloak.example.com:8080/realms/master/protocol/saml
-
Keycloak 16 и предшествующих версий
http://<хост>:8080/auth/realms/master/protocol/saml
Если для IdP-сервера настроен публичный адрес
, укажите его URL. Например:http://keycloak.example.com:8080/auth/realms/master/protocol/saml
В ссылке допустимо использовать только протоколы HTTP и HTTPS.
-
-
--sso-binding
— укажите тип привязки для Single Sign-on. Большинство поставщиков поддерживают тип привязкиPOST
. -
(Опционально)
force-authn
— при истечении сессии в Yandex Cloud поставщик удостоверений запросит у пользователя повторную аутентификацию.
-
-
-
Создайте файл с телом запроса, например
body.json
:-
Keycloak 17 или новее
{ "name": "my-federation", "organizationId": "<идентификатор_организации>", "autoCreateAccountOnLogin": true, "cookieMaxAge":"43200s", "issuer": "http://<хост>:8080/realms/master", "ssoUrl": "http://<хост>:8080/realms/master/protocol/saml", "securitySettings": { "encryptedAssertions": true, "forceAuthn": true }, "ssoBinding": "POST" }
-
Keycloak 16 и предшествующих версий
{ "name": "my-federation", "organizationId": "<идентификатор_организации>", "autoCreateAccountOnLogin": true, "cookieMaxAge":"43200s", "issuer": "http://<хост>:8080/auth/realms/master", "ssoUrl": "http://<хост>:8080/auth/realms/master/protocol/saml", "securitySettings": { "encryptedAssertions": true, "forceAuthn": true }, "ssoBinding": "POST" }
Где:
-
name
— имя федерации. Имя должно быть уникальным в каталоге. -
organizationId
— идентификатор организации. -
autoCreateAccountOnLogin
— флаг, который активирует автоматическое создание новых пользователей в облаке после аутентификации на IdP-сервере.
Опция упрощает процесс заведения пользователей, но созданный таким образом пользователь не сможет выполнять никаких операций с ресурсами в облаке. Исключение — те ресурсы, на которые назначены роли публичной группеAll users
илиAll authenticated users
.Если опцию не включать, то пользователь, которого не добавили в организацию, не сможет войти в консоль управления, даже если пройдет аутентификацию на вашем IdP-сервере. В этом случае вы можете управлять списком пользователей, которым разрешено пользоваться ресурсами Yandex Cloud.
-
cookieMaxAge
— время, в течение которого браузер не должен требовать у пользователя повторной аутентификации. -
issuer
— идентификатор IdP-сервера, на котором должна происходить аутентификация:-
Keycloak 17 или новее
http://<хост>:8080/realms/master
Если для IdP-сервера настроен публичный адрес
, укажите его URL. Например:http://keycloak.example.com:8080/realms/master
-
Keycloak 16 и предшествующих версий
http://<хост>:8080/auth/realms/master
Если для IdP-сервера настроен публичный адрес
, укажите его URL.Например:
http://keycloak.example.com:8080/auth/realms/master
-
-
ssoUrl
— URL-адрес страницы, на которую браузер должен перенаправить пользователя для аутентификации:-
Keycloak 17 или новее
http://<хост>:8080/realms/master/protocol/saml
Если для IdP-сервера настроен публичный адрес
, укажите его URL. Например:http://keycloak.example.com:8080/realms/master/protocol/saml
-
Keycloak 16 и предшествующих версий
http://<хост>:8080/auth/realms/master/protocol/saml
Если для IdP-сервера настроен публичный адрес
, укажите его URL. Например:http://keycloak.example.com:8080/auth/realms/master/protocol/saml
В ссылке допустимо использовать только протоколы HTTP и HTTPS.
-
-
encryptedAssertions
— флаг, который включает цифровую подпись запросов аутентификации. Для завершения настройки потребуется скачать и установить сертификат Yandex Cloud. -
forceAuthn
— параметр, который включает принудительную повторную аутентификацию пользователя по истечении сессии в Yandex Cloud. -
ssoBinding
— укажите тип привязки для Single Sign-on. Большинство поставщиков поддерживают тип привязкиPOST
.
-
-
-
Чтобы создать федерацию, воспользуйтесь методом 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
указан идентификатор созданной федерации: сохраните его, он понадобится в дальнейшем.
Если у вас еще нет Terraform, установите его и настройте провайдер Yandex Cloud.
-
В конфигурационном файле опишите параметры федерации:
-
name
— имя федерации. Имя должно быть уникальным в каталоге. -
description
— описание федерации. -
organization_id
— идентификатор организации. -
labels
— набор пар меток ключ/значение, которые присвоены федерации. -
issuer
— идентификатор IdP-сервера, на котором должна происходить аутентификация:-
Keycloak 17 или новее
http://<хост>:8080/realms/master
Если для IdP-сервера настроен публичный адрес
, укажите его идентификатор. Например:http://keycloak.example.com:8080/realms/master
-
Keycloak 16 и предшествующих версий
http://<хост>:8080/auth/realms/master
Если для IdP-сервера настроен публичный адрес
, укажите его идентификатор. Например:http://keycloak.example.com:8080/auth/realms/master
-
-
sso_binding
— укажите тип привязки для Single Sign-on. Большинство поставщиков поддерживают тип привязкиPOST
. -
sso_url
— URL-адрес страницы, на которую браузер должен перенаправить пользователя для аутентификации:-
Keycloak 17 или новее
http://<хост>:8080/realms/master/protocol/saml
Если для IdP-сервера настроен публичный адрес
, укажите его URL.Например:
http://keycloak.example.com:8080/realms/master/protocol/saml
-
Keycloak 16 и предшествующих версий
http://<хост>:8080/auth/realms/master/protocol/saml
Если для IdP-сервера настроен публичный адрес
, укажите его URL.Например:
http://keycloak.example.com:8080/auth/realms/master/protocol/saml
В ссылке допустимо использовать только протоколы 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.
Пример структуры конфигурационного файла
-
Keycloak 17 или новее
resource "yandex_organizationmanager_saml_federation" federation { name = "my-federation" organization_id = "<идентификатор_организации>" auto_create_account_on_login = "true" issuer = "http://<хост>:8080/auth/realms/master" sso_url = "http://<хост>:8080/auth/realms/master/protocol/saml" sso_binding = "POST" security_settings { encrypted_assertions = "true" } }
-
Keycloak 16 и предшествующих версий
resource "yandex_organizationmanager_saml_federation" federation { name = "my-federation" organization_id = "<идентификатор_организации>" auto_create_account_on_login = "true" issuer = "http://<хост>:8080/realms/master" sso_url = "http://<хост>:8080/realms/master/protocol/saml" sso_binding = "POST" security_settings { encrypted_assertions = "true" } }
-
-
Проверьте корректность конфигурационных файлов.
- В командной строке перейдите в папку, где вы создали конфигурационный файл.
- Выполните проверку с помощью команды:
terraform plan
Если конфигурация описана верно, в терминале отобразятся параметры федерации. Если в конфигурации есть ошибки, Terraform на них укажет.
-
Создайте федерацию.
- Если в конфигурации нет ошибок, выполните команду:
terraform apply
- Подтвердите создание федерации.
После этого в указанной организации будет создана федерация. Проверить появление федерации и ее настроек можно в организации в разделе Федерации
Добавьте сертификаты
При аутентификации у сервиса 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 попробует проверить подпись другим сертификатом.
Создание и настройка SAML-приложения в Keycloak
В роли поставщика удостоверений (IdP) выступает SAML-приложение в Keycloak. Чтобы создать и настроить SAML-приложение:
-
Войдите в аккаунт администратора Keycloak по адресу:
Keycloak 17 или новееKeycloak 16 и предшествующих версийhttp://keycloak.example.com:8080/admin
. Вместоkeycloak.example.com
должен быть указан адрес вашего локального сервера, например:http://localhost:8080/admin
.http://keycloak.example.com:8080/auth/admin
. Вместоkeycloak.example.com
должен быть указан адрес вашего локального сервера, например:http://localhost:8080/auth/admin
.Параметры входа по умолчанию:
- User name or email :
admin
. - Password :
Pa55w0rd
.
- User name or email :
-
Создайте SAML-приложение:
Keycloak 19 или новееKeycloak 18 и предшествующих версий-
На панели слева выберите Clients. Нажмите кнопку Create client.
-
В поле Client ID укажите ACS URL, на который пользователи будут перенаправляться после аутентификации.
Как получить ID федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля Идентификатор.
Как получить ACS URL федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля ACS URL.
-
-
В поле Client type выберите вариант saml.
-
Нажмите Save.
-
На панели слева выберите Clients. Нажмите кнопку Create.
-
В поле Client ID укажите ACS URL, на который пользователи будут перенаправляться после аутентификации.
Как получить ID федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля Идентификатор.
Как получить ACS URL федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля ACS URL.
-
-
В поле Client Protocol выберите вариант saml.
-
Нажмите Save.
-
-
Настройте параметры SAML-приложения на вкладке Settings:
-
Укажите ACS URL для перенаправления, в полях:
Keycloak версии 19 или новееKeycloak 18 и предшествующих версий- Home URL;
- Valid Redirect URIs;
- IDP Initiated SSO Relay State.
- Valid Redirect URIs;
- Base URL;
- IDP Initiated SSO Relay State.
Как получить ACS URL федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля ACS URL.
-
Включите опции:
- Include AuthnStatement;
- Sign Assertions;
- Force POST Binding;
- Front Channel Logout.
-
В поле Signature Algorithm выберите RSA_SHA256.
-
В поле SAML Signature Key Name выберите CERT_SUBJECT.
-
В качестве Name ID Format выберите подходящий вариант из списка. Чтобы выбранный вариант передавался вне зависимости от настроек Yandex Cloud Organization, включите опцию Force Name ID format.
-
Нажмите кнопку Save.
-
-
Если при создании федерации в Yandex Cloud Organization вы включили опцию Подписывать запросы аутентификации, настройте в SAML-приложении проверку цифровой подписи:
Keycloak 19 или новееKeycloak 18 и предшествующих версий-
На вкладке Keys SAML-приложения включите опции Encrypt Assertions, опция Client Signature Required должна быть выключена.
-
Для опций Client Signature Required нужно выбрать метод Import.
-
В поле Archive Format выберите Certificate PEM. (возможно понадобится сначала сгенерировать сертификаты, чтобы после нажатия кнопки Import key стал доступен вариант Certificate PEM)
-
Нажмите кнопку Browse и выберите сертификат для подписи запросов аутентификации. Сертификат доступен на странице сведений о федерации в Yandex Cloud Organization в поле Подписывать запросы аутентификации.
-
Нажмите Confirm.
-
В настройках SAML-приложения включите опции Encrypt Assertions и Client Signature Required и сохраните приложение, чтобы обновить доступные вкладки.
-
На вкладке Keys SAML-приложения в разделах Signing Key и Encryption Key нажмите кнопку Import.
-
В поле Archive Format выберите Certificate PEM.
-
Нажмите кнопку Select file и выберите сертификат для подписи запросов аутентификации. Сертификат доступен на странице сведений о федерации в Yandex Cloud Organization в поле Подписывать запросы аутентификации.
-
Нажмите Import.
-
-
Добавьте пользователей:
-
На панели слева выберите Users.
-
Нажмите Add user и введите данные пользователя.
-
Нажмите кнопку Save.
-
На вкладке Credentials нажмите Set Password и задайте пароль.
-
Добавление пользователей в Yandex Cloud Organization
Если при создании федерации вы не включили опцию Автоматически создавать пользователей, федеративных пользователей нужно добавить в организацию вручную.
Для этого вам понадобятся пользовательские 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
Настройка сопоставления атрибутов пользователей
После аутентификации IdP-сервер отправит пользователю через браузер SAML-сообщение, которое будет содержать:
-
информацию об успешной аутентификации;
-
атрибуты пользователя, такие как список ролей, имя, фамилия и адрес электронной почты.
Вы можете настроить сопоставление между атрибутами SAML-сообщения и персональными данными, которые хранятся на IdP-сервере. Для этого:
-
Включите опцию сопоставления ролей поставщика удостоверений и Yandex Cloud Organization:
-
На панели слева выберите Client Scopes → role_list.
-
Перейдите на вкладку Mappers и выберите role list.
-
Включите опцию Single Role Attribute.
-
-
Настройте атрибуты, которые будут передаваться в Yandex Cloud:
Keycloak 19 или новееKeycloak 18 и предшествующих версий-
На панели слева выберите Client и откройте настройки вашего SAML-приложения → role_list.
-
На вкладке Client Scopes выберите напротив пункта role_list значение optional и нажмите на строку с одноименным названием вашего клиента
-
В открывшемся окне нажмите кнопку Add predefined mappers.
-
Отметьте атрибуты в списке и нажмите кнопку Add. В Keycloak по умолчанию доступны атрибуты пользователя:
X500 email
— адрес электронной почты;X500 surname
— фамилия;X500 givenName
— имя;role list
— перечень ролей.
-
Вы можете создать дополнительные атрибуты для пользователей, например номер телефона. Для этого нажмите Add mappers -> By configuration -> User Property, в таблице Configure a new mapper выберите пункт User Attribute и введите параметры атрибута.
-
Настройте синхронизацию атрибутов Keycloak и Yandex Cloud Organization: откройте атрибут и измените значение SAML Attribute Name. Значения SAML Attribute Name, которые поддерживаются в Yandex Cloud Organization, приведены ниже.
-
На панели слева выберите Clients и откройте настройки вашего SAML-приложения.
-
На вкладке Mappers нажмите кнопку Add Builtins.
-
Отметьте атрибуты в списке и нажмите кнопку Add selected. В Keycloak по умолчанию доступны атрибуты пользователя:
X500 email
— адрес электронной почты;X500 surname
— фамилия;X500 givenName
— имя;role list
— перечень ролей.
-
Вы можете создать дополнительные атрибуты для пользователей, например номер телефона. Для этого нажмите Create, в поле Mapper Type выберите опцию User Attribute и введите параметры атрибута.
-
Настройте синхронизацию атрибутов Keycloak и Yandex Cloud Organization: откройте атрибут и измените значение SAML Attribute Name. Значения SAML Attribute Name, которые поддерживаются в Yandex Cloud Organization, приведены ниже.
-
-
Если вы создали дополнительные атрибуты, добавьте их в параметры пользователя:
-
На панели слева выберите Users, откройте параметры пользователя и перейдите на вкладку Attributes.
-
В поле Key укажите значение Name, которые было присвоено дополнительному атрибуту.
-
В поле Value введите данные пользователя, которые будут передаваться в атрибуте.
Примечание
По умолчанию для поля Value установлено ограничение в 256 символов. Атрибуты могут содержать большее количество символов — например, аватар в кодировке Base64. Чтобы добавить такое значение, измените тип данных поля во внутреннем хранилище Keycloak в таблице
user_attribute
. -
Нажмите Add и затем Save.
-
Данные пользователя | Комментарий | SAML Attribute Name |
---|---|---|
Фамилия | Используется для поиска в сервисах Yandex Cloud. Ограничение значения по длине: 64 символа. |
lastName |
Имя | Используется для поиска в сервисах Yandex Cloud. Ограничение значения по длине: 64 символа. |
firstName |
Полное имя | Отображается в сервисах Yandex Cloud. Ограничение значения по длине: 64 символа. |
name |
Почта | Используется для отправки уведомлений из сервисов Yandex Cloud. Пример: ivanov@example.com .Ограничение значения по длине: 256 символов. |
email |
Телефон | Используется для отправки уведомлений из сервисов Yandex Cloud. Пример: +71234567890. Ограничение значения по длине: 64 символа. |
phone |
Аватар | Отображается в сервисах Yandex Cloud. Изображение должно быть представлено в символьном формате Base64. Ограничение значения по длине: 204800 символов. |
thumbnailPhoto |
Членство в группах | Используется для функционала динамического сопоставления членства в группах. | member |
Важно
Значение атрибута thumbnailPhoto
, превышающее ограничение по длине, игнорируется. Если значение другого атрибута превышает ограничения, то часть значения, выходящая за пределы ограничения, отбрасывается.
Пример сопоставления атрибутов:
Проверка аутентификации
Когда вы закончили настройку SSO, протестируйте, что все работает:
-
Откройте браузер в гостевом режиме или режиме инкогнито.
-
Перейдите по URL для входа в консоль:
https://console.yandex.cloud/federations/<ID_федерации>
Как получить ID федерации
-
Войдите в сервис Yandex Cloud Organization
. -
На панели слева выберите
Федерации. -
Выберите нужную федерацию и на странице с информацией о ней скопируйте значение поля Идентификатор.
Браузер должен перенаправить вас на страницу аутентификации в Keycloak.
-
-
Введите данные для аутентификации и нажмите кнопку Sign in.
После успешной аутентификации IdP-сервер перенаправит вас по ACS URL, который вы указали в настройках Keycloak, а после — на главную страницу консоли управления