> ## 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.

# How to manage federations in Nebius AI Cloud

A [federation](/iam/overview#federations) connects your identity provider (IdP) to Nebius AI Cloud, allowing users from your organization to log in with [single sign-on (SSO)](/iam/federations/saml-sso).

In Nebius AI Cloud, you can create, activate and deactivate federations, change their settings, and upload or delete attached certificates.

## Prerequisites

1. Make sure you are in a [group](/iam/authorization/groups/index) that has the `admin` role within your tenant; for example, the default `admins` group. You can check this in the [Administration → IAM](https://console.nebius.com/iam) section of the web console.
2. Make sure that you have access to your IdP admin portal and can get the SAML application metadata (login URL, identifier, certificate) required to create a federation.

## Creating a federation

<Tabs group="interfaces">
  <Tab title="Web console">
    1. 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**.

    2. Go to the **Federations** tab.

    3. Click **Create entity** → **Federation**.

    4. Specify the IdP settings:

       * If you have an XML file with SAML metadata:

         1. Enter a federation name.
         2. Click **Upload file** and select the XML file with the SAML metadata from your IdP, then click **Continue**.
         3. On the page that opens, enter a name for the certificate in the **Certificates** section.

       * If you don't have an XML file, enter the SAML metadata manually:

         1. Enable **Manual mode** and enter a federation name.
         2. Under **Identity provider (IdP)**, specify the **SSO URL** and **Issuer** parameters from your IdP, then click **Continue**.
         3. On the page that opens, enter a certificate name, then either upload the PEM certificate file, or copy and paste the certificate body into the field.

    5. Click **Create federation**.
  </Tab>

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

    2. To create a federation, run the following command:

       ```bash theme={null}
       nebius iam federation create \
         --name <federation_name> \
         --parent-id <tenant_ID> \
         --saml-settings-sso-url <URL_to_log_in> \
         --saml-settings-idp-issuer <application_identifier>
       ```

       The command contains the following parameters:

       * `--name`: Federation name.
       * `--parent-id`: [ID of the tenant](/iam/get-tenants#cli) in which you create the federation.
       * `--saml-settings-sso-url`: URL of the page that opens when a federated user logs in. For example, Microsoft Entra ID calls it **Login URL**.
       * `--saml-settings-idp-issuer`: Identifier of your SAML application. For example, Microsoft Entra ID calls it **Microsoft Entra Identifier**.

    3. Copy and save the federation ID. It is returned in the `metadata.id` parameter of the command output.

    4. After you create a federation, attach a certificate to it. Prepare the `federation-cert.json` file:

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

       If the certificate body is split into several lines in the source, paste the body as a single line in `federation-cert.json`.

    5. Apply the certificate file:

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

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

    2. Create a federation:

       1. Prepare the following configuration file:

          ```hcl theme={null}
          resource "nebius_iam_v1_federation" "<federation_name>" {
             name                       = "<federation_name>"
             parent_id                  = "<tenant_ID>"
             saml_settings  = {
                sso_url     = "<URL_to_log_in>"
                idp_issuer  = "<application_identifier>"
             }
          }
          ```

          The file contains the following parameters:

          * `name`: Federation name.
          * `parent_id`: [ID of the tenant](/iam/get-tenants#cli) in which you create the federation.
          * `saml_settings.sso_url`: URL of the page that opens when a federated user logs in. For example, Microsoft Entra ID calls it **Login URL**.
          * `saml_settings.idp_issuer`: Identifier of your SAML application. For example, Microsoft Entra ID calls it **Microsoft Entra Identifier**.

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

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

    3. After you create a federation, attach a certificate to it:

       1. Prepare a certificate manifest in the same file where you store the `nebius_iam_v1_federation` resource:

          ```hcl theme={null}
          resource "nebius_iam_v1_federation_certificate" "certificate_for_<federation_name>" {
            parent_id   = nebius_iam_v1_federation.<federation_name>.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 federation name, ID and the certificate body.

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

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

For more information, see examples for specific IdPs in [Configuring SSO with identity providers](/iam/federations/saml-sso).

## Changing federation settings

<Tabs group="interfaces">
  <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. Go to the **Federations** tab.

    3. Next to the federation, click <Icon icon="https://mintcdn.com/nebius-ai-cloud/1Ha0sWR6e1mnIaHS/_assets/button-vellipsis.svg?fit=max&auto=format&n=1Ha0sWR6e1mnIaHS&q=85&s=e80b8e57c43bfd117679262e6a1334ad" width="12" height="24" data-path="_assets/button-vellipsis.svg" /> → **Configure**.

    4. Update federation settings:

       * **Name**: Federation name.
       * **SSO URL**: Login URL from your IdP.
       * **Issuer**: Your IdP identifier string.

    5. Click **Save changes** to apply the new settings.
  </Tab>

  <Tab title="CLI">
    To change federation settings, run the following command:

    ```bash theme={null}
    nebius iam federation update <federation_ID> \
      --name <new_federation_name> \
      --saml-settings-sso-url <URL_to_log_in> \
      --saml-settings-idp-issuer <application_identifier>
    ```

    You can change the following parameters:

    * `--name`: Federation name.
    * `--saml-settings-sso-url`: URL of the page that opens when a federated user logs in. For example, Microsoft Entra ID calls it **Login URL**.
    * `--saml-settings-idp-issuer`: Identifier of your SAML application. For example, Microsoft Entra ID calls it **Microsoft Entra Identifier**.

    <Accordion title="How to get the federation ID">
      ```bash theme={null}
      nebius iam federation list --parent-id <tenant_ID>
      ```

      The ID is specified in the `.items.metadata.id` parameter.
    </Accordion>
  </Tab>

  <Tab title="Terraform">
    1. Modify the manifest with the deployed federation:

       ```hcl theme={null}
       resource "nebius_iam_v1_federation" "<federation_name>" {
          name           = "<federation_name>"
          saml_settings  = {
             sso_url     = "<URL_to_log_in>"
             idp_issuer  = "<application_identifier>"
          }
          ...
       }
       ```

       You can change the following parameters:

       * `name`: Federation name.
       * `saml_settings.sso_url`: URL of the page that opens when a federated user logs in. For example, Microsoft Entra ID calls it **Login URL**.
       * `saml_settings.idp_issuer`: Identifier of your SAML application. For example, Microsoft Entra ID calls it **Microsoft Entra Identifier**.

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

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

## Changing federation certificates

<Tabs group="interfaces">
  <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. Go to the **Federations** tab and open the federation whose certificate you want to change.

    3. On the **Certificates** tab, rename or delete a certificate.

           <Warning>
             A federation cannot function correctly without at least one valid certificate. If you need to delete the only certificate attached to the federation, be sure to replace it with a new one.
           </Warning>

    4. To add a new certificate:
       1. Click **Attach certificate**.
       2. Enter a certificate name, then either upload the PEM certificate file, or copy and paste the certificate body into the field.
       3. Click **Attach certificates**.
  </Tab>

  <Tab title="CLI">
    When changing federation certificates, you can rename, add or delete a certificate.

    * Rename a certificate:

      ```bash theme={null}
      nebius iam federation-certificate update <certificate_ID> --name <new_certificate_name>
      ```

    * Delete a certificate:

      ```bash theme={null}
      nebius iam federation-certificate delete <certificate_ID>
      ```

          <Warning>
            A federation cannot function correctly without at least one valid certificate. If you need to delete the only certificate attached to the federation, be sure to replace it with a new one.
          </Warning>

    For information about adding a new certificate, see [Creating a federation](#creating-a-federation).

    <Accordion title="How to get the certificate ID">
      ```bash theme={null}
      nebius iam federation-certificate list-by-federation --federation-id <federation_ID>
      ```

      The ID is specified in the `.items.metadata.id` parameter.
    </Accordion>
  </Tab>

  <Tab title="Terraform">
    When changing federation certificates, you can rename, add or delete a certificate:

    * To rename a certificate, update the `name` parameter in the `nebius_iam_v1_federation_certificate` resource.
    * To delete a certificate, remove the `nebius_iam_v1_federation_certificate` resource from the configuration file.

          <Warning>
            A federation cannot function correctly without at least one valid certificate. If you need to delete the only certificate attached to the federation, be sure to replace it with a new one.
          </Warning>

    For information about adding a new certificate, see [Creating a federation](#creating-a-federation).
  </Tab>
</Tabs>

## Deactivating a federation

When a federation is inactive, users who authenticate through that federation will not be able to sign in to Nebius AI Cloud until it's reactivated.

<Tabs group="interfaces">
  <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. Go to the **Federations** tab.
    3. Next to the federation you want to deactivate, click <Icon icon="https://mintcdn.com/nebius-ai-cloud/1Ha0sWR6e1mnIaHS/_assets/button-vellipsis.svg?fit=max&auto=format&n=1Ha0sWR6e1mnIaHS&q=85&s=e80b8e57c43bfd117679262e6a1334ad" width="12" height="24" data-path="_assets/button-vellipsis.svg" /> → **Deactivate**.

       To reactivate the federation, click <Icon icon="https://mintcdn.com/nebius-ai-cloud/1Ha0sWR6e1mnIaHS/_assets/button-vellipsis.svg?fit=max&auto=format&n=1Ha0sWR6e1mnIaHS&q=85&s=e80b8e57c43bfd117679262e6a1334ad" width="12" height="24" data-path="_assets/button-vellipsis.svg" /> → **Activate**.
  </Tab>

  <Tab title="CLI">
    To deactivate a federation, run the following command:

    ```bash theme={null}
    nebius iam federation deactivate --federation-id <federation_ID>
    ```

    To activate a federation again, run the following command:

    ```bash theme={null}
    nebius iam federation activate --federation-id <federation_ID>
    ```

    A federation is active by default after you create it. Run the `activate` command only if you deactivated the federation earlier.

    <Accordion title="How to get the federation ID">
      ```bash theme={null}
      nebius iam federation list --parent-id <tenant_ID>
      ```

      The ID is specified in the `.items.metadata.id` parameter.
    </Accordion>
  </Tab>
</Tabs>