Credentials in pipelines

Use CloudBees CD/RO credentials for:

User impersonation
Saving passwords for use inside steps and tasks

When a step needs to run as a particular user, CloudBees CD/RO can retrieve the user name and password from a stored credential. The credential is passed to the agent over an encrypted channel so the agent can authenticate itself to the operating system and set up a security context where the step runs with the user permissions in the credential.

In some cases, a step needs to enter credentials directly to an application or microservice.

The credential may be a fixed application or microservice credential that needs to be presented every time the step runs. In this case, a stored credential provides a place to put this information without needing to embed the password in a script.
Other times, the password is not known in advance. In this case, a runtime credential created when a job is launched can prompt a user for information and then pass the credential to the step in a secure manner.

Attaching a credential

A credential must be explicitly attached to the object using it so the server can perform an access control (ACL) check at definition time and limit the visibility of the password. To support accessing credentials other than the one being used for impersonation, steps, procedures, and schedules contain a list of credential names.

In the platform UI, to attach a credential (other than an impersonation credential) to a step, procedure, or schedule:

Select Attach in the Type field.
Click the Select Project field to select a project. You can select a credential from a project that is different than the one containing the application.
Click the Select Credential field to open a drop-down list of credentials for the process step.
Select a credential.
Click OK.

If you are an ectool command-line user, use the attachCredential API command.

Select Add Credentials. The Component Process Step / Add dialog box opens.

Impersonate a credential

To impersonate a user:

Select Impersonate in the Type field.
Click the Select Project field to select a project. You can select a credential from a project that is different than the one containing the application.
Select the Select Credential field to open a drop-down list of credentials for the process step.
Select a credential.
Click OK.

The Credentials dialog box now shows the one credential for impersonation.
Mac users only: If the impersonated user writes to the default TMP directory, execute the following:
1. Open a shell as root.
2. Open the “wrapper.conf” file, which is located at:
  <Enter-your-installation-directory>/conf/agent/wrapper.conf
  ▼
3. Add the following line to the wrapper.conf file.
  wrapper.java.additional.1=-Djava.io.tmpdir=/tmp
  ▼
4. Run the following command:
  <Enter-your-installation-directory>/agent/bin/commanderAgent restart
  ▼

Credential access control

Because CloudBees CD/RO stores passwords in a recoverable manner, it is important that credentials are accessible only under carefully controlled circumstances. To protect credentials, CloudBees CD/RO uses two mechanisms: access control lists (ACL) and attached credentials.

To use a credential for any purpose, a user who attempts to reference the credential must have execute permission on the credential object—this allows you to explicitly control which users are allowed to use a credential anywhere in the system.

In addition to the user-based access control check, CloudBees CD/RO requires a credential be explicitly attached to the object that is going to use it. After an object has a credential attached, object modifications are restricted to users who have both execute permission on the credential and modify permission on that object. This safeguard helps prevent credentials from accidentally being used by unauthorized users.

Attach a credential to an object in the automation platform UI one of these ways:

Set the impersonation credential for a step, procedure, project, or schedule.

You can also set the impersonation credential for an application or microservice process, component process, or a process step.

Impersonation credentials are inherited, so attaching a credential to a container object like a procedure or a project implicitly attaches it to every object inside the container, such as all steps in a procedure.
Explicitly attach the credential to a step or schedule using the UI or the attachCredential API.

To access credentials from a step, the credential must be attached directly to the step, or the credential must be passed as a parameter to the containing procedure and have the parameter attached instead.

Accessing credentials from a step

The CloudBees CD/RO server supports an API called getFullCredential that can return a password when called from inside a step. The ectool interface for this operation is:

getFullCredential <credential name> [--value <password|userName>]▼

Without the --value option, the response is the same as that returned by getCredential, with the addition of a password element. With --value, the simple text password or userName value is returned on stdout so it can be used directly without XML parsing.

The getFullCredential API is allowed only inside a running step, and is allowed to use credentials that were explicitly attached to the step only.

Passing credentials as parameters

Sometimes you may not know which credential you need to use when you define a procedure step. In this situation, you can leave the credential choice up to the caller of the procedure.

The following example describes the procedure for passing credentials as parameters:

Create a project named InnerProj.
Within that project create a procedure named InnerProc with a parameter cred of the type credential.
Within that procedure create a step named InnerStep with:
- Command: ectool getFullCredential cred
- Attached Parameter Credential: cred
Create a project named OuterProj with two credentials: cred1 and cred2.
Within that project create a procedure named OuterProc with two parameters, cred1 and cred2, of the type credential.
Within that procedure create two subprocedure steps that both call InnerStep from the InnerProj project:
- OuterStep1 with Attached Parameter Credential cred1, and cred1 in the Parameters section
- OuterStep2 with Attached Parameter Credential cred2, and cred2 in the Parameters section

If you are an ectool command-line user, use the createFormalParameter and attachParameter API commands.

Credential references

For schedules, the value for any actual parameter passed to a credential-type formal parameter is interpreted as a reference to a previously attached credential on the schedule.

For procedure steps, the value for any actual parameter passed to a credential type formal parameter is interpreted as a reference to a previously attached credential or credential parameter on the calling step.

When a job step is created, all credential references are resolved and the content is copied into transient credentials on the job step. Credential parameter references are resolved by looking for a credential in the calling job step’s transient credential map—looking for a credential with the name specified as the actual parameter value.

Credential references in the API can be specified as a relative or an absolute credential path.

A relative path is similar to rootCred and is interpreted as referring to a credential in the current project.
An absolute path includes a project name like /projects/MyProject/credentials/rootCred and can refer to a credential in any project.

Anywhere a credential reference is accepted (for example, setting an impersonation credential or attaching a credential to a step), either form can be used.

Credentials in pipelines

Credentials are passed to pipelines through applications or microservices in pipeline stages. If an application or microservice has required inputs (parameters) and any of the inputs is a credential parameter, you can enter the path to the credential, browse to it, select a credential parameter (Parameter Credential) or a credential binding to a pipeline task (Credential binding), or select a user-defined credential that is attached to the project associated with the pipeline.

A credential must be explicitly attached to the object using it so the server can perform an access control list (ACL) check at the definition time and limit the visibility of the password. To support accessing credentials at the pipeline task level, these tasks need to have the appropriate credentials attached. This is done implicitly by the UI when you are binding credentials to the pipeline tasks. If you are using ectool, use the attachCredential API command to perform the same operation.

Credentials in releases

In the Release definition, credentials appear in these objects:

Pipelines: How the credential is applied to the Release depends on the selected pipeline.

If the pipeline has required inputs (parameters) and any of the inputs is a credential parameter, you can enter the path to the credential, browse to it, select a credential parameter ( Parameter Credential ) or a credential binding to a pipeline task ( Credential binding ), or select a user-defined credential that is attached to the project associated with the pipeline.
Applications or microservices: How the credential is applied to the Release depends on the applications or microservices in the selected pipeline.

If any input to an application or microservice is a credential parameter, you can enter the path to the credential, browse to it, select a credential parameter ( Parameter Credential ) or a credential binding to a pipeline task ( Credential binding ), or select a user-defined credential that is attached to the project associated with the pipeline.

See the steps to select a pipeline and to select credential inputs for an application or microservice in the pipeline in the release definition for examples of these operations.