[Yandex Cloud documentation](../../index.md) > [Yandex Identity Hub](../index.md) > [Step-by-step guides](index.md) > Managing identity federations > Setting up a domain in an identity federation

# Setting up a domain in an identity federation


A [domain](../concepts/domains.md) allows you to authenticate through [Login Discovery](../concepts/domains.md#login-discovery). When authenticating, a user with your domain will be redirected to your [identity federation](../concepts/add-federation.md).

## Associating a domain {#add}

{% 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](user-pools/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 %}


## Getting a list of domains {#list}

{% 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 for getting a list of [domains](../concepts/domains.md) in a [federation](../concepts/add-federation.md):

     ```bash
     yc organization-manager federation saml list-domains --help
     ```

  1. Run this command:

      ```bash
      yc organization-manager federation saml list-domains <federation_name_or_ID>
      ```
      
- API {#api}

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

{% endlist %}

## Viewing information about a domain {#get}

{% 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 for viewing information about a [domain](../concepts/domains.md) in a [federation](../concepts/add-federation.md):

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

  1. Run this command:

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

      Where `--domain` is your domain.

- API {#api}

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

{% endlist %}

## Deleting a domain {#delete}

You cannot delete the default domain or a domain with associated users.

{% 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 for deleting a domain from a [federation](../concepts/add-federation.md):

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

  1. Run this command:

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

      Where `--domain` is your domain.

      For example, delete `my-domain.ru` from `my-federation`:

      ```bash
      yc organization-manager federation saml delete-domain my-federation \
        --domain my-domain.ru
      ```

- API {#api}

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

{% endlist %}