The CyberArk Credential Provider enables additional credential stores for CloudBees CI 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 CloudBees CI sees the updated passwords from the CyberArk Application Identity Manager vault.
Prerequisites
The CloudBees CyberArk Credential Provider Plugin 1.0.5 release has the following software requirements:
-
CloudBees CI on modern cloud platforms and CloudBees CI on traditional platforms 2.222.1.1 (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.
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.
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 operations center and CloudBees CI.
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 CI service to have continued access to CyberArk credentials in the event that its connection to 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 CI and operations center is using the standard Jenkins remoting protocol used between CloudBees CI 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
localhostinterface, 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 controller, 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 controller, etc.
It is helpful to understand the credentials resolution process.
-
Credentials resolution on 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
CredentialProviderextensions 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.
Due to restrictions in the APIs exposed by CyberArk, it may be necessary for the CloudBees CyberArk Credential Provider to issue a
GetPasswordrequest against the credentials that are being returned. Such requests will be tagged as for a cache refresh.By default, 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 will always issue a
GetPasswordrequest to retrieve the password.The Cache Password option can be enabled to also include the password (encypted form) in the cache details. In that case, when the username and/or password are being accessed, the cached value will be used provided that cache is still current (per the Cache Refresh TTL settings).
-
When the Operations Center Client Plugin’s Credentials Provider is consulted, it will request the credentials exposed to CloudBees CI 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 CI 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.
-
|
It is recommended that the only CyberArk credentials defined in 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 CI CloudBees CyberArk Credential Provider stores. |
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) orhttp -
Authentication:
Client Certificates(recommended),None, orHTTP BASIC -
Validation of Web Service identity:
Explicitly supply certificate,None, orUse 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 CI?
-
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 CI?
-
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.
Configuring global credentials
To configure a CyberArk Credentials provider:
-
On the Dashboard, select Manage Jenkins on the left navigation pane. The Manage Jenkins page displays.
-
Under Security, select Configure Credential Providers. The Configure Credential Providers page displays.
Figure 3. Configure Credential Providers page -
Navigate to CyberArk Credential Provider and enter the following details:
Label Definition 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.
-
Select the Advanced button and complete the following advanced options:
Label Definition 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 Password
Whether or not to also cache the password (Jenkins encrypted). If disabled, only non-secret details of the
GetPasswordresponse will be cached and a request will always be made to Cyberark to retrieve the Password.Cache refresh TTL (time to live)
The number of minutes that the caching 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)
-
Configure the credentials stores by entering the following:
Figure 4. CyberArk Credential Provider store configuration optionsLabel Definition 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
Rootfor any defined Safe:Folder pairs bound to that Jenkins folder. -
Click Save.
Configuring per-folder credentials
If the Folder credentials settings were enabled on the Configure Credential Providers page (refer to CyberArk Credential Provider store configuration options), then users with the CyberArk Credentials/Configure permission can configure the per-folder CyberArk credentials store.
To configure the CyberArk credentials store for a specific folder:
-
On the Dashboard, select the desired folder. The page for that folder displays.
-
On the left navigation pane, select the Configure. The folder configuration page displays.
Figure 5. Folder configuration page -
Enter details about the credential store:
Label Definition Enabled
Select this option to enable a folder scoped credentials store backed by CyberArk for this specific folder. Credentials in this store will be available to all jobs in this folder and sub-folders.
Application Id - Use default
Select this option to allow overriding the default CyberArk Application ID that will be used to access the configured safes. In some CyberArk architectures it may be the case that the credentials that a folder should access are only available when using an Application Id that has been created specifically for each folder.
Id
The CyberArk Application ID that will be used to access the configured safes.
Safes
The CyberArk safes to search for credentials. The safes are searched in order (you can change the order using drag and drop). The first match wins in the case of duplicate Object Ids.
Custom folder
Select this option to specify a custom safe sub-folder. By default only credentials in the Root folder will be exposed. In some CyberArk architectures credentials may be categorized within the CyberArk safes using folders and therefore the folder to search may need to be specified.
Folder
The name of the CyberArk folder within the CyberArk safe. For most CyberArk architectures this will be the default value of
Root.The CyberArk Folder uses \as a path separator. -
Select Save.
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 (Password object dialog of PrivateArk Microsoft Windows native client).
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:. Refer to Privileged Identity Management web client.
There are two classes of context within Jenkins where the credential can be exposed:
-
The Jenkins root object itself
-
A folder within Jenkins
|
Credential scope
When exposing credentials from the Jenkins root object, you also need to decide what scope to give the exposed credentials.
|
Using the Web User Interface to expose CyberArk credentials
Navigate to the Credentials page for the context within which the CyberArk credentials will be exposed.
Adding a credential
To add a credential into the CyberArk store associated with the context:
-
Hover your mouse over the
(global)domain for the CyberArk store.
Figure 10. Shortcut menu to add credentials to the '(global)' domainThe CloudBees CyberArk Credential Provider only supports the (global)domain. -
Select Add Credentials from the drop-down list. New credentials page displays.
Figure 11. New credentials page -
Enter details about the credential.
Label Definition Kind
Displays the type of credential. This field automatically displays the CyberArk ussername and password which is currently the only type of credential supported.
Scope
Determines where this credential can be used. Select one of the following.
-
System: This credential is only available to the object on which the credential is associated. This system-scoped credential could be used for email auth or agent connection (where the Jenkins instance itself is using the credential). This option significantly restricts where the credential can be used, providing a higher degree of confidentiality to the credential.
-
Global: This credential is available to the object on which the credential is associated and all objects that are children of that object. Global-scoped credentials can be used for items that are needed for jobs.
ID
A unique ID by which credentials are identified from jobs and other configurations.
If using version 1.0.19.x or later of the CyberArk Credential Provider, you can enter the CyberArk Object Id in either the ID field or the CyberArk Object ID field. If there is an issue with the ID entered in this field, you may receive one of the following error messages:
-
CyberArk was recently unavailable, won’t recheck for another 5.5 sec
-
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
Description
(Optional) A description of the credential.
CyberArk ID
The CyberArk Object ID in one of a specific CyberArk Safes that this credentials store is configured to search in.
-
-
Select Create.
Once the credential is added, it becomes visible on the Credentials page for the context object.
Figure 12. Object defined in the CyberArk credentials store
Adding a credential within a job
You can also a credential from the configuration page of a specific job. Under the Credentials, select Add to view the list of credential stores in scope for the job. The list of enabled stores is restricted to those stores to which the current user has permission to add credentials.
When you select a CyberArk credentials provider from the list, the Add Credentials dialog appears.
Using the Jenkins Command Line Interface
The create-credentials-by-xml Jenkins CLI command is the command used to expose CyberArk credentials.
Before using this CLI command, you 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:
-
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 ProviderThe 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.CyberArkCredentialsProviderbut in the above instance we also have available the short formcyberark. -
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 UsersThe 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 you want are either
com.cloudbees.plugins.credentials.CredentialsSelectHelper$SystemContextResolver(which has the short alias ofsystem) orcom.cloudbees.plugins.credentials.CredentialsSelectHelper$ItemContextResolver(which has the short alias ofitem) -
Specify the context path
-
For the
systemcontext resolver, this is always the fixed valuejenkins. -
For the
itemcontext 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 URLhttp://local.example.com/jenkins/job/example-folder/job/example-sub-folder/would have the full name/example-folder/example-sub-folderThe
config.xmlof 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::jenkinsfor the root credentials store -
cyberark::item::/full/name/of/folder
-
-
-
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 thedeploy-keycredential in the/example-folderfolder.$ 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.
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
| 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
Figure 16. Using the context menu for removing a credentials from a credentials store -
Navigate to the credential and select the Delete left hand menu action.
Figure 17. 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.
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.
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
| 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. |