gitlab

package module
v0.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 19, 2023 License: MIT Imports: 18 Imported by: 0

README

Vault Plugin for Gitlab Access Token

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

This is a standalone backend plugin for use with Hashicorp Vault. This plugin allows for Gitlab to generate personal, project and group access tokens. This was created so we can automate the creation/revocation of access tokens through Vault.

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.

Setup

Before we can use this plugin we need to create an access token that will have rights to do what we need to.

Security Model

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

Examples

Setup

Before we can use the plugin we need to register and enable it in Vault.

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

Config

Due to how Gitlab manages expiration the minimum is 24h and maximum is 365 days. As per non-expiring-access-tokens and Remove ability to create deprecated non-expiring access tokens. Since Gitlab 16.0 the ability to create non expiring token has been removed.

The command bellow will set up the config backend with a max TTL of 48h.

$ vault write gitlab/config max_ttl=48h base_url=https://gitlab.example.com token=gitlab-super-secret-token

Roles

This will create three roles, one of each type.

# personal access tokens can only be created by Gitlab Administrators (see https://docs.gitlab.com/ee/api/users.html#create-a-personal-access-token)
$ vault write gitlab/roles/personal name=personal-token-name path=username scopes="read_api" token_type=personal token_ttl=24h

$ vault write gitlab/roles/project name=project-token-name path=group/project scopes="read_api" access_level=guest token_type=project token_ttl=24h

$ vault write gitlab/roles/group name=group-token-name path=group/subgroup scopes="read_api" access_level=developer token_type=group token_ttl=24h

Get access tokens

Personal
$ vault read gitlab/token/personal
Key                Value
---                -----
lease_id           gitlab/token/personal/0FrzLFkRKaUNZSfa6WfFqjWK
lease_duration     20h1m37s
lease_renewable    false
access_level       n/a
created_at         2023-08-31T03:58:23.069Z
expires_at         2023-09-01T00:00:00Z
name               vault-generated-personal-access-token-227cb38b
path               username
scopes             [read_api]
token              7mbpSExz7ruyw1QgTjL-

$ vault lease revoke gitlab/token/personal/0FrzLFkRKaUNZSfa6WfFqjWK
All revocation operations queued successfully!
Group
$ vault read gitlab/token/group
Key                Value
---                -----
lease_id           gitlab/token/group/LqmL1MtuIlJ43N8q2L975jm8
lease_duration     20h14s
lease_renewable    false
access_level       developer
created_at         2023-08-31T03:59:46.043Z
expires_at         2023-09-01T00:00:00Z
name               vault-generated-group-access-token-913ab1f9
path               group/subgroup
scopes             [read_api]
token              rSYv4zwgP-2uaFEAsZyd

$ vault lease revoke gitlab/token/group/LqmL1MtuIlJ43N8q2L975jm8
All revocation operations queued successfully!
Project
$ vault read gitlab/token/project
Key                Value
---                -----
lease_id           gitlab/token/project/ZMSOrOHiP77l5kjWXq3zizPA
lease_duration     19h59m6s
lease_renewable    false
access_level       guest
created_at         2023-08-31T04:00:53.613Z
expires_at         2023-09-01T00:00:00Z
name               vault-generated-project-access-token-842113a6
path               group/project
scopes             [read_api]
token              YfRu42VaGGrxshKKwtma

$ vault lease revoke gitlab/token/project/ZMSOrOHiP77l5kjWXq3zizPA
All revocation operations queued successfully!

Revoke all created tokens by this plugin

$ vault lease revoke -prefix gitlab/
All revocation operations queued successfully!

Force rotation of the main token

If the original token that has been supplied to the backend is not expired. We can use the endpoint bellow to force a rotation of the main token. This would create a new token with the same expiration as the original token.

vault put gitlab/config/rotate

TODO

  • Add tests against real Gitlab instance

Documentation

Index

Constants

