Table of contents

Administering CloudBees Jenkins Enterprise 2.x


Securing CloudBees Jenkins Enterprise 2.x

Caution

This guide is an old version of Securing CloudBees Jenkins Enterprise 2.x, and is superseded by Securing CloudBees Core.

Please refer to Securing CloudBees Core for updated content.

Access controls are essential to ensure only authorized users have access to sensitive information, like credentials, to prevent potential malicious use of that information. In CloudBees Jenkins Enterprise, these controls are configured from a central dashboard in Operations Center and then enforced on all connected Managed or Client Masters.

Operations Center’s security options follow the standard Jenkins security model, offering two axes to security, as well as options for adjusting how strict enforcement of these security settings should be. Administrators can force connected masters to delegate all of their security settings, allow teams complete control over their own security settings, or delegate only some security settings to teams.

CloudBees Jenkins Enterprise provides additional permission controls through:

  • Folders Plus - advanced folder-based access control (limit agents to only execute jobs within specific folders and more)

  • Nodes Plus - assign agent owners and notify owners of changes in agent availability

  • Wikitext - securely render wiki formatted text

Centrally managing security for masters

Most administrators will choose to strictly enforce their security configurations to ensure their organization remains compliant with their industry’s security requirements. CloudBees Jenkins Enterprise enables this use-case through the Operations Center security dashboard.

Out of the box, CloudBees Jenkins Enterprise will create some basic security configurations restricting access to the cluster to only the administrator who created it. This protects the cluster from unauthorized and malicious access after the initial setup is complete.

The default password is the instance’s API token, which can be found on http://your.jenkins.server/me/configure.

Once logged in, navigate to Operations Center’s global security dashboard under the Jenkins  Manage Jenkins  Global Security menu item.

Security will be enabled by default, but most administrators will also want to connect their existing authentication server to CloudBees Jenkins Enterprise to allow their organization’s users to quickly and easily onboard, while empowering the administrator to assign their organization’s existing groups certain access controls in CloudBees Jenkins Enterprise.

Because CloudBees Jenkins Enterprise includes a CloudBees Verified version of the open-source LDAP Plugin, administrators can connect their organization’s authentication server to CloudBees Jenkins Enterprise by selecting ‘LDAP’ as the CloudBees Jenkins Enterprise cluster’s Security Realm within the Global Security Configuration. Security realms are a security domain for the CloudBees Jenkins Enterprise cluster that identifies users and reports which groups a user belongs to within that realm.

Administrators can then set granular permissions on what users and groups can do within CloudBees Jenkins Enterprise by selecting Role-Based Access Control as CloudBees Jenkins Enterprise’s Authorization Strategy. An Authorization Strategy determines the set of permissions that a given user has on any specific object within CloudBees Jenkins Enterprise, including the permissions to create or delete configurations, update masters, and manage other users.

recommended config
Figure 1. Configuration for centrally managing master security

Most administrators should also opt to enforce that teams do not use any on-master executors to protect against a malicious user or script altering the master’s configuration. Most administrators should also ensure each connected master delegates their Security Realm and Authorization Strategy to the administrator’s definitions in the Operations Center security dashboard by enabling the Single Sign-On (security realm and authorization strategy) enforcement policy.

In addition to propagating and enforcing security configurations in a cluster, Single Sign-On security mode provides a fallback mechanism for connected masters’ security in the event of Operations Center downtime. If Operations Center goes offline, the Client or Managed Master connected to Operations Center will fallback to using a local copy of the same Security Realm as defined in Operations Center. This fallback behavior allows connected masters to continue to authenticate users until Operations Center connectivity is restored.

Note

To enable this fallback behavior, ensure any plugins used for authentication in Operations Center are installed on all connected masters participating with Single Sign-On enabled.

Administrators should also enable options for protecting connected masters from cross-site scripting (XSS) attacks and the Agent → Master Access Control option if they are not already on by default. Agent → Master Access Control__ restricts an agent’s permissions to prevent them from accessing files on a master, allowing teams who need to manually connect agents to their master with minimal risk to the master’s security.

CyberArk Credential Provider Plugin

Introduction

The CyberArk Credential Provider enables additional credential stores for Jenkins where the credentials are stored in a remote CyberArk Application Identity Manager vault and the secrets are only accessed on demand. The result is that Jenkins sees the updated passwords from the CyberArk Application Identity Manager vault.

Prerequisites

The CloudBees CyberArk Credential Provider Plugin 1.0.0 release has the following software requirements:

  • Jenkins LTS 2.7.4 (or newer)

  • Jenkins Credentials Plugin 2.1.12 (or newer)

  • CyberArk Enterprise Password Vault 7.2 (or newer)

  • CyberArk Central Credential Provider Web Service (version appropriate to CyberArk Enterprise Password Vault)

Architecture overview

A basic architectural overview is illustrated below.

cyberark architecture
Figure 2. Architecture overview

Some notes on the above architecture:

  • The diagram illustrates the service interactions only.

  • For the sake of simplicity, we have shown a minimal deployment of the CyberArk services. Consult the CyberArk documentation for a recommended CyberArk deployment.

    Note
    The CyberArk documentation recommends that the Central Credentials Provider be deployed on a different server from the Enterprise Password Vault, which is why we show two servers.
  • We have illustrated a deployment involving both CloudBees Jenkins Operations Center and CloudBees Jenkins Enterprise.

While it is not strictly necessary to deploy and configure the CloudBees CyberArk Credential Provider on both, for availability and continuity of service it is recommended that the CyberArk Credential Provider be deployed and configured on both, because this will allow the CloudBees Jenkins Enterprise service to have continued access to CyberArk credentials in the event that its connection to CloudBees Jenkins Operations Center is interrupted.

Communication between the various services is as follows:

  • For details on the communication protocols between the CyberArk Credential Provider server and the CyberArk Enterprise Password Vault server, please consult the CyberArk documentation.

  • The communication between CloudBees Jenkins Enterprise and CloudBees Jenkins Operations Center is using the standard Jenkins remoting protocol used between CloudBees Jenkins Enterprise and Operations Center.

  • The communication between the CloudBees CyberArk Credential Provider and the CyberArk Credential Provider Web Service depends on how the hosting Microsoft IIS service has been configured.

    • The CyberArk recommended configuration is that CyberArk Credential Provider Web Service be deployed on a Microsoft IIS service bound to a TLS secured port only.

      In such cases the recommendation is to use client certificates to authenticate client connections.

      HTTP BASIC authentication can also be used but is considered less secure.

    • An alternative configuration is available where the Jenkins instance is running on the same machine as the CyberArk Credential Provider Web Service.

      This would require that the Jenkins instance be running on Microsoft Windows as it is not possible to run the CyberArk Credential Provider Web Service on a unix server.

      In the event that the Microsoft IIS service is exclusively bound to the localhost interface, a suitably locked down Jenkins installation could be trusted to connect to the CyberArk Credential Provider Web Service without any authentication.

CloudBees does not recommend this deployment option as it requires significant hardening of the Jenkins master, e.g. ensuring that the ability to run scripts has been removed from all untrusted users, configuration of strict script security, prevention of builds on the master, etc.

