Skip to main content

Managing Credentials

1. Adding Username/Password Credentials

Field Description Example Value
Username Username for the credential admin
Password Password for the credential secret123
ID Unique identifier for the credential my-credentials

Example: Adding Username/Password Credentials via UI

1. Go to Jenkins Dashboard
2. Navigate to "Manage Jenkins" > "Manage Credentials"
3. Select the appropriate domain (e.g., "System")
4. Click "Add Credentials"
5. Choose "Username with password" type
6. Fill in the username and password fields
7. Provide an ID for the credential (e.g., "my-credentials")
8. Save the credentials
Note: Ensure that the credential ID is unique within the domain to avoid conflicts.

2. Adding SSH Keys

Field Description Example
SSH Key Private SSH key content (PEM format) -----BEGIN RSA PRIVATE KEY-----<br>MIIEowIBAAKCAQEA...<br>-----END RSA PRIVATE KEY-----
Passphrase (optional) Passphrase for encrypted private key mySecurePassphrase
Description Human-readable description for the credential Deployment key for prod server

Example: Adding SSH Key via Jenkins UI

1. Go to Jenkins Dashboard
2. Navigate to "Manage Jenkins" > "Manage Credentials"
3. Select "System" > "Global credentials (unrestricted)"
4. Click "Add Credentials"
5. Choose "SSH Username with private key"
6. Paste the private key content
7. Enter passphrase if required
8. Add a description
9. Save credentials
Note: Ensure the private key is in PEM format and has proper permissions (e.g., chmod 600) before adding to Jenkins.
Warning: Never store or expose private keys in plain text outside of Jenkins' secure credential storage.

3. Adding Secret Text Credentials

Field Description Example Value
Credentials ID Unique identifier for the credential my-secret-text-id
Secret Text The actual secret text to store my-super-secret-password
Description (Optional) Human-readable description of the credential Database password for production

Example: Adding Secret Text via UI

1. Navigate to Jenkins Dashboard
2. Click "Manage Jenkins"
3. Select "Manage Credentials"
4. Choose the appropriate store (e.g., "System")
5. Click "Add Credentials"
6. Select "Secret Text" from the Kind dropdown
7. Fill in the ID, Secret Text, and optional Description
8. Click "OK"
Note: The secret text is encrypted at rest using Jenkins' built-in encryption.
Warning: Never expose secret text in logs or console output.

4. Adding Secret Files

Field Description Example
File Content Content of the secret file to be stored <?xml version="1.0" encoding="UTF-8"?>
File Name Name of the secret file in Jenkins my-config.xml

Example: Adding a Secret File via UI

1. Go to Jenkins Dashboard
2. Navigate to "Manage Jenkins" > "Manage Credentials"
3. Select the appropriate store (e.g., "System")
4. Click "Add Credentials"
5. Choose "Secret File" from the Kind dropdown
6. Paste file content into the "File" field
7. Enter a description in the "Description" field
8. Click "OK"
Note: Secret files are stored securely in Jenkins and can be accessed by jobs using the withCredentials step.

5. Adding Certificate Credentials

Field Description Example Value
Name Unique identifier for the credential within Jenkins my-certificate
Type Must be set to Certificate Certificate
Certificate PEM-encoded certificate content or file path
-----BEGIN CERTIFICATE-----
MIIF...
-----END CERTIFICATE-----
Private Key PEM-encoded private key content or file path
-----BEGIN PRIVATE KEY-----
MIIE...
-----END PRIVATE KEY-----
Password (if encrypted) Password to decrypt the private key mySecretPassword

Example: Adding Certificate Credential via UI

1. Go to Jenkins Dashboard
2. Navigate to "Manage Jenkins" > "Manage Credentials"
3. Select the appropriate domain (e.g., System)
4. Click "Add Credentials"
5. Choose "Certificate" from the Kind dropdown
6. Fill in the Name, Certificate, and Private Key fields
7. Save the credential
Note: Ensure that the certificate and private key are in PEM format. Jenkins does not support PKCS#12 (.p12) files directly.

6. Using Credentials Binding

Property Description Usage
credentialsId Identifier for the credential in Jenkins withCredentials([usernamePassword(credentialsId: 'my-cred', variable: 'USER_PASS')]) { ... }
variable Environment variable name to bind the credential to withCredentials([usernamePassword(credentialsId: 'my-cred', variable: 'USER_PASS')]) { echo env.USER_PASS }

Example: Binding Username and Password

withCredentials([usernamePassword(credentialsId: 'my-cred', variable: 'USER_PASS')]) {
    sh "echo $USER_PASS"
}