View Source 
const (
	DefaultConfigFieldAccessTokenMaxTTL = 7 * 24 * time.Hour
	DefaultConfigFieldAccessTokenRotate = 2 * 24 * time.Hour
	DefaultRoleFieldAccessTokenMaxTTL   = 24 * time.Hour
	DefaultAccessTokenMinTTL            = 24 * time.Hour
	DefaultAccessTokenMaxPossibleTTL    = 365 * 24 * time.Hour
	DefaultAutoRotateBeforeMinFraction  = 0.1
	DefaultAutoRotateBeforeMaxFraction  = 0.5
)
View Source 
const (
	AccessLevelNoPermissions            = AccessLevel("no_permissions")
	AccessLevelMinimalAccessPermissions = AccessLevel("minimal_access")
	AccessLevelGuestPermissions         = AccessLevel("guest")
	AccessLevelReporterPermissions      = AccessLevel("reporter")
	AccessLevelDeveloperPermissions     = AccessLevel("developer")
	AccessLevelMaintainerPermissions    = AccessLevel("maintainer")
	AccessLevelOwnerPermissions         = AccessLevel("owner")

	AccessLevelUnknown = AccessLevel("")
)
View Source 
const (
	// TokenScopeApi grants complete read and write access to the scoped group and related project API, including the Package Registry
	TokenScopeApi = TokenScope("api")
	// TokenScopeReadApi grants read access to the scoped group and related project API, including the Package Registry
	TokenScopeReadApi = TokenScope("read_api")
	// TokenScopeReadRegistry grants read access (pull) to the Container Registry images if any project within expected group is private and authorization is required.
	TokenScopeReadRegistry = TokenScope("read_registry")
	// TokenScopeWriteRegistry grants write access (push) to the Container Registry.
	TokenScopeWriteRegistry = TokenScope("write_registry")
	// TokenScopeReadRepository grants read access (pull) to the Container Registry images if any project within expected group is private and authorization is required
	TokenScopeReadRepository = TokenScope("read_repository")
	// TokenScopeWriteRepository grants read and write access (pull and push) to all repositories within expected group
	TokenScopeWriteRepository = TokenScope("write_repository")
	// TokenScopeCreateRunner grants permission to create runners in expected group
	TokenScopeCreateRunner = TokenScope("create_runner")

	// TokenScopeReadUser grants read-only access to the authenticated user’s profile through the /user API endpoint, which includes username, public email, and full name. Also grants access to read-only API endpoints under /users.
	TokenScopeReadUser = TokenScope("read_user")
	// TokenScopeSudo grants permission to perform API actions as any user in the system, when authenticated as an administrator.
	TokenScopeSudo = TokenScope("sudo")
	// TokenScopeAdminMode grants permission to perform API actions as an administrator, when Admin Mode is enabled.
	TokenScopeAdminMode = TokenScope("admin_mode")

	TokenScopeUnknown = TokenScope("")
)
View Source 
const (
	TokenTypePersonal = TokenType("personal")
	TokenTypeProject  = TokenType("project")
	TokenTypeGroup    = TokenType("group")

	TokenTypeUnknown = TokenType("")
)
View Source 
const (
	PathConfigStorage = "config"
)
View Source 
const (
	PathRoleStorage = "roles"
)
View Source 
const (
	PathTokenRoleStorage = "token"
)

Variables

View Source 
var (
	ErrNilValue             = errors.New("nil value")
	ErrInvalidValue         = errors.New("invalid value")
	ErrFieldRequired        = errors.New("required field")
	ErrFieldInvalidValue    = errors.New("invalid value for field")
	ErrBackendNotConfigured = errors.New("backend not configured")
)
View Source 
var (
	ErrAccessTokenNotFound = errors.New("access token not found")
	ErrRoleNotFound        = errors.New("role not found")
)
View Source 
var (
	ErrUnknownAccessLevel = errors.New("unknown access level")

	ValidAccessLevels = []string{
		AccessLevelNoPermissions.String(),
		AccessLevelMinimalAccessPermissions.String(),
		AccessLevelGuestPermissions.String(),
		AccessLevelReporterPermissions.String(),
		AccessLevelDeveloperPermissions.String(),
		AccessLevelMaintainerPermissions.String(),
		AccessLevelOwnerPermissions.String(),
	}

	ValidPersonalAccessLevels = []string{
		AccessLevelUnknown.String(),
	}
	ValidProjectAccessLevels = []string{
		AccessLevelGuestPermissions.String(),
		AccessLevelReporterPermissions.String(),
		AccessLevelDeveloperPermissions.String(),
		AccessLevelMaintainerPermissions.String(),
		AccessLevelOwnerPermissions.String(),
	}
	ValidGroupAccessLevels = []string{
		AccessLevelGuestPermissions.String(),
		AccessLevelReporterPermissions.String(),
		AccessLevelDeveloperPermissions.String(),
		AccessLevelMaintainerPermissions.String(),
		AccessLevelOwnerPermissions.String(),
	}
)
View Source 
var (
	ErrUnknownTokenScope = errors.New("unknown token scope")

	ValidGroupTokenScopes   = validTokenScopes
	ValidProjectTokenScopes = validTokenScopes

	ValidPersonalTokenScopes = []string{
		TokenScopeReadUser.String(),
		TokenScopeSudo.String(),
		TokenScopeAdminMode.String(),
	}
)
View Source 
var BuildDate string
View Source 
var (
	ErrUnknownTokenType = errors.New("unknown token type")
)
View Source 
var FullCommit string
View Source 
var Version string = "v0.0.0-dev"