It is helpful to understand the credentials resolution process.

  • Credentials resolution on CloudBees Jenkins Operations Center.

    • When a request is made for a credential on Operations Center this request will be initiated by a plugin using the Credentials API.

    • The Credentials API will construct a list of all the enabled CredentialProvider extensions in the Jenkins instance.

    • Each enabled provider will be consulted.

    • When the CloudBees CyberArk Credential Provider is consulted it will look at its list of CyberArk Object IDs.

      Note

      Due to restrictions in the APIs exposed by CyberArk, it may be necessary for the CloudBees CyberArk Credential Provider to issue a GetPassword request against the credentials that are being returned. Such requests will be tagged as for a cache refresh.

      While the password will have been retrieved, it will not have been stored or parsed in any way.

      When the credential’s password is actually being accessed, the CloudBees CyberArk Credentials Provider to will always issue a GetPassword request to retrieve the password.

    • When the Operations Center Client Plugin’s Credentials Provider is consulted, it will request the credentials exposed to CloudBees Jenkins Enterprise by Operations Center from Operations Center Server’s Credentials Gateway.

      The Credentials Gateway will relay the request to the Operations Center Credentials API, which will also route the request to Operations Center’s CloudBees CyberArk Credential Provider.

      All credentials passed from Operations Center to CloudBees Jenkins Enterprise will be snapshotted before being serialized over the remoting channel.

      Snapshotting a credential provided by the CloudBees CyberArk Credential Provider will cause the password to be retrieved at the point in time when the snapshotting occurs as a snapshotted credential should be self-contained and not require access to remote services.

Tip

It is recommended that the only CyberArk credentials defined in CloudBees Jenkins Operations Center are those credentials used to connect Shared Agents or agents within Shared Clouds.

Credentials for use in build jobs should be defined in the CloudBees Jenkins Enterprise CloudBees CyberArk Credential Provider stores.

cyberark sequence
Figure 3. Credentials retrieval process

Deployment planning

The CloudBees CyberArk Credential Provider has a number of important settings and choices that need to be made:

  • How will the CloudBees CyberArk Credential Provider connect and authenticate to the CyberArk CCP Web Service.

    • Transport: https (recommended) or http

    • Authentication: Client Certificates (recommended), None, or HTTP BASIC

    • Validation of Web Service identity: Explicitly supply certificate, None, or Use JVM Trust Store

  • Which credentials stores will be enabled for the CloudBees CyberArk Credential Provider

    • Global store allows access for all items within Jenkins

    • Per folder store allows access for all jobs within the folder or its sub-folders

  • How many CyberArk Application IDs will be used to access credentials?

    • The Global store will access using the default Application ID

    • Each folder store will access using the default Application ID but it is possible to enabling the ability to override the Application ID on a per-folder basis

  • What Safe:Folder pairs to map to which Jenkins folders?

Before deploying the CloudBees CyberArk Credential Provider it can be helpful to consider the following questions:

Will CyberArk credentials be used to connect dedicated agents to CloudBees Jenkins Enterprise?

If yes, you will need to enable the Global CyberArk Credentials store.

Are there any CyberArk credentials that should be available to all jobs in CloudBees Jenkins Enterprise?

If yes, you will need to enable the Global CyberArk Credentials store.

Are any of the CyberArk credentials categorized using CyberArk folders within the CyberArk Safes?

If yes, you will need to enable the ability to specify folders other than Root.

How many CyberArk Application IDs will Jenkins use?

If Jenkins will use a single CyberArk Application ID to access all credentials then you can simplify the configuration of CyberArk credentials by disabling the ability to override the Application ID.

How are credentials distributed among Safes in the CyberArk Vault and how will that map to the Jenkins folder structure?

In the ideal case, each Safe will be mapped to at most one Jenkins context object (i.e. the root of Jenkins or a folder within Jenkins). Additionally it may be the case that multiple Safes map to the same Jenkins context object. Deployment planning is significantly simpler if a Safe is only exposed to a single Jenkins context object.

Some example deployment plans include:

  • Application ID per product - Each product (or team) gets their own Jenkins folder, their own CyberArk Safe and their own Application ID. The CloudBees RBAC plugin is used to restrict access to the team’s Jenkins folder based on the product team membership.

    Has the advantage that if the product is retired all the credentials for that product can be removed by just removing a single CyberArk Safe.

    The use of an Application ID per product allows for the restriction of access to the product’s safe such that other products cannot access the credentials exposed within the product’s Jenkins folder.

  • CyberArk Safe per product - Each product (or team) gets their own Jenkins folder, their own CyberArk Safe. The CloudBees RBAC plugin is used to restrict access to the team’s Jenkins folder based on the product team membership.

    Has the advantage that if the product is retired all the credentials for that product can be removed by just removing a single CyberArk Safe.

    The use of a single Application ID for all of Jenkins reduces the number of Application IDs required to be configured and have access permissions within CyberArk maintained.

  • CyberArk Safe per service - CyberArk Safes are divided up by service. For example, there is a safe for Database passwords, a safe for deployment passwords, etc. Within each safe either the credentials are organized using the CyberArk Folders or the credentials access permissions are controlled at the object level.

    Allows all the credentials for a single service category to be maintained in one safe. May make it harder to know when CyberArk credentials are no longer required.

    Will require either specifying custom Application IDs or overriding the default CyberArk Folder of Root.

Additionally, you may want to consider which of the Jenkins credential stores to retain as enabled. For example, you may want to disable the Jenkins per-user credential store and apply type restrictions on the other Jenkins credential stores such that they cannot be used to store username and password credentials in order to enforce that all password credentials are stored in the CyberArk Vault.

Global Credentials Configuration

Navigate to the Jenkins  Manage Jenkins  Configure Credentials screen

empty global configuration
Figure 4. Unconfigured CyberArk Credential Provider

To enable the CyberArk provider you need to configure:

AIM server URL

Typically this will look something like https://ccp.cyberark.example.com/AIMWebService/V1.1/AIM.asmx (with the hostname modified to the hostname of your CyberArk CCP Web Service)

AIM server authentication

It is recommended to use Client certificate but the correct option depends on the authentication methods that have been configured on the Microsoft IIS server that is hosting the CyberArk CCP Web Service.

AIM server verification

It is recommended to specify an explicit certificate match.

populated global configuration
Figure 5. Configured CyberArk Credential Provider

There are some additional advanced options available:

Connection timeout

The number of seconds to wait for a connection to the CyberArk Credential Provider Web Service before failing the operation.

Request timeout

The number of seconds to wait for a response from the CyberArk Credential Provider Web Service before failing the operation.

Password request reason

The reason text to supply to the CyberArk Credential Provider Web Service when requesting the password for a credential.

The originating Job and Run will be appended to this reason text if the details can be determined. If the request cannot be associated with a Job and Run then the originating thread name will be appended to the reason text.

Cache refresh TTL (time to live)

The number of minutes that the caching of the non-secret properties of CyberArk credentials will be considered as current.

When listing credentials in the Jenkins UI, the cache will be refreshed if the cache entry is older than this TTL.

When listing credentials in the Jenkins UI, the cache will be used as a fall-back in the event that the CyberArk Credential Provider Web Service is unavailable in order to ensure that job configuration does not get broken.

Cache refresh reason

