> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebius.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration of single sign-on in Keycloak

export const provider_1 = "Keycloak"

export const entity_1 = "client"

export const entity_0 = "client"

export const provider_0 = "Keycloak"

In this tutorial, you'll learn to configure SSO in Nebius AI Cloud with [Keycloak](https://www.keycloak.org).

To configure SSO, you need access to two systems:

* Nebius AI Cloud, where you create and configure a federation.
* {provider_1}, where you create an application, make it available to the users for whom you configure SSO, and connect the {entity_1} to the federation.

After the federation and {entity_1} are set up, users can sign in to Nebius AI Cloud by using their {provider_1} credentials.

## Costs

This tutorial doesn't include any chargeable resources. The infrastructure you create is free of charge.

## Prerequisites

1. [Deploy and configure a Keycloak server](https://www.keycloak.org/guides#getting-started).
2. Make sure that your Nebius AI Cloud account is [added](/iam/authorization/groups/members) to the tenant's group of administrators. To check this, in the [web console](https://console.nebius.com), go to <Icon icon="https://mintcdn.com/nebius-ai-cloud/1Ha0sWR6e1mnIaHS/_assets/sidebar/administration.svg?fit=max&auto=format&n=1Ha0sWR6e1mnIaHS&q=85&s=e6411dc023fd6972922c0a12a59ccf21" width="16" height="16" data-path="_assets/sidebar/administration.svg" /> **Administration** → **IAM** → **Users**.
3. If you prefer not to use the [web console](https://console.nebius.com), prepare one of the other available Nebius AI Cloud interfaces:

   <Tabs>
     <Tab title="CLI">
       [Install](/cli/install) and [configure](/cli/configure) the Nebius AI Cloud CLI.
     </Tab>

     <Tab title="Terraform">
       [Install and configure](/terraform-provider/quickstart) the Nebius AI Cloud provider for Terraform.
     </Tab>
   </Tabs>

## Steps

### Create a client in Keycloak

1. Open the Keycloak admin console.

2. [Create a client](https://www.keycloak.org/docs/latest/server_admin/index.html#_client-saml-configuration):

   1. Go to **Clients** and click **Create client**.
   2. On the **General settings** step, specify the following required parameters:

      * **Client type**: `SAML`
      * **Client ID**: `https://auth.eu.nebius.com/saml2/rp/federation-id`

   Click **Next** to proceed to the **Login settings** step and specify the following parameters:

   * **Valid redirect URIs**: `https://auth.nebius.com/login/saml2/provider/federation-id`

     <Note>
       `federation-id` is used temporarily until you [create a federation](#create-a-federation-in-nebius-ai-cloud) and get its ID. After that, replace `federation-id` with the actual value.
     </Note>

   Click **Save** to create the client.

3. Open the newly created client, go to the **SAML capabilities** section in the **Settings** tab and specify the following parameters:

   * **Force POST binding**: `On`
   * **Include AuthnStatement**: `On`

4. In the **Signature and Encryption** section, specify the following parameters:

   * **Sign documents**: `On`
   * **Signature algorithm**: `RSA_SHA256`

### Download the SAML metadata file from Keycloak

1. Go to the **Realm settings** section in the Keycloak admin console.
2. On the **General** tab, find the **Endpoints** section and click **SAML 2.0 Identity Provider Metadata**.
3. In the browser tab that opens, save the XML file with metadata (for example, by using **Command** + **S** on macOS or **Ctrl** + **S** on Windows).

### Create a federation in Nebius AI Cloud

1. To create a federation:

   <Tabs>
     <Tab title="Web console">
       1. In the sidebar, go to <Icon icon="https://mintcdn.com/nebius-ai-cloud/1Ha0sWR6e1mnIaHS/_assets/sidebar/administration.svg?fit=max&auto=format&n=1Ha0sWR6e1mnIaHS&q=85&s=e6411dc023fd6972922c0a12a59ccf21" width="16" height="16" data-path="_assets/sidebar/administration.svg" /> **Administration** → **IAM**.

       2. Click **Create entity** and select **Federation**.

       3. Enter your federation name and click **Upload file**.

       4. Select the XML file you saved in the [previous step](#download-the-saml-metadata-file-from-keycloak) and click **Continue**.

       5. Enter a name for your certificate in the **Certificates** section and click **Create federation**.

          Copy the ID of the newly created federation.
     </Tab>

     <Tab title="CLI">
       1. Run the following command:

          ```bash theme={null}
          nebius iam federation create \
            --parent-id <tenant_ID> \
            --name <federation_name> \
            --user-account-auto-creation=true \
            --saml-settings-sso-url <Login_URL> \
            --saml-settings-idp-issuer <Identity_Provider_Identifier>
          ```

          The command contains the following parameters:

          * `--parent-id`: [Tenant ID](/iam/get-tenants#cli).

          * `--name`: The federation name.

          * `--user-account-auto-creation`: When the user signs in to Nebius AI Cloud via SSO, their account is automatically created in the tenant with the configured federation.

          * `--saml-settings-sso-url`: Keycloak login URL.

          * `--saml-settings-idp-issuer`: Keycloak identifier.

            To get values for `--saml-settings-sso-url` and `--saml-settings-idp-issuer`:

            1. Open the XML file with metadata that you saved in the [previous step](#download-the-saml-metadata-file-from-keycloak).

            2. In the `EntityDescriptor` element, find the `entityID` attribute and use its value for `--saml-settings-idp-issuer`.

            3. In one of the `SingleSignOnService` elements, find the `Location` parameter and use its value for `--saml-settings-sso-url`.

       2. Copy and save the federation ID. It is returned in the `metadata.id` field of the command output.
     </Tab>

     <Tab title="Terraform">
       1. Create the following configuration file:

          ```hcl theme={null}
          resource "nebius_iam_v1_federation" "<federation_name>" {
            name                       = "<federation_name>"
            parent_id                  = "<tenant_ID>"
            user_account_auto_creation = true
            saml_settings = {
              sso_url    = "<login_URL>"
              idp_issuer = "<Keycloak_identifier>"
            }
          }

          output "federation_id" {
            description = "ID of the created federation"
            value = nebius_iam_v1_federation.<federation_name>.id
          }
          ```

          The file contains a resource with federation settings and an output that returns the federation ID. The resource contains the following parameters:

          * `name`: The federation name.

          * `parent_id`: [Tenant ID](/iam/get-tenants).

          * `user_account_auto_creation`: When the user signs in to Nebius AI Cloud via SSO, their account is automatically created in the tenant with the configured federation.

          * `saml_settings.sso_url`: Keycloak login URL.

          * `saml_settings.idp_issuer`: Keycloak identifier.

            To get values for `saml_settings.sso_url` and `saml_settings.idp_issuer`:

            1. Open the XML file with metadata that you saved in the [previous step](#download-the-saml-metadata-file-from-keycloak).

            2. In the `EntityDescriptor` element, find the `entityID` attribute and use its value for `saml_settings.idp_issuer`.

            3. In one of the `SingleSignOnService` elements, find the `Location` parameter and use its value for `saml_settings.sso_url`.

       2. Check that the configuration is correct:
          ```bash theme={null}
          terraform validate
          ```

       3. Apply the changes:
          ```bash theme={null}
          terraform apply
          ```

       4. Copy and save the federation ID. It is returned in the `terraform apply` output:

          ```text theme={null}
          Outputs:

          federation_id = "federation-e00*******"
          ```
     </Tab>
   </Tabs>

2. Update the SSO settings of your client in the Keycloak admin console:

   1. Go to **Clients** and open your client page.
   2. On the **Settings** tab, find the **Client ID** and **Valid redirect URIs** fields and replace the `federation-id` part of the values with the copied federation ID.

### Add a certificate to the federation

<Note>
  If you used the [web console](https://console.nebius.com) to create a federation, you can skip this part and proceed to the [next step](#log-in-to-nebius-ai-cloud).
</Note>

Add the certificate from the metadata file you obtained in the [previous step](#download-the-saml-metadata-file-from-keycloak) to the federation:

<Tabs>
  <Tab title="CLI">
    1. Prepare the `federation-cert.json` file:

       ```json theme={null}
       {
          "metadata": {
             "parent_id": "<federation_ID>"
          },
          "spec": {
             "description": "certificate for a federation",
             "data": "-----BEGIN CERTIFICATE-----\n<certificate_body>\n-----END CERTIFICATE-----\n"
          }
       }
       ```

       Specify the federation ID and the certificate body from the downloaded XML file.

       In this file, the certificate body is stored in the `X509Certificate` element. Paste it as a single line to `federation-cert.json`.

    2. Apply the certificate file:

       ```bash theme={null}
       nebius iam federation-certificate create --file federation-cert.json
       ```
  </Tab>

  <Tab title="Terraform">
    1. Prepare the certificate file in the same directory where you [store](#create-a-federation-in-nebius-ai-cloud) the `nebius_iam_v1_federation` resource:

       ```hcl theme={null}
       resource "nebius_iam_v1_federation_certificate" "certificate-for-<federation_name>" {
          parent_id   = "<federation_ID>"
          name        = "certificate"
          data        = <<EOT
       -----BEGIN CERTIFICATE-----
       <certificate_body>
       -----END CERTIFICATE-----
       EOT
          description = "certificate for a federation"
          depends_on = [
             nebius_iam_v1_federation.<federation_name>
          ]
       }
       ```

       Specify the following:

       * Federation name
       * Federation ID
       * Certificate body from the downloaded XML file

         In this file, the certificate body is stored in the `X509Certificate` element.

    2. Check that the configuration is correct:
       ```bash theme={null}
       terraform validate
       ```

    3. Apply the changes:
       ```bash theme={null}
       terraform apply
       ```
  </Tab>
</Tabs>

### Log in to Nebius AI Cloud

1. Open the [Nebius AI Cloud web console](https://console.nebius.com).
2. Click **Get started with SSO**.
3. Enter the federation ID and click **Sign in**.
4. In the **Contact details** window that opens:

   1. Specify your name and email.
   2. Confirm that you agree with the [Nebius AI Cloud Terms of Use](/legal/terms-of-use).
   3. Click **Continue**.

A successful login means that you have correctly configured the federation and {entity_0} in Nebius AI Cloud and {provider_0}.

### Assign administrator rights for the new account

After your first login to the new federation, a new user account is created in the tenant.

To complete the setup and grant the new user account access to the platform, add it to a group with admin rights in Nebius AI Cloud:

1. Log out of your new account in the [web console](https://console.nebius.com).
2. Log in to your main Nebius AI Cloud account.
3. Go to <Icon icon="https://mintcdn.com/nebius-ai-cloud/1Ha0sWR6e1mnIaHS/_assets/sidebar/administration.svg?fit=max&auto=format&n=1Ha0sWR6e1mnIaHS&q=85&s=e6411dc023fd6972922c0a12a59ccf21" width="16" height="16" data-path="_assets/sidebar/administration.svg" /> **Administration** → **IAM** → **Users** and [add](../authorization/groups/members) the new user to the relevant admin group.