Skip to content

README.md

Latest commit

 

History

History
96 lines (68 loc) · 4.39 KB

README.md

File metadata and controls

96 lines (68 loc) · 4.39 KB

Vault Plugin for Gitlab Access Token

Go Report Card Codecov GitHub go.mod Go version (subdirectory of monorepo) GitHub Release

This is a standalone backend plugin for use with Hashicorp Vault/OpenBao. It lets you automate the creation and revocation of GitLab personal, project, and group access tokens through Vault.

IMPORTANT: Upgrading to >= 0.7.x will require you to revoke, remove all the paths, and remove the mount path. This is required because the paths internally have changed to accommodate config per role.

Security model

The current authentication model requires providing Vault with a Gitlab Token.

GitLab Support

  • GitLab CE/EE (Self-Managed)
    • 17.11.7 CE (tested)
    • 18.11.2 CE (tested)
  • GitLab.com
    • Personal access tokens and user service accounts are not supported
  • GitLab Dedicated
    • Personal access tokens and user service accounts are not supported

Quick links

Token types

All tiers = Free + Premium + Ultimate · All offerings = GitLab.com + Self-Managed + Dedicated

Token type Tier Offering Status
Personal Access Tokens All tiers All offerings GA
Project Access Tokens All tiers All offerings GA
Group Access Tokens All tiers All offerings GA
User/Group Service Account Tokens¹ All tiers All offerings GA
Pipeline Project Trigger Tokens All tiers All offerings GA
Group/Project Deploy Tokens All tiers All offerings GA

¹ Service accounts on GitLab Free are capped: up to 100 per top-level group on GitLab.com, or 100 per instance on Self-Managed. Premium and Ultimate are unlimited.

Getting started

This is a Vault plugin and is 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 this guide on how to get started with Vault.

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

Quickstart

Register the plugin binary and enable it:

vault plugin register \
  -sha256=$(sha256sum path/to/plugin/directory/gitlab | cut -d " " -f 1) \
  -command=vault-plugin-secrets-gitlab \
  secret gitlab

vault secrets enable gitlab

Configure the backend and verify the config:

vault write gitlab/config/default base_url=https://gitlab.example.com token=gitlab-super-secret-token auto_rotate_token=false auto_rotate_before=48h type=self-managed
vault read gitlab/config/default

Create a role and request a token:

vault write gitlab/roles/personal name='{{ .role_name }}-{{ .token_type }}-{{ randHexString 4 }}' path=username scopes="read_api" token_type=personal ttl=48h
vault read gitlab/token/personal/username

Documentation

Info

Running the logging with debug level will show sensitive information in the logs.