Authentication using Active Directory
With an identity federation, you can use Active Directory Federation Services
To set up authentication:
Getting started
To follow the steps in this section, you will need:
-
Working AD FS farm. If you did not configure AD FS on your server, install and configure it now
. To deploy AD FS, you also need to install and configure Active Directory Domain Services (AD DS).Tip
We recommend that you include more than one server in the farm to ensure more reliable authentication.
-
Valid certificate used for signing in the AD FS service. If you do not have a valid SSL certificate, get one.
To prevent the browser from blocking the authentication page, make sure the subject name in the certificate contains the IdP server's FQDN, e.g.,
fs.contoso.com
.
Create a federation in your organization
To 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, enter a link in
http://<ADFS>/adfs/services/trust
format, where<ADFS>
is the FQDN of your AD FS server. -
In the Single Sign-On method field, choose POST.
-
In the Link to the IdP login page field, enter a link in
https://<ADFS>/adfs/ls/
format, where<ADFS>
is the FQDN of your AD FS server.You can only use HTTP and HTTPS in a link.
-
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 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.
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 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 "http://example.com/adfs/services/trust" \ --sso-url "https://example.com/adfs/ls/" \ --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 for which roles are assigned to theAll users
orAll authenticated users
public group.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.
-
--cookie-max-age
: Time before the browser asks the user to re-authenticate. -
--issuer
: ID of the IdP server to use for authentication.Enter a link in
http://<ADFS>/adfs/services/trust
format, where<ADFS>
is the FQDN of your AD FS server. -
--sso-url
: URL to which the browser redirects the user for authentication.Enter a link in
https://<ADFS>/adfs/ls/
format, where<ADFS>
is the FQDN of your AD FS server.You can only use HTTP and HTTPS in a link.
-
--sso-binding
: Single sign-on binding type. Most identity providers support thePOST
binding type. -
(Optional)
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
: ID of the IdP server to use for authentication.Enter a link in
http://<ADFS>/adfs/services/trust
format, where<ADFS>
is the FQDN of your AD FS server. -
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.Enter a link in
https://<ADFS>/adfs/ls/
format, where<ADFS>
is the FQDN of your AD FS server.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 for which roles are assigned to theAll users
orAll authenticated users
public group.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 will 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 = "http://example.com/adfs/services/trust" sso_url = "https://example.com/adfs/ls/" sso_binding = "POST" security_settings { encrypted_assertions = "true" } }
-
-
Make sure the configuration files are correct.
-
In the command line, go to the folder 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
section. -
-
Create a file with the request body, e.g.,
body.json
:{ "name": "my-federation", "organizationId": "<organization_ID>", "autoCreateAccountOnLogin": true, "cookieMaxAge":"43200s", "issuer": "http://example.com/adfs/services/trust", "ssoUrl": "https://example.com/adfs/ls/", "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 for which roles are assigned to theAll users
orAll authenticated users
public group.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.
-
cookieMaxAge
: Time before the browser asks the user to re-authenticate. -
issuer
: ID of the IdP server to use for authentication.Enter a link in
http://<ADFS>/adfs/services/trust
format, where<ADFS>
is the FQDN of your AD FS server. -
ssoUrl
: URL of the page the browser redirects the user to for authentication.Enter a link in
https://<ADFS>/adfs/ls/
format, where<ADFS>
is the FQDN of your AD FS server.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.
Note
To ensure correct ForceAuthn in IdP, change the IdP settings. To do this, open the PowerShell
console on your ADFS server and run the following command:
Get-AdfsRelyingPartyTrust -Name YC | Set-AdfsRelyingPartyTrust -AlwaysRequireAuthentication $true
Specify certificates for the federation
When the identity provider (IdP) informs Yandex 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 get an AD FS certificate:
-
Log in to your AD FS server and open Server Manager.
-
Open the AD FS management console: Tools → AD FS Management.
-
In the window that opens, click Services → Certificates in the tree on the left.
-
Right-click the certificate in the Token-signing section and select View certificate.
-
In the window that opens, go to the Details tab.
-
Click the Copy to file button.
-
Click Next.
-
Select the format Base-64 encoded X.509 (.CER) and click Next.
-
Specify where to save the certificate and under what name, then click Next.
-
Check the certificate export settings and click Finish.
To add a certificate to a federation:
-
Go to Yandex 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 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-name my-federation \ --name "my-certificate" \ --certificate-file test.pem
To add a certificate, use the create method for the Certificate resource:
-
Create the request body by specifying the contents of the certificate's
data
property:{ "federationId": "<federation_ID>", "name": "my-certificate", "data": "MII...==" }
-
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 use afterwards. If one certificate goes invalid, Yandex Cloud will try another one to verify the signature.
Configure authentication on the AD FS server
After you set up the federation in Yandex Cloud Organization, you can configure the AD FS server to notify the management console of each successful authentication session and redirect the user back to the management console.
This section offers guidelines written for Windows Server 2016 (different steps might be needed for other versions).
To set up authentication on the AD FS server:
Create a relying party trust
AD FS requires a relying party trust for each Service Provider (SP) that uses AD FS for authentication.
Create a relying party trust for the federation you created in the cloud:
-
Log in to your AD FS server and open Server Manager.
-
Open the AD FS management console: Tools → AD FS Management.
-
In the list of actions, select Add Relying Party Trust.
-
The wizard window opens. On the first page, select Claims aware and click Start.
-
Select Enter data about the relying party manually and click Next.
-
Enter a name, e.g.,
Yandex Cloud
and click Next. -
In the next step, you are asked to specify a certificate for signing tokens. This step is optional, so click Next.
-
In the Configure URL step, select Enable support for the SAML 2.0 WebSSO protocol and specify the ACS URL to redirect users to after successful authentication.
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.
How to get the federation ACS URL
-
Go to Yandex Cloud Organization
. -
In the left-hand panel, select Federations
. -
From the list, pick the federation you are configuring access to, and copy its ACS URL.
Then click Next.
-
-
On the next page, enter the same redirect URL as an identifier and click Add. Then click Next.
-
On the next page, you can choose who can authenticate using this federation. By default, the Permit for everyone policy is selected enabling access for all users.
You can choose a different policy. For example, to grant access to a specific user group, select Permit specific group and click
<parameter>
to select the groups. Read more about access control policies . -
Click Next.
-
On the Ready to Add Trust page, check the data entered and click Close.
Configure Claims Mapping
When AD FS authenticates a user, it sends a SAML message to Yandex Cloud to confirm successful authentication. The message must contain the name ID that uniquely identifies the user and may also contain some other user data, such as the user's name or email address. Make sure to set up a mapping between the user attributes and Outgoing Claim Types. Types of personal data supported by Yandex Cloud Organization are given below.
User data | Comment | Outgoing Claim Type |
---|---|---|
Unique user ID | Required attribute. We recommend using one of the unique and fixed Active Directory user attributes: User-Principal-Name, Object-Sid, Object-Guid, or email address. | Name ID |
Last name | Displayed in Yandex Cloud services. We recommend using the Surname attribute. Value length limit: 64 characters. |
Surname |
Name | Displayed in Yandex Cloud services. We recommend using the Given-Name attribute. Value length limit: 64 characters. |
Given Name |
Full name | Displayed in Yandex Cloud services. Example: John Smith. We recommend using the Display-Name attribute. Value length limit: 64 characters. |
Name |
Used to send notifications from Yandex Cloud services. Example: smith@example.com We recommend using the E-Mail-Address attribute. Value length limit: 256 characters. |
E-Mail Address | |
Phone | Used to send notifications from Yandex Cloud services. Example: +71234567890 We recommend using the Telephone-Number attribute.Value length limit: 64 characters. |
Type phone in the Outgoing Claim Type field. |
Profile image | Displayed in Yandex Cloud services. We recommend using the thumbnailPhoto attribute. How to add a profile image.Value length limit: 204800 characters. |
Type thumbnailPhoto in the Outgoing Claim Type field. |
Warning
For Name ID
, use only the Active Directory user attributes that are unique and unlikely to change. If a federation user's Name ID
changes, this user will have to get a new federation account created and will lose access to previous settings and data in Yandex Cloud.
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.
To set up a mapping between the user data and Outgoing Claim Types:
-
In the AD FS management console under Relying Party Trusts, right-click on the relying party trust created earlier and select Edit Claim Issuance Policy.
-
In the window that opens, click Add Rule.
-
Select Send LDAP Attributes as Claims and click Next.
-
On the next page, set up the data to send in the message:
-
In the Claim rule name field, enter a name for the rule, e.g.,
Claims mapping
. -
In the Attribute Store field, click Active Directory.
-
Specify what the server will return as the name ID to uniquely identify the user. To do this, add a line to the Mapping of LDAP attributes list:
In the LDAP Attribute column, select an attribute for a unique and fixed user ID: User-Principal-Name, Object-Sid, Object-Guid, or E-Mail-Addresses.
In the Outgoing Claim Type column, select Name ID.
-
For a user to be able to contact Yandex Cloud technical support from the management console
, add the user's email address (the E-Mail Address claim type) or name (the Name claim type). -
To provide the user's first and last name separately, add the Given Name and Surname claim types.
-
To add the user's phone number or profile image, enter the
phone
orthumbnailPhoto
type, respectively, in the Outgoing Claim Type field.
-
-
Click Finish, then click OKto close the Edit Claim Issuance Policy window.
How to add a profile image to Active Directory
To add a user's profile image to Active Directory, write the image to the thumbnailPhoto
attribute using PowerShell.
Note
The thumbnailPhoto
attribute supports files of up to 100 KB. The recommended file size is up to 10 KB and the recommended image size is up to 96×96 pixels.
-
Start PowerShell.
-
Connect the Active Directory Module for Windows PowerShell with the command:
Import-Module ActiveDirectory
-
To add a profile image for a single user, run the command:
Set-ADUser <user_name> -Replace @{thumbnailPhoto=([byte[]](Get-Content "<path_to_image>" -Encoding byte))}
-
To bulk add profile images for multiple users:
-
Create a CSV file with a list of usernames and image paths.
Sample CSV file:
AD_username, Photo smith, C:\Photo\smith.jpg jones, C:\Photo\jones.jpg
-
Run this command:
Import-Csv <path_to_CSV_file> |%{Set-ADUser -Identity $_.AD_username -Replace @{thumbnailPhoto=([byte[]](Get-Content $_.Photo -Encoding byte))}}
-
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 user name IDs returned by the Identity Provider (IdP) server together with the successful authentication response. 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. 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.
To add federation users to an organization:
-
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 --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.cloud.yandex.net/organization-manager/v1/saml/federations/<federation ID>:addUserAccounts
Test the authentication process
Now that you finished configuring authentication with Active Directory, test that it runs properly:
-
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.yandex.cloud/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 AD FS authentication page, which by default looks as follows:
-
-
Enter your authentication data. By default, you must enter the UPN and password. Then click Sign in.
-
On successful authentication, the AD FS server will redirect you to the ACS URL that you specified in the server settings, and then, to the management console home page. In the top-right corner, you can see that you are logged in to the console under an Active Directory account.