[Yandex Cloud documentation](../../../index.md) > [Yandex Identity Hub](../../index.md) > [Step-by-step guides](../index.md) > Managing domains > Associating a domain

# Associating a domain


You can associate a [domain](../../concepts/domains.md) with a [user pool](../../concepts/user-pools.md) or [federation](../../concepts/add-federation.md), which allows authentication through the [Login Discovery](../../concepts/domains.md#login-discovery) system. When authenticating, a user with your domain will be redirected to your federation or user pool.

To use a domain in a user pool or federation, domain ownership must be [verified](validate-domain.md) via a DNS record.

{% note warning %}

You can only associate each domain with one user pool or one federation.

{% endnote %}

## Associating a domain with a user pool {#userpool}

{% list tabs group=instructions %}

- Cloud Center UI {#cloud-center}

  1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization) using an administrator or organization owner account.
  1. In the left-hand panel, click ![userpool](../../../_assets/organization/userpool.svg) **User pools** and select the user pool.
  1. In the top-right corner, click **Add domain**.
  1. Enter the domain name.
  1. Click **Add**.

  To use the domain to add new users, have it [verified](validate-domain.md).

- 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 <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. See the description of the CLI command to associate a domain with a user pool:

     ```bash
     yc organization-manager idp userpool domain add --help
     ```

  1. Run this command:

      ```bash
      yc organization-manager idp userpool domain add <pool_ID> <domain>
      ```

      Result:

      ```text
      done (1s)
      domain: example. com
      status: NEED_TO_VALIDATE
      status_code: organization/domain-diagnostics#need-to-validate
      created_at: "2025-10-09T06:40:18.704791371Z"
      validated_at: "1970-01-01T00:00:00Z"
      challenges:
      - created_at: "2025-10-09T06:40:18.704791371Z"
      updated_at: "2025-10-09T06:40:18.704791371Z"
      type: DNS_TXT
      status: PENDING
      dns_challenge:
      name: _yandexcloud-challenge. example. com
      type: TXT
      value: TlHc5HKJDeQIgPqaoiiSXxgy3CWFD+MLMJJP********
      ```

      Save the `value` as you will need it to [validate the domain](validate-domain.md).

- API {#api}

  Use the [Userpool.AddDomain](../../idp/api-ref/Userpool/addDomain.md) REST API method for the [Userpool](../../idp/api-ref/Userpool/index.md) resource or the [UserpoolService/AddDomain](../../idp/api-ref/grpc/Userpool/addDomain.md) gRPC API call.

{% endlist %}

## Associating a domain with a federation {#federation}

{% list tabs group=instructions %}

- 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 <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. See the description of the CLI command to associate a domain with a federation:

     ```bash
     yc organization-manager federation saml add-domain --help
     ```

  1. Run this command:

      ```bash
      yc organization-manager federation saml add-domain <federation_name_or_ID> \
        --domain <domain>
      ```

      Where `--domain` is your domain.

      Result:

      ```text
      done (1s)
      domain: example. com
      status: NEED_TO_VALIDATE
      status_code: organization/domain-diagnostics#need-to-validate
      created_at: "2025-10-09T06:40:18.704791371Z"
      validated_at: "1970-01-01T00:00:00Z"
      challenges:
      - created_at: "2025-10-09T06:40:18.704791371Z"
      updated_at: "2025-10-09T06:40:18.704791371Z"
      type: DNS_TXT
      status: PENDING
      dns_challenge:
      name: _yandexcloud-challenge. example. com
      type: TXT
      value: TlHc5HKJDeQIgPqaoiiSXxgy3CWFD+MLMJJP********
      ```

      Save the `value` as you will need it to [validate the domain](validate-domain.md).

- API {#api}

  Use the [Federation.AddDomain](../../saml/api-ref/Federation/addDomain.md) REST API method for the [Federation](../../saml/api-ref/Federation/index.md) resource or the [FederationService/AddDomain](../../saml/api-ref/grpc/Federation/addDomain.md) gRPC API call.

{% endlist %}