Authentication using a SAML-compatible identity federation
This is a common guide on how to configure authentication in the cloud through a SAML-compatible identity federation. Use this guide if there is no specific guide for your identity federation.
To set up authentication:
Getting started
To use the instructions in this section, you will need a valid certificate to sign SAML messages on the Identity Provider's (IdP) server. If you do not have a valid SSL certificate, get one.
The subject name in the certificate must contain the FQDN of the Identity Provider (IdP) server, for example, fs.contoso.com
, to prevent the browser from blocking the authentication page.
Create a federation in your organization
To create a federation:
-
Go to Cloud Organization
. -
In the left-hand panel, select Federations
. -
Click Create federation.
-
Give your federation a name. It must be unique within the folder.
-
You can also add a description, if required.
-
In the Cookie lifetime field, specify the period of time that must elapse before the browser asks the user to re-authenticate.
-
In the IdP Issuer field, specify the IdP server ID to be used for authentication. The IdP server must send the same ID in its response to Cloud Organization during user authentication.
Note
ID format depends on the type of IdP server you use (for example, Active Directory or Google Workspace).
-
In the SSO method field, choose POST.
-
In the Link to the IdP login page field, specify the address of the page that the browser redirects the user to for authentication.
You can only use HTTP and HTTPS in a link.
-
Add an identity provider certificate to the created federation.
-
Enable Automatically create users to add authenticated users to your organization automatically. If you do not enable this option, you will need to manually add your federated users.
A federated user is created automatically only when they log in to a cloud for the first time. If you deleted a user from a federation, you can only add them back manually.
-
Configure the identity provider's server to transmit successful authentication information and user attributes to Nebius AI.
User attributes supported by Cloud Organization services are listed below.
If you don't have the Nebius AI command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
-
See the description of the create federation command:
ncp organization-manager federation saml create --help
-
Create a federation:
ncp organization-manager federation saml create --name my-federation \ --organization-id <organization ID> \ --auto-create-account-on-login \ --cookie-max-age 12h \ --issuer "https://accounts.google.com/o/saml2?idpid=C03xolm0y" \ --sso-binding POST \ --sso-url "https://accounts.google.com/o/saml2/idp?idpid=C03xolm0y" \ --force-authn
Where:
-
name
: Federation name. It must be unique within the folder. -
organization-id
: Your organization ID. -
auto-create-account-on-login
: Flag to enable the automatic creation of new cloud users following authentication on the IdP server.
This option makes it easier to create users; however, users created this way will not be able to do anything with cloud resources.If this option is disabled, users who are not added to the organization cannot log in to the management console, even if they authenticate with your server. In this case, you can manage a list of users allowed to use Nebius AI resources.
-
cookie-max-age
: Time that must elapse before the browser asks the user to re-authenticate. -
issuer
: IdP server ID to be used for authentication. The IdP server also responds to Cloud Organization with this ID after the user is authenticated. -
sso-url
: URL of the page that the browser redirects the user to for authentication.You can only use HTTP and HTTPS in a link.
-
sso-binding
: Specify the Single Sign-on binding type. Most Identity Providers support thePOST
binding type. -
force-authn
: Flag that requires user re-authentication once a session expires in Nebius AI.
-
-
Create a file with the request body, e.g.,
body.json
:{ "name": "my-federation", "organizationId": "<organization ID>", "autoCreateAccountOnLogin": true, "cookieMaxAge":"43200s", "issuer": "https://accounts.google.com/o/saml2?idpid=C03xolm0y", "ssoUrl": "https://accounts.google.com/o/saml2/idp?idpid=C03xolm0y", "ssoBinding": "POST", "securitySettings": { "forceAuthn": true } }
Where:
-
name
: Federation name. It must be unique within the folder. -
organizationId
: Organization ID. -
autoCreateAccountOnLogin
: Flag to activate the automatic creation of new cloud users after authenticating on the IdP server.
This option makes it easier to create users; however, users created this way will not be able to do anything with cloud resources.If this option is disabled, users who are not added to the organization cannot log in to the management console, even if they authenticate with your server. In this case, you can manage a list of users allowed to use Nebius AI resources.
-
cookieMaxAge
: Time that must elapse before the browser asks the user to re-authenticate. -
issuer
: IdP server ID to be used for authentication. The IdP server also responds to Cloud Organization with this ID after the user is authenticated. -
ssoUrl
: URL of the page the browser redirects the user to for authentication.You can only use HTTP and HTTPS in a link.
-
ssoBinding
: Specify the Single Sign-on binding type. Most Identity Providers support thePOST
binding type. -
forceAuthn
: Parameter that requires user re-authentication once a session expires in Nebius AI.
-
Specify certificates for the federation
When the identity provider (IdP) informs Cloud Organization that a user has been authenticated, they sign the message with their certificate. To enable Cloud Organization to verify this certificate, add it to the created federation.
To add a certificate to a federation:
- Get your identity provider certificate.
Note
To find out how to get a certificate, see the documentation or go to the support service of your identity provider.
-
Go to Cloud Organization
. -
In the left-hand panel, select Federations
. -
Click the name of the federation to add a certificate to.
-
At the bottom of the page, click Add certificate.
-
Enter certificate name and description.
-
Choose how to add a certificate:
- To add a certificate as a file, click Choose a file and specify the path to it.
- To paste the contents of a copied certificate, select the Text method and paste the contents.
-
Click Add.
If you don't have the Nebius AI command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
-
View a description of the add certificate command:
ncp organization-manager federation saml certificate create --help
-
Add a federation certificate by specifying the certificate file path:
ncp organization-manager federation saml certificate create --federation-name my-federation \ --name "my-certificate" \ --certificate-file test.pem
Tip
To ensure the authentication is not interrupted when the certificate expires, we recommend adding multiple certificates to the federation, i.e., both the current one and those to be used afterwards. If a certificate turns out to be invalid, Nebius AI will attempt to verify the signature with another certificate.
Configure authentication on your server
Once you have created a federation, configure the Identity Provider (IdP) server. After each successful authentication, the server must send a relevant SAML message to the management console.
Example of an SAML message:
<samlp:Response ID="_bcdf7b6b-ea42-4191-8d5e-ebd4274acec6" Version="2.0" IssueInstant="2019-07-30T13:24:25.488Z"
Destination="https://auth.nebius.ai/federations/bfbrotp6l1b2avhe1spu" Consent="urn:oasis:names:tc:SAML:2.0:consent:unspecified"
InResponseTo="19fb953133b313a86a001f2d387160e47f3e7aa0" xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol">
<Issuer xmlns="urn:oasis:names:tc:SAML:2.0:assertion">http://example.org/auth</Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
</samlp:Status>
<Assertion ID="_90cd8dcc-6105-4300-9ae4-f2c8c5aeb1e5" IssueInstant="2019-07-30T13:24:25.488Z"
Version="2.0" xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
<Issuer>http://example.org/auth</Issuer>
<ds:Signature xmlns:ds="http://www.w3.org/2000/09/xmldsig#">
<ds:SignedInfo>
<ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
<ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256" />
<ds:Reference URI="#_90cd8dcc-6105-4300-9ae4-f2c8c5aeb1e5">
<ds:Transforms>
<ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature" />
<ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#" />
</ds:Transforms>
<ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256" />
<ds:DigestValue>phUQR...</ds:DigestValue>
</ds:Reference>
</ds:SignedInfo>
<ds:SignatureValue>VACd7O...</ds:SignatureValue>
<KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
<ds:X509Data>
<ds:X509Certificate>MIIC7j...</ds:X509Certificate>
</ds:X509Data>
</KeyInfo>
</ds:Signature>
<Subject>
<NameID>user@example.org</NameID>
<SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<SubjectConfirmationData InResponseTo="19fb953133b313a86a001f2d387160e47f3e7aa0" NotOnOrAfter="2019-07-30T13:29:25.488Z" Recipient="https://auth.nebius.ai/federations/bfbrotp6l1b2avhe1spu" />
</SubjectConfirmation>
</Subject>
<Conditions NotBefore="2019-07-30T13:24:25.482Z" NotOnOrAfter="2019-07-30T14:24:25.482Z">
<AudienceRestriction>
<Audience>https://auth.nebius.ai/federations/bfbrotp6l1b2avhe1spu</Audience>
</AudienceRestriction>
</Conditions>
<AttributeStatement>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress">
<AttributeValue>user@example.org</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname">
<AttributeValue>First Name</AttributeValue>
</Attribute>
<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname">
<AttributeValue>Last Name</AttributeValue>
</Attribute>
</AttributeStatement>
</Assertion>
</samlp:Response>
When setting up the message:
-
Use the
Response
and theSubjectConfirmationData
properties of theInResponseTo
attribute to specify the ID from the SAML authentication request sent by Nebius AI. -
Specify the URL to redirect users to after successful authentication, such as
https://auth.nebius.ai/federations/<federation_ID>
, in the following elements:- In the
Destination
attribute ofResponse
. - In the
Recipient
attribute ofSubjectConfirmationData
. - In
Audience
.
How to get a federation ID-
Go to Cloud Organization
. -
In the left-hand panel, select Federations
. -
Copy the ID of the federation you are configuring access for.
- In the
-
Specify a unique user ID in the
NameID
element. We recommend using the User Principal Name (UPN) or email address. -
Specify the link to the IdP page in the
Issuer
element. The user was forwarded to this page for authentication. -
Enter a signed message in the
SignatureValue
element and the certificate it was signed with in theKeyInfo
element. -
Note that Nebius AI validates that the response was received in the interval specified in the
Conditions
orSubjectConfirmationData
element attributes. -
For a user to be able to contact Nebius AI technical support from the management console
, provide the user's name and email address in theAttributeStatement
property. Email, first name, and last name are provided in separateAttribute
elements. You can also provide the first name and last name together, for example:<Attribute Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"> <AttributeValue>John Doe</AttributeValue> </Attribute>
In the
Name
attribute, you can specify a short attribute name, for example:<Attribute Name="name"> <AttributeValue>John Doe</AttributeValue> </Attribute>
Configure user attribute mapping
After a user authenticates, the identity provider's server forwards to Nebius AI an SAML message with information about successful authentication and user attributes, such as ID, name, email address, and so on.
To correctly pass user information to Cloud Organization, map SAML message attributes to the user's personal information stored on the identity provider's server.
User data | Comment | SAML message elements |
---|---|---|
Unique user ID | Required attribute. We recommend using the User Principal Name (UPN) or email address. | <NameID> |
Last name | Displayed in Nebius AI services. Value length limit: 64 characters. |
<Attribute> with theName="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname" parameter |
First name | Displayed in Nebius AI services. Value length limit: 64 characters. |
<Attribute> with theName="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname" parameter |
Full name | Displayed in Nebius AI services. Example: John Smith. Value length limit: 64 characters. |
<Attribute> with theName="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name" parameter |
Used to send notifications from Nebius AI services. Example: smith@example.com .Value length limit: 256 characters. |
<Attribute> with theName="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" parameter |
|
Phone | Used to send notifications from Nebius AI services. Example: . Value length limit: 64 characters. |
<Attribute> with theName="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone" parameter |
Profile image | Displayed in Nebius AI services. Images are transmitted in Base64 encoding. Example. Value length limit: 204800 characters. |
<Attribute> with theName="thumbnailPhoto" parameter |
Warning
The thumbnailPhoto
attribute value exceeding the length limit is ignored. If the value of a different attribute exceeds the limit, the value part that goes beyond the limit is truncated.
Sample Base64-encoded image
The profile image is transmitted in text format using Base64
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
UYGmIgo9HwAAAABJRU5ErkJggg==
Add users to your organization
If you did not enable the Automatically create users option when creating a federation, you will have to add federated users to your organization manually.
To do this, you need to know the name IDs of the users that the Identity Provider Server (IdP) returns along with the successful authentication confirmation. This is usually the user's primary email address. If you do not know what the server returns as the name ID, contact the administrator who configured authentication for your federation.
If the Automatically create users option is enabled, a federation will only add users logging in to a cloud for the first time. You can only add a federated user again manually after deleting them from a federation.
To add users to an organization, you must be in its admins
group.
To add federation users to an organization:
-
Log in to an account
that belongs to an organization administrator or owner. -
Go to Cloud Organization
. -
In the left-hand panel, select Users
. -
In the top-right corner, click
-
Select the identity federation to add users from.
-
List the name IDs of users, separating them with line breaks.
-
Click Add. This will give the users access to the organization.
If you don't have the Nebius AI command line interface yet, install and initialize it.
The folder specified in the CLI profile is used by default. You can specify a different folder using the --folder-name
or --folder-id
parameter.
-
View a description of the add user command:
ncp organization-manager federation saml add-user-accounts --help
-
Add users by listing their name IDs separated by a comma:
ncp organization-manager federation saml add-user-accounts --name my-federation \ --name-ids=alice@example.com,bob@example.com,charlie@example.com
To add identity federation users to the cloud:
-
Create a file with the request body, e.g.,
body.json
. In the request body, specify the array of name IDs of users you want to add:{ "nameIds": [ "alice@example.com", "bob@example.com", "charlie@example.com" ] }
-
Send the request by specifying the Federation ID in the parameters:
$ curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <IAM token>" \ -d '@body.json' \ https://organization-manager.api.ai.nebius.cloud/organization-manager/v1/saml/federations/<federation ID>:addUserAccounts
Test the authentication process
When you finish configuring the server, check the authentication process:
-
Open the browser in guest or incognito mode for a clean new user simulation.
-
Follow the URL to log in to the management console:
https://console.nebius.ai/federations/<federation_ID>
How to get a federation ID-
Go to Cloud Organization
. -
In the left-hand panel, select Federations
. -
Copy the ID of the federation you are configuring access for.
The browser forwards you to the authentication page.
-
-
Enter your authentication data. By default, you must enter the UPN and password. Then click Sign in.
-
On successful authentication, the server will redirect you to the
https://auth.nebius.ai/federations/<federation_ID>
URL that you specified in the server settings, and then to the management console home page. In the top-right corner, you will see being logged in to the console as a federated user.
What's next
- Add new users to groups to grant them permissions.