vault-plugin-secrets-jenkins

README

vault-plugin-secrets-jenkins

This is a backend plugin to be used with Hashicorp Vault. This plugin generates ephemeral Jenkins Users and API tokens.

• vault-plugin-secrets-jenkins
  • Quick Links
  • Usage
  • Enable plugin
  • Configure Plugin
    • Root User Validation
  • Creating API tokens for configured user
    • Set default token TTL
    • Create a token
      • Specifiying a TTL per token
      • Parsing a token value from Vault response
    • List all active token leases
    • Revoking all tokens for configured user
  • Managing ephemeral users
    • Create a user
      • Specifiying a TTL per user
    • List all active users
    • Revoking a User
    • Revoking all users
  • Developing
    • Get Plugin
    • Build plugin and start Vault
    • Enable and configure plugin
    • Start Jenkins + Vault
    • Tests
      • Create example credentials

Quick Links

• Vault Website
• Jenkins API Tokens

Usage

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.

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 and placing it in the plugins directory. Hashicorp Vault plugin documentation can be found here.

Enable plugin

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:

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:

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:

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:

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.

⚠ 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. ⚠

Specifiying a TTL per token

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

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:

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

CLI:

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:

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:

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 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/<name> endpoint:

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.

⚠ The password is not stored in Vault and will not accessible within Vault itself. ⚠

Specifiying a TTL per user

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

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:

❯ 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:

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:

vault lease revoke -prefix=true jenkins/users/

Developing

If you wish to work on this plugin, you'll first need Go installed on your machine (whichever version is required by Vault) as well as docker to run Jenkins.

Get Plugin

Clone this repository:

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:

make all

Enable and configure plugin

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

make jenkins

Then configure the plugin:

make enable-plugin

Start Jenkins + Vault

docker-compose up

Tests

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

make jenkins

To run the integration tests:

make test

Create example credentials

Create a token:

make token

Create a user:

make user