This plugin allows you to store credentials in Jenkins.
The credentials plugin provides a standardized API for other plugins to store and retrieve different types of credentials. User visible features are:
- A “Manage Credentials” screen on the “Manage Jenkins” screen allowing you to manage system and global credentials.
- If you are using Jenkins security, when you go to “Users” / your username / “Configure” you would see the option to manage personal credentials.
- Anywhere those credentials are needed, there is a drop down list of the appropriate available credentials, and you just select the appropriate one.
- When the time comes to change the password, you just change it once.
And that is about it, from the end-user's perspective. A single point for managing each credential. Change it in one place and you are done.
As of version 1.5, the plugin now supports categorising credentials into different "domains" in order to allow plugins to restrict the choice of credentials to only those that are appropriate.
For example, you may use the same username with a different password on multiple services. e.g. Wile E Coyote may have an account with Acme Industries, Jenkins CI, etc. in each case using the same username but a different password.
If you need to select the credentials to use when connecting to a service, it can be difficult to ensure that you select the correct one. Selecting the wrong one may mean that the incorrect password triggers a service lockout.
Credential Domains are a solution to help with this problem.
When a plugin is asking for a list of credentials, it can add some specifications about where and how the credential will be used. If we configure the following Credential Domain:
And we are trying to make an update to the Acme wiki (e.g. https://wiki.acme.com) then the plugin asking for credentials can say that it is looking for username/password credentials and it needs ones that support the https URI scheme, the hostname is wiki.acme.com and the port is 443. The credentials plugin will compare each credential domain's specification against the requirements and exclude any which do not match. Thus the user would be presented with the appropriate and relevant set of credentials.
When creating credential domains, it is important to note that domains are excluded based on requirements failing to match the specification. Thus if there is a specification for a specific URI scheme and the requirements do not detail a specific URI scheme then the credential domain is still considered to be a match. The logic is necessary to be this way in order to both allow existing plugins to retrieve credentials from within domains (even if they do not construct and supply a list of domain requirements) and also with the principle of allowing the user to be in control, i.e. the user can still select a credential if there is a possibility that the credential might apply, only where we know the credential is not appropriate do we exclude the domain.
Information for Plugin Developers
The credentials plugin provides two main extension points:
- Credentials - a base class for all Credentials types managed by the credentials plugin. Most plugin authors will just want to subclass this type to define what they need to store in the credential type... better yet, if you can find an existing Credentials subclass that stores your credentials. So, for example, if somebody created a ssh-credentials plugin that just defines a SshCredentials class, then anyone needing ssh credentials could just depend on that... [Note that careful use of readResolve can allow this to be introduced after the fact]
- CredentialsProvider - an extension point for something that can provide credentials. For example, the CloudBees Folders plugin uses this extension point to provide folder scoped credentials, so that the credentials are only available to jobs within the folder.
When you need to get back some credentials you just callCredentialsProvider.lookupCredentials(type,item,auth,domainRequirements) to retrieve the appropriate credentials.
The type parameter is the class of credentials you want to retrieve.
The item parameter is the job you want to retrieve the credentials for, but this could also be the Jenkins instance itself; e.g., if getting the email credentials when Jenkins is sending emails, if getting the ssh credentials for Jenkins to start a slave node with, etc.
The auth parameter is the authentication that is requesting the credentials. In general this will be ACL.SYSTEM but, for example, the version 2.0 of the CloudBees Deployer plugin adds a “Deploy Now” action which allows a user to use their own user-scoped credentials to deploy an already built web application to their own RUN servlet container instance (useful for testing older builds to see if you have a valid test case for that bug).
The domainRequirements parameter is the list of requirements against which domain specifications will be verified when retrieving credentials.