Credentials and User Impersonation

11 minute read

Credential overview

In CloudBees Flow, a "credential" is an object that stores a user name and password for later use. Two credential types are available, stored or dynamic :

  • stored credentials – These credentials are given a name and stored in encrypted form in the database. Each Project has a list of stored credentials it owns. These credentials are managed from the Project Details page.

  • dynamic credentials – These credentials are captured when a job is created. Dynamic credentials are stored on the server temporarily until the job completes and then discarded.

Stored credential encryption

128-bit AES (Advanced Encryption Standard) is used to store credential data in CloudBees Flow, including passwords.

Defining a credential

After a credential is created, no one can view the password for the credential’s account. This means one person can define a credential and enter the password, and other people can use the credential (and its account) without needing to know the password.

To create a new credential in the automation platform UI:

  1. Click the Projects tab.

  2. Select a project (first column) to see the Project Details page.

  3. Select the Credentials tab and then click Create Credential.

    Click the Help link on the New Credential page if you need more information about what to enter in the fields.

To create a new credential in the Deploy UI:

  1. From the Projects list, click the Actions selector for the desired project and select Details. The Project edit dialog appears.

  2. Click the Manage Credentials right arrow button. The Credentials dialog appears.

  3. Click Add and the Credential dialog appears. Enter data into the fields.

  4. Click OK to save the credential.

Using credentials

Use CloudBees Flow credentials for:

  • User impersonation

  • Saving passwords for use inside steps

When a step needs to run as a particular user, CloudBees Flow 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 dynamic 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.

Credential access control

Because CloudBees Flow stores passwords in a recoverable manner, it is important that credentials are accessible only under carefully controlled circumstances. To protect credentials, CloudBees Flow 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 Flow 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.

Using credentials for impersonation

This information addresses the question, "When a job step is running on a resource, under which account is it running and how can I control that?" By default, a job step runs under the account used by the CloudBees Flow agent that runs the step, which was chosen when the agent was installed. This approach works well in environments where it makes sense to run all jobs under a single user such as a "build" user. You install all agents to run as the desired user, and you do not have to worry about anything else—every step of every job runs as that user.

However, in other environments you may prefer to run different jobs, or even different job steps, under different accounts.

For example:

  • If independent groups are sharing a CloudBees Flow system, you may want each group to use a different account for its jobs.

  • You may need to run jobs as particular users to access ClearCase views for those users.

  • There may be certain steps that require special privileges.

    For example, as part of your builds you may need to run a step that generates a certificate using privileged corporate information; that step must run under a special high-privileged account, but you want the remainder of the steps in the build to use a less-privileged account.

CloudBees Flow allows you to select accounts on a per-job or per-job-step basis. This mechanism is called impersonation , where the CloudBees Flow agent impersonates a particular user for the duration of a job step, and this impersonation is implemented using credentials. The use of credentials creates special security challenges.

It is important to ensure privileged accounts can be used only for the purposes you intend and cannot be "hijacked" for other purposes. The CloudBees Flow access control mechanism contains special facilities to ensure proper credential use.

Setting the impersonation credential

Attaching impersonation credentials to steps

You can attach impersonation credentials to procedure steps, procedures, and projects before executing a job step.

CloudBees Flow searches for a credential in the following order and uses the first credential it finds:

  1. Procedure step

  2. Procedure to which the step belongs

  3. Project to which the project belongs

If the step is in a nested procedure, and no credential is found on the step, its procedure, or its project, CloudBees Flow checks the calling step (and its procedure and project), its caller, and so on until it has worked up through the topmost procedure in the job. If no credential is found, the job step runs under the CloudBees Flow agent account on its resource.

This approach makes it easy to manage your account usage. For example, if you want all jobs in one project to use a particular account, define a credential in that project for the account, and then attach the credential to the project. If you want all jobs in a project to use a particular account, except for one step that should use a different account, create two credentials in the project. Attach the first credential to the project and attach the second credential to the particular step.

Attaching impersonation credentials to schedules

You can also attach a credential to a schedule. The credential in the schedule is used for steps where no other credential is available.

The schedule’s credential receives the lowest priority.

Attaching impersonation credentials to jobs

You can specify a credential when you launch a job manually one of these ways:

  • Provide the name of an existing credential

  • Enter an account and password.

If you choose the second approach, the account and password are stored only in CloudBees Flow for the duration of the job.

For either way, the credential you specified when you launched the job is used as a last resort for steps only with no other credential.

Attaching a new impersonation credential

