Vault Plugin for Gitlab Project Access Token

This is a backend plugin to be used with Vault. This plugin generates Gitlab Project Access Tokens

• Requirements
• Getting Started
  • Usage
• Design Principles
• Development
• Contribution
• License

Requirements

• Gitlab instance with 13.10 or later for API compatibility

• You need 14.1 or later to have access level

• Self-managed instances on Free and above. Or, GitLab SaaS Premium and above

• a token of a user with maintainer or higher permission in a project

• Lifting API rate limit for the user whose token will be used in this plugin to generate/revoke project access tokens. Admin of self-hosted can check this doc to allow specific users to bypass authenticated request rate limiting. For SaaS Gitlab, I have not confirmed how to lift API limit yet.

Getting Started

This is a Vault plugin meant to work with Vault. This guide assumes you have already installed Vault and have a basic understanding of how Vault works.

Otherwise, first read how to get started with Vault.

To learn specifically about how plugins work, see documentation on Vault plugins.

Usage

# Please mount a plugin, then you can enable a secret
$ vault secrets enable -path=gitlab vault-plugin-secrets-gitlab
Success! Enabled the vault-plugin-secrets-gitlab secrets engine at: gitlab/

# configure the /config backend. You must supply a token which can generate project access tokens
$ vault write gitlab/config base_url="https://gitlab.example.com" token=$GITLAB_TOKEN 

# see supported paths
$ vault path-help gitlab/
$ vault path-help gitlab/config

# generate an ephemeral gitlab token
$ vault write gitlab/token id=1 name=ci-token scopes=api,write_repository
Key           Value
---           -----
id            12345
name          ci-token
scopes        [api write_repository]
token         REDACTED_TOKEN

# create a role
$ vault write gitlab/roles/ci-role id=1 name=project1-role scopes=read_api,read_repository
Key           Value
---           -----
role_name     ci-role
id            1
name          project1-role
scopes        [read_api read_repository]
token_ttl     86400s

# generate an ephemeral gitlab token for ci-role
$ vault write gitlab/token/ci-role
Key           Value
---           -----
id            12346
name          project1-role
scopes        [read_api read_repository]
token         REDACTED_TOKEN
expires_at    2021-09-13

Design Principles

The Gitlab Vault secrets plugin dynamically generates gitlab project access token based on passed parameters. This enables users to gain access to Gitlab projects without needing to create or manage project access tokens manually.

You can find detail design principles

Development

Full dev environment

To be coming...

TODO: spin up a gitlab instance in docker

Developing with an existing Gitlab instance

Requirements:

• vault

# Build binary in plugins directory, and spin up dev vault
make vault-only

# In New Terminal
export VAULT_ADDR=http://localhost:8200
export GITLAB_URL="https://gitlab.example.com"
export GITLAB_TOKEN=TOKEN


# enable secrets backend and configuration
./scripts/setup_dev_vault.sh

You can then issue a project access following above usage.

Tests

# run unit tests
make test

# run subset of tests
make test TESTARGS='-run=TestConfig'

# run acceptance tests (uses Vault and Gitlab Docker containers against the compiled plugin)
make acc-test

# generate a code coverage report
make report
open coverage.html

Contribution

This plugin was initially created as Hackathon project to enahance ephemeral credential suite. Another example is vault-plugin-secrets-artifactory. Contribution in a form of issue, merge request and donation will always be welcome.

Please refer CONTRIBUTING.md and CODE_OF_CONDUCT.md before contributing.

License

Apache Software License version 2.0