Contact UsGet started

Configuring an identity federation

Written by
Updated at December 20, 2024

You can use identity federation to set up user authentication in the cloud. Identity federations are compatible with any identity provider (IdP) that supports SAML 2.0.

To set up federated authentication, follow these steps:

  1. Create an identity federation.
  2. Add the IdP server certificate to the federation.
  3. Add the federation certificate to the IdP server.
  4. Set up a SAML application in your IdP.
  5. Configure user attribute mapping.
  6. Test authentication.

For IdP-specific examples, see our tutorials:

Creating an identity federation

  1. Log in to Yandex Cloud Organization.

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

  3. Click Create federation.

  4. Give your federation a name. It must be unique within the folder.

  5. (Optional) Add a description for your federation.

  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 use for authentication. The format of the ID depends on the server type.

    To learn how to get the IdP server ID, consult the provider's documentation or contact their support.

  8. In the Single Sign-On method field, select the redirect binding method. Most IdPs support the POST binding method.

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

    To learn how to get the redirect page URL, consult your identity provider's documentation or contact their support.

    You can only use HTTP and HTTPS in a link.

  10. In Advanced, specify the following parameters as required:

    • Automatically create users: If enabled, a federated user will be automatically added to your organization once they sign in. Otherwise, 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.

    • Sign authentication requests: Ensures authentication requests from Yandex Cloud contain a digital signature. To complete this configuration, you will need to install a Yandex Cloud SAML certificate for your IdP.

      In the SAML certificates block that appears, you will see the information about the current Yandex Cloud SAML certificate.

      Click Download and save the downloaded certificate file. You will need to upload it to you IdP server.

      Tip

      Track certificate expiration dates and always install a new certificate before the current one expires. Make sure to download the re-issued Yandex Cloud SAML certificate and install it on the IdP provider's side and in your federation well in advance.

    • Case-insensitive user names: If enabled, federated user name IDs will be case-insensitive.

    • Mandatory re-authentication (ForceAuthn) in IdP: When the Yandex Cloud session expires, your IdP will prompt the user to re-authenticate.

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

To create a federation:

  1. View the description of the create federation command:

    yc organization-manager federation saml create --help

  2. Specify the federation parameters in the create command:

    yc organization-manager federation saml create \
  --name <federation_name> \
  --organization-id <organization_ID> \
  --cookie-max-age <cookie_lifetime> \
  --issuer "<IdP_server_ID>" \
  --sso-binding <POST_or_REDIRECT> \
  --sso-url "<redirect_page_address>" \
  --encrypted-assertions \
  --auto-create-account-on-login \
  --case-insensitive-name-ids \
  --force-authn

    Where:

    • --name: Federation name. It must be unique within the folder.

    • --organization-id: Organization ID.

    • --cookie-max-age: Time that must elapse before the browser asks the user to re-authenticate, e.g., 12h.

    • --issuer: IdP server ID to use for authentication.

      To learn how to get the IdP server ID, consult the provider's documentation or contact their support.

    • --sso-binding: Single sign-on binding type. The possible values are POST and REDIRECT. Most identity providers support the POST binding type.

    • --sso-url: URL of the page the browser redirects the user to for authentication.

      To learn how to get the redirect page URL, consult your identity provider's documentation or contact their support.

      You can only use HTTP and HTTPS in a link.

    • (Optional) --encrypted-assertions: Ensures that authentication requests from Yandex Cloud contain a digital signature. To complete this configuration, you will need to install a Yandex Cloud certificate for your IdP.

    • (Optional) --auto-create-account-on-login: If enabled, a federated user will be automatically added to your organization once they sign in. Otherwise, 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.

    • (Optional) --case-insensitive-name-ids: If enabled, federated user name IDs will be case-insensitive.

    • (Optional) --force-authn: When the Yandex Cloud session expires, your IdP will prompt the user to re-authenticate.

With Terraform, you can quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. These files store the infrastructure description written in HashiCorp Configuration Language (HCL). If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

Terraform is distributed under the Business Source License. The Yandex Cloud provider for Terraform is distributed under the MPL-2.0 license.

