Configuring single sign-on with a SAML identity provider

In this tutorial, you’ll learn to configure single sign-on (SSO) in Nebius AI Cloud with an identity provider that supports SAML 2.0. The names of settings and sections depend on the identity provider, but the SAML values that Nebius AI Cloud requires are the same. To configure SSO, you need access to two systems:

Nebius AI Cloud, where you create and configure a federation.
An identity provider, where you create a SAML application, make it available to the users for whom you configure SSO and connect it to the federation.

After the federation and SAML application are set up, users can sign in to Nebius AI Cloud by using their identity provider credentials.

Costs

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

Prerequisites

Make sure you are in a group that has the admin role within your tenant or project; for example, the default admins group. You can check this in the Administration → IAM section of the web console.
Make sure that you have access to an identity provider that supports SAML 2.0 and permissions to create and configure SAML applications.

Install and configure the Nebius AI Cloud CLI.
Make sure you are in a group that has the admin role within your tenant or project; for example, the default admins group. You can check this in the Administration → IAM section of the web console.
Make sure that you have access to an identity provider that supports SAML 2.0 and permissions to create and configure SAML applications.

Install and configure the Nebius AI Cloud provider for Terraform.
Make sure you are in a group that has the admin role within your tenant or project; for example, the default admins group. You can check this in the Administration → IAM section of the web console.
Make sure that you have access to an identity provider that supports SAML 2.0 and permissions to create and configure SAML applications.

Install and initialize the Nebius SDK for Go.
Make sure you are in a group that has the admin role within your tenant or project; for example, the default admins group. You can check this in the Administration → IAM section of the web console.
Make sure that you have access to an identity provider that supports SAML 2.0 and permissions to create and configure SAML applications.

Install and initialize the Nebius SDK for Python.
Make sure you are in a group that has the admin role within your tenant or project; for example, the default admins group. You can check this in the Administration → IAM section of the web console.
Make sure that you have access to an identity provider that supports SAML 2.0 and permissions to create and configure SAML applications.

Install and initialize the Nebius SDK for JavaScript.
Make sure you are in a group that has the admin role within your tenant or project; for example, the default admins group. You can check this in the Administration → IAM section of the web console.
Make sure that you have access to an identity provider that supports SAML 2.0 and permissions to create and configure SAML applications.

Steps

Create a SAML application in the identity provider

Sign in to your identity provider’s admin console.
Create a SAML 2.0 application or client for Nebius AI Cloud. In the application settings, specify the following required parameters. The names of these parameters can differ depending on the identity provider:
- Service Provider (SP) Entity ID, Audience URI or Identifier: https://auth.eu.nebius.com/saml2/rp/federation-id
- Assertion Consumer Service (ACS) URL, Reply URL or Single sign-on URL: https://auth.nebius.com/login/saml2/provider/federation-id
- Name ID format: Unspecified, if your identity provider requires this parameter.
The two values use different domain names: auth.eu.nebius.com and auth.nebius.com.federation-id is used temporarily until you create a federation and get its ID. After that, replace federation-id with the actual value.
If your identity provider lets you configure SAML response settings, use HTTP POST binding, include an AuthnStatement, enable signed responses or assertions and select the RSA-SHA256 signature algorithm.
Make the application available to the users who need SSO access to Nebius AI Cloud.

Get SAML settings from the identity provider

In the identity provider’s admin console, open the SAML application or SAML configuration that you created in the previous step.
Get the values that you need to create a federation:
- To create the federation in the web console by uploading metadata, download or open the SAML metadata XML file. If the metadata opens in a browser tab, save the page as an XML file.
- To create the federation manually in the web console, CLI, Terraform or SDK, copy the SSO URL and issuer from the application settings and download the SAML signing certificate. If your identity provider provides only a metadata XML file, use it to get the SSO URL, issuer and certificate body.

Create a federation in Nebius AI Cloud

To create a federation:
- Web console
- CLI
- Terraform
- Go SDK
- Python SDK
- JavaScript SDK
1. In the sidebar, go to Administration → IAM.
2. Click Create entity and select Federation.
3. Enter your federation name.
4. If you have a metadata file, click Upload file, select the XML file that you downloaded in the previous step and click Continue.
5. If you don’t have a metadata file, enable Manual mode and specify the following parameters under Identity provider (IdP):
  
  SSO URL: Identity provider login URL.
  
  Issuer: Identity provider issuer or identifier.
