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

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

[VK Cloud](https://cloud.vk.com/) is a Russian cloud platform offering IaaS and PaaS services, data and AI/ML tools, as well as solutions you need to build a cloud infrastructure. VK Cloud supports [SAML](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language)-based user authentication via an identity federation.

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

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 VK Cloud to the users of your organization:

1. [Create an app](#create-app).
1. [Set up the integration](#setup-integration).
1. [Add users and configure permissions](#add-users).
1. [Make sure the application works correctly](#validate).

## 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: `vkcloud-saml`.

        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**.

{% endlist %}

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

To integrate VK Cloud with the SAML app you created in Yandex Identity Hub, complete the setup both on the VK Cloud and Yandex Identity Hub side.

### Configuring an identity federation on the VK Cloud side {#setup-sp}

{% note info %}

Only a project owner can create an identity federation in VK Cloud.

{% endnote %}

1. Get the metadata for the [new app](#create-app):

    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 required metadata and a certificate used for SAML response signature verification.

1. Create an identity federation in VK Cloud using Yandex Identity Hub metadata:

    1. Go to your [VK Cloud account](https://cloud.vk.com/account).
    1. Open the **Identity federation** section and navigate to the **Federations** tab.
    1. Click **Create**.
    1. Click **Upload IdP metadata** and upload the XML metadata file you downloaded from Yandex Identity Hub.
    1. Click **Upload**.

1. In the new federation's info, copy and save the federation ID. You will need it to set up a SAML application in Yandex Identity Hub and to manage federated user sign-ins.

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

#### Set up service provider endpoints {#sp-endpoints}

{% 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. At the top right, click ![pencil](../../../../_assets/console-icons/pencil.svg) **Edit** and in the window that opens:
        1. In the **SP EntityID ** field, specify the address `https://msk.cloud.vk.com/federation-service/v1/federation/saml/<federation_ID>/metadata`, where `<federation_ID>` is the federation ID you copied when [creating the federation in VK Cloud](#setup-sp).
        1. In the **ACS URL** field, enter this address: `https://msk.cloud.vk.com/federation-service/v1/federation/saml/<federation_ID>/acs`.
        1. Click **Save**.

{% endlist %}

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

{% note warning %}

For the federation to function correctly in VK Cloud, SAML attribute names must have URI prefixes: `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/` for user attributes; `http://schemas.xmlsoap.org/claims/` for group attribute.
Without these prefixes (and if there are case variations, e.g., `Group`), attribute mapping in VK Cloud may fail.

{% endnote %}

Set user attributes for integration with VK Cloud:

{% 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. Make sure the attributes are configured as follows:

        Attribute | Value
        --- | ---
        `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress` | `SubjectClaims.email`
        `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name` | `SubjectClaims.firstName`
        `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname` | `SubjectClaims.lastName`

    1. If you plan to use group mapping, add an attribute for group transfer:

        1. Click **Attribute name**.
        1. In the **Attribute name** field, enter `http://schemas.xmlsoap.org/claims/Group`.
        1. In the **Value** field, specify `SubjectClaims.groups`.
        1. Click **Save**.

{% endlist %}

## Add users and configure permissions {#add-users}

For the users of your organization to be able to authenticate in VK Cloud via a SAML application in Yandex Identity Hub, add them to the application and configure access permissions in VK Cloud.

{% 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 %}

### Add users to the Yandex Identity Hub SAML application {#add-app-users}

{% 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 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).

### Configure group and role mapping in VK Cloud {#vkcloud-groups-roles}

To define federated users' access permissions in VK Cloud, configure mappings between IdP groups and VK Cloud roles.

1. Go to your [VK Cloud account](https://cloud.vk.com/account).
1. Open the **Identity federation** section and navigate to the **Groups** tab.
1. Select the project you want to configure the federation for.
1. Click **Add** (or **Add group** if groups already exist).
1. Specify the IdP group name in lowercase and select the scope of permissions (**Domain** or **Project**), then proceed to assign roles.
1. Click **Add**.

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

To make sure your SAML app and its integration with VK Cloud work correctly, sign in to VK Cloud as one of the users you added to the app.

Proceed as follows:

1. In your browser, open the federated user sign-in URL: `https://cloud.vk.com/v1/federation/saml/<federation_ID>/signin`, where `<federation_ID>` is the federation ID you copied when [creating the federation in VK Cloud](#setup-sp).
1. Authenticate in Yandex Cloud under a user account from your organization.
1. Make sure you have signed in to VK Cloud following a successful authentication.