×
Find plugins

Credentials2.1.13Minimum Jenkins requirement: 1.625.3ID: credentials

Installs: 146832
Last released: 2 months ago
Maintainers
Stephen Connolly
Dependencies
No dependencies found

Plugin Information

Credentials Plugin

Versions Status


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 call CredentialsProvider.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.

Plugins that provide credentials

If your plug-in is not listed here, then simply add the label credentials-provider to your plug-in wiki page and it will be automatically listed.

Plugins that consume credentials

If your plug-in is not listed here, then simply add the label credentials-consumer to your plug-in wiki page and it will be automatically listed.

Version History

Version 2.1.13 (March 2nd, 2017)

  • CSS width problems with credentials select drop-down (issue #41512)

Version 2.1.12 (February 22nd, 2017)

  • IllegalArgumentException: unable to convert to class com.cloudbees.plugins.credentials.SecretBytes (issue #41946)
  • Inconsistency in encoding of keystores (issue #41952)

Version 2.1.11 (January 26th, 2017)

  • When duplicate credentials have the same ID, the first one should win (issue #41004)
  • The credentials usage tracking should warn that it may give false negatives (issue #40701)
  • The Add button in a credentials select control should be enabled if the user has create permission in any stores in scope, not just the root store (issue #41478)
  • Use the Jenkins.XSTREAM2 instance so that plugins can use alias to assist migration of credentials (issue #40914)

Version 2.1.10 (November 23, 2016)

  • Modified API method name introduced in 2.1.9

Version 2.1.9 (November 17, 2016)

  • Add API method which allows to check if a given String is of type SecretBytes (issue #39381)
  • Provide a mechanism for forcing a save of all credential store which will only be available via groovy scripting (issue #39317)

Version 2.1.8 (October 25, 2016)

  • Add additional diagnostic logging to certificate credentials to help local malformed credentials
  • Add additional exception safety to name inference of credentials

Version 2.1.7 (October 18, 2016)

  • Add support for ESC closing the add credentials dialog (issue #38961)

Version 2.1.6 (October 10, 2016)

  • Suppress incorrect duplicate ID warning when updating credentials (issue #38861)

Version 2.1.5 (September 20, 2016)

  • Resolve confusion for plugin authors on how to get form validation URLs in config.jelly (issue #36315)
  • Provide a mechanism to report that a credential's secrets are unavailable (issue #36431)
  • Provide a SecretBytes type for space efficient local storage of an encrypted byte[] (issue #36432)
  • Fix some failing test cases when using the PCT (issue #37801)
  • Saving SecretBuildWrapper for the first time fails due to duplicated credentialsId field unless git also installed (issue #37707)

Version 2.1.4 (June 23, 2016)

  • Make it easier for CredentialProvider implementers to handle context objects that are both an Item and an ItemGroup (issue #36161)

Version 2.1.3 (June 20, 2016)

  • Context menu icon URLs were incorrect when using a context path of / so the icons would not display on the main Credentials view pages

Version 2.1.2 (June 20, 2016)

  • If you added type restrictions you could not completely remove them (issue #36090)
  • The workaround for issue #26578 was breaking the unit tests for ssh-credentials (bug in htmlunit) so delay the "workaround" by 1ms so that htmlunit does not bomb out (issue #36034)  

Version 2.1.1 (June 15, 2016)

  • Add support to track where a credential is used (issue #20139) - Note that tracking relies on credentials consumers recording the usage, so if there are issues with this please file issues against the credential consuming plugin as it is not a problem with the credentials API.
  • Create credentials through CLI (issue #28407)

Version 2.1.0 (June 9, 2016)

  • Credentials store XML/JSON REST API cannot browse into domains (issue #24631)
  • Added some extra NPE safety to try and prevent a NPE in plugins that do not use the API correctly (issue #35317)
  • System credentials store showing twice for credentials parameter Add button drop down when logged in as a user (issue #35488)
  • Credentials providers need to be able to list credentials without retrieving the backing secret (issue #35306) - this change changes the recommended way to populate drop down select boxes for plugin authors. The old way still works but is no longer recommended, hence the minor version bump. An example of a new style implementation is as follows:
    public ListBoxModel doFillCredentialsIdItems(@AncestorInPath Job context, @QueryParameter String source, @QueryParameter String value) {
        if (context == null || !context.hasPermission(Item.CONFIGURE)) {
            // previously it was recommended to just return an empty ListBoxModel
            // now recommended to return a model with just the current value
            return new StandardUsernameListBoxModel().includeCurrentValue(value);
        }
        // previously it was recommended to use the withXXX methods providing the credentials instances directly
        // now recommended to populate the model using the includeXXX methods which call through to
        // CredentialsProvider.listCredentials and to ensure that the current value is always present using
        // includeCurrentValue
        return new StandardUsernameListBoxModel()
                .includeEmptySelection()
                .includeAs(Tasks.getAuthenticationOf(context), context, StandardUsernameCredentials.class,
                    URIRequirementBuilder.fromUri(source).build())
                .includeCurrentValue(value);
    }
    
    The main changes in this sample are:
  1. #* Adding a QueryParameter for the current value. We can then ensure that the current value is always available by using the includeCurrentValue helper method
    • Using includeAs to add the credentials using CredentialsProvider.listCredentials rather than the old pattern whereby the credentials would be retrieved directly and then converted into display name & id
    • Now recommended to use Tasks.getAuthenticationOf(job) to get the authentication that the job will run as. When issue #35081 is resolved this will become more important

Version 2.0.7 (May 27, 2016)

  • Delete and Move credentials does not work with providers that do not have modifiable domains (issue #35130)
  • Add credentials button broken on Build with Parameters screen (issue #35168)
  • Be more forgiving of users who have not configured their HTTPS front-end to forward the protocol details correctly (issue #35150

Version 2.0.6 (May 25, 2016)

  • The fix in 2.0.5 introduced a javascript error for configuring existing jobs that have already got the Add button. This has been fixed.  

Version 2.0.5 (May 24, 2016)

  • Improve the JENKINS-26578 workaround so that the in-place Add button works in newly created hetero lists again (was broken since 2.0)

Version 2.0.4 (May 24, 2016)

  • Add a workaround for the Jenkins core bug with bottom sticker bars (issue #24662)
  • Fix minor bug in credential descriptor visibility filtering

Version 2.0.3 (May 24, 2016)

  • Infinite loop in traversing the list of available credential stores for ComputerSet, Node, Computer context objects (issue #35075)

Version 2.0.2 (May 24, 2016)

  • Follow-up for one remaining incorrect icon sizing when using a custom theme (issue #33191)
  • The help text for the credentials providers was reporting the Credentials/UseItem permission in cases where that permission was disabled and the Item/Configure permission should have been reported

Version 2.0.1 (May 23, 2016)

  • Moved the Credential ID out of the advanced box
  • Where possible, the parameters view page of a build will present the credential parameter as a link to the credential to assist in disambiguation (issue #31991)
  • Impossible to scroll down the Add Credentials window content (issue #28864)
  • Users should be able to view their own credentials (issue #33872)
  • Incorrect icon sizing when using a custom theme (issue #33191)
  • Notify SaveableListener for global credentials updates (issue #33111)

Version 2.0 (May 20, 2016)

  • The Add button now features a drop-down menu to allow selecting the destination store
  • The Add modal dialog now supports selecting the credential domain to add into
  • The credentials management has been moved fully into the Credentials action links
  • The main page for the Credentials action has been reworked to show the effective credentials available within the current scope (as well as any masked credentials from parent scopes) as well as all the credentials stores contributing to the current scope. All the links are now context menu links.
  • The Manage Jenkins » Configure Credentials screen has been reworked to actually allow for managing the credentials providers and types. It is now possible to restrict the credential types available per credential store as well as globally disable individual credential stores.

Version 1.28 (Apr 30, 2016)

  • Stop allowing to update domain with blank names (issue #34329)
  • Add french translation
  • Sort credentials by credential name in select lists
  • Upgrade to new parent pom

Version 1.27 (Apr 4, 2016)

  • After looking up user-scoped credentials, the SecurityContext is set to null causing user-scoped credentials to not be retrieved properly (issue #33944)

Version 1.26 (Mar 23, 2016)

  • User may view some information in credential-store of other users (issue #31610)

Version 1.25 (Feb 19, 2016)

  • Consider default value to be the default (issue #32642)
  • Fix incorrect parameter order that breaks Rebuild plugin with credentials parameters (issue #29646)

Version 1.24 (Oct 12, 2015)

  • Fix NPE when taking a snapshot of certificate credentials.

Version 1.23 (Sep 7, 2015)

Version 1.22 (Jan 25, 2015)

  • Added a work-around for issue #26578 until the baseline version of Jenkins has fixed that issue

Version 1.21 (Jan 15, 2015)

  • JENKINS-26099 Allow the user to specify the ID of newly created credentials. (For username/password and certificate credentials. Credentials defined in other plugins need to use BaseStandardCredentialsDescriptor to pick up this feature.)
  • Suppressing a stack trace in case of a failure to unlock certificate credentials due to an empty password.

Version 1.20 (Dec 19, 2014)

Version 1.19 (Dec 18, 2014)

Version 1.18 (Oct 19, 2014)

  • UI glitch with icon tags

Version 1.17 (Oct 17, 2014)

  • Simplified handling of uploaded-file certificates on slaves.
  • Allowing parameter values to be used from workflow projects.
  • Improved Javadoc for list box models.
  • JENKINS-21051 Japanese translation fixes.
  • Exported description and displayName for use by REST API.

Version 1.16.1 (Aug 11, 2014)

  • Fix NPE in new parameter resolving helper method

Version 1.16 (Aug 11, 2014)

  • Add support for credentials parameters (note these are not exposed as environment variables, rather the IDs are exposed and plugin support is required to retrieve the credentials from the respective credential stores and act on those credentials as necessary)

Version 1.15 (Jul 10, 2014)

  • Fix the check for `isScopeRelevant(x) so that updating credentials within a credentials domain does not reset the scope to 'Global' (SECURITY-137

Version 1.14 (Jun 16, 2014)

  • Added support for snapshotting credentials.

Version 1.13 (May 30, 2014)

  • Added a defensive NPE check to UserCredentialsProvider to prevent log file spamming when using private security realm.

Version 1.12 (May 23, 2014)

  • Added a URI path domain requirement and specification to the standard API.

Version 1.11 (May 21, 2014)

  • Fix the permission scope to flag that credential store permissions are scoped to items, item groups and Jenkins and not limited in scope to just Jenkins.
  • Added an annotation to provide future assistance in identifying string fields that hold credential ids.

Version 1.10 (Feb 11, 2014)

  • Add /api/ support
  • Add support for domain restricted credentials that can further restrict themselves within a domain

Version 1.9.4 (Dec 6, 2013)

  • Fixed issue with c:select and renderOnDemand on 1.500ish+ Jenkins instances (JENKINS-20647)

Version 1.9.3 (Nov 8, 2013)

  • Minimum version of Jenkins is now 1.466
  • Added support for in-place adding of new credentials (JENKINS-20072)

Version 1.9.2 (Nov 8, 2013)

  • UI improvements and bugfixes

Version 1.9.1 (Oct 16, 2013)

  • Fix data binding issue with /lib/credentials/select.jelly

Version 1.9 (Oct 11, 2013)

  • Make DomainRequirement serializable as it may need to be transferred across remoting channels
  • Update to German L10N
  • Add a /lib/credentials/select.jelly taglib to make it possible to retrofit and add credentials UI to plugins that use this for selecting a credential from a drop-down list (note there is a bug in this version that is fixed in 1.9.1 where it fails to correctly prepare data-binding)

Version 1.8.3 (Sep 25, 2013)

Version 1.8.2 (Sep 13, 2013)

Version 1.8.1 (Sep 12, 2013)

  • Fixed some minor layout issues.
  • There is a bug in core with lazy rendering which will affect the ability to configure the credential scope via the new UI. Suspect this will require a fix in Jenkins core.

Version 1.8 (Sep 12, 2013)

  • Added an API to allow plugins to configure credentials
  • Added an abstract Action to allow credential stores which permit configuration of credentials to expose a user-space UI for credential management
  • Added distinct permissions for viewing the credential management UI; managing credential domains; adding credentials; removing credentials; and updating credentials.
  • Added the user space UI to the system credentials provider: JENKINS-19563

Version 1.7.6 (Aug 28, 2013)

  • Exception in Manage Credentials screen in 1.7.5.

Version 1.7.5 (Aug 28, 2013)

  • Fix issue with null values in domainCredentials.jelly taglib

Version 1.7.4 (Aug 22, 2013)

  • Include fix for JENKINS-19308
  • Add some more German translations

Version 1.7.3 (Aug 16, 2013)

Version 1.7.2 (Aug 15, 2013)

  • Fix naming of StandardUsernamePasswordCredentials

Version 1.7.1 (Aug 15, 2013)

  • Minor bug-fix in looking up names of credential instances.

Version 1.7 (Aug 15, 2013)

  • Provide a standard client certificate credential implementation type.

Version 1.6 (Aug 7, 2013)

  • Provide a standard username & password credential implementation type.
  • Add a builder for URI based domain requirements.
  • Add a ListBoxModel implementation to assist the common task of selecting a credential from a set of credentials.

Version 1.5 (Jul 23, 2013)

  • Add some common credential type marker interfaces
  • Add API support for filtering credentials
  • Add support for partitioning credentials into domains

Version 1.4 (Apr 15, 2013)

  • Add help page for scope.

 Version 1.3 (Feb 27, 2012)

  • Missed renaming a critical stapler view.

Version 1.2 (Feb 27, 2012)

  • Missed a critical constructor.

Version 1.1 (Feb 27, 2012)

  • Missed a couple of cosmetic references in open-sourcing this previously closed source plugin

Version 1.0 (Feb 27, 2012)

  • Initial release 
ArchivesGet past versions
Labels
This plugin has no labels