The reason text to supply to the CyberArk Credential Provider Web Service when requesting the object details of a credential for a cache refresh (which, due to the limitations of the CyberArk APIs will necessarily include requesting the password)

advanced global configuration
Figure 6. Advanced CyberArk Credential Provider configuration options

Finally you need to configure the credentials stores:

Application Id

The default CyberArk Application Id that will be used to access credentials from CyberArk.

Global credentials » Enabled

If selected, this option enables a credentials store available from the root of Jenkins.

Global credentials » Safes

The list of CyberArk Safe:Folder pairs to consult (in order) when resolving credentials exposed by the global credentials store.

Folder credentials » Enabled

If selected, this option enables per-folder credentials stores scoped to the folders they are enabled on.

Folder credentials » Allow custom Application Ids

If selected, the per-folder credentials stores can specify a custom CyberArk Application Id to use when resolving credentials for that folder’s store.

Folder credentials » Allow custom folders

If selected, the per-folder credentials stores can specify a CyberArk Folder other than Root for any defined Safe:Folder pairs bound to that Jenkins folder.

store global configuration
Figure 7. CyberArk Credential Provider store configuration options

Per-folder Credentials Configuration

If the Jenkins  Manage Jenkins  Configure Credentials  CyberArk Credential Provider  Folder credentials  Enabled has been selected then users with the CyberArk Credentials/Configure permission will be able to configure the per-folder CyberArk credentials store.

empty folder configuration
Figure 8. Per-folder CyberArk Credential Provider store disabled

To enable the CyberArk credentials store for a specific folder, navigate to that folder and then select the Configure screen.

The Jenkins  Manage Jenkins  Configure Credentials  CyberArk Credential Provider  Folder credentials  Allow custom Application Ids and the Jenkins  Manage Jenkins  Configure Credentials  CyberArk Credential Provider  Folder credentials  Allow custom folders settings control the available configuration options.

populated folder basic configuration
Figure 9. Per-folder CyberArk Credential Provider store enabled (Jenkins  Manage Jenkins  Configure Credentials  CyberArk Credential Provider  Folder credentials  Allow custom Application Ids and Jenkins  Manage Jenkins  Configure Credentials  CyberArk Credential Provider  Folder credentials  Allow custom folders disabled)
populated folder detailed configuration
Figure 10. Per-folder CyberArk Credential Provider store enabled (Jenkins  Manage Jenkins  Configure Credentials  CyberArk Credential Provider  Folder credentials  Allow custom Application Ids and Jenkins  Manage Jenkins  Configure Credentials  CyberArk Credential Provider  Folder credentials  Allow custom folders enabled)

If Jenkins  Manage Jenkins  Configure Credentials  CyberArk Credential Provider  Folder credentials  Allow custom Application Ids is enabled then each Jenkins folder will have the option to override the default Application Id.

In all cases you can provide the CyberArk Safe:Folder pairs to consult (in order) when resolving credentials exposed by the global credentials store.

If Jenkins  Manage Jenkins  Configure Credentials  CyberArk Credential Provider  Folder credentials  Allow custom folders is enabled then there is the option to override the default CyberArk Folder from Root to some other folder within the CyberArk Safe.

Note
The CyberArk Folder uses \ as a path separator.

Managing CyberArk Credential Stores

This section will cover the following tasks:

  • Exposing CyberArk credentials to jobs

  • Removing CyberArk credentials that no longer exist

Exposing CyberArk credentials

Before you can expose credentials from CyberArk to jobs in Jenkins you need to know the CyberArk Object Id of the credential you want to expose and the context within Jenkins where the credential is to be made available.

In the CyberArk PrivateArk Microsoft Windows native client, this will be the object name (PrivateArk Microsoft Windows Native client screenshot of the Password Object dialog for a password object with Object Id deploy-key).

privateark client
Figure 11. PrivateArk Microsoft Windows Native client screenshot of the Password Object dialog for a password object with Object Id deploy-key

In the CyberArk Privileged Identity Management Web client this can either be inferred from the object path or the name. If the object path in the Safe is Root\deploy-key then the Object Id is deploy-key. Similarly the Account details screen will also show the Name:. See Privileged Identity Management Web client screenshot of the Account details dialog for a password object with Object Id deploy-key

pim client
Figure 12. Privileged Identity Management Web client screenshot of the Account details dialog for a password object with Object Id deploy-key

There are two classes of context within Jenkins where the credential can be exposed:

  1. The Jenkins root object itself

  2. A folder within Jenkins

Note
Credential scope

When exposing a credentials from the Jenkins root object, you will also need to decide what scope to give the exposed credentials.

  • Using the SYSTEM scope will allow the credentials to be used for launching Jenkins agents as well as for some secondary system wide processes configured through the Jenkins  Manage Jenkins  Configure Jenkins screen. The credential will not be available to jobs within Jenkins.

  • Using the GLOBAL scope will, in addition to the usage permitted by SYSTEM scope, will make the credential available to all jobs within Jenkins running as an authentication that has the Credentials/UseItem permission.

Understanding the Authorize Project Plugin and Credentials

Jenkins associates an authentication with all internal operations.

When a user makes a request from the web browser or from the Jenkins CLI, that request is tagged with the user’s authentication and permission checks will restrict the scope of that request to the user’s permissions.

The internal operations of Jenkins typically run with the authentication of SYSTEM which is the most powerful authentication and has all permissions.

For simple build jobs, this is typically not an issue. More complex build jobs can involve bi-directional control between Jenkins and the build job. If the build job has the ability to control Jenkins itself, then the authentication that the build job is running as within Jenkins becomes important.

The Authorize Project plugin was developed to allow jobs to run with a lesser authentication.

In a Jenkins instance without the Authorize Project plugin (or an alternative plugin providing a Queue item authenticator) the Jenkins  Manage Jenkins  Configure Global Security screen will not show any Access control for builds options

global config no authorize project
Figure 13. The Configure Global Security screen without any Queue item authenticator plugins installed

Once at least one Queue item authenticator is installed in the Jenkins instance, then the configuration options will be displayed.

global config authorize project
Figure 14. The Configure Global Security screen with at least one Queue item authenticator plugins installed

The Access Control for Builds section is an ordered list of Queue item authenticator. The first one that declares an interest in providing authentication for the build job will determine the authentication that the build job will run as.

global config authorize project config
Figure 15. The Configure Global Security screen adding the Authorize Project plugin's Queue item authenticator

To actually use the Authorize Project plugin you also need to enable it for the specific build job.

job config authorize project
Figure 16. Configuring a job to use the Authorize Project plugin

Once you switch jobs from running as SYSTEM you will encounter a feature of the Credentials API, namely that credentials are only exposed to specific authentications.

There is a permission within the Credentials plugin known as Credentials/UseItem. In order for an authentication to be able to resolve a credentials in either the root scoped store or a folder scoped store, that authentication must have the Credentials/UseItem permission.

By default the Credentials/UseItem permission is hidden and users receive this permission through implication by the Job/Configure permission. A Jenkins administrator can make the permission visible by defining the com.cloudbees.plugins.credentials.UseItemPermission system property with the value of true, e.g. by adding -Dcom.cloudbees.plugins.credentials.UseItemPermission=true to the Jenkins JVM start-up options.

