GitLab is a web-based DevOps lifecycle tool that provides a Git-repository manager including a wiki, issue-tracking, and continuous integration and deployment pipeline features.

The Akeyless plugin for GitLab enables a secure, easy, and integrative way to fetch Secrets into GitLab pipelines.

Authentication

Each job has a JSON Web Token (JWT) provided as CI/CD variable named CI_JOB_JWT_V2.

When a pipeline is about to run, GitLab uses the CI_JOB_JWT_V2 job token and generates a unique token for it.

The CI_JOB_JWT_V2 is an RS256 JSON web token that is being used to authenticate with third-party systems that support JWT authentication, in our case, Akeyless.

The token is valid only while the pipeline job runs. After the job finishes, you can’t use the token anymore.

To work with the Akeyless GitLab plugin, we will use an OAuth 2.0 / JWT Authentication Method

OAuth 2.0 / JWT

In Akeyless Platform, create a new OAuth 2.0 / JWT Authentication Method with the following parameters:

akeyless create-auth-method-oauth2 --name \Dev\GitLabAuth \ 
--jwks-uri https://gitlab.com/-/jwks \
--unique-identifier user_login
--force-sub-claims

Where:

• --jwks-uri - The URL to the JWKS that contains the public keys that should be used for JWT verification.

• --unique-identifier - A unique claim name that contains details uniquely identifying the request. In the following example, we will use the GitLab user_login claim.

• --force-sub-claims - Enforce Sub-Claims on role association.

Create a dedicated Access Role, please note that you will assign it the necessary permissions in a later stage of this guide:

akeyless create-role --name \Dev\GitLabRole \

Associate your new Role with the created Authentication Method, and assign it Sub Claims:

akeyless assoc-role-am --role-name \Dev\GitLabRole \ 
--am-name \Dev\GitLabAuth \ 
--sub-claims user_login=<YOUR GitLab USERNAME>

🚧

Sub Claims:

It is mandatory to add an appropriate Sub Claim based on the claims available in the GitLab documentation to prevent access of unauthorized users.

Set Read and List permissions for Secrets & Keys:

akeyless set-role-rule --role-name \Dev\GitLabRole \ 
--path /Path/To/your/secret/'*' \
--capability read --capability list

Usage

Open your GitLab project and make sure you have a yaml file named .gitlab-ci.yml and update it to contain the following steps while making sure that the path to the relevant secrets, as well as the access-id value with your matching JWT access-id, was replaced.

If you are working with your own Akeyless Gateway, set the value of the VAULT_ADDR field as your Akeyless Gateway URL on port 8200. For example, https://akeyless-gw:8200.

👍

GitLab Version 15 and higher

Starting from v15 GitLab supports CI_JOB_JWT_V2, for older versions you can use the legacy environment CI_JOB_JWT instead.

The image is akeyless/ci_base which is a public docker image based on ruby:2.4 that contains the Akeyless CLI as well as other essential components.

variables: 
  ACCESS_ID: <access_id>

akeyless:
  image: 
    name:  akeyless/ci_base:latest-alpine
  before_script:
    - export MY_SECRET=akeyless://path/to/secret # Static / Dynamic secret
    - export VAULT_ADDR=https://hvp.akeyless.io 
    - export TOKEN=$(akeyless auth --access-id $ACCESS_ID --access-type jwt --jwt $CI_JOB_JWT_V2) 
    - source ~/.akeyless/akeyless_env.sh
  script:
    - echo "Fetching Secrets is Easy [$MY_SECRET]"

Sample output of a successful job:

Success! - the secrets are accessible to use within the job logic (in this example, they are just being printed).