Authentication using Active Directory

With an identity federation, you can set up Single Sign-On (SSO) and use Microsoft Active Directory in conjunction with Microsoft Active Directory Federation Services (AD FS) for cloud authentication.

To configure SSO:

1. Create a federation in your organization.

2. Specify certificates for the federation.

3. Add users to your organization.

4. Test authentication.

Getting startedGetting started

To follow the steps in this section, you will need:​

1. An operational AD FS farm.

   If you do not have the an AD FS farm configured yet, follow these steps to set one up:

   1. Deploy and configure Active Directory Domain Services (AD DS) if you have not already done so. You must have AD AS to deploy AD FS.

   2. Deploy and configure an AD FS farm of one or more servers.

      Tip

      Add multiple servers to your AD FS farm for fault tolerance.

      In which case SSO will be available even if some of the servers go down.

2. A valid SSL certificate for use in AD FS. If you do not have a valid certificate, get one.

   To prevent browsers from blocking the authentication page when using SSO, the certificate must satisfy the following requirements:

   • The certificate must be trusted by devices and users within the Active Directory forest.

   • The certificate's Subject Name property and Alternative Name extension must contain the AD FS farm's FQDN.

     How to get a farm FQDN

     1. Connect to any server in the AD FS farm and open the PowerShell console.

     2. Get the federation service endpoint:

        Get-AdfsEndpoint -AddressPath /adfs/ls/ | Select FullUrl
        

        The endpoint contains the FQDN of the AD FS farm and has the following format:

        https://<AD_FS_farm_FQDN>/adfs/ls/
        

Create a federation in your organizationCreate a federation in your organization

To create a federation:

Specify certificates for the federationSpecify certificates for the federation

When the identity provider 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 your federation:

1. Get an AD FS farm certificate:

   MMC snap-in

   PowerShell

   1. Connect to any server in the AD FS farm and open Server Manager.

   2. Open the AD FS management console: Tools → AD FS Management.

   3. In the window that opens, click Services → Certificates 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.

   1. Connect to any server in the AD FS farm and open the PowerShell console.

   2. Get a Token-Signing certificate in Base64 format. To do this, run these commands, specifying the path you want to save the certificate at:

      $ADFS_CERT_PATH = "<path_to_certificate>/adfs_certificate.cer"
      
      $TEMP_CERT = (Get-AdfsCertificate -CertificateType Token-Signing |
                      where {$_.IsPrimary -eq $true} | Select-Object -First 1
                   ).Certificate.Export([System.Security.Cryptography.X509Certificates.X509ContentType]::Cert)
      
      @(
          '-----BEGIN CERTIFICATE-----'
          [System.Convert]::ToBase64String($TEMP_CERT, 'InsertLineBreaks')
          '-----END CERTIFICATE-----'
      ) | Out-File -FilePath $ADFS_CERT_PATH -Encoding ascii
      
      

      The certificate will be saved as adfs_certificate.cer.

2. Add the farm certificate to the federation:

   Cloud Center interface

   CLI

   API

   1. Log in to Yandex Cloud Organization.

   2. In the left-hand panel, select Federations.

   3. Click the row with the federation you want to add a certificate to.

   4. Click Adding a certificate under Certificates at the bottom of the page.

   5. Enter certificate name and description.

   6. 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.

   7. 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.

   1. View a description of the add certificate command:

      yc organization-manager federation saml certificate create --help
      

   2. 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:

   1. Create the request body by specifying the contents of the certificate's data property:

      {
        "federationId": "<federation_ID>",
        "name": "my-certificate",
        "data": "MII...=="
      }
      

   2. Send the request to add the certificate:

      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"
      

Configure the AD FS farm to notify Yandex Cloud of every successful authentication and then redirect the user to the console. To set up a farm, you will need information about the federation you created earlier.

To configure a farm:

1. Create a relying party trust.

2. Configure Claims Mapping.

Create a relying party trustCreate a relying party trust

Create a relying party trust so that Yandex Cloud can use AD FS for authentication:

1. Connect to any server in the AD FS farm and open Server Manager.

2. Open the AD FS management console: Tools → AD FS Management.

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

   The wizard window opens.

4. At the Welcome step, select Claims aware and click Start.

5. At the Select Data Source step, select Enter data about the relying party manually and click Next.

6. At the Specify Display Name step, enter a name, e.g., Yandex Cloud and click Next.

7. Skip the Configure Certificate step by clicking Next. You will configure certificates later.

8. At 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

   1. Log in to Yandex Cloud Organization.
   2. In the left-hand panel, select Federations.
   3. Select the required federation and copy the Identifier field value on the federation info page.
   How to get the federation ACS URL

   1. Log in to Yandex Cloud Organization.

   2. In the left-hand panel, select Federations.

   3. Select the required federation and copy the ACS URL field value on the federation info page.

   

   Then click Next.

9. At the Configure Identifiers step, enter the same redirect URL as an identifier and click Add. Then click Next.

10. At the Choose Access Control Policy step, 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 <parameter> to select the groups to get the access permission. Read more about access control policies.

    

    After you select a policy, click Next.

11. At the Ready to Add Trust step, check the entered data and click Close.