The combination of the two of these features with the CloudBees RBAC plugin and nesting of folders should enable the ability to restrict jobs to only access those credentials that they should have access to.

Using the Web User Interface

Navigate to the Credentials view for the context within which the CyberArk credentials will be exposed.

add flow credentials view
Figure 17. The Credentials view for the Jenkins root context
add flow credentials view folder
Figure 18. The Credentials view for a folder context within Jenkins

Next you need to add a credential into the CyberArk store associated with the context. There are two ways to add the credential.

add flow shortcut
Figure 19. The shortcut for adding credentials to the (global) domain of the Jenkins context’s CyberArk credentials store
add flow shortcut folder
Figure 20. The shortcut for adding credentials to the (global) domain of a folder context’s CyberArk credentials store

The other way is to navigate the left-hand menu sub-items of the Credentials view. First select the CyberArk sub-item.

add flow cyberark store
Figure 21. A CyberArk credentials store (in this case scoped to the Jenkins root context)

Next select the (global) credential domain.

Note
The CloudBees CyberArk Credential Provider only supports the (global) domain.
add flow cyberark domain selection
Figure 22. The (global) credentials domain in a CyberArk credentials store.

Finally select the Add Credentials action.

Irrespective of which path to the Add Credentials screen you choose, you now need to enter the CyberArk Object Id as the credentials ID.

add flow create credentials
Figure 23. Adding CyberArk Username Password credentials to a CyberArk credentials store.

The CyberArk API used to get the details of the credential is deliberately obtuse in reporting errors.

add flow does not exist
Figure 24. Form validation showing the credential as not visible to Jenkins

The same / similar error messages are returned in all of the following cases:

  • The Object Id does not exist

  • The Folder within the Safe does not exist

  • The Safe within the Vault does not exist

  • The Application Id used by Jenkins does not have permission to access the Object

  • The Application Id used by Jenkins does not have permission to access the Safe

  • The Application Id used by the CyberArk Central Credential Provider Web Service does not have permission to access the Object

  • The Application Id used by the CyberArk Central Credential Provider Web Service does not have permission to access the Safe

  • The Application Id used by the CyberArk Central Credential Provider does not have permission to access the Object

  • The Application Id used by the CyberArk Central Credential Provider does not have permission to access the Safe

You may optionally provide a description which can be helpful to disambiguate similar credentials in the Credentials drop down selector fields when configuring jobs.

add flow populated credentials
Figure 25. The Object Id populated and the form validation confirming the username of the resolved Object.

Once the credential has been added, it should be visible on the Credentials view for the context object that the credential was added to.

add flow credentials view final
Figure 26. The Object defined in the CyberArk credentials store.

The in-place Add functionality is also available for adding credentials.

add flow in place
Figure 27. The Add menu for a Credentials drop-down field showing the credential stores in scope for the job. The enabled stores will be restricted to those stores that the current user has permission to add credentials to.
Using the Jenkins Command Line Interface

The create-credentials-by-xml Jenkins CLI command is the command used to expose CyberArk credentials.

add flow cli command
Figure 28. The Jenkins CLI command for adding credentials to a credentials store.

Before we can use this CLI command we need to determine the Store Id and Domain.

The domain will always be "_" because the CyberArk credentials store only supports the global domain.

The Store Id consists of three components separated by the ::. The components are provider :: resolver :: context path. In the case of the CloudBees CyberArk Credential Provider there are only two choices, but it is probably helpful to illustrate the general process:

  1. List the credentials providers:

    Listing the credentials providers
    $ java -jar jenkins-cli.jar -s http://local.example.com/ \
    list-credentials-providers
    Name                                                                           Provider
    ============================================================================== ==============================
    CyberArkCredentialsProvider                                                    Cyber Ark Credentials Provider
    FolderCredentialsProvider                                                      Folder Credentials Provider
    SystemCredentialsProvider                                                      Jenkins Credentials Provider
    UserCredentialsProvider                                                        User Credentials Provider
    com.cloudbees.hudson.plugins.folder.properties.FolderCredentialsProvider       Folder Credentials Provider
    com.cloudbees.jenkins.plugins.cyberark.credentials.CyberArkCredentialsProvider Cyber Ark Credentials Provider
    com.cloudbees.plugins.credentials.SystemCredentialsProvider$ProviderImpl       Jenkins Credentials Provider
    com.cloudbees.plugins.credentials.UserCredentialsProvider                      User Credentials Provider
    cyberark                                                                       Cyber Ark Credentials Provider
    folder                                                                         Folder Credentials Provider
    system                                                                         Jenkins Credentials Provider
    user                                                                           User Credentials Provider

    The CloudBees CyberArk Credential Provider is exposed using three different names (the names are derived by code and simplifications are only exposed if there are no conflicting credentials provider implementations). The most specific provider identifier is com.cloudbees.jenkins.plugins.cyberark.credentials.CyberArkCredentialsProvider but in the above instance we also have availble the short form cyberark.

  2. List the context resolvers

    Listing the context resolvers
    $ java -jar jenkins-cli.jar -s http://local.example.com/ \
    list-credentials-context-resolvers
    Name                                                                            Resolves
    =============================================================================== =======
    ItemContextResolver                                                             Items
    SystemContextResolver                                                           Jenkins
    UserContextResolver                                                             Users
    com.cloudbees.plugins.credentials.CredentialsSelectHelper$ItemContextResolver   Items
    com.cloudbees.plugins.credentials.CredentialsSelectHelper$SystemContextResolver Jenkins
    com.cloudbees.plugins.credentials.CredentialsSelectHelper$UserContextResolver   Users
    item                                                                            Items
    system                                                                          Jenkins
    user                                                                            Users

    The CloudBees CyberArk Credential Provider only provides implementations of the credentials store for the root context and for folders (which are items). The context resolvers that we want are either com.cloudbees.plugins.credentials.CredentialsSelectHelper$SystemContextResolver (which has the short alias of system) or com.cloudbees.plugins.credentials.CredentialsSelectHelper$ItemContextResolver (which has the short alias of item)

  3. Specify the context path

    • For the system context resolver, this is always the fixed value jenkins.

    • For the item context resolver, this is the full name of the item (folder). The full name is normally the names separated by '/' characters. The full name is not the URL of the job as that includes /job/ in the URL. For example a folder with the URL http://local.example.com/jenkins/job/example-folder/job/example-sub-folder/ would have the full name /example-folder/example-sub-folder

      Note

      The config.xml of that folder would - by default - be stored in $JENKINS_HOME/jobs/example-folder/jobs/example-sub-folder.

      The breadcrumb bar, if the display name has been customized for these folders might look like Jenkins » Example Folder » Example Sub-Folder)

So the two possible Store Id variants are:

  • cyberark::system::jenkins for the root credentials store

  • cyberark::item::/full/name/of/folder

Next we need to create the XML representation of the credential we want to expose. The following is the template to use for the XML representation.

XML template of CyberArk Username Password credentials
<com.cloudbees.jenkins.plugins.cyberark.credentials.CyberArkUsernamePasswordCredential>
  <id><!-- Insert Object Id here--></id>
  <description><!-- Insert Description here if you want --></description>
