This is a backend plugin to be used with Hashicorp Vault. This plugin generates ephemeral Jenkins Users and API tokens.
- vault-plugin-secrets-jenkins
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.
vault secrets enable -path=jenkins vault-plugin-secrets-jenkins
Success! Enabled the vault-plugin-secrets-jenkins secrets engine at: jenkins/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/configBy 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/configYou 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/tuneTokens will automatically be revoked and deleted from Jenkins after the TTL has expired.
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 mytokenThe token value is what is to be used to authenticate with Jenkins as a subsitution for the user's password.
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 mytokenHTTP:
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'
119e4f728a738a1ca4e2c65329a5ebdba9You 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
xlY32KoMTuS54rgAPnK2QvjRYou can revoke all Vault managed tokens by revoking all leases under the /jenkins/tokens mount:
vault lease revoke -prefix=true jenkins/tokens/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:
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 protected]
Key Value
--- -----
lease_id jenkins/users/myuser/hTGbJhDFbAQpALv1FjJyJ4vz
lease_duration 5m
lease_renewable true
email [email protected]
fullname Jenkins the Butler
username myuserOnce 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.
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 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 myuserYou can view all of the all active Jenkins Users that Vault is managing by listing the /users/ endpoint:
❯ vault list jenkins/users/
Keys
----
myuserYou 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!You can revoke all Vault managed Jenkins users by revoking all users under the /jenkins/users mount:
vault lease revoke -prefix=true jenkins/users/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.
Clone this repository:
git clone https://github.com/circa10a/vault-plugin-secrets-jenkins.gitOnce the server is started, register the plugin in the Vault server's plugin catalog:
make allFor configuration to work, jenkins will need to be running (via docker):
make jenkinsThen configure the plugin:
make enable-plugindocker-compose upJenkins needs to be running for the tests to execute successfully:
make jenkinsTo run the integration tests:
make testCreate a token:
make tokenCreate a user:
make user