Authentication using Azure Active Directory
With an identity federation, you can use Azure Active Directory (Azure AD)
Authentication setup includes the following steps:
Getting started
To follow the steps described in this section, you will need an Azure account with an active subscription.
Creating and setting up a SAML application in Azure AD
Create a SAML application and download a certificate
A SAML application in Azure AD acts as an identity provider (IdP). Create a SAML application and download a certificate:
-
Go to the Azure AD portal
. -
In Azure Services, select Azure Active Directory.
-
On the left-hand panel, select Enterprise Applications.
-
Click New application.
-
On the Browse Azure AD Gallery page, click Create your own application.
-
In the window that opens:
-
Name the application.
-
Select Integrate any other application you don't find in the gallery (Non-gallery).
-
Click Create.
-
-
On the Browse page that opens, use the left-hand panel to select Single sign-on.
-
Select the SAML single sign-on method.
-
Use the SAML-based sign-on page, Section 3. SAML Signature Certificate to download the certificate (base64). The IdP uses it to sign the user authenticated message.
Do not close the page, as you will need the IdP server data when creating and setting up a federation.
Add users
Add users to the IdP server:
-
Go to the Enterprise Applications
page. -
Select the SAML application created.
-
On the left-hand panel, select Users and groups.
-
Click Add user or group.
-
In the Users field, click None Selected.
-
In the window that opens, check users and click Select.
-
Click Assign.
Creating and setting up a federation in Yandex Cloud Organization
Create a federation
-
Go to Yandex 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 time before the browser asks the user to re-authenticate.
-
In the IdP Issuer field, insert the link from the Azure AD ID field on the Azure AD SAML-based sign-on page. The link should have the following format:
https://sts.windows.net/<SAML_application_ID>/
-
In the Link to the IdP login page field, insert the link from the Login URL field on the Azure AD SAML-based sign-on page. The link should have the following format:
https://login.microsoftonline.com/<SAML_application_ID>/saml2
You can only use HTTP and HTTPS in a link.
-
Enable Automatically create users to automatically add users to your organization once they sign in. If this option is disabled, 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 removed a user from the federation, you can only add them back manually.
-
Enable Mandatory re-authentication (ForceAuthn) in IdP to set
true
for the ForceAuthn parameter in a SAML authentication request. If enabled, the IdP will request the user to re-authenticate once the Yandex Cloud session expires. -
Click Create federation.
If you do not have the Yandex Cloud 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:
yc organization-manager federation saml create --help
-
Create a federation:
yc organization-manager federation saml create --name my-federation \ --organization-id <organization_ID> \ --auto-create-account-on-login \ --cookie-max-age 12h \ --issuer "https://sts.windows.net/<SAML_application_ID>/" \ --sso-url "https://login.microsoftonline.com/<SAML_application_ID>/saml2" \ --sso-binding POST \ --force-authn
Where:
-
--name
: Federation name. It must be unique within the folder. -
--organization-id
: 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. This does not apply to the resources theallUsers
orallAuthenticatedUsers
system group roles are assigned to.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 IdP server. In this case, you can manage a list of users allowed to use Yandex Cloud resources.
-
--cookie-max-age
: Time before the browser asks the user to re-authenticate. -
--issuer
: ID of the IdP server to be used for authentication.Use the link from the Azure AD ID field on the Azure AD SAML-based sign-on page. The link should have the following format:
https://sts.windows.net/<SAML_application_ID>/
-
--sso-url
: URL to which the browser redirects the user for authentication.Use the link from the Login URL field on the Azure AD SAML-based sign-on page. The link should have the following format:
https://login.microsoftonline.com/<SAML_application_ID>/saml2
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
: When the session in Yandex Cloud expires, the identity provider will ask the user to re-authenticate.
-
If you don't have Terraform, install it and configure the Yandex Cloud provider.
-
Specify the federation parameters in the configuration file:
-
name
: Federation name. It must be unique within the folder. -
description
: Federation description. -
organization_id
: Organization ID. -
labels
: Set of key/value label pairs assigned to the federation. -
issuer
: IdP server ID to be used for authentication.Use the link from the Azure AD ID field on the Azure AD SAML-based sign-on page. The link should have the following format:
https://sts.windows.net/<SAML_application_ID>/
-
sso_binding
: Specify the Single Sign-on binding type. Most identity providers support thePOST
binding type. -
sso_url
: URL of the page the browser redirects the user to for authentication.Use the link from the Login URL field on the Azure AD SAML-based sign-on page. The link should have the following format:
https://login.microsoftonline.com/<SAML_application_ID>/saml2
You can only use HTTP and HTTPS in a link.
-
cookie_max_age
: Time, in seconds, before the browser asks the user to re-authenticate. The default value is8 hours
. -
auto_create_account_on_login
: 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. This does not apply to the resources theallUsers
orallAuthenticatedUsers
system group roles are assigned to.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 Yandex Cloud resources.
-
case_insensitive_name_ids
: Flag that indicates whether usernames are case-insensitive.
If the option is enabled, the IDs of federated user names will be case-insensitive. -
security_settings
: Federation security settings:encrypted_assertions
: Sign authentication requests.
If this option is enabled, all authentication requests from Yandex Cloud will have a digital signature. You need to download and install a Yandex Cloud certificate.
Here is an example of the configuration file structure:
resource "yandex_organizationmanager_saml_federation" federation { name = "my-federation" organization_id = "<organization_ID>" auto_create_account_on_login = "true" issuer = "https://sts.windows.net/<SAML_application_ID>/" sso_url = "https://login.microsoftonline.com/<SAML_application_ID>/saml2" sso_binding = "POST" security_settings { encrypted_assertions = "true" } }
-
-
Make sure the configuration files are valid.
-
In the command line, go to the directory where you created the configuration file.
-
Run a check using this command:
terraform plan
If the configuration is described correctly, the terminal displays the federation parameters. If the configuration contains any errors, Terraform will point them out.
-
-
Create a federation.
-
If the configuration does not contain any errors, run this command:
terraform apply
-
Confirm you want to create a federation.
This will create a federation in the specified organization. You can check the new federation and its settings in the organization's Federations(https://org.cloud.yandex.com/federations) section.
-
-
Create a file with the request body, e.g.,
body.json
:{ "name": "my-federation", "organizationId": "<organization_ID>", "autoCreateAccountOnLogin": true, "cookieMaxAge":"43200s", "issuer": "https://sts.windows.net/<SAML_application_ID>/", "ssoUrl": "https://login.microsoftonline.com/<SAML_application_ID>/saml2", "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. This does not apply to the resources the
allUsers
orallAuthenticatedUsers
system group roles are assigned to.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 IdP server. In this case, you can manage a list of users allowed to use Yandex Cloudresources.
-
cookieMaxAge
: Time that must elapse before the browser asks the user to re-authenticate. -
issuer
: IdP server ID to be used for authentication.Use the link from the Azure AD ID field on the Azure AD SAML-based sign-on page. The link should have the following format:
https://sts.windows.net/<SAML_application_ID>/
-
ssoUrl
: URL of the page the browser redirects the user to for authentication.Use the link from the Login URL field on the Azure AD SAML-based sign-on page. The link should have the following format:
https://login.microsoftonline.com/<SAML_application_ID>/saml2
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 Yandex Cloud.
-
-
To create a federation, use the create REST API method for the Federation resource or the FederationService/Create gRPC API call and provide a file with the request parameters in your request.
Sample request:
curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <IAM_token>" \ -d '@body.json' \ https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/federations
Response example:
{ "done": true, "metadata": { "@type": "type.googleapis.com/yandex.cloud.organization-manager.v1.saml.CreateFederationMetadata", "federationId": "ajeobmje4dgj********" }
The
federationId
property contains the ID of the federation you created; make sure to save it, you will need it later.
Add certificates
While authenticating, the Cloud Organization service should be able to verify the IdP server certificate. To enable this, add the downloaded certificate to the federation:
-
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 Adding a 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 do not have the Yandex Cloud 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:
yc organization-manager federation saml certificate create --help
-
Add a federation certificate by specifying the certificate file path:
yc organization-manager federation saml certificate create \ --federation-id <federation_ID> \ --name "my-certificate" \ --certificate-file certificate.cer
Use the create method for the Certificate resource:
-
Generate the request body. In the
data
property, specify the contents of the certificate:{ "federationId": "<federation_ID>", "name": "my-certificate", "data": "-----BEGIN CERTIFICATE..." }
-
Send the add certificate request:
export IAM_TOKEN=CggaAT******** curl -X POST \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${IAM_TOKEN}" \ -d '@body.json' \ "https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/certificates"
Tip
To make sure authentication is not interrupted when the certificate expires, we recommend adding multiple certificates to your federation, i.e., the current one and those to be used afterwards. If one certificate turns invalid, Yandex Cloud will attempt to verify the signature with another one.
Setting up Single Sign-On (SSO)
Specify the redirect URL
Once you have created a federation, complete the creation of the SAML application in Azure AD:
-
Open the SAML-based sign-on SAML application settings page.
-
In Section 1. Basic SAML configuration, specify information on Yandex Cloud acting as the service provider. To do this, in the ID (entity) and Response URL (assertion consumer service URL) fields, enter the URL to redirect users to after successful authentication:
https://console.cloud.yandex.ru/federations/<federation_ID>
How to get a federation ID-
Go to Yandex Cloud Organization
. -
In the left-hand panel, select Federations
. -
Copy the ID of the federation you are configuring access for.
-
-
Click Save.
Configure user attribute mapping
Following user authentication, the IdP server will send a SAML message to Yandex Cloud containing:
-
Information about successful authentication.
-
User attributes, such as the name ID, name, and email address.
You can set up a mapping between the SAML message attributes and the personal data stored on the IdP server. To do this, on the SAML-based sign-on page in Section 2. User Attributes & Claims, click Edit.
The types of personal data supported by Yandex Cloud Organization for Azure AD are listed below.
User data | Comment | Application Attributes |
---|---|---|
Unique user ID (name ID) | Required attribute. By default, Azure AD uses User Principal Name (UPN) in <login>_<domain>#EXT#@<provider>.onmicrosoft.com format as the attribute source. When manually adding users to a federation, this name ID format is not supported. We recommend changing the attribute source in Azure AD: choose the user.mail email address instead of the user.userprincipalname UPN. |
Unique user ID claim |
Last name | Displayed in Yandex Cloud services. Value length limit: 64 characters. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname |
Name | Displayed in Yandex Cloud services. Value length limit: 64 characters. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname |
Full name | Displayed in Yandex Cloud services. Example: John Smith .Value length limit: 64 characters. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name |
Used to send notifications from Yandex Cloud services. Example: smith@example.com .Value length limit: 256 characters. |
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress |
Warning
If the attribute value exceeds the length limit, the value part that goes beyond the limit is truncated.
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 will need user name IDs. They are returned by the IdP server together with a response confirming successful authentication.
If the Automatically create users option is enabled, a federation will only add users logging in to a cloud for the first time. If a federated user has been removed, they can only be added again manually.
A user can be added by an organization administrator (the organization-manager.admin
role) or owner (the organization-manager.organizations.owner
role). To learn how to grant roles to a user, see Roles.
-
Log in
as the organization administrator or owner. -
Go to Yandex Cloud Organization
. -
In the left-hand panel, select Users
. -
In the top-right corner, click
→ Add federated users. -
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 do not have the Yandex Cloud 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:
yc organization-manager federation saml add-user-accounts --help
-
Add users by listing their name IDs separated by a comma:
yc organization-manager federation saml add-user-accounts --id <federation_ID> \ --name-ids=alice@example.com,bob@example.com,charlie@example.com
Where:
-
--id
: Federation ID. -
--name-ids
: Users' name IDs.
-
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.cloud.yandex.net/organization-manager/v1/saml/federations/<federation ID>:addUserAccounts
Authentication
When you finish setting up SSO, test that everything works properly:
-
Open your browser in guest or private browsing mode.
-
Follow the URL to log in to the management console:
https://console.cloud.yandex.com/federations/<federation_ID>
How to get a federation ID-
Go to Yandex 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 Microsoft authentication page.
-
-
Enter your credentials and click Next.
On successful authentication, the IdP server will redirect you to the https://console.cloud.yandex.ru/federations/<federation_ID>
URL that you specified in the Azure AD settings, and then to the management console