</com.cloudbees.jenkins.plugins.cyberark.credentials.CyberArkUsernamePasswordCredential>
Example of exposing the deploy-key credential in the /example-folder folder.
$ cat > credential.xml <<EOF
<com.cloudbees.jenkins.plugins.cyberark.credentials.CyberArkUsernamePasswordCredential>
 <id>deploy-key</id>
</com.cloudbees.jenkins.plugins.cyberark.credentials.CyberArkUsernamePasswordCredential>
EOF
$ java -jar jenkins-cli.jar -s http://local.example.com/ \
create-credentials-by-xml cyberark::item::/example-folder  _ < credential.xml
$ java -jar jenkins-cli.jar -s http://local.example.com/ \
list-credentials cyberark::item::/example-folder
========================
Domain           (global)
Description
# of Credentials 1
========================
Id               Name
================ =======
deploy-key       /******
========================
Using the Jenkins REST Interface

To use the REST interface, you need to make a POST request to the createCredentials sub-URL of the credentials domain. For example, for the folder example-folder in a Jenkins instance hosted at http://local.example.com/ this would be the URL http://local.example.com/job/example-folder/credentials/store/cyber-ark/domain/_/createCredentials

Example of exposing the deploy-key credential in the /example-folder folder.
$ cat > credential.xml <<EOF
<com.cloudbees.jenkins.plugins.cyberark.credentials.CyberArkUsernamePasswordCredential>
 <id>deploy-key</id>
</com.cloudbees.jenkins.plugins.cyberark.credentials.CyberArkUsernamePasswordCredential>
EOF
$ curl -X POST -H content-type:application/xml -d @credential.xml \
http://local.example.com/job/example-folder/credentials/store/cyber-ark/\
domain/_/createCredentials
Note
If your Jenkins instance has CSRF protection enabled or uses authentication then you will need to provide the required headers to the REST request. Details of the exact headers required depends on the CSRF protection that has been configured and the exact authentication mechanism being used.
Removing CyberArk credentials that no longer exist

If the backing credentials are removed from CyberArk, you will need to remove the corresponding credential definition from the credentials store in Jenkins.

Using the Web User Interface

Navigate to the Credentials view for the context containing the the CyberArk credentials to be removed.

There are two ways to remove the credential:

  • Use the context menu for the credential and select Delete

    del flow shortcut
    Figure 29. Using the context menu for removing a credentials from a credentials store.
  • Navigate to the credential and select the Delete left hand menu action.

    del flow long way
    Figure 30. Using the credential’s Delete action directly.
Using the Jenkins Command Line Interface

The delete-credentials Jenkins CLI command is the command used to remove CyberArk credentials.

del flow cli command
Figure 31. The Jenkins CLI command for removing credentials drom a credentials store.
Example of removing the deploy-key credential from the /example-folder folder.
$ java -jar jenkins-cli.jar -s http://local.example.com/ \
delete-credentials cyberark::item::/example-folder  _ deploy-key
$ java -jar jenkins-cli.jar -s http://local.example.com/ \
list-credentials cyberark::item::/example-folder
========================
Domain           (global)
Description
# of Credentials 0
========================
Id               Name
================ =======
========================
Using the Jenkins REST Interface

To use the REST interface, you need to make a DELETE request to the config.xml sub-URL of the credentials. For example, for the deploy-key credential in the folder example-folder in a Jenkins instance hosted at http://local.example.com/ this would be the URL http://local.example.com/job/example-folder/credentials/store/cyber-ark/domain/_/credential/deploy-key/config.xml

Example of removing the deploy-key credential from the /example-folder folder.
$ curl -X DELETE  http://local.example.com/job/example-folder/credentials/\
store/cyber-ark/domain/_/credential/deploy-key/config.xml
Note
If your Jenkins instance has CSRF protection enabled or uses authentication then you will need to provide the required headers to the REST request. Details of the exact headers required depends on the CSRF protection that has been configured and the exact authentication mechanism being used.

Enabling advanced use cases: cross-master triggers and bulk operations

For some advanced use-cases, administrators will need to further tweak the cluster’s security configurations to ensure connected masters have the correct permissions for those use cases.

Configuring permissions for cross-master triggers

If all masters in the CloudBees Jenkins Enterprise cluster will be Managed Masters and there are teams who will need the ability to promote artifacts and trigger jobs on other teams’ masters, administrators should also configure the CloudBees Jenkins Enterprise cluster’s Authentication Mapping to Trusted master with equivalent security realm .

This will grant Anonymous users permissions to view a team’s master and job configurations. These permissions will be used by a master in the CloudBees Jenkins Enterprise cluster to discover any downstream jobs on another team’s that it needs to trigger - e.g. a developer team’s master handing off an artifact to the QA team’s master for testing.

Operations Center acts as a gateway between each of the connected masters, so a request from one connected master to another will first be routed through Operations Center. Each request will be tagged with the authentication that originated the request.

Defining this default authentication mapping strategy standardizes client masters’ level of trust or authentication/authorization strategies and enables the cross-master communication necessary for teams to trigger jobs across their masters.

Caution
Changing the authentication mapping strategy

For security reasons, the authentication mapping cannot be updated while masters are connected to CloudBees Jenkins Enterprise.

After changing the authentication mapping, the connected masters must be reconnected to Operations Center because the authentication mapping is installed on connection to Operations Center’s remoting channel.

Configuring permissions for bulk management operations in CloudBees Jenkins Enterprise

Administrators who anticipate performing bulk maintenance operations against their cluster’s masters and update centers will need to grant the Ad-hoc cluster operations authenticator access control for builds within the Operations Center Global Security Configuration. This option captures which user is performing an ad-hoc cluster operation in Operations Center and will run that operation with that user’s permissions.

Restricting access and delegating administration with Role-Based Access Control in CloudBees Jenkins Enterprise

Administrators with a CloudBees Jenkins Enterprise cluster supporting multiple teams of users can delegate some management powers to team leads and limit the permissions that unauthenticated and other users have to make changes and view items in the cluster. Delegating the assignment of such permissions to project administrators allows teams to define more granular permissions for specific projects and objects within their master, enabling them to do things like hiding a "secret" project from other teams.

These fine-grained permissions are enabled through the Role-Based Access Control (RBAC) Authorization Strategy defined by an administrator in the Operations Center Global Security Configuration.

Administrators will need to define various security roles for use in their cluster and assign those roles to groups of users, including groups and users imported from an authentication server like LDAP.

To illustrate this use case, consider the following scenario where an administrator has two configured client masters with some Folders configured for projects:

  • Master-1

    • developers-team-A-folder (Working folder for developers-team-A-group)

    • another-folder (accessible by everyone)

  • Master-2

The administrator in this scenario will support four different teams with their CloudBees Jenkins Enterprise cluster. Each team will only need access and permissions over a very limited set of items within the context of the CloudBees Jenkins Enterprise cluster, specifically:

  • Developers team A - Within CloudBees Jenkins Enterprise, this group will be called internal-developers-team-A-group. They should only have read access to the Operations Center instance and only be able to access to Master-1. In Master-1, these users should only see the folder developers-team-A-folder.

  • Developers team B - Within CloudBees Jenkins Enterprise, this group will be called internal-developers-team-B-group. They should only have read access to the Operations Center instance and should only be able to access to Master-2.

  • Tester team - Within CloudBees Jenkins Enterprise, this group will be called internal-tester-team-group. They should only have read access to the Operations Center instance and should be able to access to Master-1 and Master-2.

  • Admin team - Within CloudBees Jenkins Enterprise, this group will be called internal-admin-team-group. They should be able to administer the Operations Center and client masters systems.

There are at least two levels of permissions for an administrator to consider when configuring permissions - permissions over the cluster itself (Operations Center-level) and permissions over particular masters, the administrator will first need to log into Operations Center and creates roles and groups.

Roles are sets of configured permissions that can be assigned to groups, and they are configured from the "Roles" > "Manage Roles" configuration page.

oc rbac img 001
Figure 32. Manage Roles

Out of the box, Operations Center offers two options - anonymous and authenticated. For this scenario, administrators will want to create 3 new roles in Operations Center with the following permissions:

Table 1. Sample roles for a CloudBees Jenkins Enterprise cluster
Role Permissions

read_role

  • Overall | Read

  • Job | Read

admin_role

  • Overall | Administer

developer_role

  • Overall | Read

  • Job | Read

  • Job | Configure

  • Job | Build

Setting up Operations Center-level access controls

In this scenario, the administrator wants to delegate administer permissions, so the internal-oc-admin-group will be assigned the default pre-configured admin_role. All users in that group will be able to perform cluster management functions in Operations Center, so membership for this group should be limited to only the Admin team in this example organization. This configuration is propagated to all connected masters, so Operations Center-level admins will also have administer permissions over those masters.

For non-admin teams, the administrator will want to prevent them from changing any configurations to the cluster in {OC}, and so the administrator will need to create another group - internal-oc-read-group - and assign to that group the pre-configured read_role. Developer teams and Tester team belong in this group, as they will have limited interactions with Operations Center and therefore do not need any permissions above read access at the Operations Center-level.

oc rbac img 002

Groups can be created and configured from the "Groups" item in the left-hand menu. Once a group has been added, administrators will be able to assign roles and users to the group.

Table 2. Sample Operations Center-level groups
Context Group Role(s) Member(s)

ROOT

internal-oc-admin-group

  • admin_role (current level/propagation)

All the administrator(s) of the Operations Center instance

ROOT

internal-oc-read-group

  • read_role

  • developers-team-A-group

  • developers-team-B-group

  • tester-team-group

oc rbac img 004

Once the administrator has added themselves to a group with the admin_role, the administrator should disable the default roles of authenticated and anonymous. The *authenticated permission includes overall administration permissions and is no longer necessary once a formal admin role exists and is assigned to an administration group.

Setting up access controls on connected masters

In this scenario, the administrator wants to limit the Developer teams’ access to only their team’s master while giving the Tester team access to both. This configuration protects teams from unauthorized users accessing their credentials and artifacts while still empowering a trusted team to access only the resources they need. Within the master itself, administrators can also set up specific permissions to restrict access on certain objects, such as a folder containing a "secret" internal project.

In this scenario, the administrator will configure permissions on two folders that exist on Master-1 - the developers-team-A-folder, which will be restricted to only the developers-team-A-group as a "secret project", and another-folder, which will be accessible by everyone logged into the instance.

oc rbac img 010

To achieve this, the administrator will configure the following groups and roles on the following masters:

Table 3. Sample master-level groups
Context Group Role(s) Member(s)

ROOT

internal-oc-read-group

  • read_role

  • developers-team-A-group

  • developers-team-B-group

  • tester-team-group

Master-1

  • internal-developers-team-A-group

  • read_role (current level/no propagation)

  • developers-team-A-group

Master-1

  • internal-master-1-group

  • developer_role (current level/propagation)

  • read_role (current level/no propagation)

  • tester-team-group

Master-1/developers-team-A-folder

  • internal-developers-team-A-group

  • developer_role (current level/propagation)

  • developers-team-A-group

  • tester-team-group

Master-2

  • internal-master-2-group

  • developer_role (current level/propagation)

  • developers-team-B-group

  • tester-team-group

Once these settings are configured any member of the internal-developer-team-A-group who logs into Operations Center will only be able to access to the Master-1/developers-team-A-folder.

Folders Plus

Folders Plus provides additional capabilities not available in open source Folders, including the ability to:

  • restrict the use of agents to specific folders

  • move jobs (or subfolders) from one folder to another (or to or from the root of Jenkins)

  • get additional health reports for jobs within a folder

  • set custom icons on a folder

  • define environment variables that will be passed to the builds of all jobs within a folder

  • display selected jobs from subfolders in a higher-level view

  • restrict which kinds of items may be created in a folder

Controlled agents

Folders Plus controlled agents can restrict the jobs that may execute on an agent.

By default, jobs may be assigned to any labeled agent. This can be a problem when specific agents contain secrets or are intentionally task-specific.

Consider the case of a Jenkins instance shared by an operations group and multiple developer groups. The operations group has specific credentials and tools that deploy the company website into production. The operations group has configured a dedicated agent with those credentials and tools. The agent is configured to only accept jobs assigned to that specific agent. However, without Folders Plus, a developer could configure a job to run on the operations agent and copy the credentials or the tools.

Folders Plus controlled agents allow the operations group to limit their task-specific agent to jobs from specific folders.

Configuring controlled agents

The first step is to configure the agent to only accept jobs from within approved folders. Agents configured to only accept jobs from within approved folders will refuse to build jobs outside those folders.

Open the configure screen of the agent (Enabling approved folders functionality on an agent) and select the Only accept builds from approved folders option.

enable approved folders
Figure 33. Enabling approved folders functionality on an agent

After saving the configuration you should see a screen like that in An agent with approved folders functionality enabled and no approved folders assigned

approved folders enabled
Figure 34. An agent with approved folders functionality enabled and no approved folders assigned

At this point the person with permissions to configure the folder needs to create a request for a controlled agent. They need to open the folder in Jenkins (Creating a controlled agent request - step 1) and select the Controlled Slaves action.

approving a folder step 1
Figure 35. Creating a controlled agent request - step 1

This will display the list of controlled agents assigned to the folder (Creating a controlled agent request - step 2). We want to add a new controlled agent so select the Create request action. Confirm the request creation (Creating a controlled agent request - step 3) and the Request Key should be generated and displayed (Creating a controlled agent request - step 4). The request key needs to be given to the person with permissions to configure the controlled agent.

approving a folder step 2
Figure 36. Creating a controlled agent request - step 2
approving a folder step 3
Figure 37. Creating a controlled agent request - step 3
approving a folder step 4
Figure 38. Creating a controlled agent request - step 4

At this point the person with permissions to configure the agent needs to approve the request. They need to select the Approved Folders action from the agent (An agent’s approved folders screen) and select the Controlled Slaves action.

approving a folder step 5
Figure 39. An agent’s approved folders screen
Note

The Approved Folders screen allows for multiple tokens to be issued, a token can be used to sign multiple requests, and it is left to the administrator of the agent to decide whether they want to create a new token or use an existing token.

Creating a new token for each agent has the advantage that each approved folder can be revoked individually. Conversely, re-using an existing token allows for bulk revocation of folders.

If there are no existing tokens for approving controlled agent requests you will need to create a new token by selecting the Create token action and confirming the creation (Creating a token for approving requests) otherwise the authorize button on any existing token can be used to authorize a request using that token. Either route should display the Authorize Request screen (Approving a controlled agent request).

approving a folder step 6
Figure 40. Creating a token for approving requests
approving a folder step 7
Figure 41. Approving a controlled agent request

Enter the Request Key and press the Authorize button. The Request Secret should be generated and displayed (An approved request for a controlled agent). The request key needs to be given to the person with permissions to configure the folder.

approving a folder step 8
Figure 42. An approved request for a controlled agent

At this point the person with permissions to configure the folder needs to return to the request screen and enter the Request Secret provided by the person responsible for configuring the agent. (Completing a controlled agent request) and click the Authorize button.

approving a folder step 9
Figure 43. Completing a controlled agent request

Once the controlled agent request has been completed, the controlled agent should appear in the list of agents (A folder with an approved agent) and the folder should appear on the agent (An agent with an approved folder)

Note

If the person viewing the agent does not have permissions to view the folder, they will not see the folder name when viewing the agent’s status screen or list of approved folders. In this case an additional indicator will be provided detailing the number of "hidden" folders in addition to those that the user is permitted to see.

folder with controlled slave
Figure 44. A folder with an approved agent
slave with approved folder
Figure 45. An agent with an approved folder

Troubleshooting

Issues with third-party plugins

In order to enforce that only jobs belonging to approved folders can be built on a controlled agent it is necessary to identify the job that owns any build submitted to the build queue of Jenkins. Once the job has been identified, the folder hierarchy can be traversed to see if any parent folder is on the list of approved folders.

Once of the extension points that Jenkins provides is the ability to define custom build types that can be submitted to the build queue. When a plugin author is developing such a plugin, they should ensure that the owning build type hierarchy eventually resolves to the build job to which the task belongs whenever a custom build type is associated with a build job.

In the event that a third-party plugin author has not correctly ensured that their custom build type is correctly associated with its originating job, the controlled agents functionality will be unable to identify the originating job, and consequently will refuse to let the job build on the controlled agent.

If it is critical to enable the third-party plugin to build on the agent, and the administrator accepts the risk of allowing other custom build types to run on the controlled agent, there is an advanced option that can be enabled on a per-agent basis.

Issues with builds being blocked forever

There are multiple reasons why Jenkins can block a build from executing. The controlled agent functionality adds an additional reason, however, it should be noted that when Jenkins evaluates a job for building, once it has identified a reason why the job cannot be started, it does not evaluate any of the other reasons. Therefore when Jenkins reports the reason as to why the build is blocked, it will only report the first reason it encountered. In such cases, the user may not realize that the reason for the build being blocked is because it is not within an approved folder.

Jenkins does not re-evaluate whether builds are still blocked until an event causes a probability of jobs being executed. Such events include, but are not limited to

  • A job being added to the build queue

  • A job being removed from the build queue

  • A job completing execution

  • A node coming on-line

  • A node going off-line

If a job is submitted to the build queue and is blocked because it is not in an approved folder, it will not be re-considered for execution until one of the re-evaluation triggers occurs. Therefore, even if the folder containing the job is added to the list of approved folders, existing blocked builds will not become unblocked until a queue re-evaluation trigger is fired.

Other features

There are other smaller features available in Folders Plus.

Moving

You can use the Move action to move a job, or entire subfolder, from one location to another. The configuration, build records, and so on will be physically relocated on disk.

Beware that many kinds of configuration in Jenkins refer to jobs by their relative or full path. If you move a job to a different folder, you may also need to update configuration that was referring to that job.

Health reports

The base Folders plugin has a simple way of displaying a health report next to a folder in the dashboard: it simply indicates the worst status (such as failing) of any job in the folder. Folders Plus offers some alternate metrics:

  • the average health of jobs within the folder

  • whether some jobs are disabled

  • counts of jobs with different statuses, such as stable or unstable

Icons

Normally folders all have a fixed "folder" icon. Folders Plus allows you to customize this with other kinds of icons:

  • a blue, yellow, or red ball corresponding to the most broken job in the folder

  • a variety of icons packaged with Jenkins, such as that for a "package"

  • any icon you like, if you provide a URL

Environment variables

You may configure an Environment variables property on a folder giving a list of variable names and values. These will be accessible as environment variables during builds. This is a good way to define common configuration to be used by a lot of jobs, such as SCM repository locations.

Newer versions of Jenkins also allow these variables to be used during SCM polling or other contexts outside of builds.

List view column

The Pull information from nested job list view column may be selected when configuring a view on a folder or at top level in Jenkins. This column allows you to display some aspect of a job (available as another kind of list view column) for every subfolder being displayed.

For example, you might have a dozen folders corresponding to different products, each containing several jobs with predictable names: build, release, and so on. You can create a view at the Jenkins root which contains all these folders as entries. Then add this kind of list view column, specifying the job name build and the standard Status list view column. Now your custom view will display all of the product folders, and for each will show a blue, yellow, or red ball corresponding to the current status of the build job in that folder.

Restricting children

The Folders Plus plugin allows you to specify the types of jobs that a particular folder allows. To choose the specific job types that the folder can allow, enable Restrict the kind of children in this folder as shown in Specifying parameter types for Folders.

folder options
Figure 46. Specifying parameter types for Folders

Nodes Plus Plugin

The Nodes Plus plugin provides additional functionality for managing Jenkins build agents (nodes), including:

  • Assign owners to agents

  • Notify owners when agent availability changes

Agent owners

In a Jenkins instance that is shared by a large team (or a number of teams) there can often be a pattern whereby certain individuals are responsible for certain specific build agents. If the build agent goes off-line and fails to come back on-line then builds which are tied to that build agent can end up stuck in the build queue. Most Jenkins users, eventually settle on filtering out the e-mail notification that is associated with a successful build (either by configuring the build only to email when the build fails, or by setting up rules in their mail client). Thus if a specific project’s builds are stuck in the build queue, nobody may notice until they actually browse the Jenkins instance in their web browser.

The Node Owners property introduced by the Nodes Plus plugin provides an e-mail notification to the designated owners based on a configurable set of availability triggers

Note

In some cases Jenkins can take a number of minutes to confirm that an agent is off-line. E-mail notifications are only sent after Jenkins has confirmed that the agent is off-line, which may involve waiting for socket connections to time-out.

Configuring owners

On the agent configuration screen enable the Node owners checkbox in the Node Properties section. The configuration options should then be visible.

node owners property
Figure 47. Configuring the agent owners

Enter the list of people who should receive e-mails when the agent availability changes in the Owner(s) input box. E-mail addresses should be separated by whitespace or blank lines or ,.

Send email when connected

This trigger fires when the communication channel has been established with the agent. If the agent has been marked as Temporarily off-line then no build jobs will be accepted by the agent. + NOTE: This trigger will only fire on transition from disconnected to connected.

Send email when disconnected

This trigger fires when the communication channel with the agent has been confirmed dead. Where an agent is configured to be kept on-line as much as possible Jenkins will immediately try to reconnect the agent, and so in such cases the email from this trigger will be immediately followed by either the launch failure or successful connection email. As such this trigger is typically most useful where one of the other availability strategies has been selected for the agent. + NOTE: This trigger will only fire on transition from connected to disconnected.

Send email on launch failure

This trigger fires when an attempt to establish a communication channel with the agent fails. + NOTE: This trigger will fire each and every time a connection attempt fails.

Send email when temporary off-line mark applied

This trigger fires when the agent is marked as temporarily off-line. + NOTE: This trigger will fire within the first 5 seconds of the agent being marked off-line.

Send email when temporary off-line mark removed

This trigger fires when the agent mark of being temporarily off-line has been removed from the agent. + NOTE: This trigger will fire within the first 5 seconds of the agent ceasing to be marked off-line.

Save the agent configuration to apply the changes.

Wikitext Security Plugin

The WikiText Security plugin addresses security concerns that arise from permitting arbitrary HTML in description fields in Jenkins. The plugin allows you to enter descriptions in one of multiple wiki markup languages.

Jenkins lets users enter description fields in HTML as shown in Setting up project-specific descriptions. For some teams that are concerned about XSS attacks via the description fields, or have policy preferences towards writing wiki over HTML, this CloudBees Jenkins Enterprise plugin allows you to use one of several well-known wiki markup formats in place of HTML.

wikitext description
Figure 48. Setting up project-specific descriptions

Supported Wiki Markup Languages

The WikiText Security plugin supports the following wiki markup languages today:

Configuration

Select the desired wiki language by going "Manage Jenkins" and "Configure Global Security". Under "Markup Formatter" are the supported wiki languages.

wikitext configuration

Using the Wikitext Security plugin

Once the plugin is installed and configured, click the "add description" link on a particular project and enter the description in the preferred wiki markup language. In Wikitext Usage, we have used the wiki markup to render the description in bold. Wikitext Output shows the corresponding output.

wikitext usage
Figure 49. Wikitext Usage
wikitext output
Figure 50. Wikitext Output

Security Warnings

The Security Warnings Administrative Monitor shows all published security warnings affecting your current installation. These warnings can apply to the product core itself or to any installed plugins. The Security Warnings Administrative Monitor will recommend an update path for you to follow to make your installation secure.

  • If the warning is related to the product core, Beekeeper will suggest to update the instance to mitigate the problem.

  • If the warning is affecting a plugin inside CAP, Beekeeper will also suggest to update to a newer version.

  • If the warning concerns a compatible plugin, Beekeeper will suggest updating that plugin to the version that fixes the problem.

Security Warnings Administrative Monitor

Whenever Beekeeper detects that there is a security warning, the Security Warnings Administrative Monitor will give you the following information:

Administrative Monitor number
Figure 51. Security Warnings Administrative Monitor. Number of messages

When you click the number, it shows you the message:

administrative monitor message
Figure 52. Security Warnings Administrative Monitor. Messages

The More Info button takes you to the Security Warnings page of Beekeeper Upgrade Assistant.

Beekeeper Upgrade Assistant

In the main page of Beekeeper Upgrade Assistant you can see the same message as in the Security Warnings Administrative Monitor:

beekeeper upgrade assistant title
beekeeper upgrade assistant sw message
Figure 53. Beekeeper Upgrade Assistant

Security Warnings page

There are several ways to reach the Security Warnings page: you can click on the More Info button on the administrative monitor or on the Beekeeper Upgrade Assistant page; or you can click the Security Warnings link on the side panel. On this page you can see all the warnings detected about your instance.

security warnings page
Figure 54. Security Warnings page

The Vulnerabilities column gives a short description of the security warning, and the link guides you to the published Security Advisory where you can find all of the information about the warning.

The link in the Recommendation column guides you to the release notes / changelog of the compatible plugin with the vulnerability. In case one or more vulnerabilities affect the plugin, the proposed version is the one that fixes all of them.

In case of vulnerabilities affecting CAP plugins or the core of the instance, it shows a link titled Click here to read the release notes for this version that will guide you to the release notes of the product. From here, you can navigate to the Security Advisory with the security warnings that have been fixed in that version.

security advisory
Figure 55. A Security Advisory

Disable the Security Warnings Administrative Monitor

As with any other administrative monitor, you can deactivate it and avoid showing every security warning detected. To do that, go to Jenkins  Manage Jenkins  Configure System  Administrative monitors configuration. Click on the Administrative monitors button and clear the Security Warnings Monitor check box.

disable sw monitor
Figure 56. Check to disable the Security Warnings Administrative Monitor

Auto deactivation of the Security Warnings Administrative monitor

If the instance cannot download updated information about security warnings after 24 hours, the Security Warnings Administrative Monitor will be deactivated automatically. After fixing the issue that prevented the updated information from being obtained as said before, you can reactivate it again in the Administrative monitors configuration as mentioned in the Disable the Security Warnings Administrative Monitor section.

Select security warnings to show

You can choose what type of security warnings the Security Warnings Administrative Monitor should advise you of. To do that, go to Jenkins  Manage Jenkins  Beekeeper Upgrade Assistant  CAP Configuration. Here you can choose whether or not the Administrative Monitor should notify you in the top menu when warnings related to the product core and / or installed plugins are detected. In any case, the Security Warnings page will show all the vulnerabilities.

cap configuration sw
Figure 57. CAP Configuration. Security Warnings checks

More detailed help information can be obtained by clicking on the ? icon.

cap configuration sw help
Figure 58. CAP Configuration. Help for Security Warnings check

Troubleshooting

The Security Warnings Administrative Monitor retrieves all the security information via HTTP/HTTPS connections, so the first point to check when something is wrong should be the network and the instance’s internet connectivity.

For proper operation, the administrative monitor needs to communicate to https://beekeeper-server.cloudbees.com/api/security-warnings and many elements can affect that communication. The log files will contain information to better diagnose the issue.

security warnings unable connect
Figure 59. Unable to connect to Beekeeper Server

When this message is displayed, the Security Warnings Administrative Monitor has detected some kind of error in the network configuration that is preventing the product from connecting to Beekeeper Server.

To diagnose the root cause, look into the log files the SECURITY-WARNING_ERROR: %s message, where %s is the error message. Besides, the points to check would be:

Whether the communication remains down, the Security Warnings Administrative Monitor will automatically deactivate itself.

security warnings network issues
Figure 60. Network issues happening

This message is displayed when similar circumstances to the stated in the previous message happen but the bad configuration issue is in the running instance itself. Once more, to diagnose the root cause, look into the log files the SECURITY-WARNING_ERROR: %s message, where %s is the error message. Besides, the points to check would be:

  • The Proxy Configuration is properly configured in Jenkins  Manage Jenkins  Manage Plugins  Advanced.

  • Same network configuration points than in previous error.

security warnings unexpected error
Figure 61. Unexpected error message

Whether the Security Warnings Administrative Monitor displays this error, the response retrieved from Beekeeper Server corresponds to a strange situation in the communication. In this case the points to check would be:

  • The error code in the response: Check in logs if the SECURITY-WARNING_ERROR: Beekeeper server is responding %d code message appears, where %d means the error code in response.

  • The existence of a trace in log file: Check in log file if the SECURITY-WARNING_ERROR: %s message is present, where %s is the error message.