For more information about the provider resources, see the documentation on the Terraform website or mirror website.

  1. If you don't have Terraform, install it and configure the Yandex Cloud provider.

  2. Create a configuration file describing the federation.

    Here is an example of the configuration file structure:

    resource "yandex_organizationmanager_saml_federation" federation {
  name            = "my-federation"
  description     = "My new SAML federation"
  organization_id = "<organization_ID>"
  issuer          = "<IdP_server_ID>" 
  sso_url         = "<redirect_page_address>"
  sso_binding     = "<POST_or_REDIRECT>"
  cookie_max_age = <cookie_lifetime>
  auto_create_account_on_login = "<true_or_false>"
  case_insensitive_name_ids = "<true_or_false>"
  security_settings {
    encrypted_assertions = "<true_or_false>"
    force_authn          = "<true_or_false>"
  }
}

    Where:

    • name: Federation name. It must be unique within the folder.

    • (Optional) description: Federation description.

    • organization_id: Organization ID.

    • issuer: IdP server ID to use for authentication.

      To learn how to get the IdP server ID, consult the provider's documentation or contact their support.

    • sso_binding: Single sign-on binding type. The possible values are POST and REDIRECT. Most identity providers support the POST binding type.

    • sso_url: URL of the page the browser redirects the user to for authentication.

      To learn how to get the redirect page URL, consult your identity provider's documentation or contact their support.

      You can only use HTTP and HTTPS in a link.

    • cookie_max_age: Time, in seconds, before the browser prompts the user to re-authenticate. The default value is 28800 (8 hours).

    • auto_create_account_on_login: If true, a federated user will be automatically added to your organization once they sign in. Otherwise, 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.

    • case_insensitive_name_ids: If true, federated user name IDs will be case-insensitive.

    • security_settings: Federation security settings:

      • encrypted_assertions: Ensures authentication requests from Yandex Cloud contain a digital signature. To complete this configuration, you will need to install a Yandex Cloud certificate for your IdP.

      • force-authn: When the Yandex Cloud session expires, your IdP will prompt the user to re-authenticate. This is an optional parameter.

    For more information about the yandex_organizationmanager_saml_federation resource parameters, see the provider documentation.

  3. Check that the Terraform configuration files are correct:

    1. Using the command line, navigate to the folder that contains the up-to-date Terraform configuration files with an infrastructure plan.

    2. Run the command:

      terraform validate

      If there are errors in the configuration files, Terraform will point to them.

  4. Create a federation:

    1. Run the command to view planned changes:

      terraform plan

      If the resource configuration descriptions are correct, the terminal will display a list of the resources to modify and their parameters. This is a test step. No resources are updated.

    2. If you are happy with the planned changes, apply them:

      1. Run the command:

        terraform apply

      2. Confirm the update of resources.

      3. Wait for the operation to complete.

You can check the new federation and its settings in the Federations section of your organization.

Note

You can also configure an end-to-end Keycloack federation setup using Terraform.

  1. Create a file with the request body, e.g., body.json:

    {
  "name": "my-federation",
  "description": "My new SAML federation",
  "organizationId": "<organization_ID>",
  "cookieMaxAge":"43200s",
  "issuer": "<IdP_server_ID>",
  "ssoUrl": "<redirect_page_address>",
  "ssoBinding": "<POST_or_REDIRECT>",
  "autoCreateAccountOnLogin": true,
  "caseInsensitiveNameIds": true,
  "securitySettings": {
    "encryptedAssertions": true,
    "forceAuthn": true
  }
}

    Where:

    • name: Federation name. It must be unique within the folder.

    • organizationId: Organization ID.

    • (Optional) description: Federation description.

    • cookieMaxAge: Time, in seconds, before the browser prompts the user to re-authenticate. The default value is 28800 (8 hours).

    • issuer: IdP server ID to use for authentication.

      To learn how to get the IdP server ID, consult the provider's documentation or contact their support.

    • ssoUrl: URL of the page the browser redirects the user to for authentication.

      To learn how to get the redirect page URL, consult your identity provider's documentation or contact their support.

      You can only use HTTP and HTTPS in a link.

    • ssoBinding: Single sign-on binding type. The possible values are POST and REDIRECT. Most identity providers support the POST binding type.

    • autoCreateAccountOnLogin: If true, a federated user will be automatically added to your organization once they sign in. Otherwise, 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.

    • caseInsensitiveNameIds: If true, federated user name IDs will be case-insensitive.

    • encryptedAssertions: If true, authentication requests from Yandex Cloud will contain a digital signature. To complete this configuration, you will need to install a Yandex Cloud certificate for your IdP.

    • forceAuthn: Parameter that requires user re-authentication once a session expires in Yandex Cloud.

  2. 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 query parameters in your query.

    Query example:

    curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer <IAM_token>" \
  --data '@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. Save it for later use.

Adding an IdP server certificate to a 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 your federation:

  1. Get your identity provider certificate.

    To learn how to do this, consult the identity provider's documentation or contact their support.

    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.

  2. Convert the certificate file to the PEM format:

    -----BEGIN CERTIFICATE-----
  <certificate value>
