This document provides a quick reference for frequently questioned concepts and features in Credentials.
By default, Jenkins uses an internal credentials store where credentials secret data are encrypted at rest in the Jenkins controller file system. This security model does not prevent anyone with read access to the controller file system from reading and decrypting those secrets. For more sensitive secrets, it is highly recommended to install and use an external credentials provider plugin which delegates the secure storage of secrets to a proper key management system. There are several solutions available for storing and securing secrets, many of which integrate with hardware security modules (HSMs) for additional physical security of secrets. Examples of common external credentials stores for cloud providers or self-hosted environments include:
A full listing (including some developer-level details) of plugins that provide credentials extensions is available in the developer documentation.
Credentials are accessed through a combination of scopes and contexts, which are further categorized into types and domains.
The context of a credential is the path in Jenkins (i.e., the URL) where the credentials are accessed. Contexts include the root Jenkins context, jobs, users, agents, views, folders, and generally any other kind of model object.
The scope of a credential can be global, system, or user, which determines the visibility of a credential to a context. System-scoped credentials are only visible in the root Jenkins context (typically useful for things like agent SSH keys). User-scoped credentials are only visible to a context running as that user (such as a user-provided credentials parameter to a build). Global-scoped credentials are visible to their associated contexts and any children contexts; this is the default credential scope.
|
Important
|
Global-scoped credentials in the Jenkins Credentials Provider (system credentials) are accessible to any job in the system! |
The domain of a credential is a property of credentials that allows them to be grouped together more logically in the UI. This does not provide any security feature itself and is strictly enforced through the UI.
Different credentials providers give different means of organizing and exposing credentials. For example, the Jenkins Credentials Provider uses a system-wide credentials store at the root context and supports both system and global scoped credentials. Folder plugins provide a Folder Credentials Provider to anchor credentials storage in a folder along with the advanced authorization strategies possible there. User-scoped credentials are primarily accessed through the User Credentials Provider which stores secrets with the user profile in Jenkins.
Credentials should be organized to minimize granting access. This can make use of both logical organization into team or product folders as well as fine grained ACLs to grant access to credentials per principal. Deployment credentials can be added to a user’s profile to be used interactively in a deployment job to further isolate credentials access. Enabling the Credentials/UseOwn or Credentials/UseItem permissions (feature flags documentation) allows for further refinement of permissions (e.g., to allow some users to run a build, but only allow certain users to use its folder’s or triggering user’s deployment credentials).
First, ensure that you are following the Jenkins security best practices. In particular, you’ll need to use a non-trivial authorization strategy such as matrix, role-based, or folder-based; the trivial authorization strategies would defeat the purpose of securing your secrets! In a multi-user Jenkins setup where multiple groups or roles use the same Jenkins controller, you’ll need to use a plugin such as Folders or Authorize Project so that more fine-grained permission controls are available to configure to jobs so that credentials accessible to one job aren’t necessarily accessible to every other job. The Job and Node ownership plugin extends many of the mentioned authorization strategies to allow for further configuration. Additional hardening can be applied via the Job Restrictions plugin.
When working with especially sensitive secrets such as code signing certificates, use of a hardware security module (HSM) is recommended for physical storage and protection of secret and private keys. The internal credentials stores are not sufficiently secure for these purposes. Cloud providers typically have HSMs as a service, and secrets management software typically offers HSM integration as an enterprise feature. Credentials provider plugins provide integration points with this plugin to allow for externally managed secrets to be accessible via the same UI and API as Jenkins-managed secrets.
Credentials plugin exports numerous REST APIs and CLI commands for the various features exposed through the UI. These APIs and commands are documented in the user documentation.
JCasC provides numerous integration points for bootstrapping credentials providers to avoid storing plaintext credentials in configuration repositories. These are documented in detail in the JCasC Handling Secrets docs.