[Yandex Cloud documentation](../../index.md) > [Yandex Identity Hub](../index.md) > [Step-by-step guides](index.md) > Managing identity federations > Configuring an identity federation # Configuring an identity federation You can use [identity federation](../concepts/add-federation.md) to set up user authentication in the cloud. Identity federations are compatible with any identity provider (IdP) that supports [SAML 2.0](https://wiki.oasis-open.org/security/FrontPage). To set up authentication through an identity federation, you need _at least_ the `organization-manager.federations.editor` [role](../security/index.md#organization-manager-federations-editor) for the [organization](../concepts/organization.md). To set up federated authentication, follow these steps: 1. [Create an identity federation](#create-federation). 1. [Add the IdP server certificate to the federation](#add-certificate-fed). 1. [Add the federation certificate to the IdP server](#add-certificate-idp). 1. [Set up a SAML application in your IdP](#configure-sso). 1. [Configure user attribute mapping](#claims-mapping). 1. [Test authentication](#test-auth). For IdP-specific examples, see our tutorials: * [Active Directory](../tutorials/federations/integration-adfs.md). * [Google Workspace](../tutorials/federations/integration-gworkspace.md). * [Microsoft Entra ID](../tutorials/federations/integration-azure.md). * [Keycloak](../tutorials/federations/integration-keycloak.md). ## Creating an identity federation {#create-federation} {% list tabs group=instructions %} - Cloud Center UI {#cloud-center} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization). 1. In the left-hand panel, select ![VectorSquare](../../_assets/console-icons/vector-square.svg) **Federations**. 1. Click ![Circles3Plus](../../_assets/console-icons/circles-3-plus.svg) **Create federation**. 1. Give your federation a name. It must be unique within the folder. 1. (Optional) Add a description for your federation. 1. In the **Cookie lifetime** field, specify the time before the browser asks the user to re-authenticate. 1. 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. 1. In the **Single Sign-On method** field, select the redirect binding method. Most IdPs support the **POST** binding method. 1. 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. 1. 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](add-account.md#add-user-sso) 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. You will need to install a Yandex Cloud SAML certificate on the IdP side. In the **SAML certificates** block that appears, you will see the information about the current Yandex Cloud SAML certificate. Click ![ArrowDownToLine](../../_assets/console-icons/arrow-down-to-line.svg) **Download** and save the downloaded certificate file. You will need to upload it to you IdP server. {% note 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](renew-yc-certificate.md) it on the IdP provider's side and in your federation well in advance. {% endnote %} * **Case-insensitive user names**: If enabled, federated user name IDs will be case-insensitive. * **Mandatory re-authentication (ForceAuthn) in IdP**: Once the Yandex Cloud session expires, your IdP will prompt the user to re-authenticate. 1. Click **Create federation**. - CLI {#cli} If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install). The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id ` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions. To create a federation: 1. View the description of the create federation command: ```bash yc organization-manager federation saml create --help ``` 1. Specify the federation parameters in the create command: ```bash yc organization-manager federation saml create \ --name \ --organization-id \ --cookie-max-age \ --issuer "" \ --sso-binding \ --sso-url "" \ --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. * `--encrypted-assertions`: Ensures authentication requests from Yandex Cloud contain a digital signature. You will need to install a Yandex Cloud certificate on the IdP side. This is an optional setting. * `--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](add-account.md#add-user-sso) your federated users. This is an optional setting. 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 enabled, federated user name IDs will be case-insensitive. This is an optional setting. * `--force-authn`: Once the Yandex Cloud session expires, your IdP will prompt the user to re-authenticate. This is an optional parameter. - Terraform {#tf} With [Terraform](https://www.terraform.io/), 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](https://github.com/hashicorp/terraform/blob/main/LICENSE). The [Yandex Cloud provider for Terraform](https://github.com/yandex-cloud/terraform-provider-yandex) is distributed under the [MPL-2.0](https://www.mozilla.org/en-US/MPL/2.0/) license. For more information about the provider resources, see the guides on the [Terraform](https://www.terraform.io/docs/providers/yandex/index.html) website or [its mirror](../../terraform/index.md). 1. If you do not have Terraform yet, [install it and configure the Yandex Cloud provider](../../tutorials/infrastructure-management/terraform-quickstart.md#install-terraform). To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), [authenticate](../../terraform/authentication.md) using the appropriate method. 1. Create a configuration file describing the federation. Here is an example of the configuration file structure: ```hcl resource "yandex_organizationmanager_saml_federation" federation { name = "my-federation" description = "My new SAML federation" organization_id = "" issuer = "" sso_url = "" sso_binding = "" cookie_max_age = auto_create_account_on_login = "" case_insensitive_name_ids = "" security_settings { encrypted_assertions = "" force_authn = "" } } ``` Where: * `name`: Federation name. It must be unique within the folder. * `description`: Federation description. This is an optional setting. * `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](add-account.md#add-user-sso) 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. You will need to install a Yandex Cloud certificate on the IdP side. * `force-authn`: Once the Yandex Cloud session expires, your IdP will prompt the user to re-authenticate. This is an optional parameter. For more on the properties of the `yandex_organizationmanager_saml_federation` resource, see [this provider guide](../../terraform/resources/organizationmanager_saml_federation.md). 1. Make sure the Terraform configuration files are correct: 1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure. 1. Run this command: ```bash terraform validate ``` Terraform will show any errors found in your configuration files. 1. Create a federation: 1. Run this command to view the planned changes: ```bash terraform plan ``` If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources. 1. If everything looks correct, apply the changes: 1. Run this command: ```bash terraform apply ``` 1. Confirm updating the resources. 1. Wait for the operation to complete. You can check the new federation and its settings in the [Federations](https://org.yandex.cloud/federations) section of your organization. {% note info %} You can also configure an [end-to-end Keycloack federation setup](https://github.com/yandex-cloud-examples/yc-iam-federation-with-keycloak-vm) using Terraform. {% endnote %} - API {#api} 1. Create a file with the request body, e.g., `body.json`: ```json { "name": "my-federation", "description": "My new SAML federation", "organizationId": "", "cookieMaxAge":"43200s", "issuer": "", "ssoUrl": "", "ssoBinding": "", "autoCreateAccountOnLogin": true, "caseInsensitiveNameIds": true, "securitySettings": { "encryptedAssertions": true, "forceAuthn": true } } ``` Where: * `name`: Federation name. It must be unique within the folder. * `organizationId`: Organization ID. * `description`: Federation description. This is an optional setting. * `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](add-account.md#add-user-sso) 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. You will need to install a Yandex Cloud certificate on the IdP side. * `forceAuthn`: Parameter that requires the user to re-authenticate once their Yandex Cloud session expires. This is an optional parameter. 1. To create a federation, use the [create](../saml/api-ref/Federation/create.md) REST API method for the [Federation](../saml/api-ref/Federation/index.md) resource or the [FederationService/Create](../saml/api-ref/grpc/Federation/create.md) gRPC API call and provide a file with the query parameters in your query. Query example: ```bash curl \ --request POST \ --header "Content-Type: application/json" \ --header "Authorization: Bearer " \ --data '@body.json' \ https://organization-manager.api.cloud.yandex.net/organization-manager/v1/saml/federations ``` Response example: ```bash { "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. {% endlist %} ## Adding an IdP server certificate to a federation {#add-certificate-fed} When informing Yandex Identity Hub that a user has been authenticated, the IdP signs the message with its own certificate. To enable Yandex Identity Hub 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`. 1. Convert the certificate file to the PEM format: ```text -----BEGIN CERTIFICATE----- -----END CERTIFICATE----- ``` 1. Add the certificate to the federation: {% list tabs group=instructions %} - Cloud Center UI {#cloud-center} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization) with an administrator or organization owner account. 1. In the left-hand panel, select ![VectorSquare](../../_assets/console-icons/vector-square.svg) **Federations**. 1. Click the row with the federation you want to add a certificate to. 1. Click **Certificates** under **Adding a certificate** at the bottom of the page. 1. Enter certificate name and description. 1. 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. 1. Click **Add**. - CLI {#cli} If you do not have the Yandex Cloud CLI yet, [install and initialize it](../../cli/quickstart.md#install). The folder used by default is the one specified when [creating](../../cli/operations/profile/profile-create.md) the CLI profile. To change the default folder, use the `yc config set folder-id ` command. You can also specify a different folder for any command using `--folder-name` or `--folder-id`. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions. 1. View the description of the add certificate command: ```bash yc organization-manager federation saml certificate create --help ``` 1. Add a federation certificate by specifying the certificate file path: ```bash yc organization-manager federation saml certificate create --federation-name \ --name "" \ --certificate-file ``` - API {#api} 1. Create the `body.json` request body file and specify the contents of the certificate in the `data` property: ```json { "federationId": "", "description": "", "name": "", "data": "" } ``` 1. Use the [create](../saml/api-ref/Certificate/create.md) REST API method for the [Certificate](../saml/api-ref/Certificate/index.md) resource or the [FederationService/Create](../saml/api-ref/grpc/Certificate/create.md) gRPC call and provide a file with the request parameters in your request. Sample cURL request: ```bash 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" ``` {% endlist %} {% note 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](subscribe-user-for-notifications.md) to notifications from the organization. Subscribed users get notifications 60, 30, and 5 days before the certificate expires and after its expiration. {% endnote %} ## Adding a federation certificate to an IdP server {#add-certificate-idp} If you enabled **Sign authentication requests** when creating the 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 a Yandex Cloud SAML certificate when creating the identity federation, download it now: {% list tabs group=instructions %} - Cloud Center UI {#cloud-center} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization) with an administrator or organization owner account. 1. In the left-hand panel, select ![VectorSquare](../../_assets/console-icons/vector-square.svg) **Federations**. 1. In the list that opens, select the identity federation of interest. In the **Sign authentication requests** field, click ![ArrowDownToLine](../../_assets/console-icons/arrow-down-to-line.svg) **Download certificate**. If you see ![TriangleExclamation](../../_assets/console-icons/triangle-exclamation.svg) to the left of ![ArrowDownToLine](../../_assets/console-icons/arrow-down-to-line.svg) **Download certificate**, your current Yandex Cloud SAML certificate has either expired or is about to expire. [Download a re-issued Yandex Cloud SAML certificate and install it](renew-yc-certificate.md) in your identity federation. {% note tip %} In the top-right corner, click ![pencil](../../_assets/console-icons/pencil.svg) **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](renew-yc-certificate.md) in your federation and on the IdP server. {% endnote %} {% endlist %} 1. 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 {#configure-sso} 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. {% cut "Sample SAML message" %} ```xml http://example.org/auth http://example.org/auth phUQR... VACd7O... MIIC7j... user@example.org https://console.cloud.yandex.ru/federations/bfbrotp6l1b2avhe1spu user@example.org First Name Last Name ``` {% endcut %} 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`. {% cut "How to get the federation ID" %} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization). 1. In the left-hand panel, select ![VectorSquare](../../_assets/console-icons/vector-square.svg) **Federations**. 1. Select the required federation and copy the **Identifier** field value on the federation info page. {% endcut %} {% cut "How to get the federation ACS URL" %} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization). 1. In the left-hand panel, select ![VectorSquare](../../_assets/console-icons/vector-square.svg) **Federations**. 1. Select the required federation and copy the **ACS URL** field value on the federation info page. {% endcut %} * 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](https://center.yandex.cloud/support). 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: * [Active Directory](../tutorials/federations/integration-adfs.md). * [Google Workspace](../tutorials/federations/integration-gworkspace.md). * [Microsoft Entra ID](../tutorials/federations/integration-azure.md). * [Keycloak](../tutorials/federations/integration-keycloak.md). ## Setting up user attribute mapping {#claims-mapping} {% note info %} The federated user's [attributes](setup-federation.md#claims-mapping) are loaded into their profile in the Yandex Identity Hub [organization](../concepts/organization.md) after the user's first authentication to Yandex Cloud. {% endnote %} 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 Identity Hub, you need to set up mapping between SAML message attributes and the personal data stored with your IdP. #| || **User data** | **Comment** | **Attribute names in SAML Response** || || Unique user ID | Required attribute. We recommend using the User Principal Name (UPN) or email address. | * `NameID` || || Surname | Displayed in Yandex Cloud services. Value length limit: 64 characters. | * `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` * `surname` * `lastname` || || Name | Displayed in Yandex Cloud services. Value length limit: 64 characters. | * `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname` * `givenname` * `firstname` || || Full name | Displayed in Yandex Cloud services. Here is an example: Ivan Ivanov. Value length limit: 64 characters. | * `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` * `name` * `displayname` || || Email | Used to send notifications from Yandex Cloud services. Here is an example: `ivanov@example.com`. Value length limit: 256 characters. | * `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` * `emailaddress` * `email` || || Phone | Used to send notifications from Yandex Cloud services. Here is an example: +71234567890. Value length limit: 64 characters. | * `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/mobilephone` * `phone` * `phones` * `mobile` || || Profile image | Displayed in Yandex Cloud services. Images are transmitted in [Base64](https://ru.wikipedia.org/wiki/Base64) encoding. Value length limit: 204,800 characters. | * `thumbnailPhoto` * `photos` * `picture` || || Group membership | Used for dynamic mapping of group members. | * `member` * `http://schemas.xmlsoap.org/claims/group` * `http://schemas.microsoft.com/ws/2008/06/identity/claims/groups` || || Company name | Displayed in Yandex Cloud services. Here is an example: Holiday LLC. | * `company_name` * `companyname` || || Organizational unit | Displayed in Yandex Cloud services. Here is an example: Control systems department. | * `department` || || Job title | Displayed in Yandex Cloud services. Here is an example: Software engineer. | * `job_title` * `jobtitle` || || Employee ID | Displayed in Yandex Cloud services. Here is an example: 08012. | * `employee_id` * `employeeid` || |# {% note info %} The `thumbnailPhoto` attribute value exceeding the length limit is ignored. Other attribute values exceeding the limit are truncated. {% endnote %} ## Testing authentication {#test-auth} Test federated user authentication: 1. If you disabled the **Automatically create users** option in your federation, [add](add-account.md#add-user-sso) the users manually. 1. Open the browser in guest or incognito mode for a clean new user simulation. 1. Follow the URL to log in to the management console: ```url https://console.yandex.cloud/federations/ ``` {% cut "How to get the federation ID" %} 1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization). 1. In the left-hand panel, select ![VectorSquare](../../_assets/console-icons/vector-square.svg) **Federations**. 1. Select the required federation and copy the **Identifier** field value on the federation info page. {% endcut %} The browser will forward you to your IdP's authentication page. 1. Enter your authentication data. By default, you must enter the UPN and password. 1. Click **Sign in**. 1. 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.