Аутентификация с помощью Keycloak

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

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

1. Посмотрите описание команды создания федерации:

   yc organization-manager federation saml create --help
   

2. Создайте федерацию:

   • 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 поставщик удостоверений запросит у пользователя повторную аутентификацию.

1. Создайте файл с телом запроса, например 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.

2. Чтобы создать федерацию, воспользуйтесь методом 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.

1. В конфигурационном файле опишите параметры федерации.

   Пример структуры конфигурационного файла:

   • Keycloak 17 или новее

     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"
         force_authn          = "true"
       }
     }
     

   • Keycloak 16 и предшествующих версий

     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"
         force_authn          = "true"
       }
     }
     

   Где:

   • 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 будут содержать цифровую подпись.

     • force-authn — при истечении сессии в Yandex Cloud поставщик удостоверений запросит у пользователя повторную аутентификацию. Необязательный параметр.

   Более подробную информацию о параметрах ресурса yandex_organizationmanager_saml_federation см. в документации провайдера.

2. Проверьте корректность конфигурационных файлов.

   1. В командной строке перейдите в папку, где вы создали конфигурационный файл.

   2. Выполните проверку с помощью команды:

      terraform plan
      

      Если конфигурация описана верно, в терминале отобразятся параметры федерации. Если в конфигурации есть ошибки, Terraform на них укажет.

3. Создайте федерацию.

   1. Если в конфигурации нет ошибок, выполните команду:

      terraform apply
      

   2. Подтвердите создание федерации.

После этого в указанной организации будет создана федерация. Проверить появление федерации и ее настроек можно в организации в разделе Федерации.

Если у вас еще нет интерфейса командной строки 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-id <ID_федерации> \
     --name "my-certificate" \
     --certificate-file certificate.cer
   

Воспользуйтесь методом create для ресурса Certificate:

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

   {
     "federationId": "<ID_федерации>",
     "name": "my-certificate",
     "data": "-----BEGIN CERTIFICATE..."
   }
   

2. Отправьте запрос на добавление сертификата:

   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 (CLI), установите и инициализируйте его.

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

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

   yc organization-manager federation saml add-user-accounts --help
   

2. Добавьте пользователей, перечислив их 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 пользователей.

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

1. Сформируйте файл с телом запроса, например body.json. В теле запроса укажите массив Name ID пользователей, которых необходимо добавить:

   {
     "nameIds": [
       "alice@example.com",
       "bob@example.com",
       "charlie@example.com"
     ]
   }
   

2. Отправьте запрос, указав в параметрах идентификатор федерации:

   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