-----END CERTIFICATE-------

  3. Add the certificate to the federation:

    1. Log in to Yandex Cloud Organization with an administrator or organization owner account.

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

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

    4. Click Certificates under Adding a certificate 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.

    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 <federation_name> \
  --name "<certificate_name>" \
  --certificate-file <certificate_file_path>

    1. Create the body.json request body file and specify the contents of the certificate in the data property:

      {
  "federationId": "<federation_ID>",
  "description": "<certificate_description>",
  "name": "<certificate_name>",
  "data": "<certificate_contents>"
}

    2. Use the create REST API method for the Certificate resource or the FederationService/Create gRPC call and provide a file with the request parameters in your request.

    Sample cURL request:

    export IAM_TOKEN=CggaATEVAgA...
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data '@body.json' \
  "https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/certificates"

    Tip

    Make sure to reissue certificates and add them to a federation in a timely manner.

    To keep track of when your certificate expires, subscribe to notifications from the organization. Subscribed users get notifications 60, 30, and 5 days before the certificate expires and after its expiration.

    Adding a federation certificate to an IdP server

    If you enabled Sign authentication requests when creating a federation, all authentication requests from Yandex Cloud will contain a digital signature. The IdP server should be able to verify this signature. To enable this, you will need to add the Yandex Cloud certificate to the server:

    1. If you did not download the Yandex Cloud SAML certificate when creating the identity federation, download it now:

      1. Log in to Yandex Cloud Organization with an administrator or organization owner account.

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

      3. In the list that opens, select the identity federation you need. In the Sign authentication requests field, click Download certificate.

        If you see to the left of Download certificate, your current Yandex Cloud SAML certificate either has expired or is about to expire.

        Download a re-issued Yandex Cloud SAML certificate and install it in your identity federation.

        Tip

        In the top-right corner, click Update to see the expiration date of your current SAML certificate. The date is stated in the SAML certificate section, under Advanced.

        Save your SAML certificate expiration date to your calendar. A few months before that date, you will need to download the re-issued Yandex Cloud SAML certificate and install it in your federation and on the IdP server.

    2. Provide the downloaded Yandex Cloud SAML certificate to the IdP server. To learn how to do this, consult the identity provider's documentation or contact their support.

    Setting up a SAML application in your IdP

    The process for setting up a SAML application is IdP-specific and may vary. Here, you can find the general requirements to a SAML message that the IdP server will send to Yandex Cloud following user authentication.

    Sample 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.ru/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.ru/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.ru/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>

    Set up the SAML application for the message to contain:

    • The ID from the SAML authentication request sent by Yandex Cloud in the Response and SubjectConfirmationData elements of the InResponseTo attribute.

    • ACS URL in the following elements:

      • In Response of the Destination attribute.
      • In SubjectConfirmationData of the Recipient attribute.
      • Audience.
      How to get the 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.

    • User's unique ID was specified in the NameID element. We recommend using the User Principal Name (UPN) or email address as the ID.

    • Your IdP's redirect URL for user authentication was specified in the Issuer element.

    • Signed message was specified in the SignatureValue element, and the certificate used to sign the message, in the KeyInfo element.

    • Make sure to specify the username and email address in the AttributeStatement element; this will enable the user to contact Yandex Cloud support from the management console.

    For more information on how to set up a SAML application, consult you IdP's documentation or contact their support. You can also find examples of IdP-specific setups in our tutorials:

    Setting up user attribute mapping

    After a user gets authenticated, the IdP server will send a SAML message to Yandex Cloud confirming successful authentication. The message contains various user attributes, such as the ID, name, email address, etc.

    To correctly provide user information to Yandex Cloud Organization, you need to set up mapping between SAML message attributes and the personal data stored with your IdP.

    User data Comment SAML message elements
    Unique user ID Required attribute. We recommend using the User Principal Name (UPN) or email address. <NameID>
    Last name Displayed in Yandex Cloud services.
    Value length limit: 64 characters.    		 <Attribute> with the following parameter:
    Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname"
    Name Displayed in Yandex Cloud services.
    Value length limit: 64 characters.    		 <Attribute> with the following parameter:
    Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname"
    Full name Displayed in Yandex Cloud services.
    Here is an example: Ivan Ivanov.
    Value length limit: 64 characters.    		 <Attribute> with the following parameter:
    Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
    Email Used to send notifications from Yandex Cloud services.
    Example: ivanov@example.com.
    Value length limit: 256 characters.    		 <Attribute> with the following parameter:
    Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"
    Phone Used to send notifications from Yandex Cloud services.
    Example: +71234567890.
    Value length limit: 64 characters.    		 <Attribute> with the following parameter:
    Name="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone"
    Profile image Displayed in Yandex Cloud services.
    Images are transmitted in Base64 encoding.
    Value length limit: 204800 characters.    		 <Attribute> with the following parameter:
    Name="thumbnailPhoto"
    Group membership Used for dynamic mapping of group members. <Attribute> with the following parameter:
    Name="member"

    Note

    The thumbnailPhoto attribute value exceeding the length limit is ignored. Other attribute values exceeding the limit are truncated.

    Testing authentication

    Test federated user authentication:

    1. If you disabled the Automatically create users option in your federation, add the users manually.

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

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

      https://console.yandex.cloud/federations/<federation_ID>
      How to get the 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 will forward you to your IdP's authentication page.

    4. Enter your authentication data. By default, you must enter the UPN and password.

    5. Click Sign in.

    6. On successful authentication, the IdP server will redirect you to the ACS URL you specified in the server settings, and from there to the management console home page.

    Make sure you are logged in to the console as a federated user.

Previous
Overview
Next
Configuring user group mapping for your federation