6. Enter a name for your certificate in the Certificates section. If you created the federation in manual mode, upload the SAML signing certificate from your identity provider.
7. 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: 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: Identity provider login URL.
  
  --saml-settings-idp-issuer: Identity provider issuer or identifier. Use the SSO URL and issuer that you copied from the application settings. If your identity provider provides only a metadata XML file, get the values from it:
  
  Open the XML file with metadata that you downloaded or opened 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 = "<identity_provider_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.
  
  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: Identity provider login URL.
  
  saml_settings.idp_issuer: Identity provider issuer or identifier. Use the SSO URL and issuer that you copied from the application settings. If your identity provider provides only a metadata XML file, get the values from it:
  
  Open the XML file with metadata that you downloaded or opened 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*******"
1. Run the following code:
  federationOp, err := sdk.Services().IAM().V1(). Federation().Create( ctx, &iam.CreateFederationRequest{ Metadata: &common.ResourceMetadata{ ParentId: "<tenant_ID>", Name: "<federation_name>", }, Spec: &iam.FederationSpec{ UserAccountAutoCreation: true, Settings: &iam.FederationSpec_SamlSettings{ SamlSettings: &iam.SamlSettings{ SsoUrl: "<login_URL>", IdpIssuer: "<identity_provider_identifier>", }, }, }, }, ) if err != nil { return err } if _, err = federationOp.Wait(ctx); err != nil { return err }
  In the code, set the following parameters:
  
  Metadata.ParentId: Tenant ID.
  
  Metadata.Name: The federation name.
  
  Spec.UserAccountAutoCreation: When the user signs in to Nebius AI Cloud via SSO, their account is automatically created in the tenant with the configured federation.
  
  Spec.Settings.SamlSettings.SsoUrl: Identity provider login URL.
  
  Spec.Settings.SamlSettings.IdpIssuer: Identity provider issuer or identifier. Use the SSO URL and issuer that you copied from the application settings. If your identity provider provides only a metadata XML file, get the values from it:
  
  Open the XML file with metadata that you downloaded or opened in the previous step.
  
  In the EntityDescriptor element, find the entityID attribute and use its value for Spec.Settings.SamlSettings.IdpIssuer.
  
  In one of the SingleSignOnService elements, find the Location parameter and use its value for Spec.Settings.SamlSettings.SsoUrl.
2. Copy and save the federation ID. It is available as federationOp.ResourceID() after the operation completes.
1. Run the following code:
  federation_service = FederationServiceClient(sdk) federation_operation = await federation_service.create( CreateFederationRequest( metadata=ResourceMetadata( parent_id="<tenant_ID>", name="<federation_name>", ), spec=FederationSpec( user_account_auto_creation=True, saml_settings=SamlSettings( sso_url="<login_URL>", idp_issuer="<identity_provider_identifier>", ), ), ), ) await federation_operation.wait()
  In the code, set the following parameters:
  
  metadata.parent_id: Tenant ID.
  
  metadata.name: The federation name.
  
  spec.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.
  
  spec.saml_settings.sso_url: Identity provider login URL.
  
  spec.saml_settings.idp_issuer: Identity provider issuer or identifier. Use the SSO URL and issuer that you copied from the application settings. If your identity provider provides only a metadata XML file, get the values from it:
  
  Open the XML file with metadata that you downloaded or opened in the previous step.
  
  In the EntityDescriptor element, find the entityID attribute and use its value for spec.saml_settings.idp_issuer.
  
  In one of the SingleSignOnService elements, find the Location parameter and use its value for spec.saml_settings.sso_url.
