Configuration of single sign-on in Keycloak

In this tutorial, you’ll learn to configure SSO in Nebius AI Cloud with Keycloak. To configure SSO, you need access to two systems:

Nebius AI Cloud, where you create and configure a federation.
Keycloak, where you create a client, make it available to the users for whom you configure SSO, and connect the client to the federation.

After the federation and client are set up, users can sign in to Nebius AI Cloud by using their Keycloak credentials.

Costs

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

Prerequisites

Deploy and configure a Keycloak server.
Make sure that your Nebius AI Cloud account is added to the tenant’s group of administrators. To check this, in the web console, go to Administration → IAM → Users.
If you prefer not to use the web console, prepare one of the other available Nebius AI Cloud interfaces:
- CLI
- Terraform
Install and configure the Nebius AI Cloud CLI.
Install and configure the Nebius AI Cloud provider for Terraform.

Steps

Create a client in Keycloak

Open the Keycloak admin console.
Create a client:
1. In the admin console, 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
  federation-id is used temporarily until you create a federation and get its ID. After that, replace federation-id with the actual value.
Click Save to create the client.
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
In the Signature and Encryption section, specify the following parameters:
- Sign documents: On
- Signature algorithm: RSA_SHA256

Download the SAML metadata file from Keycloak

Go to the Realm settings section in the Keycloak admin console.
On the General tab, find the Endpoints section and click SAML 2.0 Identity Provider Metadata.
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

To create a federation:
- Web console
- CLI
- Terraform
1. In the sidebar, go to 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 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.
1. Run the following command:
  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: The ID of the tenant where you are going to create a federation. To get the tenant ID, go to the web console and expand a top-left list of projects. Next to the tenant’s name, click → Copy tenant ID.
  
  --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:
  
  Open the XML file with metadata that you saved in the previous step.
  
  In the EntityDescriptor element, find the entityID attribute and use its value for --saml-settings-idp-issuer.
  
  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.
1. Create the following configuration file:
  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: The ID of the tenant where you are going to create a federation. To get the tenant ID, go to the web console and expand a top-left list of projects. Next to the tenant’s name, click → Copy tenant ID.
  
  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:
  
  Open the XML file with metadata that you saved in the previous step.
  
  In the EntityDescriptor element, find the entityID attribute and use its value for saml_settings.idp_issuer.
  
  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:
  terraform validate
3. Apply the changes:
  terraform apply
4. Copy and save the federation ID. It is returned in the terraform apply output:
  Outputs: federation_id = "federation-e00*******"
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

If you used the web console to create a federation, you can skip this part and proceed to the next step.

Add the certificate from the metadata file you obtained in the previous step to the federation:

CLI
Terraform

Prepare the federation-cert.json file:

{
   "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.

Apply the certificate file:

nebius iam federation-certificate create --file federation-cert.json

Prepare the certificate file in the same directory where you store the nebius_iam_v1_federation resource:

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.

Check that the configuration is correct:
```
terraform validate
```
Apply the changes:
```
terraform apply
```

Log in to Nebius AI Cloud

Open the Nebius AI Cloud web console.
Click the Get started with SSO button.
Enter the federation ID and click the Sign in button.
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.
3. Click the Continue button.

A successful login means that you have correctly configured the federation and client in Nebius AI Cloud and Keycloak.

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:

Log out of your new account in the web console.
Log in to your main Nebius AI Cloud account.
Go to Administration → IAM → Users and add the new user to the relevant admin group.

Nebius AI Cloud signup and payments

Identity and Access Management in Nebius AI Cloud

Overview of Nebius AI Cloud

Configuration of single sign-on in Keycloak

Costs

Prerequisites

Steps

Create a client in Keycloak

Download the SAML metadata file from Keycloak

Create a federation in Nebius AI Cloud

Add a certificate to the federation

Log in to Nebius AI Cloud

Assign administrator rights for the new account

Nebius AI Cloud signup and payments

Identity and Access Management in Nebius AI Cloud

Overview of Nebius AI Cloud

​Costs

​Prerequisites

​Steps

​Create a client in Keycloak

​Download the SAML metadata file from Keycloak

​Create a federation in Nebius AI Cloud

​Add a certificate to the federation

​Log in to Nebius AI Cloud

​Assign administrator rights for the new account

Costs

Prerequisites

Steps

Create a client in Keycloak

Download the SAML metadata file from Keycloak

Create a federation in Nebius AI Cloud

Add a certificate to the federation

Log in to Nebius AI Cloud

Assign administrator rights for the new account