Using an SSH agent to authenticate SSH connections


How can I authenticate SSH connections on slaves without copying the SSH key to the slave?



DEV@cloud's default configuration is designed for the convenience and simplicity of small / new users where a single shared credential is shared by all jobs. Typically this configuration is suitable where the Jenkins is used by a small team of trusted users.

DEV@cloud exposes a single shared id_rsa or id_dsa SSH private-key as a file to all jobs.

This SSH private-key is transferred directly to remote slaves for use in jobs.

Security / Compartmentalisation

For customers who require a higher level of compartmentalisation and control, the job administrator can configure SSH keys at a folder level using the Credentials plugin.

This will help mitigate risks of the SSH private-key being compromised intentionally or unintentionally by a job administrator.

Using the Credentials plugin allows the user to

  • configure an SSH key in a folder - and allow access to all jobs contained within that folder or below
  • configure the job to pass the SSH private-key using an SSH agent

This allows the user to securely provide access to remote resources (using SSH authentication) without exposing the SSH private-key material to the job.

Note: while the SSH private-key content is not directly exposed to the job, this key (via the agent) can be used to authenticate to any remote resource while the agent connection is open (i.e. the job is running)


Separate your environments into folders

You can create a folder “deploy-app”, and then sub-folders for production and staging.

The production folder will have production credentials, and the staging folder will have staging credentials.

Passphrase protect your SSH keys

Due to how the Credentials plugin works, your SSH private key can be copied back out of the credential configuration - while the passphrase can not. This provides an extra layer of protection.

It is possible for a suitably motivated Jenkins administrator to recover the passphrase.

Generate a 4096 bit key

ssh-keygen -t rsa -b 4096 -f test-key

Generating an SSH key

The detailed steps for generating an SSH key are out of scope for this article.
Note: To ssh successfully, SSH Agents needs the public key (matching with the SSH private keys which injects) included into the ~/.ssh/authorized_keys in the remote server to connect.

Configuring an SSH Agent

1. Select Folder

Navigate to the top level folder that requires SSH keys.

3. Select “Credentials”

On the bottom left navigation, select the “Credentials” link.

4. Select “Folder”

On the bottom left navigation, select the “Folder” link.

5. Select “Global credentials”

On the main display, select the “Global Credentials” link.

6. Select “Add credentials”

On the left navigation, select the “Add Credentials” link.

7. Select “SSH Username with private key”

From the dropdown, select “SSH Username with private key”

Fill in all the required settings. Use globally unique names for simplicity in configuring jobs.

Consider a naming scheme like <env>-<purpose>-id_rsa - which expands to production-github-id_rsa.

8. Navigate back to folder

Select the main folder from the breadcrumb bar at the top of the page.

9. Create a new job

Add a new “item”

10. Add freestyle job

Note that you will need to configure each job separately - the SSH agent is not automatically added to each of the contained jobs.

11. Add shell step

12. Confirm that the SSH private-key was used

Have more questions? Submit a request


Please sign in to leave a comment.