Authentication using an SAML-compatible identity federation

This is a generic guide to configure authentication in the cloud via an SAML-compatible identity federation. Use these instructions if there aren't any ad-hoc instructions for your identity federation.

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 your 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 in the cloud that you want to set up SAML authentication for.

  2. A valid certificate used to sign SAML messages on the Identity Provider (IdP) server. 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. In the IdP Issuer field, specify the IdP server ID to be used for authentication. The IdP server also responds to IAM with this ID after the user authenticates.

  8. In the Link to the IdP login page field, specify the address of the page that the browser redirects the user to for authentication.

  9. 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 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 your server

After you create a federation and obtain a management console login link, 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://console.cloud.yandex.com/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://console.cloud.yandex.com/federations/bfbrotp6l1b2avhe1spu" />
      </SubjectConfirmation>
    </Subject>
    <Conditions NotBefore="2019-07-30T13:24:25.482Z" NotOnOrAfter="2019-07-30T14:24:25.482Z">
      <AudienceRestriction>
        <Audience>https://console.cloud.yandex.com/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:

  • In the InResponseTo attribute of the Response and SubjectConfirmationData elements, specify the ID from the SAML authentication request that Yandex.Cloud sent.

  • Enter the console login link in the following elements:

    • In the Destination attribute of Response.
    • In the Recipient attribute of SubjectConfimirationData.
    • In Audience.
  • 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 the KeyInfo element.

  • Note that Yandex.Cloud validates that the response was received in the interval specified in the attributes of the Conditions or SubjectConfimirationsData element.

  • For the user to be able to contact Yandex.Cloud technical support from the management console, pass their email address and name in the AttributeStatement element. Email, first name, and last name are passed in separate Attribute elements. You can also pass 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>
    

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 the server, check the authentication process:

  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 authentication page.
  3. Enter your authentication data. By default, you must enter the UPN and password. Then click Sign in.
  4. On successful authentication, the server will redirect you back to the management console login link and then to the console's home page. In the upper-right corner, you can see that you are logged in to the console as a federated user.

What's next