[Yandex Cloud documentation](../../../index.md) > [Yandex Identity Hub](../../index.md) > [Step-by-step guides](../index.md) > Managing apps (SSO) > SAML apps > Creating an app

# Creating a SAML application in Yandex Identity Hub


To authenticate your [organization](../../concepts/organization.md)'s users to external apps using [SAML](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language)-based SSO, create a [SAML application](../../concepts/applications.md#saml) in Yandex Identity Hub and configure it appropriately both in Yandex Identity Hub and on your service provider side.

SAML apps can be managed by users with the `organization-manager.samlApplications.admin` [role](../../security/index.md#organization-manager-samlApplications-admin) or higher.

## Create an app {#create-app}

{% 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 ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps**.
  1. In the top-right corner, click ![Circles3Plus](../../../_assets/console-icons/circles-3-plus.svg) **Create application** and in the window that opens:
      1. Select the **SAML (Security Assertion Markup Language)** single sign-on method.
      1. In the **Name** field, specify a name for your new app. The name must be unique within the organization and follow these naming requirements:

          * It must be from 1 to 63 characters long.
          * It may contain lowercase Latin letters, numbers, and hyphens.
          * It must start with a letter and cannot end with a hyphen.

      1. Optionally, in the **Description** field, enter a description for the new app.
      1. Optionally, add [labels](../../../resource-manager/concepts/labels.md):

          1. Click **Add label**.
          1. Add a label in `key: value` format.
          1. Press **Enter**.
      1. Click **Create application**.

- 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 creating a SAML application:

     ```bash
     yc organization-manager idp application saml application create --help
     ```

  1. Create a SAML application:

     ```bash
     yc organization-manager idp application saml application create \
       --organization-id <organization_ID> \
       --name <application_name> \
       --description <application_description> \
       --labels <key>=<value>[,<key>=<value>]
     ```

     Where:

     * `--organization-id`: [ID of the organization](../organization-get-id.md) you want to create your SAML application in. This is a required setting.
     * `--name`: SAML application name. This is a required setting. The name must be unique within the organization and follow the naming requirements:

       * It must be from 1 to 63 characters long.
       * It may contain lowercase Latin letters, numbers, and hyphens.
       * It must start with a letter and cannot end with a hyphen.

     * `--description`: SAML application description. This is an optional setting.
     * `--labels`: List of [labels](../../../resource-manager/concepts/labels.md). This is an optional setting. You can specify one or more labels separated by commas in `<key1>=<value1>,<key2>=<value2>` format.

     Result:

     ```text
     id: ek0o663g4rs2********
     name: saml-app
     organization_id: bpf2c65rqcl8********
     group_claims_settings:
       group_distribution_type: NONE
     status: ACTIVE
     created_at: "2025-10-21T10:51:28.790866Z"
     updated_at: "2025-10-21T12:37:19.274522Z"
     ```

     Save the `id` field value: you will need it to configure your app.

  1. Optionally, get information about the application's certificates:

     ```bash
     yc organization-manager idp application saml signature-certificate list \
       --application-id <app_ID>
     ```

     When you create a SAML application, a certificate is automatically created to verify the SAML response signature.

- Terraform {#tf}

  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. Describe the SAML application parameters in the configuration file:

     ```hcl
     resource "yandex_organizationmanager_idp_application_saml_application" "saml_app" {
       organization_id = "<organization_ID>"
       name            = "<application_name>"
       description     = "<application_description>"
       labels          = {
         "<key>" = "<value>"
       }
     }
     ```

     Where:

     * `organization_id`: [ID of the organization](../organization-get-id.md) you want to create your SAML application in. This is a required setting.
     * `name`: SAML application name. This is a required setting. The name must be unique within the organization and follow the naming requirements:

         * It must be from 1 to 63 characters long.
         * It may contain lowercase Latin letters, numbers, and hyphens.
         * It must start with a letter and cannot end with a hyphen.

     * `description`: SAML application description. This is an optional setting.
     * `labels`: List of [labels](../../../resource-manager/concepts/labels.md). This is an optional setting.

     For more on the properties of the `yandex_organizationmanager_idp_application_saml_application` resource, see [this provider guide](../../../terraform/resources/organizationmanager_idp_application_saml_application.md).

  1. Create the resources:

     1. In the terminal, navigate to the configuration file directory.
     1. Make sure the configuration is correct using this command:
     
        ```bash
        terraform validate
        ```
     
        If the configuration is valid, you will get this message:
     
        ```bash
        Success! The configuration is valid.
        ```
     
     1. Run this command:
     
        ```bash
        terraform plan
        ```
     
        You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
     1. Apply the configuration changes:
     
        ```bash
        terraform apply
        ```
     
     1. Type `yes` and press **Enter** to confirm the changes.

     Terraform will create all the required resources. You can check the new resources and their settings in the [Cloud Center interface](https://center.yandex.cloud/organization).

   When you create a SAML application, a certificate is automatically created to verify the SAML response signature.

- API {#api}

  Use the [Application.Create](../../idp/application/saml/api-ref/Application/create.md) REST API method for the [Application](../../idp/application/saml/api-ref/Application/index.md) resource or the [ApplicationService/Create](../../idp/application/saml/api-ref/grpc/Application/create.md) gRPC API call.

{% endlist %}

## Set up your application {#setup-application}

To integrate an external application with the created SAML application in Yandex Identity Hub, complete the setup on the service provider side and in Yandex Identity Hub.

### Set up integration on the service provider side {#setup-sp}

You can look up the values of integration settings to use on the service provider side on the app info page in the [Cloud Center interface](https://center.yandex.cloud/organization/apps).

Depending on the options supported by your service provider, you can set the required settings manually or automatically by uploading a metadata file or specifying a metadata URL:

{% list tabs %}

- Manual setup

  1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
  1. In the left-hand panel, select ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and then, the SAML app.
  1. On the **Overview** tab, under **Identity provider (IdP) configuration**, copy the parameter values to use on the service provider side:

      * `Issuer / IdP EntityID`: Unique app ID. The value must be the same on the service provider's and Yandex Identity Hub side.
      * `Login URL`: Address to which the service provider will send requests for user authentication.
      * `Logout URL`: Address to which the service provider will send the SAML request when the user logs out of the system.

  1. Download the app certificate under **Application certificate** by clicking **Download certificate**.
  1. On the service provider side, set up integration with your Yandex Identity Hub SAML application by pasting the copied parameters and adding the certificate you downloaded. If you need help, refer to your service provider's documentation or support team.

- Metadata file

  1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
  1. In the left-hand panel, select ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and then, the SAML app.
  1. On the **Overview** tab, under **Identity provider (IdP) configuration**, click **Download metadata file**.

      The downloaded [XML](https://en.wikipedia.org/wiki/XML) file contains the values of all the required settings and a certificate to verify the signature of SAML responses. Upload the file to your service provider’s platform if the provider supports using metadata files to configure the application. If you need help, refer to your service provider's documentation or support team.

- Metadata URL

  1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
  1. In the left-hand panel, select ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and then, the SAML app.
  1. On the **Overview** tab, under **Identity provider (IdP) configuration**, copy the **Metadata URL** field value.

      Follow the link to get values for all the required settings and a certificate to verify the signature of SAML responses. Specify the link in the settings on the service provider side if the provider supports using a metadata URL to configure the application. If you need help, refer to your service provider's documentation or support team.

{% endlist %}

### Set up the SAML application in Yandex Identity Hub {#setup-idp}

Before configuring your SAML application in Yandex Identity Hub, get the required setting values from your service provider. Then, navigate to the SAML application settings in Yandex Identity Hub.

{% 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 ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and then, the SAML app.
  1. On the top right, click ![pencil](../../../_assets/console-icons/pencil.svg) **Edit** and in the window that opens:
     
     1. In the **SP EntityID ** field, enter the unique service provider ID.
     
         The value must be the same on the service provider's and Yandex Identity Hub side.
     1. In the **ACS URL** field, specify the URL Yandex Identity Hub will send the SAML response to.
     
         If your service provider uses ACS indexes instead of ACS URLs, in addition to ACS URLs, you can specify the index value you got on the service provider's side.
     
         Optionally, use the **Add URL** button to specify multiple ACS URLs/indexes.
     
         {% note info %}
         
         If you have specified an index for one of the URLs in the **ACS URL** field settings, you must also specify indexes for all the other URLs.
         
         {% endnote %}
     
     1. In the **Signature mode** field, select the elements of the SAML response that will be signed with a digital signature:
     
         * `Assertions`: Only provided attributes will be signed. This is a default value.
         * `Response`: The full SAML response will be signed.
         * `Assertions and Response`: The full SAML response and, separately, the provided attributes will be signed.
         
         {% note warning %}
         
         The signing mode configured for the SAML app on the Yandex Identity Hub side must be the same as the signing mode on the service provider's side.
         
         {% endnote %}
     
     1. Click **Save**.

- 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 setting up a SAML application:

     ```bash
     yc organization-manager idp application saml application update --help
     ```

  1. Run this command to configure service provider settings:

     ```bash
     yc organization-manager idp application saml application update \
       --id <app_ID> \
       --sp-entity-id <service_provider_ID> \
       --acs-urls <URL>[,<URL>] \
       --signature-mode <signature_mode>
     ```

     Where:

     * `--id`: SAML application ID. This is a required setting.
     * `--sp-entity-id`: Unique service provider ID. The value must be the same on the service provider's and Yandex Identity Hub side.
     * `--acs-urls`: URL or comma-separated URLs to which Yandex Identity Hub will send the SAML response. The ACS URL must follow the `https` schema. You can only use an encryption-free protocol for testing purposes on a local host (`http://127.0.0.1` and `http://localhost` values).
     * `--signature-mode`: SAML response elements that will be digitally signed. The possible values are:
       * `assertion_only`: Only the provided user attributes.
       * `response_only`: Full SAML response.
       * `response_and_assertion`: Full SAML response and, separately, the provided attributes.

     Result:

     ```text
     id: ek0o663g4rs2********
     name: saml-app
     organization_id: bpf2c65rqcl8********
     sp_entity_id: https://example.com/saml
     acs_urls:
       - url: https://example.com/saml/acs
     signature_mode: RESPONSE_AND_ASSERTION
     group_claims_settings:
       group_distribution_type: NONE
     status: ACTIVE
     created_at: "2025-10-21T10:51:28.790866Z"
     updated_at: "2025-10-21T12:37:19.274522Z"
     ```

- Terraform {#tf}

  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. Describe the SAML application configuration parameters in the configuration file:

     ```hcl
     resource "yandex_organizationmanager_idp_application_saml_application" "saml_app" {
       organization_id = "<organization_ID>"
       name            = "<application_name>"

       service_provider = {
         entity_id = "<service_provider_ID>"
         acs_urls  = [
           {
             url = "URL"
           }
         ]
         security_settings = {
           signature_mode = "RESPONSE_AND_ASSERTIONS"
         }
       }
     }
     ```

     Where:

     * `organization_id`: [ID of the organization](../organization-get-id.md) you want to create your SAML application in. This is a required setting.
     * `entity_id`: Unique service provider ID. The value must be the same on the service provider's and Yandex Identity Hub side.
     * `acs_urls`: List of URLs Yandex Identity Hub will send the SAML response to. The ACS URL must follow the `https` schema. You can only use an encryption-free protocol for testing purposes on a local host (`http://127.0.0.1` and `http://localhost` values).
     * `signature_mode`: SAML response elements that will be digitally signed. The possible values are:
       * `ASSERTION_ONLY`: Only the provided user attributes.
       * `RESPONSE_ONLY`: Full SAML response.
       * `RESPONSE_AND_ASSERTION`: Full SAML response and, separately, the provided attributes.

     For more on the properties of the `yandex_organizationmanager_idp_application_saml_application` resource, see [this provider guide](../../../terraform/resources/organizationmanager_idp_application_saml_application.md).

  1. Apply the changes:

     1. In the terminal, navigate to the configuration file directory.
     1. Make sure the configuration is correct using this command:
     
        ```bash
        terraform validate
        ```
     
        If the configuration is valid, you will get this message:
     
        ```bash
        Success! The configuration is valid.
        ```
     
     1. Run this command:
     
        ```bash
        terraform plan
        ```
     
        You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
     1. Apply the configuration changes:
     
        ```bash
        terraform apply
        ```
     
     1. Type `yes` and press **Enter** to confirm the changes.

     You can check the changes to the resources and their settings in the [Cloud Center interface](https://center.yandex.cloud/organization).

- API {#api}

  Use the [Application.Update](../../idp/application/saml/api-ref/Application/update.md) REST API method for the [Application](../../idp/application/saml/api-ref/Application/index.md) resource or the [ApplicationService/Update](../../idp/application/saml/api-ref/grpc/Application/update.md) gRPC API call.

{% endlist %}

### Configure user and group attributes {#setup-attributes}

You can configure the attributes Yandex Identity Hub will transmit to the service provider:

{% 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 ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and select the desired app.
  1. Navigate to the **Attributes** tab.
  1. To add a user group attribute, in the top-right corner of the page, click ![circles-3-plus](../../../_assets/console-icons/circles-3-plus.svg) **Add group attribute** and do the following in the window that opens:

      1. In the **Attribute name** field, set a name for the user group attribute. The attribute name must be unique within your application.
      1. In the **Transmitted groups** field, select one of these values:

          * `All groups`: In a SAML response, this field will include all [groups](../../concepts/groups.md) the user belongs to.
          
              The maximum number of groups this field can include is 1,000. If the user belongs to more groups than this, only the first thousand will go to the service provider. 
          * `Assigned groups only`: In a SAML response, this field will include only those groups that are explicitly specified on the **Users and groups** tab of your SAML app.

      1. Click **Add**.
  1. To add more user group attributes, in the top-right corner of the page, click ![plus](../../../_assets/console-icons/plus.svg) **Add attribute** and do the following in the window that opens:

      1. In the **Attribute name** field, set an attribute name unique within your app.
      1. In the **Value** field, select one of these values:

          * `SubjectClaims.sub`: [User ID](../users-get.md). The field value is the same as the one displayed in the **ID** field in the organization's user list in the Cloud Center's Yandex Identity Hub interface, e.g., `aje0fapf84ofj57q1r0b`.
          * `SubjectClaims.preferred_username`: Unique login for the user. The field value is the same as the one displayed in the **Username** field in the organization's user list in the Cloud Center's Yandex Identity Hub interface, e.g., `ivanov@example-federation.ru`.
          * `SubjectClaims.name`: User’s full name. The field value is the same as the one displayed in the **User** field in the organization's user list in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Ivan Ivanov`.
          * `SubjectClaims.given_name`: Name. The field value is the same as the one displayed in the **Name** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Ivan`.
          * `SubjectClaims.family_name`: Last name. The field value is the same as the one displayed in the **Surname** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Ivanov`.
          * `SubjectClaims.email`: Email address. The field value is the same as the one displayed in the **Email** field on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., `ivanov@example-company.ru`.
          * `SubjectClaims.phone_number`: Phone number. The field value is the same as the one displayed in the **Phone** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., `+74951234567`.
          * `SubjectClaims.company_name`: Company name. The field value is the same as the one displayed in the **Company name** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Holiday LLC`.
          * `SubjectClaims.department`: Department name. The field value is the same as the one displayed in the **Department** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Control systems department`.
          * `SubjectClaims.job_title`: Job title. The field value is the same as the one displayed in the **Job title** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Software engineer`.
          * `SubjectClaims.employee_id`: Digital user code from the company's HR system. The field value is the same as the one displayed in the **Employee ID** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., `08012`.
          
          {% note info %}
          
          You can add any of these attribute values more than once under different names.
          
          {% endnote %}

      1. Click **Add**.
  1. To modify an existing attribute, click its row and do the following in the window that opens:
  
      1. Edit the attribute name and/or value.

          You can edit format and value of the `NameID` attribute (user ID). The list of possible values for the **Value** field depends on the format you select. When you change the format, the attribute automatically resets to that format’s default value.
          
          Possible attribute formats and values:
          
          * `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress `: User ID is provided in email address format. Available values:
              * `SubjectClaims.preferred_username`: Default value when switching to this format.
          
                  The uniqueness and invariability of the provided ID is not guaranteed: one organization may have two users with the same `preferred_username` ID. For example: a [federated](../../../iam/concepts/users/accounts.md#saml-federation) and a [local](../../../iam/concepts/users/accounts.md#local) user can have the same value for this attribute.
          
                  If the federated user's `preferred_username` ID is not in email format, the provided ID will be automatically suffixed with `@<identity_federation_ID>` to bring it to that format.
              * `SubjectClaims.email`: User email address.
          
          * `urn:oasis:names:tc:SAML:2.0:nameid-format:persistent`: User ID is provided in the [organization's](../../concepts/organization.md) user [ID](../users-get.md) format. In this case, the provided value is guaranteed to be unique and invariable. Available values:
              * `SubjectClaims.sub`: Default value when switching to this format.
              * `SubjectClaims.external_id`: External user ID.
              * `SubjectClaims.employee_id`: Employee ID.
          * `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`: User ID is provided in the current user [session](../../concepts/sessions.md) ID. The value of this ID changes depending on session and cannot be used to uniquely identify the user.
          
              You cannot explicitly specify the `urn:oasis:names:tc:SAML:2.0:nameid-format:transient` format in the `NameID` attribute's settings: the user ID comes in the SAML response in this format only if this format was explicitly requested in the SAML request.
          
          {% note warning %}
          
          If the service provider's SAML request explicitly indicates the expected user's `NameID` value format, then the SAML response will present the value in the format specified in the SAML request. In this case, the format value specified in the Yandex Identity Hub settings will be ignored.
          
          {% endnote %}
      
      1. Click **Update**.
  1. To delete an existing user or group attribute, click ![ellipsis](../../../_assets/console-icons/ellipsis.svg) in its row and select ![trash-bin](../../../_assets/console-icons/trash-bin.svg) **Delete**, then confirm the deletion.

      {% note info %}

      You can delete any attributes except the required `NameID` attribute.

      {% endnote %}

- 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. View the description of the CLI command for adding an attribute:

     ```bash
     yc organization-manager idp application saml attribute create --help
     ```

  1. To add a user attribute, run this command:

     ```bash
     yc organization-manager idp application saml attribute create \
       --application-id <app_ID> \
       --name <attribute_name> \
       --value <attribute_value>
     ```

     Where:

     * `--application-id`: SAML application ID.
     * `--name`: Attribute name unique to your application.
     * `--value`: Attribute value. The possible values are:

       * `SubjectClaims.sub`: [User ID](../users-get.md). The field value is the same as the one displayed in the **ID** field in the organization's user list in the Cloud Center's Yandex Identity Hub interface, e.g., `aje0fapf84ofj57q1r0b`.
       * `SubjectClaims.preferred_username`: Unique login for the user. The field value is the same as the one displayed in the **Username** field in the organization's user list in the Cloud Center's Yandex Identity Hub interface, e.g., `ivanov@example-federation.ru`.
       * `SubjectClaims.name`: User’s full name. The field value is the same as the one displayed in the **User** field in the organization's user list in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Ivan Ivanov`.
       * `SubjectClaims.given_name`: Name. The field value is the same as the one displayed in the **Name** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Ivan`.
       * `SubjectClaims.family_name`: Last name. The field value is the same as the one displayed in the **Surname** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Ivanov`.
       * `SubjectClaims.email`: Email address. The field value is the same as the one displayed in the **Email** field on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., `ivanov@example-company.ru`.
       * `SubjectClaims.phone_number`: Phone number. The field value is the same as the one displayed in the **Phone** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., `+74951234567`.
       * `SubjectClaims.company_name`: Company name. The field value is the same as the one displayed in the **Company name** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Holiday LLC`.
       * `SubjectClaims.department`: Department name. The field value is the same as the one displayed in the **Department** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Control systems department`.
       * `SubjectClaims.job_title`: Job title. The field value is the same as the one displayed in the **Job title** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Software engineer`.
       * `SubjectClaims.employee_id`: Digital user code from the company's HR system. The field value is the same as the one displayed in the **Employee ID** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., `08012`.
       
       {% note info %}
       
       You can add any of these attribute values more than once under different names.
       
       {% endnote %}

  1. To add a user group attribute, run this command:

     ```bash
     yc organization-manager idp application saml attribute create \
       --application-id <app_ID> \
       --name <group_attribute_name> \
       --value <group_attribute_value>
     ```

     Where:

     * `--name`: User group attribute name. The attribute name must be unique within your application.
     * `--value`: Group attribute value. The possible values are:

       * `All groups`: In a SAML response, this field will include all [groups](../../concepts/groups.md) the user belongs to.
       
           The maximum number of groups this field can include is 1,000. If the user belongs to more groups than this, only the first thousand will go to the service provider. 
       * `Assigned groups only`: In a SAML response, this field will include only those groups that are explicitly specified on the **Users and groups** tab of your SAML app.

  1. To update the attribute, run this command:

     ```bash
     yc organization-manager idp application saml attribute update \
       --id <attribute_ID> \
       --name <new_attribute_name> \
       --value <new_attribute_value>
     ```

  1. To delete the attribute, run this command:

     ```bash
     yc organization-manager idp application saml attribute delete <attribute_ID>
     ```

- Terraform {#tf}

  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. Describe the following SAML application attributes in the configuration file:

     ```hcl
     resource "yandex_organizationmanager_idp_application_saml_application" "saml_app" {
       organization_id = "<organization_ID>"
       name            = "<application_name>"

       attribute_mapping = {
         name_id  = {
           format = "EMAIL"
         }

         attributes = [{
           name  = "email"
           value = "SubjectClaims.email"
         }, {
           name  = "firstName"
           value = "SubjectClaims.given_name"
         }, {
           name  = "lastName"
           value = "SubjectClaims.family_name"
         }]
       }

       group_claims_settings = {
         group_attribute_name    = "<group_attribute_name>"
         group_distribution_type = "ALL_GROUPS"
       }
     }
     ```

     Where:

     * `organization_id`: [ID of the organization](../organization-get-id.md) you want to create your SAML application in. This is a required setting.
     * `name`: SAML application name. This is a required setting.
     * `attributes`: List of attributes Yandex Identity Hub will be delivering to the service provider. Each attribute contains:
       * `name`: Attribute name unique to your application.
       * `value`: Attribute value. The possible values are:

         * `SubjectClaims.sub`: [User ID](../users-get.md). The field value is the same as the one displayed in the **ID** field in the organization's user list in the Cloud Center's Yandex Identity Hub interface, e.g., `aje0fapf84ofj57q1r0b`.
         * `SubjectClaims.preferred_username`: Unique login for the user. The field value is the same as the one displayed in the **Username** field in the organization's user list in the Cloud Center's Yandex Identity Hub interface, e.g., `ivanov@example-federation.ru`.
         * `SubjectClaims.name`: User’s full name. The field value is the same as the one displayed in the **User** field in the organization's user list in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Ivan Ivanov`.
         * `SubjectClaims.given_name`: Name. The field value is the same as the one displayed in the **Name** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Ivan`.
         * `SubjectClaims.family_name`: Last name. The field value is the same as the one displayed in the **Surname** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Ivanov`.
         * `SubjectClaims.email`: Email address. The field value is the same as the one displayed in the **Email** field on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., `ivanov@example-company.ru`.
         * `SubjectClaims.phone_number`: Phone number. The field value is the same as the one displayed in the **Phone** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., `+74951234567`.
         * `SubjectClaims.company_name`: Company name. The field value is the same as the one displayed in the **Company name** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Holiday LLC`.
         * `SubjectClaims.department`: Department name. The field value is the same as the one displayed in the **Department** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Control systems department`.
         * `SubjectClaims.job_title`: Job title. The field value is the same as the one displayed in the **Job title** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface. Here is an example: `Software engineer`.
         * `SubjectClaims.employee_id`: Digital user code from the company's HR system. The field value is the same as the one displayed in the **Employee ID** field under **Personal info** on the user info page in the Cloud Center's Yandex Identity Hub interface, e.g., `08012`.
         
         {% note info %}
         
         You can add any of these attribute values more than once under different names.
         
         {% endnote %}

     * `group_claims_settings`: User group attribute parameters:
       * `group_attribute_name`: User group attribute name. The attribute name must be unique within your application.
       * `group_distribution_type`: Group attribute value. The possible values are: 
         * `ASSIGNED_GROUPS`: In a SAML response, this field will include only those groups that are explicitly specified on the **Users and groups** tab of your SAML app.
         * `ALL_GROUPS`: In a SAML response, this field will include all [groups](../../concepts/groups.md) the user belongs to.

             The maximum number of groups this field can include is 1,000. If the user belongs to more groups than this, only the first thousand will go to the service provider. 

     For more on the properties of the `yandex_organizationmanager_idp_application_saml_application` resource, see [this provider guide](../../../terraform/resources/organizationmanager_idp_application_saml_application.md).

  1. Apply the changes:

     1. In the terminal, navigate to the configuration file directory.
     1. Make sure the configuration is correct using this command:
     
        ```bash
        terraform validate
        ```
     
        If the configuration is valid, you will get this message:
     
        ```bash
        Success! The configuration is valid.
        ```
     
     1. Run this command:
     
        ```bash
        terraform plan
        ```
     
        You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
     1. Apply the configuration changes:
     
        ```bash
        terraform apply
        ```
     
     1. Type `yes` and press **Enter** to confirm the changes.

     You can check the changes to the resources and their settings in the [Cloud Center interface](https://center.yandex.cloud/organization).

- API {#api}

  Use the [Application.Update](../../idp/application/saml/api-ref/Application/update.md) REST API method for the [Application](../../idp/application/saml/api-ref/Application/index.md) resource or the [ApplicationService/Update](../../idp/application/saml/api-ref/grpc/Application/update.md) gRPC API call.

{% endlist %}

Make sure the attributes you added are also added to the SAML app's integration settings and can be processed correctly on the service provider's side.

### Configure users and groups {#users-and-groups}

For your organization's users to be able to authenticate in an external application with Yandex Identity Hub's SAML app, you need to explicitly add these users and/or [user groups](../../concepts/groups.md) to the SAML application:

{% note info %}

Users and groups added to a SAML application can be managed by a user with the `organization-manager.samlApplications.userAdmin` [role](../../security/index.md#organization-manager-samlApplications-userAdmin) or higher.

{% endnote %}

{% 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 ![shapes-4](../../../_assets/console-icons/shapes-4.svg) **Apps** and select the required app.
  1. Navigate to the **Users and groups** tab.
  1. To add a user or user group to a SAML app:

      1. Click ![person-plus](../../../_assets/console-icons/person-plus.svg) **Add users**.
      1. In the window that opens, select the required user or user group.
      1. Click **Add**.
  1. To delete a user or user group from a SAML app:

      1. In the list of users and groups, click ![ellipsis](../../../_assets/console-icons/ellipsis.svg) and select ![trash-bin](../../../_assets/console-icons/trash-bin.svg) **Delete** next to the user or user group.
      1. Confirm the deletion.

- 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. Get the [user ID](../users-get.md) or [user group ID](../group-get-id.md).

  1. To add a user or user group to the app:
   
     1. See the description of the CLI command for adding users to an app:
   
        ```bash
        yc organization-manager idp application saml application add-assignments --help
        ```
   
     1. Run this command:
   
        ```bash
        yc organization-manager idp application saml application add-assignments \
          --id <app_ID> \
          --subject-id <user_or_group_ID>
        ```
   
        Where:
   
        * `--id`: App ID.
        * `--subject-id`: User or user group ID.
   
        Result:
   
        ```text
        assignment_deltas:
          - action: ADD
            assignment:
              subject_id: ajetvnq2mil8********
        ```

  1. To delete a user or user group from the app:

     1. See the description of the CLI command for removing users from an app:
   
        ```bash
        yc organization-manager idp application saml application remove-assignments --help
        ```
   
     1. Run this command:
   
        ```bash
        yc organization-manager idp application saml application remove-assignments \
          --id <app_ID> \
          --subject-id <user_or_group_ID>
        ```
   
        Where:
   
        * `--id`: SAML application ID.
        * `--subject-id`: User or user group ID.
   
        Result:
   
        ```text
        assignment_deltas:
          - action: REMOVE
            assignment:
              subject_id: ajetvnq2mil8********
        ```

- Terraform {#tf}

  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. Describe the parameters of the SAML application with users and groups in the configuration file:

     ```hcl
     resource "yandex_organizationmanager_idp_application_saml_application_assignment" "example_assignment" {
       application_id = "<SAML_app_ID>"
       subject_id     = "<user_or_group_ID>"
     }
     ```

     Where:

     * `application_id`: SAML application ID.
     * `subject-id`: ID of the user or user group that will have access to the SAML application. To get the user ID, follow [this guide](../users-get.md). To get the user group ID, follow [this guide](../group-get-id.md).

     For more on the properties of the `yandex_organizationmanager_idp_application_saml_application_assignment` resource, see [this provider guide](../../../terraform/resources/organizationmanager_idp_application_saml_application_assignment.md).

  1. Apply the changes:

     1. In the terminal, navigate to the configuration file directory.
     1. Make sure the configuration is correct using this command:
     
        ```bash
        terraform validate
        ```
     
        If the configuration is valid, you will get this message:
     
        ```bash
        Success! The configuration is valid.
        ```
     
     1. Run this command:
     
        ```bash
        terraform plan
        ```
     
        You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.
     1. Apply the configuration changes:
     
        ```bash
        terraform apply
        ```
     
     1. Type `yes` and press **Enter** to confirm the changes.

     You can check the changes to the resources and their settings in the [Cloud Center interface](https://center.yandex.cloud/organization).

- API {#api}

  Use the [Application.UpdateAssignments](../../idp/application/saml/api-ref/Application/updateAssignments.md) REST API method for the [Application](../../idp/application/saml/api-ref/Application/index.md) resource or the [ApplicationService/UpdateAssignments](../../idp/application/saml/api-ref/grpc/Application/updateAssignments.md) gRPC API call.

{% endlist %}

{% note tip %}

If you want to fine-tune user authentication in your applications, including authentication only from specific IP addresses, use [authentication policies](*authentication_policies).

{% endnote %}

[*authentication_policies]: Authentication policies are a Yandex Identity Hub tool that allows you to flexibly configure access to applications by denying or allowing authentication for specific users in specific applications and/or from specific IP addresses. For more information, see [Authentication policies in Yandex Identity Hub](../../concepts/authentication-policy.md).

## Make sure your application works correctly {#validate}

To make sure both your SAML application and service provider integration work correctly, authenticate to the external app as one of the users you added to the application.

#### Useful links {#see-also}

* [Updating a SAML app in Yandex Identity Hub](saml-update.md)
* [Deactivating and deleting a SAML application in Yandex Identity Hub](saml-deactivate-remove.md)
* [Adding a user](../add-account.md)
* [SAML applications](../../concepts/applications.md#saml)
* [Managing user groups](../manage-groups.md)