Contact UsGet started

Configuring an identity federation

Written by
Updated at November 18, 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 certificate for your IdP.

    • 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 session in Yandex Cloud expires, the identity provider will ask the user to re-authenticate.

Terraform allows you to quickly create a cloud infrastructure in Yandex Cloud and manage it using configuration files. Configuration files store the infrastructure description in the HashiCorp Configuration Language (HCL). Terraform and its providers are distributed under the Business Source License.

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

If you change the configuration files, Terraform automatically detects which part of your configuration is already deployed, and what should be added or removed.

  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>"
    }
}

    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.

  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 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 to add your certificate to.

    4. At the bottom of the page, under Certificates, click Adding a certificate.

    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_content>"
}

    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

    To ensure the authentication is not interrupted when the certificate expires, add multiple certificates to the federation, i.e., both the current one and those to use afterwards. When one certificate goes invalid, Yandex Cloud will use another one to verify the signature.

    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. Download a Yandex Cloud certificate:

      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 required federation. In the Sign authentication requests field, click Download certificate.

    2. Add the certificate to the IdP server. To learn how to do this, consult the 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.

    • Username and email address must be specified 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.
    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 federated authentication

    Test that federated authentication works properly:

    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 that you specified in the server settings, and then, 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