Functions

func Factory 

func Factory(ctx context.Context, conf *logical.BackendConfig) (logical.Backend, error)

Factory returns expected new Backend as logical.Backend

Types

type AccessLevel 

type AccessLevel string

func AccessLevelParse 

func AccessLevelParse(value string) (AccessLevel, error)

func (AccessLevel) String 

func (i AccessLevel) String() string

func (AccessLevel) Value 

func (i AccessLevel) Value() int

type Backend 

type Backend struct {
	*framework.Backend
	// contains filtered or unexported fields
}

func (*Backend) Invalidate 

func (b *Backend) Invalidate(ctx context.Context, key string)

Invalidate invalidates the key if required

func (*Backend) SetClient 

func (b *Backend) SetClient(client Client)

type Client 

type Client interface {
	Valid() bool

	CurrentTokenInfo() (*EntryToken, error)
	RotateCurrentToken(revokeOldToken bool) (newToken *EntryToken, oldToken *EntryToken, err error)
	CreatePersonalAccessToken(username string, userId int, name string, expiresAt time.Time, scopes []string) (*EntryToken, error)
	CreateGroupAccessToken(groupId string, name string, expiresAt time.Time, scopes []string, accessLevel AccessLevel) (*EntryToken, error)
	CreateProjectAccessToken(projectId string, name string, expiresAt time.Time, scopes []string, accessLevel AccessLevel) (*EntryToken, error)
	RevokePersonalAccessToken(tokenId int) error
	RevokeProjectAccessToken(tokenId int, projectId string) error
	RevokeGroupAccessToken(tokenId int, groupId string) error
	GetUserIdByUsername(username string) (int, error)
}

func NewGitlabClient 

func NewGitlabClient(config *EntryConfig, httpClient *http.Client) (client Client, err error)

type EntryConfig added in v0.2.0 

type EntryConfig struct {
	BaseURL                string        `json:"base_url" structs:"base_url" mapstructure:"base_url"`
	Token                  string        `json:"token" structs:"token" mapstructure:"token"`
	MaxTTL                 time.Duration `json:"max_ttl" structs:"max_ttl" mapstructure:"max_ttl"`
	AutoRotateToken        bool          `json:"auto_rotate_token" structs:"auto_rotate_token" mapstructure:"auto_rotate_token"`
	AutoRotateBefore       time.Duration `json:"auto_rotate_before" structs:"auto_rotate_before" mapstructure:"auto_rotate_before"`
	TokenExpiresAt         time.Time     `json:"token_expires_at" structs:"token_expires_at" mapstructure:"token_expires_at"`
	RevokeAutoRotatedToken bool          `json:"revoke_auto_rotated_token" structs:"revoke_auto_rotated_token" mapstructure:"revoke_auto_rotated_token"`
}

func (EntryConfig) LogicalResponseData added in v0.2.0 

func (e EntryConfig) LogicalResponseData() map[string]interface{}

type EntryToken 

type EntryToken struct {
	TokenID     int         `json:"token_id"`
	UserID      int         `json:"user_id"`
	ParentID    string      `json:"parent_id"`
	Path        string      `json:"path"`
	Name        string      `json:"name"`
	Token       string      `json:"token"`
	TokenType   TokenType   `json:"token_type"`
	CreatedAt   *time.Time  `json:"created_at"`
	ExpiresAt   *time.Time  `json:"expires_at"`
	Scopes      []string    `json:"scopes"`
	AccessLevel AccessLevel `json:"access_level"` // not used for personal access tokens
}

func (EntryToken) SecretResponse 

func (e EntryToken) SecretResponse() (map[string]interface{}, map[string]interface{})

type TokenScope 

type TokenScope string

func TokenScopeParse 

func TokenScopeParse(value string) (TokenScope, error)

func (TokenScope) String 

func (i TokenScope) String() string

func (TokenScope) Value 

func (i TokenScope) Value() string

type TokenType 

type TokenType string

func TokenTypeParse 

func TokenTypeParse(value string) (TokenType, error)

func (TokenType) String 

func (i TokenType) String() string

func (TokenType) Value 

func (i TokenType) Value() string

Source Files

View all Source files

Directories

Path Synopsis
cmd
vault-plugin-secrets-gitlab command

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.