12. (Optional) If you enabled Sign authentication requests when creating the federation in Yandex Cloud Organization, configure the associated relying party trust parameters:

    1. Open the context menu of the relying party trust you created and select Properties.

       This will open the window with relying party trust properties.

    2. Go to the Encryption tab and add the Yandex Cloud SAML certificate you downloaded earlier to sign authentication requests:

       1. Click Browse.

       2. Select the certificate file, such as YandexCloud.cer.

          If you did not download a SAML certificate when creating the federation, you can download it on the Yandex Cloud Organization federation info page by clicking Download certificate in the Sign authentication requests field.

    3. Go to the Signature tab and add the same certificate:

       1. Click Add.
       2. Select the certificate file.

    4. Click OK.

    5. Enable required claim encryption and request signing for the created relying party trust:

       Set-AdfsRelyingPartyTrust `
           -TargetName "Yandex Cloud" `
           -EncryptClaims $true `
           -SignedSamlRequestsRequired $true `
           -SamlResponseSignature MessageAndAssertion
       

13. (Optional) If you enabled Mandatory re-authentication (ForceAuthn) in IdP when creating the federation in Yandex Cloud Organization, enable forced authentication on the relying party trust side:

    Set-AdfsRelyingPartyTrust `
        -TargetName "Yandex Cloud" `
        -AlwaysRequireAuthentication $true
    

Configure Claims MappingConfigure Claims Mapping

When AD FS authenticates a user, it sends a SAML message to Yandex Cloud confirming successful authentication. The message must contain the Name ID that uniquely identifies the user and may also contain other user data, such as name, email, etc. For this you need to configure mapping between the user attributes and Outgoing Claim Types.

Review the list of data, attributes, and types of outgoing claimsReview the list of data, attributes, and types of outgoing claims

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 an email address.	Name ID
List of groups the user belongs to.	This list is used for group mapping when authenticating the user in Yandex Cloud. Use a Token-Groups family attribute. Depending on the attribute you select, the group list format will vary. For example, if using Token-Groups - Unqualified Names, short group names will be provided (e.g., adfs_group, Domain Users) that do not specify the domain. For an example of how to configure group mapping, see User group mapping in Microsoft Active Directory Federation Services.	Group
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: Ivan Ivanov. We recommend using the Display-Name attribute. Value length limit: 64 characters.	Name
Email	Used to send notifications from Yandex Cloud services. Example: ivanov@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.	phone
Profile image	Displayed in Yandex Cloud services. We recommend using the thumbnailPhoto attribute. How to add a profile image. Value length limit: 204800 characters.	thumbnailPhoto

Configure attribute and claim mappingsConfigure attribute and claim mappings

Configure mapping:

1. In the AD FS management console, under Relying Party Trusts, right-click 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, set up the data to send in the message:

   1. In the Claim rule name field, enter a name for the rule, e.g., Claims mapping.

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

   3. Configure mapping for the mandatory Name ID claim by adding an entry to the Mapping of LDAP attributes list:

      1. Select the Name ID claim type in the Outgoing Claim Type column.

      2. Select the required attribute in the LDAP Attribute column.

         You can select either one of the recommended attributes or another attribute. The selected attribute must be permanent and unique to ensure unambiguous user identification.

         Warning

         If user ID changes, the user will have to get a new federation account created and will lose access to previous settings and data in Yandex Cloud.

   4. Similarly, configure mapping for the Group claim if you are using user group mapping.

   5. Similarly, configure mappings for the Name and E-Mail Address claims if you want the user to be able to contact Yandex Cloud support from the management console.

   6. (Optional) Similarly, configure mappings for other claims. The actual list of mappings depends on what user data you need to deliver to the Yandex Cloud side after authentication.

      How to save a user's avatar image to the thumbnailPhoto attribute

      1. Prepare images to use as your avatar.

         Make sure the image meets the following requirements:

         • Maximum image file size: 100 KB.
         • Recommended image file size: up to 10 KB; recommended image size: up to 96×96 pixels.

      2. Start PowerShell.

      3. Connect the Active Directory Module for Windows PowerShell using this command:

         Import-Module ActiveDirectory
         

      4. To add a profile image for a single user, run this command:

         Set-ADUser <username> -Replace @{thumbnailPhoto=([byte[]](Get-Content "<path_to_image>" -Encoding byte))}
         

      5. To bulk add profile images for multiple users:

         1. 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
            

         2. Run this command:

            Import-Csv <path_to_CSV_file> |%{Set-ADUser -Identity $_.AD_username -Replace @{thumbnailPhoto=([byte[]](Get-Content $_.Photo -Encoding byte))}}
            

      If you need to configure mappings for phone and thumbnailPhoto, enter the names of these outgoing claim types manually in the Outgoing Claim Type field. You cannot select these types from the drop-down list:

      

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

Add users to your organizationAdd users to your organization

If you did not enable the Automatically create users option when creating the federation, you will have to add federated users to your organization manually.

To do this, you need to know the user's name IDs returned by the identity provider together with the successful authentication response. These are usually the users' primary email addresses. If you do not know what the identity provider returns as the name ID, contact the administrator who had 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 the organization administrator (the organization-manager.admin role) or owner (the organization-manager.organizations.owner role). To learn how to grant a role to a user, see the Roles section.

To add federation users to an organization:

Test authenticationTest authentication

Now that you are done configuring SSO, test authentication:

1. Open the browser in guest or incognito mode for a clean new user simulation.

2. Follow the URL to log in to the management console:

   https://console.yandex.cloud/federations/<federation_ID>
   

   How to get a federation ID

   1. Log in to Yandex Cloud Organization.
   2. In the left-hand panel, select Federations.
   3. Select the required federation and copy the Identifier field value on the federation info page.

   The browser forwards you to the AD FS authentication page, which by default looks like this:

   

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

4. On successful authentication, AD FS will redirect you to the ACS URL you specified in the AD FS relying party trust settings, and from there 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.

What's nextWhat's next

• Assign roles to the new users.