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

# Creating a SAML app in Yandex Identity Hub for integration with Managed Service for GitLab

For the users of your [organization](../../concepts/organization.md) to be able to authenticate to Yandex Managed Service for GitLab via [SAML](https://en.wikipedia.org/wiki/Security_Assertion_Markup_Language) SSO, create a [SAML app](../../concepts/applications.md#saml) in Yandex Identity Hub and configure it both in Yandex Identity Hub and Managed Service for GitLab.

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 Managed Service for GitLab to the users of your organization:

1. [Create a GitLab instance](#create-mgl-instance).
1. [Create an app in Yandex Identity Hub](#create-app).
1. [Set up the integration](#setup-integration).
1. [Make sure the application works correctly](#validate).

## Create a GitLab instance {#create-mgl-instance}

{% list tabs group=instructions %}

- Management console {#console}

   1. In the management console, select the [folder](../../../resource-manager/concepts/resources-hierarchy.md#folder) where you want to create a [GitLab](../../../managed-gitlab/concepts/index.md#instance) instance.
   1. Navigate to **Managed Service for GitLab**.
   1. Click **Create instance**.
   1. At the top of the page:

      1. Enter a name for your instance. It must be unique within Yandex Cloud.

   1. Under **Configuration**:

      1. Select the [instance type](../../../managed-gitlab/concepts/index.md#config). After you create an instance, you can [upgrade its type](../../../managed-gitlab/operations/instance/instance-update.md) to a higher performing one.
      1. Specify the [availability zone](../../../overview/concepts/geo-scope.md). After you create an instance, you cannot change its availability zone.
      1. Specify the [subnet](../../../vpc/concepts/network.md#subnet) to host the instance.
      1. Select a [security group](../../../vpc/concepts/security-groups.md) or create a new one:

         1. Click **Create group**.
         1. Enter a name and description for the security group. You can add rules for the security group later in **Virtual Private Cloud**.
         1. Click **Create**.

      1. Select the [disk](../../../compute/concepts/disk.md) size. After you create an instance, [you can increase](../../../managed-gitlab/operations/instance/instance-update.md) its disk size.
      1. Specify the [instance domain name](../../../compute/concepts/network.md#hostname): the system will automatically create the relevant DNS records for it in the `.gitlab.yandexcloud.net` domain.

      1. Set up the automatic backup retention period in days.

   1. Under **Administrator data**, specify:
      * **Email**: Email address of the GitLab instance administrator. This is the address to receive the email with a link to create a password.
      * **Login**: Administrator login.
   1. Click **Create**.
   1. Wait until the instance is ready: its status on the Managed Service for GitLab dashboard will change to **Running**. This may take a while.

{% endlist %}

## Create an app in Yandex Identity Hub {#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: `managed-gitlab-app`.

      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**.
   1. Save the **Login URL**, **Issuer / IdP EntityID** and **Fingerprint** values as you will need them in the next step.

{% endlist %}

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

### Set up GitLab authentication using OmniAuth {#setup-sp}

To enable GitLab authentication using OmniAuth, add an authentication provider:

1. In the [management console](https://console.yandex.cloud), select a folder.
1. Navigate to **Managed Service for GitLab**.
1. Click the instance you created and select the **OmniAuth** tab.
1. Click **Configure**.
1. To add an authentication provider, click **Add**.
1. Select `SAML` for the type and configure the provider as follows:

   * **Label**: Name of the authentication provider. Specify any name, e.g., `Identity Hub`.
   * **Assertion consumer service URL**: HTTPS endpoint of the GitLab instance. To create this URL, add `/users/auth/saml/callback` to your GitLab instance URL, such as `https://example.gitlab.yandexcloud.net/users/auth/saml/callback`.
   * **IDP certificate fingerprint**: SHA1 fingerprint of a public certificate key. Use the **Fingerprint** field value you got when creating the app in Yandex Identity Hub.
   * **IDP SSO target URL**: IdP URL. Use the **Login URL** field value.
   * **Issuer**: Unique ID of the application where user authentication will be performed, such as `https://example.gitlab.yandexcloud.net`.
   * **Name identifier format**: Name ID format. Set it to `Persistent`.
   * **Allow single sign on**: Enables SSO. Set it to `true`. If set to `false`, only users who already have a GitLab account will be able to authenticate.
   * **Auto link users by email**: Maps the username in OmniAuth to that in GitLab if both share the same email address. Set it to `true`.
   * **Block auto-created users**: Automatically marks the created accounts as [Pending approval](https://docs.gitlab.com/ee/administration/moderate_users.html#users-pending-approval) until approved by an administrator. Set it to `false`.
   * **External provider**: Sets the _external_ attribute for the provider. Users authenticated through this provider will be treated as [external](https://docs.gitlab.com/ee/user/admin_area/external_users.html) and will have no access to [internal projects](https://docs.gitlab.com/ee/user/public_access.html#internal-projects-and-groups). Set it to `false`.
   * **Auto link LDAP user**: Creates an LDAP entity for automatically created accounts. This setting only applies to instances with an LDAP provider. Set it to `false`.

1. Click **Create**.

### 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, provide the endpoint URL you specified under **Issuer** when setting up OmniAuth.
      1. In the **ACS URL** field, provide the endpoint URL you specified under **Assertion consumer service URL** when setting up OmniAuth, e.g., `https://example.gitlab.yandexcloud.net/users/auth/saml/callback`.
      1. Click **Save**.

{% endlist %}

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

{% note warning %}

For integration with GitLab, users must have the `email` attribute.

{% 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 desired app.
    1. Navigate to the **Attributes** tab.
    1. Click the `emailaddress` attribute and do the following in the window that opens:

        1. Change the **Attribute name** field value to `email`.
        1. Click **Update**.

{% endlist %}

For more information about configuring attributes, see [Configure user and group attributes](../../operations/applications/saml-create.md#setup-attributes).

### Add a user {#add-user}

For your organization's users to be able to authenticate in GitLab 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 %}

1. Add users to the 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 user or user group.
        1. Click **Add**.

    {% endlist %}

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

To make sure both your SAML app and GitLab integration work correctly, authenticate to GitLab as one of the users you added to the app. Follow these steps:

1. In your browser, open the URL of your GitLab instance, e.g., `https://example.gitlab.yandexcloud.net`.
1. If you are already authenticated in GitLab, log out.
1. On the GitLab authentication page, click the name of the authentication provider you created (`Identity Hub` in this example).
1. On the Yandex Cloud authentication page, enter the user email address and password. The user or group they belong to must be added to the application. The user must also have their email address specified.
1. Make sure you have successfully authenticated in GitLab.