2. Copy and save the federation ID. It is available as federation_operation.resource_id after the operation completes.
1. Run the following code:
  const federationService = new FederationService(sdk); const federationOperation = await federationService.create( CreateFederationRequest.create({ metadata: ResourceMetadata.create({ parentId: "<tenant_ID>", name: "<federation_name>", }), spec: FederationSpec.create({ userAccountAutoCreation: true, settings: { $case: "samlSettings", samlSettings: SamlSettings.create({ ssoUrl: "<login_URL>", idpIssuer: "<identity_provider_identifier>", }), }, }), }), ).result; await federationOperation.wait();
  In the code, set the following parameters:
  
  metadata.parentId: Tenant ID.
  
  metadata.name: The federation name.
  
  spec.userAccountAutoCreation: When the user signs in to Nebius AI Cloud via SSO, their account is automatically created in the tenant with the configured federation.
  
  spec.settings.samlSettings.ssoUrl: Identity provider login URL.
  
  spec.settings.samlSettings.idpIssuer: Identity provider issuer or identifier. Use the SSO URL and issuer that you copied from the application settings. If your identity provider provides only a metadata XML file, get the values from it:
  
  Open the XML file with metadata that you downloaded or opened in the previous step.
  
  In the EntityDescriptor element, find the entityID attribute and use its value for spec.settings.samlSettings.idpIssuer.
  
  In one of the SingleSignOnService elements, find the Location parameter and use its value for spec.settings.samlSettings.ssoUrl.
2. Copy and save the federation ID. It is available as federationOperation.resourceId() after the operation completes.
Update the SAML settings of the application in your identity provider:
1. Open the SAML application or client that you created in the previous step.
2. In the fields where you specified the Nebius AI Cloud SP entity ID and ACS URL, replace the federation-id part of the values with the copied federation ID.

Add a certificate to the federation

Make sure the federation has the signing certificate from the identity provider:

If you created the federation in the web console, no extra certificate step is required.To manage certificates for an existing federation:

In the sidebar, go to Administration → IAM.
Go to the Federations tab and open the federation.
On the Certificates tab:
- Rename or delete a certificate.
  A federation can’t 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.
- 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.

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 metadata XML file or certificate file. In a metadata XML 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 metadata XML file or certificate file In a metadata XML file, the certificate body is stored in the X509Certificate element.

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

Run the following code:

certificateOperation, err := sdk.Services().IAM().V1().
    FederationCertificate().Create(
        ctx,
        &iam.CreateFederationCertificateRequest{
            Metadata: &common.ResourceMetadata{
                ParentId: "<federation_ID>",
            },
            Spec: &iam.FederationCertificateSpec{
                Description: "certificate for a federation",
                Data:        certificateData,
            },
        },
    )
if err != nil {
    return err
}
if _, err = certificateOperation.Wait(ctx); err != nil {
    return err
}

In the code, set the following parameters:

Metadata.ParentId: Federation ID that you obtained when creating the federation.
certificateData: The certificate body from the downloaded metadata XML file or certificate file, wrapped in -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----. This value is passed as Spec.Data.
Spec.Description: Description of the certificate.

Run the following code:

cert_service = FederationCertificateServiceClient(sdk)
certificate_operation = await cert_service.create(
    CreateFederationCertificateRequest(
        metadata=ResourceMetadata(parent_id="<federation_ID>"),
        spec=FederationCertificateSpec(
            description="certificate for a federation",
            data=certificate_data,
        ),
    ),
)
await certificate_operation.wait()

In the code, set the following parameters:

metadata.parent_id: Federation ID that you obtained when creating the federation.
certificate_data: The certificate body from the downloaded metadata XML file or certificate file, wrapped in -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----. This value is passed as spec.data.
spec.description: Description of the certificate.

Run the following code:

const createCertificateService =
  new FederationCertificateService(sdk);
const certificateOperation = await createCertificateService.create(
  CreateFederationCertificateRequest.create({
    metadata: ResourceMetadata.create({
      parentId: "<federation_ID>",
    }),
    spec: FederationCertificateSpec.create({
      description: "certificate for a federation",
      data: certificateData,
    }),
  }),
).result;
await certificateOperation.wait();

In the code, set the following parameters:

metadata.parentId: Federation ID that you obtained when creating the federation.
certificateData: The certificate body from the downloaded metadata XML file or certificate file, wrapped in -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----. This value is passed as spec.data.
spec.description: Description of the certificate.

Log in to Nebius AI Cloud

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

A successful login means that you have correctly configured the federation and the SAML application in Nebius AI Cloud and your identity provider.

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

Configuring single sign-on with a SAML identity provider

Costs

Prerequisites

Steps

Create a SAML application in the identity provider

Get SAML settings from the identity provider

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 SAML application in the identity provider

​Get SAML settings from the identity provider

​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 SAML application in the identity provider

Get SAML settings from the identity provider

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