To attach a new impersonation credential for a procedure, step, or schedule:

  1. Click the Projects tab.

  2. Select a project.

  3. Go to the Project Details page for the project you selected.

  4. Do one of the following:

    1. For a procedure :

      1. Click Create Procedure to go to the New Procedure page.

      2. On this page, select the Impersonation Credential drop-down box to select a credential to use for impersonation.

    2. For a step :

      1. Select a procedure to go to the Procedure Details page.

      2. Select a step name to go to the Edit Step page.

      3. On the Edit Step page, scroll down to the Impersonation section.

    3. For a schedule :

      1. Select the Schedules subtab.

      2. Select a schedule to go to the Edit Schedule page.

      3. Scroll down to Impersonation Credential section.

        For more information in the platform GUI, each of these web pages contains a Help link in the upper-right corner.

Accessing credentials from a step

The CloudBees Flow server supports an operation 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.

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 GUI, to attach a credential (other than an impersonation credential) to a step, procedure, or schedule:

  1. Go to an "Edit" page.

    For example, to create a credential for a step, a step must already exist.

  2. Select a step that needs a credential. The Edit Step page opens.

  3. Scroll to the lower section of the page and click Attach Credential.

If you are an ectool command-line user, use the attachCredential API command. For more information on the command-line interface, go to the ectool Help topics within the online Help system.

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:

  1. Create a project named InnerProj.

  2. Within that project create a procedure named InnerProc with a parameter 'cred' of the type credential.

  3. Within that procedure create a step named InnerStep with:

    • Command: ectool getFullCredential cred

    • Attached Parameter Credential: cred

  4. Create a project named OuterProj with two credentials: cred1 and cred2.

  5. Within that project create a procedure named OuterProc with two parameters, cred1 and cred2, of the type credential.

  6. 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, you can use the createFormalParameter and attachParameter API commands. For more information on the command-line interface, go to the ectool Help topics within the online Help system.

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.

Best practices for retrieving credentials

The CloudBees Flow impersonation mechanism provides powerful mechanisms for using different accounts in job steps, and it can be used to handle a variety of challenges. However, if misused, impersonation can open up dangerous security loopholes. This section discusses these risks and how to avoid them.

Use of credentials and impersonation tend to fall into two classes.

First class

In the first class, your goal is to open up access to accounts, you want to make some accounts generally available, and you trust large groups of users (such as everyone who can access a particular project) to use the accounts appropriately. This usage type is simplest and relatively safe.

  1. Define a CloudBees Flow group containing all trusted users.

  2. Set permissions on the Project so only trusted users can access the project.

  3. Define credentials for accounts in the Project and grant execute permission to everyone in the group.

After completing this task, everyone in the group can use the accounts for arbitrary purposes. No one outside the group will be able to access the project or the credentials.

Second class

In the second class, you want to provide tightly-controlled access to a highly privileged function such as generating a certificate or accessing sensitive information. This kind of usage requires careful thought to avoid allowing unintended access to the credential. The best way to implement a solution for this scenario is to restrict access to the credential and use it on individual steps only after careful analysis of issues such as the following:

  • Does the step’s command use properties?

    If so, someone could potentially change the property value to change the step behavior. For example, suppose the step’s command is defined like this:

    echo $[/myProject/x]

    Anyone with write access to property x can hijack the step by placing the value "nothing; myCommand" in the property. After property substitution, the final command will be:

    echo nothing; myCommand

    that will cause "myCommand" to execute in the step. Either restrict access to the property sheet or avoid substitutions.

  • Does the step execute code or commands that can be modified?

    In most jobs that execute build and test sequences, the job extracts various files from a source code control system and some of those files contain code executed during the build. In this case, anyone with access to the source code control system can affect the executed code.

    For example, suppose a step runs a Make or Ant command using a configuration file extracted from the source code control system. Anyone with access to the source code control system can modify the configuration file to introduce new commands executed during the Make or Ant step. In this situation, it is virtually impossible to control what happens during the step, so you should never attach a credential for a privileged account to such a step.

    The higher you attach a credential, the greater the risk of uncontrolled access to the credential’s account.

    For example, if you attach a credential to a project, there is a good chance anyone with write access to the project, or even the ability to execute the project’s procedures, can hijack the credential using one of the loopholes described above. If you attach a credential to a step that invokes a subprocedure, you effectively give anyone with write access to the subprocedure complete access to the credential’s account. If you care about access to an account, you should use its credential in the narrowest possible fashion, such as attaching it to a single job step.

Avoid passing passwords on the command line

When using credentials, avoid passing the password on the command line because [on most platforms] those passwords will be visible to all users logged into the system. The secure way to pass a credential to an application or microservice is to use a secured file in the file system or to pipe the value into the application or microservice via stdin.