Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/circa10a/vault-plugin-secrets-jenkins
A plugin for Hashicorp Vault to create ephemeral users and API tokens for Jenkins CI
https://github.com/circa10a/vault-plugin-secrets-jenkins
ephemeral-credentials golang jenkins jenkinsci-platform-integrations security-automation vault vault-plugins
Last synced: 14 days ago
JSON representation
A plugin for Hashicorp Vault to create ephemeral users and API tokens for Jenkins CI
- Host: GitHub
- URL: https://github.com/circa10a/vault-plugin-secrets-jenkins
- Owner: circa10a
- License: mit
- Created: 2021-12-27T20:15:29.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2022-01-13T01:22:27.000Z (about 3 years ago)
- Last Synced: 2025-01-10T22:41:51.796Z (25 days ago)
- Topics: ephemeral-credentials, golang, jenkins, jenkinsci-platform-integrations, security-automation, vault, vault-plugins
- Language: Go
- Homepage:
- Size: 46.9 KB
- Stars: 9
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# vault-plugin-secrets-jenkins
[](https://pkg.go.dev/github.com/circa10a/vault-plugin-secrets-jenkins?tab=overview)
[](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/` 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=` 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: " 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:
### Create a user
A user with a lease is generated by using a `write` operation on the `/users/` endpoint:
```shell
vault write jenkins/users/myuser password=password fullname="Jenkins the Butler" [email protected]
Key Value
--- -----
lease_id jenkins/users/myuser/hTGbJhDFbAQpALv1FjJyJ4vz
lease_duration 5m
lease_renewable true
email [email protected]
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=` parameter like so:
```shell
vault write jenkins/users/myuser password=password fullname="Jenkins the Butler" [email protected] ttl=1m
Key Value
--- -----
lease_id jenkins/users/myuser/hBUoPCrwAySlmQuMoGEiZtUF
lease_duration 1m
lease_renewable true
email [email protected]
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
```