Jenkins : Credentials Plugin

Plugin Information

View Credentials on the plugin site for more information.

Older versions of this plugin may not be safe to use. Please review the following warnings before using an older version:

Credentials Plugin

Versions Status

Criteria

Version

Notes

I do not want to have to restart my Jenkins in the next two weeks

2.1.16

No major known issues.

I am ok with a <5% probability of having to restart my Jenkins in the next two weeks because of a bug in the credentials plugin



I want to try the latest version and help shake out any bugs. This may mean needing to upgrade and restart if I do find bugs



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. 

There are three sets of documentation for the Credentials API plugin:

  • User guide
    If you are using Jenkins and want to understand how to manage credentials using the Credentials API plugin, you should read the user guide.
  • Consumer guide
    If you are writing a plugin for Jenkins and you need to retrieve credentials using the Credentials API, you should read the consumer guide.
  • Implementation guide
    If you are writing a plugin for Jenkins and you need to:
    • Define a new type of credential

    • Define a new type of credentials domain specification

    • Define a new credentials providers

    Then the implementation guide is for you.

The guides are also available as PDFs (The PDFs need to be generated, so these may not be as up-to-date as the documentation in GitHub, however, GitHub is has some issues with rendering certain elements so the PDFs should look better)

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.

Compatibility Policy

The credentials plugin is used by a large number of plugins, therefore we endevour to be conservative in the baseline Jenkins requirements. When there is a good technical driver for upgrading the baseline, the aim in updating the baseline is that:

  • At least 90% of installations using the most recent version of the plugin that is at least 2 months old shall be able to upgrade to the latest version of the plugin. 

Version History

Version 2.3.0 (August 26th, 2019)

  • Allow credentials parameters to shadow credentials with the same id in credentials lookup (JENKINS-58170).
  • Various code cleanups.

Version 2.2.1 (August 1st, 2019)

Version 2.2.0 (May 31, 2019)

Version 2.1.19 (May 21st, 2019)

Version 2.1.18 (July 20th, 2018)

  • Add a CLI command named list-credentials-as-xml  to list all credentials in a store in XML format (issue #52175)

Version 2.1.17 (June 25th, 2018)

Version 2.1.16 (September 14th, 2017)

  • All
    • (info) Minor code change to credentials action in order to aid comprehension by anyone reading the code

Version 2.1.15 (September 6th, 2017)

  • All
    • (info) Canonical reference documentation for plugin released. This documentation should be taken on a canonical basis, in other words, where behaviour deviates from the canonical documentation there is a bug. Sources such as https://jenkins.io/doc/ and https://jenkins.io/doc/developer/ are expected to use the canonical documentation as a basis for authoring original content that describes in a cohesive narative how to use the credentials plugin.
  • User
    • (warning) Mix a hash of the secret value into the fingerprints to remove false duplicate tracking (issue #43263) NOTE: all existing credentials fingerprint tracking history will be lost.
    • (warning) Editing the description field of a credential will no longer change its fingerpint (issue #44171NOTE: all existing credentials fingerprint tracking history will be lost.
    • (info) All BASE-64 handling has been standardized so that chunkend and url-safe variants are handled consistently (issue #45185)
  • Consumer
    • (plus) Allow <c:select> tags to specify the checkMethod
  • Provider
    • (info) No changes affecting plugins implementing credentials providers

Version 2.1.14 (June 12th, 2017)

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)

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 

Attachments:

Screen Shot 2013-08-07 at 13.50.42.png (image/png)
image2017-7-24 12:55:33.png (image/png)
consumer.pdf (application/pdf)
implementation.pdf (application/pdf)
user.pdf (application/pdf)