Example: Binding SSH Key

withCredentials([sshUserPrivateKey(credentialsId: 'ssh-key', keyFileVariable: 'SSH_KEY')]) {
    sh "ssh -i $SSH_KEY user@host"
}
Note: Credentials binding is available in Jenkins Pipeline DSL and supports various credential types including username/password, SSH private keys, and secret text.

7. Scoping Credentials

Scope Description Usage
Global Available to all jobs and nodes in the Jenkins instance Used for credentials that are shared across the entire Jenkins environment
Job-specific Restricted to a specific job or pipeline Used for credentials that should only be accessible within a particular job context
Node-specific Restricted to a specific node or set of nodes Used for credentials that are required only on certain agents or nodes

Example: Using Job-specific Credentials

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                withCredentials([string(credentialsId: 'job-secret', variable: 'SECRET')]) {
                    sh 'echo $SECRET'
                }
            }
        }
    }
}
Note: Scoping credentials helps enforce least privilege and improves security by limiting access to sensitive data.

8. Managing Credential Domains

Domain Description Usage Notes
Global Applies to all jobs and build agents All credentials available globally Default domain for system-wide credentials
Job-specific Restricted to a specific job or project Credentials used only in that job context Isolated from other jobs and agents
Agent-specific Bound to a specific build agent or node Credentials used for connecting to agents Useful for agent-specific access control

Example: Setting up a Job-specific Domain

pipeline {
    agent any
    environment {
        CREDENTIALS = credentials('job-specific-credentials')
    }
    stages {
        stage('Use Credentials') {
            steps {
                sh 'echo "Using credentials: $CREDENTIALS"'
            }
        }
    }
}
Note: Credential domains help in managing access control and scope of credentials across Jenkins jobs and agents.

9. Using Credentials in Pipelines

Property Description Usage
credentials() Declares a credential to be used in the pipeline
withCredentials([credentials(credentialsId: 'my-credential', variable: 'MY_VAR')]) {
    sh 'echo $MY_VAR'
}

Example: Using a Username/Password Credential

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                withCredentials([usernamePassword(credentialsId: 'my-credential', 
                                                  usernameVariable: 'USERNAME', 
                                                  passwordVariable: 'PASSWORD')]) {
                    sh 'echo "Username: $USERNAME"'
                }
            }
        }
    }
}

Example: Using a Secret Text Credential

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                withCredentials([secretText(credentialsId: 'my-secret', 
                                           variable: 'SECRET')]) {
                    sh 'echo "Secret: $SECRET"'
                }
            }
        }
    }
}
Note: Ensure the credential ID matches exactly what is configured in Jenkins.
Warning: Never hardcode credentials in pipeline scripts. Always use Jenkins' credential store.

10. Rotating and Updating Credentials

Operation Description Command/Method Notes
Rotating Credentials Replacing existing credentials with new ones to maintain security credentials.update() Use Jenkins UI or API to update credential values
Updating Credential ID Changing the identifier of a credential for better organization credentials.rename() Requires reconfiguration of jobs using the credential
Reverting to Previous Version Restoring a credential from a previous version or backup credentials.rollback() Only available if version control is enabled

Example: Updating a Username/Password Credential

const Jenkins = require('jenkins');
const jenkins = new Jenkins({ baseUrl: 'http://localhost:8080', crumbIssuer: true });

jenkins.credentials.update({
  id: 'my-credential-id',
  username: 'new-user',
  password: 'new-password'
});
Note: Ensure that all jobs and build configurations referencing the updated credential are validated to prevent runtime errors.

11. Integrating with Secret Management Tools

Tool Integration Method Notes
HashiCorp Vault jenkins-plugin:Vault Credential Provider Provides credential binding and secret retrieval from Vault
AWS Secrets Manager jenkins-plugin:AWS Credentials Plugin Allows Jenkins to fetch secrets from AWS Secrets Manager
Azure Key Vault jenkins-plugin:Azure Credentials Plugin Enables fetching of secrets from Azure Key Vault
Google Secret Manager jenkins-plugin:Google Secret Manager Plugin Supports integration with GCP Secret Manager for credential storage

Example: Using Vault Credentials in a Pipeline

pipeline {
    agent any
    stages {
        stage('Example') {
            steps {
                withCredentials([vaultString(credentialsId: 'my-vault-secret', variable: 'SECRET')]) {
                    sh 'echo "Secret value is: $SECRET"'
                }
            }
        }
    }
}
Note: Ensure the Vault plugin is installed and configured with proper permissions to access secrets.

Was this article helpful?