Authentication using Active Directory

If you have an identity federation, you can use Active Directory Federation Services (ADFS) to authenticate in the cloud.

To set up authentication:

  1. Create an identity federation in the cloud.
  2. Add certificates to the federation.
  3. Get a console login link.
  4. Configure authentication on the AD FS server.
  5. Add users to the cloud.
  6. Test the authentication process.

Before you start

To use the instructions in this section, you need:​

  1. The admin or resource-manager.clouds.owner role in the cloud.

  2. A working ADFS farm. If you didn't configure ADFS on your server, install and configure it now. To deploy ADFS, you also need to install and configure Active Directory Domain Services (AD DS).

    If you don't have a Windows machine to deploy an ADFS server, you can create a VM in Yandex.Cloud.

    Tip

    We recommend that you include more than one server in the farm to ensure more reliable authentication.

  3. A valid certificate that is used for signing in the ADFS service. If you don't 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 the cloud

To create a federation in IAM:

  1. Open the folder page in the management console.

  2. Select the Federations tab in the left menu.

  3. Click Create federation.

  4. Enter a name for the federation. The name is unique within the project.

  5. Add a description if necessary.

  6. In the Cookie lifetime field, specify the time before the browser asks the user to re-authenticate.

  7. Enter the link in https://<ADFS>/adfs/services/trust format in the IdP Issuer field, where <ADFS> is the FQDN of your ADFS server.

  8. In the SSO method field, choose POST.

  9. In the Link to the IdP login page field, enter the link in https://[ADFS]/adfs/ls/ format, where <ADFS> is the FQDN of your ADFS server.

  10. Enable Automatically create users to automatically add authenticated users to the cloud. This option simplifies the user setup, but users created this way are only assigned the resource-manager.clouds.member role by default: they can't do anything with cloud resources. Exceptions are the resources that the allUsers or allAuthenticatedUsers system group roles are assigned to.

    If this option is disabled, users who aren't added to the cloud can't log in to the management console, even if they authenticate with your server. In this case, you can manage the white list of users who are allowed to use Yandex.Cloud.

Specify certificates for the identity federation

When the Identity Provider (IdP) informs Yandex.Cloud that a user passed authentication, they sign the message with their certificate. To enable Yandex.Cloud to verify this certificate, add it to the federation in IAM.

Tip

To ensure that authentication isn't interrupted when the certificate expires, we recommend adding several certificates to the federation: the current one and the ones that will be used after. If a certificate is invalid, Yandex.Cloud tries to verify the signature with a different one.

To get an ADFS certificate:

  1. Log in to your ADFS server and open Server Manager.
  2. Open the ADFS management console: ToolsADFS Management.
  3. In the window that opens, click ServicesCertificates in the tree on the left.
  4. Right-click the certificate in the Token-signing section and select View certificate.
  5. In the window that opens, go to the Details tab.
  6. Click the Copy to file button.
  7. Click Next.
  8. Select the format Base-64 encoded X. 509 (.CER) and click Next.
  9. Specify where to save the certificate and under what name, then click Next.
  10. Check the certificate export settings and click Finish.

To add a certificate to a federation:

  1. Open the folder page in the management console.
  2. Select the Federations tab in the left menu.
  3. Click the name of the federation you want to add a certificate to.
  4. Click Add certificate at the bottom of the page.
  5. Choose how to add the 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.

When you set up federation authentication, users can log in to the management console from a link containing the federation ID. You must specify the same link when configuring the authentication server.

Obtain and save this link:

  1. Get the federation ID:

    1. Open the folder page in the management console.
    2. Select the Federations tab in the left menu.
    3. Copy the ID of the federation you're configuring access for.
  2. Generate a link using this ID:

    https://console.cloud.yandex.com/federations/<federation ID>

Configure authentication on the ADFS server

After you obtained your management console login link, you can configure the ADFS server to notify the management console of each successful authentication session and forward the user to the specified address to log in to the management console.

The instructions in this section are written for Windows Server 2016 (different steps might be needed for other versions).

To set up authentication on the ADFS server:

  1. Create a relying party trust
  2. Configure Claims Mapping

Create a relying party trust

ADFS requires a relying party trust for each Service Provider (SP) that uses ADFS for authentication.

Create a relying party trust for the federation you created in the cloud:

  1. Log in to your ADFS server and open Server Manager.

  2. Open the ADFS management console: ToolsADFS Management.

  3. In the list of actions, select Add Relying Party Trust.

  4. The wizard window opens. On the first page, select Claims aware and click Start.

  5. Select Enter data about the relying party manually and click Next.

  6. Enter a name, like Yandex.Cloud, and click Next.

  7. In the next step, you are asked to specify a certificate for signing tokens. This step is optional, so click Next.

  8. In the Configure URL step, select Enable support for the SAML 2.0 WebSSO protocol and specify the console login link you obtained earlier. Then click Next.

    image

  9. On the next page, enter the same console login link as an identifier and click Add. Then click Next.

  10. 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 group of users, select Permit specific group and click on the word <parameter> to select the groups to allow access to. Read more about access control policies.

    image

  11. Click Next.

  12. On the Ready to Add Trust page, check the data entered and click Close.

Configure Claims Mapping

When ADFS authenticates a user, it sends an SAML message to Yandex.Cloud to confirm successful authentication. The NameID element in this message identifies the user authenticated. For this, you need to configure the user data to match the elements of the SAML message.

Important

The NameID must be unique for every federation user. We recommend specifying the User Principal Name (UPN) or email address as the ID.

To configure mapping of user data to SAML message elements:

  1. In the ADFS management console under Relying Party Trusts, right-click on the relying party trust created earlier and select Edit Claim Issuance Policy.
  2. In the window that opens, click Add Rule.
  3. Select Send LDAP Attributes as Claims and click Next.
  4. On the next page, configure what to pass in the message fields:
    1. In the Claim rule name field, enter a name for the rule, like Claims mapping

    2. In the Attribute Store field, click Active Directory.

    3. Specify the attribute to be passed as NameID. For this, add a line to the Mapping of LDAP attributes list:

      Under LDAP Attribute, select User-Principal-Name or E-Mail Addresses.

      In Outgoing Claim Type, select Name ID.

    4. For users to be able to contact Yandex.Cloud technical support from the management console, configure the server to pass an email address (E-Mail Address and the name of the user (Name):

      image

      You can also pass the user's first and last name separately. For this, use the Given Name and Surname types instead of Name.

  5. Click Finish, then click OKto close the Edit Claim Issuance Policy window.

Add users to the cloud

If you enabled the Automatically create users option when creating an identity federation, this step is optional. If you didn't enable it, you must add users to the cloud manually.

To add identity federation users to the cloud:

  1. Open the Access management page for the selected cloud. If necessary, switch to another cloud.

  2. Click the arrow next to the Add user button.

  3. Select Add federated users.

  4. Select the identity federation to add users to.

  5. List the Name IDs of users, separating them with line breaks.

    Specify the Name IDs returned by the Identity Provider (IdP) on successful authentication. These may be UPNs or user email addresses.

Test the authentication process

When you finish configuring authentication with Active Directory, test that it runs properly:

  1. Open the browser in guest or incognito mode to simulate being a new user.

  2. Follow the management console login link you obtained earlier. The browser forwards you to the ADFS authentication page, which by default looks as follows:

    image

  3. Enter your authentication data. By default, you must enter the UPN and password. Then click Sign in.

  4. On successful authentication, ADFS redirects you back to the management console login link and then to the management console home page. In the upper-right corner, you can see that you are logged in to the console under an Active Directory account.

What's next