vault-plugin-secrets-jenkins

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

vault-plugin-secrets-jenkins

★ 9 Open GitHub ↗

A plugin for Hashicorp Vault to create ephemeral users and API tokens for Jenkins CI

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# vault-plugin-secrets-jenkins

![Build Status](https://github.com/circa10a/vault-plugin-secrets-jenkins/workflows/release/badge.svg)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/circa10a/vault-plugin-secrets-jenkins)](https://pkg.go.dev/github.com/circa10a/vault-plugin-secrets-jenkins?tab=overview)
[![Go Report Card](https://goreportcard.com/badge/github.com/circa10a/vault-plugin-secrets-jenkins)](https://goreportcard.com/report/github.com/circa10a/vault-plugin-secrets-jenkins)

This is a backend plugin to be used with [Hashicorp Vault](https://www.github.com/hashicorp/vault).
This plugin generates ephemeral Jenkins Users and API tokens.

- [vault-plugin-secrets-jenkins](#vault-plugin-secrets-jenkins)
  - [Quick Links](#quick-links)
  - [Usage](#usage)
  - [Enable plugin](#enable-plugin)
  - [Configure Plugin](#configure-plugin)
    - [Root User Validation](#root-user-validation)
  - [Creating API tokens for configured user](#creating-api-tokens-for-configured-user)
    - [Set default token TTL](#set-default-token-ttl)
    - [Create a token](#create-a-token)
      - [Specifiying a TTL per token](#specifiying-a-ttl-per-token)
      - [Parsing a token value from Vault response](#parsing-a-token-value-from-vault-response)
    - [List all active token leases](#list-all-active-token-leases)
    - [Revoking all tokens for configured user](#revoking-all-tokens-for-configured-user)
  - [Managing ephemeral users](#managing-ephemeral-users)
    - [Create a user](#create-a-user)
      - [Specifiying a TTL per user](#specifiying-a-ttl-per-user)
    - [List all active users](#list-all-active-users)
    - [Revoking a User](#revoking-a-user)
    - [Revoking all users](#revoking-all-users)
  - [Developing](#developing)
    - [Get Plugin](#get-plugin)
    - [Build plugin and start Vault](#build-plugin-and-start-vault)
    - [Enable and configure plugin](#enable-and-configure-plugin)
    - [Start Jenkins + Vault](#start-jenkins---vault)
    - [Tests](#tests)
      - [Create example credentials](#create-example-credentials)

## Quick Links

- [Vault Website](https://www.vaultproject.io)
- [Jenkins API Tokens](https://www.jenkins.io/doc/book/system-administration/authenticating-scripted-clients/)

## Usage

This is a [Vault plugin](https://www.vaultproject.io/docs/internals/plugins.html)
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](https://www.vaultproject.io/intro/getting-started/install.html).

If you are just interested in using this plugin with Vault, you will need to install it by downloading the appropriate architecture from the [releases page](https://github.com/circa10a/vault-plugin-secrets-jenkins/releases) and placing it in the plugins directory. [Hashicorp Vault plugin documentation can be found here](https://www.vaultproject.io/docs/internals/plugins#plugin-directory).

## Enable plugin

```shell
vault secrets enable -path=jenkins vault-plugin-secrets-jenkins
Success! Enabled the vault-plugin-secrets-jenkins secrets engine at: jenkins/
```

## Configure Plugin

The plugin expects a minimum configuration of a "root" user to create users and API tokens with. You can configure the plugin by writing the `/config` endpoint like so:

```shell
vault write jenkins/config url=http://localhost:8080 username=admin password=admin
Success! Data written to: jenkins/config
```

### Root User Validation

By default, the plugin will attempt to connect to the configured jenkins instance to ensure connectivity and authentication is working properly. To disable this functionality, simply pass the `validate=false` parameter like so:

```shell
vault write jenkins/config url=http://localhost:8080 username=admin password=fake validate=false
Success! Data written to: jenkins/config
```

## Creating API tokens for configured user

### Set default token TTL

You may first want to setup a default TTL on all tokens created, you can do so by writing to the `/tokens/tune` endpoint of the plugin like so, otherwise the system default of `768h` (32 days) is used:

```shell
vault write sys/mounts/jenkins/tokens/tune default_lease_ttl=5m
Success! Data written to: sys/mounts/jenkins/tokens/tune
```

Tokens will automatically be revoked and deleted from Jenkins after the TTL has expired.

### Create a token

A token with a lease is generated by using a `read` operation on the `tokens/<name>` endpoint:

```shell
vault read jenkins/tokens/mytoken
Key                Value
---                -----
lease_id           jenkins/tokens/mytoken/fJ57afQZMyXDcJnm74BgLLt8
lease_duration     5m
lease_renewable    true
token              1184cb7b22c404efa1c293e9841b66f345
token_id           1c2864f3-4108-4417-807a-358357bc8432
token_name         mytoken
```

The `token` value is what is to be used to authenticate with Jenkins as a subsitution for the user's password.

:warning: **The token is not stored in Vault and will only be viewable from the first response. The token will not be able to be accessed again.** :warning:

#### Specifiying a TTL per token

You can specify the TTL for an individual token by supplying the `ttl=<ttl>` parameter like so:

```shell
vault read jenkins/tokens/mytoken ttl=2m
Key                Value
---                -----
lease_id           jenkins/tokens/mytoken/i81VB5RmXJCQdMdUUuwngTJI
lease_duration     2m
lease_renewable    true
token              1185adcc9c996fd9b394a520ca8e0c6024
token_id           a7ffa97f-032a-40c1-b9d9-e14c7a7dbc12
token_name         mytoken
```

#### Parsing a token value from Vault response

**HTTP**:

```shell
curl -s  -H "X-Vault-Token: <token>"  http://localhost:8200/v1/jenkins/tokens/mytoken | jq '.data.token'
"119630cd3df88834e6b8000983529afcde"
```

**CLI**:

```shell
vault read jenkins/tokens/mytoken -format=json | jq -r '.data.token'
119e4f728a738a1ca4e2c65329a5ebdba9
```

### List all active token leases

You can view all of the all active Jenkins API token leases that Vault is managing:

```shell
vault list sys/leases/lookup/jenkins/tokens/mytoken
Keys
----
Yvk37n1SCCfovcvk9YswCm7m
rFbQIvo7mGUMbumYIplTewbX
xlY32KoMTuS54rgAPnK2QvjR
```

### Revoking all tokens for configured user

You can revoke all Vault managed tokens by revoking all leases under the `/jenkins/tokens` mount:

```shell
vault lease revoke -prefix=true jenkins/tokens/
```

## Managing ephemeral users

This plugin allows you to create local Jenkins users with leases. The recommended method for controlling the permissions for these users is to use the [matrix authorization strategy plugin](https://plugins.jenkins.io/matrix-auth/) and have a default permission set for authenticated users:

![alt text](https://raw.githubusercontent.com/circa10a/vault-plugin-secrets-jenkins/main/images/permissions.png)

### Create a user

A user with a lease is generated by using a `write` operation on the `/users/<name>` endpoint:

```shell
vault write jenkins/users/myuser password=password fullname="Jenkins the Butler" email=email@example.com
Key                Value
---                -----
lease_id           jenkins/users/myuser/hTGbJhDFbAQpALv1FjJyJ4vz
lease_duration     5m
lease_renewable    true
email              email@example.com
fullname           Jenkins the Butler
username           myuser
```

Once the user is created, you can follow the same steps above to create API tokens for the new user if you prefer.

Once a user is created and exists in Vault, writes to the same user endpoint will fail since it already exists. Once the lease has expired, the same username endpoint can be written to.

:warning: **The password is not stored in Vault and will not accessible within Vault itself.** :warning:

#### Specifiying a TTL per user

You can specify the TTL for an individual supplying by supplying the `ttl=<ttl>` parameter like so:

```shell
vault write jenkins/users/myuser password=password fullname="Jenkins the Butler" email=email@example.com ttl=1m
Key                Value
---                -----
lease_id           jenkins/users/myuser/hBUoPCrwAySlmQuMoGEiZtUF
lease_duration     1m
lease_renewable    true
email              email@example.com
fullname           Jenkins the Butler
username           myuser
```

### List all active users

You can view all of the all active Jenkins Users that Vault is managing by listing the `/users/` endpoint:

```shell
❯ vault list jenkins/users/
Keys
----
myuser
```

### Revoking a User

You can revoke an individual Jenkins user by revoking the user name inder the `/users/` endpoint:

```shell
vault lease revoke jenkins/users/myuser
All revocation operations queued successfully!
```

### Revoking all users

You can revoke all Vault managed Jenkins users by revoking all users under the `/jenkins/users` mount:

```shell
vault lease revoke -prefix=true jenkins/users/
```

## Developing

If you wish to work on this plugin, you'll first need [Go](https://www.golang.org)
installed on your machine (whichever version is required by Vault) as well as [docker](https://docs.docker.com/get-docker/) to run Jenkins.

### Get Plugin

Clone this repository:

```shell
git clone https://github.com/circa10a/vault-plugin-secrets-jenkins.git
```

### Build plugin and start Vault

Once the server is started, register the plugin in the Vault server's [plugin catalog](https://www.vaultproject.io/docs/internals/plugins.html#plugin-catalog):

```sh
make all
```

### Enable and configure plugin

For configuration to work, jenkins will need to be running (via docker):

```shell
make jenkins
```

Then configure the plugin:

```shell
make enable-plugin
```

### Start Jenkins + Vault

```shell
docker-compose up
```

### Tests

Jenkins needs to be running for the tests to execute successfully:

```shell
make jenkins
```

To run the integration tests:

```shell
make test
```

#### Create example credentials

Create a token:

```shell
make token
```

Create a user:

```shell
make user
```

vault-plugin-secrets-jenkins

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README