[Yandex Cloud documentation](../../index.md) > [Tutorials](../index.md) > [Security](index.md) > Integrations of workload identity federations > GitLab

# Getting Yandex Lockbox secret value on the GitLab side

[Workload identity federations](../../iam/concepts/workload-identity.md) allow you to configure a link between external systems and Yandex Cloud via the [OpenID Connect](https://openid.net/developers/how-connect-works/) (OIDC) protocol. This allows external systems to perform actions with Yandex Cloud resources under IAM [service accounts](../../iam/concepts/users/service-accounts.md) without using [authorized keys](../../iam/concepts/authorization/key.md). This is a more secure method that minimizes the risk of credential leakage and the possibility of unauthorized access.

This tutorial shows you as an example how to get the [Yandex Lockbox](../../lockbox/index.md) [secret](../../lockbox/concepts/secret.md) value from the GitLab side under a Yandex Cloud service account. Similarly, you can perform any action via the Yandex Cloud [CLI](../../cli/quickstart.md), [API](../../api-design-guide/index.md), or [Terraform](../../terraform/index.md).

To get the Yandex Lockbox secret value under a GitLab account:

1. [Create a GitLab project](#create-gitlab-project).
1. [Get your cloud ready](#prepare-cloud).
1. [Configure a GitLab CI/CD script](#gitlab-actions-workflow).

If you no longer need the resources you created, [delete them](#clear-out).

## Create a GitLab project {#create-gitlab-project}

[Create a new GitLab](https://docs.gitlab.com/ee/user/project/) project or use an existing one where you have permissions to view and run GitLab CI/CD pipelines.

## Get your cloud ready {#prepare-cloud}

Sign up for Yandex Cloud and create a [billing account](../../billing/concepts/billing-account.md):
1. Navigate to the [management console](https://console.yandex.cloud) and log in to Yandex Cloud or create a new account.
1. On the **[Yandex Cloud Billing](https://center.yandex.cloud/billing/accounts)** page, make sure you have a billing account linked and it has the `ACTIVE` or `TRIAL_ACTIVE` [status](../../billing/concepts/billing-account-statuses.md). If you do not have a billing account, [create one](../../billing/quickstart/index.md) and [link](../../billing/operations/pin-cloud.md) a cloud to it.

If you have an active billing account, you can create or select a [folder](../../resource-manager/concepts/resources-hierarchy.md#folder) for your infrastructure on the [cloud page](https://console.yandex.cloud/cloud).

[Learn more about clouds and folders here](../../resource-manager/concepts/resources-hierarchy.md).

### Required paid resources {#paid-resources}

The infrastructure support cost includes a fee for storing a [secret](../../lockbox/concepts/secret.md) and requests to it (see [Yandex Lockbox](../../lockbox/pricing.md) pricing).

### Create a workload identity federation {#federation-iam-accounts}

{% list tabs group=instructions %}

- Management console {#console}

   1. In the [management console](https://console.yandex.cloud), select the folder where you want to create a workload identity federation.
   1. Navigate to **Identity and Access Management**.
   1. In the left-hand panel, select ![cpus](../../_assets/console-icons/cpus.svg) **Workload identity federations**.
   1. Click **Create federation**.
   1. In the **Issuer value (iss)** field, enter the OIDC provider's URL: `https://gitlab.com`.
   1. In the **Acceptable Audience values (AUD)** field, enter the token recipient: `https://gitlab.com/<group_name>/<gitlab_project_name>`.
   1. In the **JWKS address** field, enter the URL of the public key list: `https://gitlab.com/oauth/discovery/keys`.
   1. In the **Name** field, enter a name for the federation, e.g., `test-iam-federation`.
   1. Click **Create**.

   {% note info %}

   If using a custom installation of GitLab, replace `https://gitlab.com` with the address of your installation in all mentioned values.

   {% endnote %}

{% endlist %}

### Create a custom secret

{% list tabs group=instructions %}

- Management console {#console}

   1. In the [management console](https://console.yandex.cloud), select the folder where you want to create your secret.
   1. Navigate to **Lockbox**.
   1. Click **Create secret**.
   1. In the **Name** field, enter a name for the secret: `MY_SECRET`.
   1. Select **Secret type** `Custom`.
   1. In the **Key** field, enter a non-secret ID, e.g., `secret`.
   1. In the **Value** field, enter the confidential data you want to store.
   1. Click **Create**.

{% endlist %}

### Create a service account

1. Create a service account:

   {% list tabs group=instructions %}

   - Management console {#console}

      1. In the [management console](https://console.yandex.cloud), select the folder where you want to create a service account.
      1. Navigate to **Identity and Access Management**.
      1. Click **Create service account**.
      1. Enter a name for the service account, e.g., `sa-lockbox`.
      1. Click **Create**.

   {% endlist %}

1. Assign the `lockbox.payloadViewer` [role](../../iam/concepts/access-control/roles.md) for the folder to the service account: 

   {% list tabs group=instructions %}

   - Management console {#console}

      1. On the management console [home page](https://console.yandex.cloud), select a folder.
      1. Navigate to the **Access bindings** tab.
      1. Find the `sa-lockbox` account in the list and click ![image](../../_assets/console-icons/ellipsis.svg).
      1. Click **Edit roles**.
      1. In the dialog that opens, click ![image](../../_assets/console-icons/plus.svg) **Add role** and select the `lockbox.payloadViewer` role.

   {% endlist %}

### Link the service account to the federation

{% list tabs group=instructions %}

- Management console {#console}

   1. In the [management console](https://console.yandex.cloud), select the folder the service account was created in.
   1. Navigate to **Identity and Access Management**.
   1. In the list of service accounts, select `sa-lockbox`.
   1. In the top panel, click ![image](../../_assets/console-icons/cpus.svg) **Link to federation**.
   1. In the **Workload identity federation** field, select the federation you created earlier.
   1. In the **Subject value (sub)** field, specify the external account ID: `project_path:<group_name>/<gitlab_project_name>:ref_type:branch:ref:<repository_branch_name>`.
   1. Click **Link**.

{% endlist %}

## Configure a GitLab CI/CD script {#gitlab-ci-workflow}

1. Clone your repository if you have not done so already:

   ```bash
   git clone <repository_URL>
   ```

1. In a local copy of your repository, create a file named `.gitlab-ci.yml` in the root directory.
1. Insert the following code into the `.gitlab-ci.yml` file that will get the value of the Yandex Lockbox secret:

   ```yaml
   stages:
   - check_token

   check_token:
     stage: check_token
     image: 
       name: ubuntu
     id_tokens:
       GITLAB_OIDC_TOKEN:
         aud: https://gitlab.com/<group_name>/<gitlab_project_name>
     script:
      - apt update && apt install curl jq -y
      # Exchanging the workflow task token for an IAM token of a service account in Yandex Cloud
      - SA_ID="<service_account_ID>"
      - >-
       IAM_TOKEN="$(curl -s
       -H "Content-Type: application/x-www-form-urlencoded" 
       -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&requested_token_type=urn:ietf:params:oauth:token-type:access_token&audience=${SA_ID}&subject_token=${GITLAB_OIDC_TOKEN}&subject_token_type=urn:ietf:params:oauth:token-type:id_token" 
       -X POST https://auth.yandex.cloud/oauth/token | jq -r '.access_token')"
      # Requesting the secret via the API using an IAM token in Yandex Cloud
      - SECRET_ID="<secret_ID>"
      - >-
       SECRET_DATA=$(curl -sH "Authorization: Bearer ${IAM_TOKEN}" https://payload.lockbox.api.cloud.yandex.net/lockbox/v1/secrets/$SECRET_ID/payload)
      - echo ${SECRET_DATA}
     tags:
       - app-test
   ```

   Where:
   * `aud`: Token recipient specified when creating the workload identity federation.
   * `SA_ID`: Service account ID.
   * `SECRET_ID`: Custom secret ID.

1. Save the file and submit the changes to the remote repository:

   ```bash
   git add . && git commit -m "Added .gitlab-ci.yml" && git push
   ```

   Once you submit the code to the repository, the workflow will begin.

1. In GitLab left-hand menu, navigate to **Build** → **Pipelines**.
1. Make sure the build status is **Passed**. This means that the build was successful.
1. In the GitLab left-hand menu, go to **Build** → **Jobs**.
1. Click the last completed task to see the result of executing the script in the log:

   ```json
   { "entries": [ { "key": "secret", "textValue": "67cH2£?pO********" } ], "versionId": "e6q8isknpcp7********" }
   ```

## Delete the resources you created {#clear-out}

Some resources are not free of charge. Delete the resources you no longer need to avoid paying for them:

* [Yandex Lockbox](../../lockbox/operations/secret-delete.md) secret
* [Service account](../../iam/operations/sa/delete.md)

## Useful links {#see-also}

* [Secure storage of GitLab CI passwords as Yandex Lockbox secrets](gitlab-lockbox-integration.md)
* [Getting Yandex Lockbox secret value on the GitHub side](wlif-github-integration.md)