Impersonation concepts

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 CD 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 CD 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 CD allows you to select accounts on a per-job or per-job-step basis. This mechanism is called impersonation , where the CloudBees CD 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 CD 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 CD 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 CD 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 CD 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 CD 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 impersonation credentials to microservices

You apply credentials and impersonation to control who can deploy applications or microservices and where the applications or microservices are deployed.

  • You can attach one or more credentials to component, application, or microservice process steps.

  • You can use only one impersonation credential when running an application or microservice process, component process, or a process step.

  • When you attach an impersonation credential in CloudBees CD, it specifies the user who can deploy the application or microservice and the environment in which the application or microservice is deployed.

  • When you attach an impersonation credential to a platform-level object (such as a procedure), it specifies the account (user) that can run the job or job step. If you want to specify another condition, you have to attach another credential to the object.

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.

When you impersonate using a credential, make sure that the impersonated user has the absolute path to the bin directories in the $PATH environment. If you define a process step with a command, you must enter the absolute path in the Post Processor and Shell fields in the Define Step dialog box.

Click in the Add Credentials field. The Component Process Step / Add dialog box opens.

  • To impersonate one credential:

    1. Select Impersonate in the Type field.

    2. 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.

    3. Select the Select Credential field to open a drop-down list of credentials for the process step.

    4. Select a credential.

    5. Click OK.

      The Credentials dialog box now shows the one credential for impersonation.

Best practices for retrieving credentials

The CloudBees CD 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 CD 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.