[Yandex Cloud documentation](../../../../index.md) > [Yandex Identity Hub](../../../index.md) > [Tutorials](../../index.md) > [Setting up single sign-on (SSO) for apps](../index.md) > Loop > SAML

# Creating a SAML app in Yandex Identity Hub for integration with Loop

[Loop](https://loop.ru/) is a corporate messenger with single sign-on support based on the SAML standard.

For the users of your [organization](../../../concepts/organization.md) to be able to authenticate to Loop via SAML SSO, create a [SAML app](../../../concepts/applications/saml.md) in Yandex Identity Hub and configure it both in Yandex Identity Hub and Loop.

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

To give access to Loop to the users of your organization:

1. [Generate a key and certificate](#generate-key-cert).
1. [Create an app](#create-app).
1. [Set up the integration](#setup-integration).
1. [Add users](#add-users).
1. [Make sure the application works correctly](#validate).

## Generate a key and certificate {#generate-key-cert}

To encrypt and sign SAML responses, Loop requires a service provider (SP) certificate and private key. To generate it, use `openssl`:

```bash
openssl req -x509 -newkey rsa:2048 \
  -keyout private.key \
  -out certificate.crt \
  -days 365 -nodes \
  -subj "/CN=<instance_name>.loop.ru"
```

Where `<instance_name>` is your Loop instance name (subdomain on `loop.ru`).

This command will create two files, `private.key` and `certificate.crt`. Save them, as you will need them to configure SAML in Loop.

## 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. 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: `loop-saml-app`.
        1. Optionally, add a description and [labels](../../../../resource-manager/concepts/labels.md) for the app.
        1. Click **Create application**.
    1. On the **Overview** tab, under **Application certificate**, click **Download certificate** and save the new app’s certificate, `loop-saml-app.cer`; you will need it to configure SAML in Loop.

{% endlist %}

## Set up the integration {#setup-integration}

To configure Loop integration with the SAML app you created in Yandex Identity Hub, complete the configuration on both the Yandex Identity Hub side and in Loop.

### Configure endpoints and upload the service provider certificate {#sp-endpoints}

Specify the details of your Loop instance. To find out endpoint values, go to the Loop system console at `https://<instance_name>.loop.ru/admin_console/authentication/saml` and copy the `Entity ID` and `ACS URL` values from the SAML settings.

{% 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, click ![shapes-4](../../../../_assets/console-icons/shapes-4.svg) **Apps** and select `loop-saml-app`.
    1. At the top right, click ![pencil](../../../../_assets/console-icons/pencil.svg) **Edit** and in the window that opens:
        1. Under **Service provider (SP) configuration**:
            1. In the **SP EntityID ** field, enter `Entity ID`, the unique service provider ID.
            1. In the **ACS URL** field, enter `ACS URL`, the address to which the service provider will send requests for user authentication.
            1. Optionally, add more `ACS URL` addresses by pressing **Add URL**.
            1. Optionally, in the **SP Logout URL** field, add the address to which the IdP will send the SAML response after the user successfully logs out.
            1. In the **Signature mode** field, select which parts of the SAML response will be signed:

                * `Assertions`: Sign only user data payloads (ID, attributes, and authentication timestamp).
                * `Response`: Sign the entire SAML response.
                * `Assertions and Response`: Sign both the user payloads and the entire response.
        1. Optionally, to only accept requests signed by one of the added certificates, enable **Only accept signed requests** and add the certificate by clicking **Add certificate**.
        1. To ensure SAML response encryption using the selected certificate, enable **Encrypt assertion in response** and add the previously created certificate by clicking **Add certificate**.
        1. From the **Data encryption algorithm** list, select **RSA-OAEP-SHA256 (recommended)**.
        1. From the **Key encryption algorithm** list, select **RSA-OAEP-SHA1**.
        1. Click **Save**.

{% endlist %}

### Configure user attributes {#user-attributes}

{% 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, click ![shapes-4](../../../../_assets/console-icons/shapes-4.svg) **Apps** and select `loop-saml-app`.
    1. Navigate to the **Attributes** tab.
    1. Add an attribute for providing the username. At the top right, click **Add attribute** and in the window that opens:
        * In the **Attribute name** field, enter `username`.
        * In the **Value** field, select `SubjectClaims.preferred_username`.

        {% note info %}
        
        Use transformations to change the attribute value before sending it to the application, e.g., to convert text to lower case, remove spaces, or extract part of the row. Transformations apply one by one, from top to bottom.
        
        {% endnote %}

        * Click **Add transformation**, and select the `ExtractBefore` transformation type. In the **Substring** field, enter `@`. This will extract the part of email address up to the `@` symbol to serve as the username in the Loop.
        * Click **Add**.

{% endlist %}

### Set up SAML authentication in Loop {#setup-sp}

1. Log in to the Loop system console at `https://<instance_name>.loop.ru/admin_console/authentication/saml`.
1. Under **Authentication**:
   1. Activate the **Enable SAML 2.0 login** option.
   1. In the **IdP metadata URL** field, enter the address to which Loop sends its metadata request.

      {% cut "How to find out the address of the app metadata file" %}

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

      {% endcut %}

   1. In the **SAML SSO URL** field, enter the address to which Loop sends the SAML request to initiate the login flow.

      {% cut "How to find out the authentication request address" %}

      1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
      1. In the left-hand panel, navigate to ![shapes-4](../../../../_assets/console-icons/shapes-4.svg) **Apps** and select `loop-saml-app`.
      1. Under **Identity provider (IdP) configuration**, copy the **Login URL** field value.

      {% endcut %}

   1. In the **IdP issuer URL** field, enter the address used for SAML requests.

      {% cut "How to find out the IdP issuer URL" %}

      1. Log in to [Yandex Identity Hub](https://center.yandex.cloud/organization).
      1. In the left-hand panel, navigate to ![shapes-4](../../../../_assets/console-icons/shapes-4.svg) **Apps** and select `loop-saml-app`.
      1. Under **Identity provider (IdP) configuration**, copy the **Issuer / IdP EntityID** field value.

      {% endcut %}

   1. Under **CA public certificate**, upload the `loop-saml-app.cer` certificate file.
   1. Enable **Signature verification**.
   1. In the **Service provider sign-in URL** field, enter `https://<instance_name>.loop.ru/login/sso/saml`. Also specify this address in the **Service provider ID** field.
   1. Activate the **Enable encryption** option.
   1. Under **Service provider private key**, upload the `private.key` file.
   1. Under **Service provider public certificate**, upload the `certificate.crt` file.
   1. In the **Signature algorithm** list, select the `RSAwithSHA512` request signature algorithm.
   1. In the **Canonicalization algorithm** list, select `Exclusive XML Canonicalization 1.0 (skip comments)`.
   1. In the **Email attribute** field, specify `emailaddress`.
   1. In the **Username attribute** field, specify `username`.
   1. Optionally, in the **Name attribute** field, specify the `givenname` attribute to populate the user’s first name in Loop.
   1. Optionally, in the **Last name attribute** field, specify the `surname` attribute to populate the user’s last name in Loop.
   1. Optionally, in the **Login button text** field, enter the sign-in button text to display on the login page. The default text is `Sign in with SAML`.
1. Click **Save**.

## Add users {#add-users}

To enable user authentication in Loop, add the required users and/or [user groups](../../../concepts/groups.md) to your Yandex Identity Hub 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 %}

To add users to a SAML application:

{% 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. Click ![person-plus](../../../../_assets/console-icons/person-plus.svg) **Add users**.
    1. In the window that opens, select the required users.
    1. Click **Add**.

{% 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 app and integration with Loop work correctly, log in to Loop as one of the users you added to the app. Proceed as follows:

1. In your browser, open the login page of your Loop instance: `https://<instance_name>.loop.ru`.
1. Select **Sing in with SAML**.
1. Authenticate in Yandex Cloud under a user account from your organization.
1. Make sure you have signed in to Loop following a successful authentication.