Configuring restricted credentials with the CloudBees Restricted Credentials plugin

The CloudBees Restricted Credentials plugin enables an additional Jenkins credentials store that lets you define restricted credentials with built-in access control using the full item names.

Restricted credentials are similar to other Jenkins credentials in that they can be used in folders, jobs, and builds to control access. However, restricted credentials are limited to the specific items that you define in allowlists and denylists.

Allowlists and denylists are comma separated lists of ANT Path matcher strings. CloudBees CI uses them to check whether an item is allowed to use the restricted credentials. If the full item name in Jenkins matches the allowlist and does not match the denylist, then the item is allowed to use the credentials. You can use any of the available types of Jenkins credentials to create restricted credentials.

Restricted credentials store

Restricted credentials are stored separately from the default Jenkins credentials store. The restricted credentials store is shown in the Jenkins UI next to the default store with a different logo.

Creating allowlists and denylists

The difference between restricted credentials and regular credentials is the use of allowlists and denylists. Allowlists and denylists provide a powerful way to define access to restricted credentials, but at the same time, they must be implemented carefully to prevent giving users undesired access.

Some example allowlist patterns include:

**/*: the credentials can be used everywhere. This functionality is equivalent to the way regular Jenkins credentials work.
my-folder/my-inner-folder/my-job: the credentials can only be used by a specific job, they are restricted everywhere else.
my-folder/my-multibranch/*: the credentials can be used by any branch or PR build in the multibranch project.
my-folder/my-multibranch/PR-*: the credentials can be used by any PR build in the multibranch project.
my-folder/my-multibranch/main-*: the credentials can be used by any branch starting with main- in the multibranch project.

You can create combinations of patterns like the examples above by separating them with commas.

You can also use the denylist to forbid some of the allowlist matching entries, for example:

Allow my-folder/my-multibranch/main-*, Deny my-folder/my-multibranch/main-dev-*: the credentials can be used on branches starting with main-, except for those starting with main-dev-.

Using wildcards

You must use the * and ** wildcard operators carefully. When you use them in a path component, they match any items (or sub-items) under the parent path. For example:

my-folder/**/main: the credentials are visible to all items named main under my-folder (including all sub-folder levels). This means that anyone with Item.CREATE permission at any level of the folder hierarchy below my-folder can create an item named main and get access to the credentials.
**/feature: the credentials are visible on any item named feature, it does not matter where the item is in the directory structure. Anyone with the Item.CREATE permission can create an item with that name and access the credentials.

If you configure restricted credentials for a multibranch project, these rules also apply to source control management (SCM) users with write access to the SCM system. For example, if credentials are restricted to my-multibranch/feature-* branches, then a user with SCM write permission can create a branch named feature-X. If the branch is detected by Jenkins, and a build is triggered on it, that build can access the credentials.

As a best practice, try to define the allowlist to be as specific as possible, and use wildcards only when you are certain that the cases described above do not pose a security problem.

Configuring restricted credentials for the operations center

The Restricted Credentials plugin is available to both the operations center and controllers (standalone or connected to the operations center). It is possible to define restricted credentials in the operations center, however the allowlist and denylist are not shared with the controllers. This means that restricted credentials defined in the operations center can only be restricted to items in the operations center.

For example, an allowlist pattern like all-controllers/controller-1 would restrict the use of the credentials to the controller-1, but it would be visible in the entire controller and all items on the controller would have access. It is not possible to restrict access to specific items in the controller.