{"id":15567759,"url":"https://github.com/circa10a/vault-plugin-secrets-jenkins","last_synced_at":"2025-10-02T23:34:38.004Z","repository":{"id":45253911,"uuid":"442263832","full_name":"circa10a/vault-plugin-secrets-jenkins","owner":"circa10a","description":"A plugin for Hashicorp Vault to create ephemeral users and API tokens for Jenkins CI","archived":false,"fork":false,"pushed_at":"2022-01-13T01:22:27.000Z","size":48,"stargazers_count":9,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-01-10T22:41:51.796Z","etag":null,"topics":["ephemeral-credentials","golang","jenkins","jenkinsci-platform-integrations","security-automation","vault","vault-plugins"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/circa10a.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-12-27T20:15:29.000Z","updated_at":"2024-08-25T01:44:22.000Z","dependencies_parsed_at":"2022-09-16T08:52:35.546Z","dependency_job_id":null,"html_url":"https://github.com/circa10a/vault-plugin-secrets-jenkins","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fvault-plugin-secrets-jenkins","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fvault-plugin-secrets-jenkins/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fvault-plugin-secrets-jenkins/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/circa10a%2Fvault-plugin-secrets-jenkins/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/circa10a","download_url":"https://codeload.github.com/circa10a/vault-plugin-secrets-jenkins/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":235048997,"owners_count":18927715,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ephemeral-credentials","golang","jenkins","jenkinsci-platform-integrations","security-automation","vault","vault-plugins"],"created_at":"2024-10-02T17:12:54.371Z","updated_at":"2025-10-02T23:34:37.947Z","avatar_url":"https://github.com/circa10a.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# vault-plugin-secrets-jenkins\n\n![Build Status](https://github.com/circa10a/vault-plugin-secrets-jenkins/workflows/release/badge.svg)\n[![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)\n[![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)\n\n\u003cimg align=\"right\" src=\"/images/jenkins-vault.png\" width=\"30%\" /\u003e\n\nThis is a backend plugin to be used with [Hashicorp Vault](https://www.github.com/hashicorp/vault).\nThis plugin generates ephemeral Jenkins Users and API tokens.\n\n- [vault-plugin-secrets-jenkins](#vault-plugin-secrets-jenkins)\n  - [Quick Links](#quick-links)\n  - [Usage](#usage)\n  - [Enable plugin](#enable-plugin)\n  - [Configure Plugin](#configure-plugin)\n    - [Root User Validation](#root-user-validation)\n  - [Creating API tokens for configured user](#creating-api-tokens-for-configured-user)\n    - [Set default token TTL](#set-default-token-ttl)\n    - [Create a token](#create-a-token)\n      - [Specifiying a TTL per token](#specifiying-a-ttl-per-token)\n      - [Parsing a token value from Vault response](#parsing-a-token-value-from-vault-response)\n    - [List all active token leases](#list-all-active-token-leases)\n    - [Revoking all tokens for configured user](#revoking-all-tokens-for-configured-user)\n  - [Managing ephemeral users](#managing-ephemeral-users)\n    - [Create a user](#create-a-user)\n      - [Specifiying a TTL per user](#specifiying-a-ttl-per-user)\n    - [List all active users](#list-all-active-users)\n    - [Revoking a User](#revoking-a-user)\n    - [Revoking all users](#revoking-all-users)\n  - [Developing](#developing)\n    - [Get Plugin](#get-plugin)\n    - [Build plugin and start Vault](#build-plugin-and-start-vault)\n    - [Enable and configure plugin](#enable-and-configure-plugin)\n    - [Start Jenkins + Vault](#start-jenkins---vault)\n    - [Tests](#tests)\n      - [Create example credentials](#create-example-credentials)\n\n## Quick Links\n\n- [Vault Website](https://www.vaultproject.io)\n- [Jenkins API Tokens](https://www.jenkins.io/doc/book/system-administration/authenticating-scripted-clients/)\n\n## Usage\n\nThis is a [Vault plugin](https://www.vaultproject.io/docs/internals/plugins.html)\nand is meant to work with Vault. This guide assumes you have already installed Vault\nand have a basic understanding of how Vault works. Otherwise, first read this guide on\nhow to [get started with Vault](https://www.vaultproject.io/intro/getting-started/install.html).\n\nIf 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).\n\n## Enable plugin\n\n```shell\nvault secrets enable -path=jenkins vault-plugin-secrets-jenkins\nSuccess! Enabled the vault-plugin-secrets-jenkins secrets engine at: jenkins/\n```\n\n## Configure Plugin\n\nThe 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:\n\n```shell\nvault write jenkins/config url=http://localhost:8080 username=admin password=admin\nSuccess! Data written to: jenkins/config\n```\n\n### Root User Validation\n\nBy 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:\n\n```shell\nvault write jenkins/config url=http://localhost:8080 username=admin password=fake validate=false\nSuccess! Data written to: jenkins/config\n```\n\n## Creating API tokens for configured user\n\n### Set default token TTL\n\nYou 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:\n\n```shell\nvault write sys/mounts/jenkins/tokens/tune default_lease_ttl=5m\nSuccess! Data written to: sys/mounts/jenkins/tokens/tune\n```\n\nTokens will automatically be revoked and deleted from Jenkins after the TTL has expired.\n\n### Create a token\n\nA token with a lease is generated by using a `read` operation on the `tokens/\u003cname\u003e` endpoint:\n\n```shell\nvault read jenkins/tokens/mytoken\nKey                Value\n---                -----\nlease_id           jenkins/tokens/mytoken/fJ57afQZMyXDcJnm74BgLLt8\nlease_duration     5m\nlease_renewable    true\ntoken              1184cb7b22c404efa1c293e9841b66f345\ntoken_id           1c2864f3-4108-4417-807a-358357bc8432\ntoken_name         mytoken\n```\n\nThe `token` value is what is to be used to authenticate with Jenkins as a subsitution for the user's password.\n\n: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:\n\n#### Specifiying a TTL per token\n\nYou can specify the TTL for an individual token by supplying the `ttl=\u003cttl\u003e` parameter like so:\n\n```shell\nvault read jenkins/tokens/mytoken ttl=2m\nKey                Value\n---                -----\nlease_id           jenkins/tokens/mytoken/i81VB5RmXJCQdMdUUuwngTJI\nlease_duration     2m\nlease_renewable    true\ntoken              1185adcc9c996fd9b394a520ca8e0c6024\ntoken_id           a7ffa97f-032a-40c1-b9d9-e14c7a7dbc12\ntoken_name         mytoken\n```\n\n#### Parsing a token value from Vault response\n\n**HTTP**:\n\n```shell\ncurl -s  -H \"X-Vault-Token: \u003ctoken\u003e\"  http://localhost:8200/v1/jenkins/tokens/mytoken | jq '.data.token'\n\"119630cd3df88834e6b8000983529afcde\"\n```\n\n**CLI**:\n\n```shell\nvault read jenkins/tokens/mytoken -format=json | jq -r '.data.token'\n119e4f728a738a1ca4e2c65329a5ebdba9\n```\n\n### List all active token leases\n\nYou can view all of the all active Jenkins API token leases that Vault is managing:\n\n```shell\nvault list sys/leases/lookup/jenkins/tokens/mytoken\nKeys\n----\nYvk37n1SCCfovcvk9YswCm7m\nrFbQIvo7mGUMbumYIplTewbX\nxlY32KoMTuS54rgAPnK2QvjR\n```\n\n### Revoking all tokens for configured user\n\nYou can revoke all Vault managed tokens by revoking all leases under the `/jenkins/tokens` mount:\n\n```shell\nvault lease revoke -prefix=true jenkins/tokens/\n```\n\n## Managing ephemeral users\n\nThis 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:\n\n![alt text](/images/permissions.png)\n\n### Create a user\n\nA user with a lease is generated by using a `write` operation on the `/users/\u003cname\u003e` endpoint:\n\n```shell\nvault write jenkins/users/myuser password=password fullname=\"Jenkins the Butler\" email=email@example.com\nKey                Value\n---                -----\nlease_id           jenkins/users/myuser/hTGbJhDFbAQpALv1FjJyJ4vz\nlease_duration     5m\nlease_renewable    true\nemail              email@example.com\nfullname           Jenkins the Butler\nusername           myuser\n```\n\nOnce the user is created, you can follow the same steps above to create API tokens for the new user if you prefer.\n\nOnce 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.\n\n:warning: **The password is not stored in Vault and will not accessible within Vault itself.** :warning:\n\n#### Specifiying a TTL per user\n\nYou can specify the TTL for an individual supplying by supplying the `ttl=\u003cttl\u003e` parameter like so:\n\n```shell\nvault write jenkins/users/myuser password=password fullname=\"Jenkins the Butler\" email=email@example.com ttl=1m\nKey                Value\n---                -----\nlease_id           jenkins/users/myuser/hBUoPCrwAySlmQuMoGEiZtUF\nlease_duration     1m\nlease_renewable    true\nemail              email@example.com\nfullname           Jenkins the Butler\nusername           myuser\n```\n\n### List all active users\n\nYou can view all of the all active Jenkins Users that Vault is managing by listing the `/users/` endpoint:\n\n```shell\n❯ vault list jenkins/users/\nKeys\n----\nmyuser\n```\n\n### Revoking a User\n\nYou can revoke an individual Jenkins user by revoking the user name inder the `/users/` endpoint:\n\n```shell\nvault lease revoke jenkins/users/myuser\nAll revocation operations queued successfully!\n```\n\n### Revoking all users\n\nYou can revoke all Vault managed Jenkins users by revoking all users under the `/jenkins/users` mount:\n\n```shell\nvault lease revoke -prefix=true jenkins/users/\n```\n\n## Developing\n\nIf you wish to work on this plugin, you'll first need [Go](https://www.golang.org)\ninstalled on your machine (whichever version is required by Vault) as well as [docker](https://docs.docker.com/get-docker/) to run Jenkins.\n\n### Get Plugin\n\nClone this repository:\n\n```shell\ngit clone https://github.com/circa10a/vault-plugin-secrets-jenkins.git\n```\n\n### Build plugin and start Vault\n\nOnce the server is started, register the plugin in the Vault server's [plugin catalog](https://www.vaultproject.io/docs/internals/plugins.html#plugin-catalog):\n\n```sh\nmake all\n```\n\n### Enable and configure plugin\n\nFor configuration to work, jenkins will need to be running (via docker):\n\n```shell\nmake jenkins\n```\n\nThen configure the plugin:\n\n```shell\nmake enable-plugin\n```\n\n### Start Jenkins + Vault\n\n```shell\ndocker-compose up\n```\n\n### Tests\n\nJenkins needs to be running for the tests to execute successfully:\n\n```shell\nmake jenkins\n```\n\nTo run the integration tests:\n\n```shell\nmake test\n```\n\n#### Create example credentials\n\nCreate a token:\n\n```shell\nmake token\n```\n\nCreate a user:\n\n```shell\nmake user\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirca10a%2Fvault-plugin-secrets-jenkins","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcirca10a%2Fvault-plugin-secrets-jenkins","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcirca10a%2Fvault-plugin-secrets-jenkins/lists"}