This plugin enables Jenkins to fetch secrets from Azure Key Vault and inject them directly into build jobs. It works similarly to the Credential Binding Plugin and borrows much from the Hashicorp Vault Plugin. The plugin acts as an Azure Active Directory Application and must be configured with a valid credential.
In the Jenkins Configure System page, configure the following two options in the Azure Key Vault Plugin section
- Key Vault URL - The url where your Key Vault resides (e.g.
https://myvault.vault.azure.net/
) - Credential ID - The ID associated with a secret in the Jenkins secret store. Supported types are:
- Azure Service Principal
- Azure Managed Identity (both user and system assigned)
This plugin supports the configuration as code plugin:
Example yaml:
credentials:
system:
domainCredentials:
- credentials:
- azure:
azureEnvironmentName: "Azure"
clientId: "d63d9de6-5f7a-48c1-ac1d-e90d4f5e5dcc"
clientSecret: "${CLIENT_SECRET}"
description: "An azure service principal"
id: "service-principal"
scope: SYSTEM
subscriptionId: "d63d9de6-5f7a-48c1-ac1d-e90d4f5e5dcc"
tenant: "d63d9de6-5f7a-48c1-ac1d-e90d4f5e5dcc"
unclassified:
azureKeyVault:
keyVaultURL: https://not-a-real-vault.vault.azure.net
credentialID: service-principal
URL:
-Djenkins.azure-keyvault.url=https://my.vault.azure.net
User or System Assigned Managed Identity:
-Djenkins.azure-keyvault.uami.enabled=true
Service principal:
-Djenkins.azure-keyvault.sp.client_id=...
-Djenkins.azure-keyvault.sp.client_secret=...
-Djenkins.azure-keyvault.sp.subscription_id=...
-Djenkins.azure-keyvault.sp.tenant_id=...
URL:
AZURE_KEYVAULT_URL=https://my.vault.azure.net
User or System Assigned Managed Identity:
AZURE_KEYVAULT_UAMI_ENABLED=true
Service principal:
AZURE_KEYVAULT_SP_CLIENT_ID=...
AZURE_KEYVAULT_SP_CLIENT_SECRET=...
AZURE_KEYVAULT_SP_SUBSCRIPTION_ID=...
AZURE_KEYVAULT_SP_TENANT_ID=...
It's possible to pass the secret from a file instead of passing the client secret as is. Simply provide the path to the secret file.
-Djenkins.azure-keyvault.sp.client_id=...
-Djenkins.azure-keyvault.sp.client_secret_file=/path/to/secret/secretFile
-Djenkins.azure-keyvault.sp.subscription_id=...
-Djenkins.azure-keyvault.sp.tenant_id=...
AZURE_KEYVAULT_SP_CLIENT_ID=...
AZURE_KEYVAULT_SP_CLIENT_SECRET_FILE=/path/to/secret/secretFile
AZURE_KEYVAULT_SP_SUBSCRIPTION_ID=...
AZURE_KEYVAULT_SP_TENANT_ID=...
The plugin will parse the contents of the file as is. The file should only contain the client_secret value.
- Run mvn package, an .hpi file will be generated in the target folder.
Note that the example echos below will only show *****'s as the plugin redacts secrets found in the build log inside the withAzureKeyvault
build wrapper.
Snippet generator is fully supported for generating the possible values (along with inline help): Go to any pipeline job and click Pipeline Syntax
Or visit the URL: /job/<job-name>/pipeline-syntax/
Simple version:
node {
def secrets = [
[ secretType: 'Certificate', name: 'MyCert00', envVariable: 'CERTIFICATE' ],
[ secretType: 'Secret', name: 'MySecret00', envVariable: 'SECRET' ],
[ secretType: 'Secret', name: 'MySecret00', version: '342432lkjhdasjld', envVariable: 'SECRET' ]
]
withAzureKeyvault(secrets) {
sh 'echo $CERTIFICATE'
sh 'echo $SECRET'
}
}
With overrides:
static LinkedHashMap<String, Object> secret(String secretName, String envVar) {
[
secretType: 'Secret',
name: secretName,
version: '342432lkjhdasjld',
envVariable: envVar
]
}
node {
def secrets = [
secret('my-secret', 'MY_SECRET')
]
withAzureKeyvault(
azureKeyVaultSecrets: secrets,
keyVaultURLOverride: 'https://mykeyvault.vault.azure.net',
credentialIDOverride: 'service-principal'
) {
sh 'echo $MY_SECRET'
}
}
Snippet generator is fully supported for generating the possible values (along with inline help): Go to any pipeline job and click Pipeline Syntax
-> Declarative Directive Generator
Or visit the URL: /job/<job-name>/directive-generator/
Simple:
pipeline {
agent any
stages {
stage('Build') {
options {
azureKeyVault([[envVariable: 'MY_SECRET', name: 'my-secret', secretType: 'Secret']])
}
steps {
sh "echo $SECRET"
}
}
}
}
With overrides:
pipeline {
agent any
stages {
stage('Build') {
options {
azureKeyVault(
credentialID: 'my-sp',
keyVaultURL: 'https://my.vault.azure.net',
secrets: [
[envVariable: 'MY_SECRET', name: 'my-secret', secretType: 'Secret']
]
)
}
steps {
sh "echo $SECRET"
}
}
}
}
Certificate:
pipeline {
agent any
stages {
stage('Build') {
options {
azureKeyVault([[envVariable: 'CERT_LOCATION', name: 'my-cert-name', secretType: 'Certificate']])
}
steps {
sh "openssl pkcs12 -in $CERT_LOCATION -nodes -password 'pass:' -out keyvault.pem"
}
}
}
}
The shell command above will convert the PFX file to a pem key file (also containing the certificate), note that Azure Key Vault removes the password on the pfx when you import it, if you're importing it back into Azure somewhere else you may need to convert it to pem and convert back to a pfx with a password.
Note: It is not supported to configure the credential provider with the Configuration as Code plugin and resolving credentials from Azure Key Vault in the same configuration file. Please use one of the other options (system properties, environment variables) if you want to retrieve secrets for use in Configuration as Code files
This plugin enables the retrieval of Secrets directly from Azure Key Vault. After the configuration is set up, secrets from the key vault can be viewed in the credentials page like this:
Note These credentials are read-only and metadata caching(10 minutes) means newly created secrets may not be here immediately. You can reload the cache on the system configuration page if you need a new secret to appear.
Use these credentials just as other normal credentials in Jenkins.
There are multiple supported credential types, string
is used by default. To use a different type add a tag called type
with one of the below values:
string
- Secret textusername
- Username with password- add a tag
username
for the username of the credential
- add a tag
secretFile
- a file with secret content- (optional) add a tag
fileName
for the secret file name, when it is fetched. Default is${secretNameIntheVault}.txt
.
- (optional) add a tag
sshUserPrivateKey
- SSH Private key- add a tag
username
for the username of the credential - (optional) add a tag
username-is-secret
and set it to true to hide the username in the build logs - (optional) add a tag
passphrase-id
that points to the secret name in the vault that has the passphrase that should be used with the ssh keys
- add a tag
certificate
- a certificate as secret- (optional) add tag
password-id
that points to the secret name in the vault that has the password of the certificate.
- (optional) add tag
Declarative Pipeline:
pipeline {
agent any
environment {
GITHUB_API_TOKEN = credentials('github-api-token')
}
stages {
stage('Foo') {
steps {
echo '$GITHUB_API_TOKEN'
}
}
}
}
Scripted Pipeline:
node {
withCredentials([string(credentialsId: 'github-api-token', variable: 'GITHUB_API_TOKEN')]) {
echo '$GITHUB_API_TOKEN'
}
}
az keyvault secret set --vault-name my-vault \
--name github-pat \
--value my-pat \
--tags username=github-user type=username
Scripted Pipeline:
job('my example') {
scm {
git {
remote {
github('my-repo', 'https')
credentials('github-pat')
}
}
}
}
az keyvault secret set --vault-name my-vault \
--name a-secret-file-vault-secret \
--value "-----BEGIN test secretFile-----\nline 1\nline2\nbla\nblob" \
--tags type=secretFile fileName=mySecretFile.txt
Scripted Pipeline:
node {
withCredentials([
file(credentialsId: "test-secretFile-credentialsId", variable: "VARIABLE_CONTAINING_PATH_TO_SECRET_FILE")]) {
sh("doSomething --use-this-secret-file \$VARIABLE_CONTAINING_PATH_TO_SECRET_FILE")
}
}
az keyvault secret set --tags type=sshUserPrivateKey username=my-username \
--vault-name my-vault \
--name test-ssh \
-f ~/.ssh/my-ssh-key
Scripted pipeline:
# This is a docker image that can be used to test out this feature
docker run --rm -it --publish 2222:2222 \
-e "PUBLIC_KEY=my-public-key" linuxserver/openssh-server
node {
withCredentials([sshUserPrivateKey(credentialsId: "test-ssh", keyFileVariable: "my_ssh_key", usernameVariable: "my_username")]) {
sh 'ssh -i $my_ssh_key -p 2222 $my_username@localhost "uname -r"'
}
}
Declarative pipeline:
pipeline {
agent any
environment {
SSH_PRIVATE_KEY = credentials('test-ssh')
}
stages {
stage('Foo') {
steps {
sh 'ssh -i $SSH_PRIVATE_KEY -p 2222 $SSH_PRIVATE_KEY_USR@localhost "cat world"'
}
}
}
}
If your SSH private keys has a passphrase you need to add a tag passphrase-id
which references the secret that the passphrase is stored in.
Create the passphrase secret:
az keyvault secret set \
--vault-name my-vault \
--name test-ssh-passphrase \
--value my-ssh-passphrase
Store the SSH key with the passphrase tag:
az keyvault secret set --tags type=sshUserPrivateKey username=my-username passphrase-id=test-ssh-passphrase \
--vault-name my-vault \
--name test-ssh \
-f ~/.ssh/my-ssh-key
If the passphrase can not be found in the vault, the secret will not load and a warning will be logged.
It is possible to load certificates from the vault. The certificate needs to be stored in a vault-secret base64-encoded and without whitespace. In addition to the secret containing the keystore info (the certificate), another vault-secret is needed to store the password of the keystore.
- If the certificate is protected by a password, Create the password secret:
az keyvault secret set \
--vault-name my-vault \
--name secret-containing-keystore-password \
--value my-keystore-password
- Store the (base64-encoded and without whitespace) keystore with the password tag:
if the certificate is protected by a password:
az keyvault secret set \
--tags type=certificate password-id=secret-containing-keystore-password \
--vault-name my-vault \
--name secret-containing-base64encoded-keystore \
--value {base64-encoded-keystore}
if the certificate has no password ( a zero length password )
az keyvault secret set \
--tags type=certificate \
--vault-name my-vault \
--name secret-containing-base64encoded-keystore \
--value {base64-encoded-keystore}
If the tag password-id
is set but the password can not be found in the vault, the secret will not load and a warning will be logged. If the keystore cannot be decoded, or cannot be loaded the pipeline using the certificate-credentialsId will throw an error.
Scripted pipeline:
node {
withCredentials([
certificate(
credentialsId: certificateCredentialsId,
keystoreVariable: 'PATH_TO_KEYSTORE',
passwordVariable: 'PASSWORD'
)
]) {
sh(
script: """
curl -X POST \
--cert-type P12 \
--cert "\$PATH_TO_KEYSTORE":\$PASSWORD \
${url}
"""
)
}
}
You can filter which secrets are visible to the credentials provider. By default, the plugin will load all secrets stored within the Key Vault. However, your Key Vault may be the Secret Source for multiple applications, or contains secrets not needed directly by Jenkins. To filter out secrets from being set, add a System Property or Environment Variable:
Via System Property:
-Djenkins.azure-keyvault.label-selector=myCustomLabel
Via Environment Variable:
AZURE_KEYVAULT_LABEL_SELECTOR=myCustomLabel
If included in your config, when the Azure Key Vault plugin is resolving credentials from your Key Vault, it will skip any secret that does not contain a tag jenkins-label=myCustomLabel
. For example, if two secrets are set within the KeyVault:
az keyvault secret set --vault-name my-vault \
--name testUserNoLabel \
--value example1 \
--tags username=testUserNoLabel type=username
az keyvault secret set --vault-name my-vault \
--name testUserWithLabel \
--value example2 \
--tags username=testUserWithLabel type=username jenkins-label=myCustomLabel
Multiple label selectors can be specified as a comma separated list:
az keyvault secret set --vault-name my-vault \
--name testUserWithLabel \
--value example2 \
--tags jenkins-label=myCustomLabel1,myCustomLabel2
With the System Property or Environment variable being set in this example, only the usernamePassword testUserWithLabel
will be present in your Jenkins instance.
The ID, description and scope of credentials can be specified with tags on the Azure Key Vault secret. The ID is specified with the tag "jenkinsID" and appears in the Jenkins credentials UI in the "ID" column. This is the credentials ID parameter used in withCredentials()
calls. The description is specified with the tag "description" and appears in the Jenkins credentials UI in the "Name" column. The scope is specified with the tag "scope" and can be set to "system" or "global". By default the scope will be set to global.
az keyvault secret set --vault-name my-vault \
--name testUserWithLabel \
--value example2 \
--tags jenkinsID=myCred description="This is my credential" scope=system
The plugin allows the Configuration as Code plugin to interpolate string secrets from Azure KeyVault.
az cli:
az keyvault secret set --vault-name my-vault --name my-password --value password
JCasC:
jenkins:
securityRealm:
local:
allowsSignup: false
users:
- id: "foo"
password: "${my-password}"