Increase security when impersonating other users

Save time with the User Impersonation feature in IBM UrbanCode Deploy

IBM UrbanCode Deploy

IBM® UrbanCode Deploy, previously known as uDeploy, is a web-based application for software deployment automation. It provides a graphical user interface (GUI) that allows for the setting up of environment configuration and the orchestration of different deployment tasks. You can also run the tasks on a number of different target systems in just a few clicks or by scheduling regular deployments.

The overall picture of a deployment process that is managed under UrbanCode Deploy consists of:

  • An UrbanCode Deploy server, which hosts the main UrbanCode Deploy application and GUI, and conducts the general deployment process.
  • An UrbanCode Deploy agent installed on each target system.
  • The UrbanCode Deploy server sends instructions to the UrbanCode Deploy agent. The agent then runs the instructions on the corresponding target system.

User Impersonation

Use a dedicated UrbanCode Deploy agent user on each target system as a security precaution (read about this in the UrbanCode Deploy documentation). With the use of a dedicated user, the access of the agent to the target system can be limited only to specific locations and commands. In this manner, the security on the corresponding target system can be enhanced. In a situation where the agent would need to access some locations or commands, to which it would not normally have access, it must run these tasks as a different user. UrbanCode Deploy provides User Impersonation feature that allows you to do this.

Apply user impersonation to a deployment process to ensure the following statements are true:

  • Each agent user has the minimum level of privilege.
  • There is support for running commands as different users.
  • Each command is run as the appropriate user.
  • UrbanCode Deploy tasks are run with the minimum level of privilege and not higher than what was originally granted to them.

The setup of User Impersonation is done on two levels:

  • The target system
  • The UrbanCode Deploy application user interface (UI)


The sudo, or sudoers, is a security system that grants user privileges to run various commands as a super user (providing corresponding level of security). The system is implemented on UNIX-like operating systems such as Ubuntu (Linux) and AIX (UNIX). The term sudo stands for super user do. Sudoers refers to a system file, /etc/sudoers, which is used as a configuration file with the corresponding operating system sudo settings. It follows a specific sudoers file format that is documented in the Sudoers Manual.

An example sudoers entry is:

Barry ALL = (Ann) NOPASSWD: /tmp/script_files/*.sh

In the code example, user Barry can access any shell script file on any host in the location /tmp/script_files as user Ann, without providing an identification password.

As defined in the Access Control List (ACL) policy for managing of UNIX-like file systems, each file is assigned a set of 10 bits (flags). They are classified as the file type flag and then three sets of three permission flags. The table below provides further explanation of these permission bits.

Table 1. ACL files permissions bits classification
ACL bit numberPossible valuesMeaningOnOff
1-, l, d
  1. - (hyphen or dash) – a regular file
  2. l (lowercase L) – a file of type: symlink
  3. d (lowercase D) – a directory
2-, rUser Owner – Read permission r -
3-, wUser Owner – Write permission w -
4-, xUser Owner – eXecute permission x -
5-, rGroup Owner – Read permission r -
6-, wGroup Owner – Write permission w -
7-, xGroup Owner – eXecute permission x -
8-, rOther Users – Read permission r -
9-, wOther Users – Write permission w -
10-, xOther Users – eXecute permission x -

This policy allows different users to be denied or granted different levels of access to various system files, locations, and commands.

For example, consider a system where you have the following situation:

  • Three users: Ann, Barry, and Cathy
  • Three user groups: groupA, groupB, and groupC. One group for each user.
  • A fourth user group: groupABC that includes all of the above users
  • Two Shell script files: and with the ACL configurations below:
-rwxr-x--- 1 Ann groupA 28 Apr 1 14:01
-rwxr-xr-x 1 Cathy groupABC 28 Apr 1 14:03

In the example code, you can see that the first script file is owned by user Ann and user group groupA. You can also see that the second file is owned by user Cathy and user group groupABC. A further break down of the above files' permission bits is provided below. Note that the file type flag (first bit) is ignored.

  • The permission bits on this file are rwxr-x--- and specify:
    • The first group of 3 bits (rwx) notes that the file User Owner – Ann, can Read (r), Write (w) and eXecute (x) the file.
    • The second group of 3 bits (r-x) is for the file Group Owner. Only the Read (r) and eXecute (x) flags are set. The second (w) bit is turned off with the (-). This means that members of groupA can read and execute the file, but cannot write to it.
    • The third group of 3 bits (---) shows that none of the permission bits is set for Other Users. This file is not accessible to the other system users Barry and Cathy.
  • The permission bits on this file are rwxr-xr-xand specify the following information.
    • File User Owner (Cathy) can Read (r), Write (w) and eXecute (x) the file as a Shell script.
    • File Group Owner (groupABC) can also Read (r), and eXecute (x), but cannot edit (write) to it.
    • Other Users can also Read (r) and eXecute (x) the file.

The system's super user, root, has complete access to all files. Therefore, root can Read, Write and eXecute (if applicable) any system file, regardless of its owners' User and Group.

If user Barry attempts to run the, a corresponding error message bash: ./tmp/script_files/ Permission denied is returned.

To provide access to the file for user Barry, complete one of the steps below:

  1. Add the user Barry to the user group groupA to provide only Read and eXecute access to the file.
  2. Update sudoers and grant access to the file for Barry as user Ann to allow user Barry to impersonate to user Ann.

To use the second method, user Barry needs to use the sudo command in combination with the corresponding command to run the required file:

Barry:# sudo -u Ann /tmp/script_files/

Recall the sudoers entry for Barry, provided earlier in this section:

Barry ALL = (Ann) NOPASSWD: /tmp/script_files/*.sh

Following on from the above sudoers record for user Barry, a password will not be required to complete the specified command if the user runs the above provided command. Instead, the requested is run as if it were run by user Ann.

It's different in a situation where the above sudoers configuration was not set, or if Barry attempts to access or execute another file on different location as user Ann. For example:

Barry:# sudo -u Ann /tmp/other_location/

In this situation, a password authentication is requested:

[sudo] password for Barry:

This is because this location was not covered by the sudoers entry, provided above, or any other sudoers rule that is specified in the file.

Set up and implement User Impersonation

This section provides a thorough guide for the setup and implementation of User Impersonation with UrbanCode Deploy. It follows a number of steps that include target system configuration and UrbanCode Deploy component setup for the use of User Impersonation.

Various Operating Systems (OS) differ in their configuration, files, and users management. Because of this, some of the steps in this article only state the action to take and do not provide a corresponding shell or other command to complete it.

Each of the provided steps are given for deployment setup of a web-based application and should be implemented on both Apache and database systems.

Further information about used variables is provided in Table 2. The values of the variables in Table 2 are only examples and are not real values. Instead, replace any of the used variables which are [ENCLOSED IN SQUARE BRACKES] with the appropriate target system value.


  • Java version 6 or newer installed on your target systems
  • A shell variable ${JAVA_HOME} is set and pointing to your Java binary home directory
  • Sudoers package is installed on each of your target systems
  • Dedicated UrbanCode Deploy agent user and user group are set on each of your target systems

Start the agent as its dedicated user

This section provides notes on how to facilitate the further setup of user Impersonation on your UrbanCode Deploy systems. The UrbanCode Deploy agent installation is documented and a walk-through guide is provided for both types of installation.

As noted in the Prerequisites section, you should have installed UrbanCode Deploy agents on both of your Apache and database systems. If not, follow one of the above installation links before you continue further in this article.

To facilitate functionality of your UrbanCode Deploy agent and run it as its dedicated user:

  1. Switch to root user using the su command.
  2. Confirm that the ${JAVA_HOME} shell variable is added to your AGENT_UserName profile.
    1. Open the [AGENT_UserHome]/.profile file for editing.
    2. Add this code to it:
      #export java path
      export JAVA_HOME=[the value of your ${JAVA_HOME} shell variable]
      export PATH=$JAVA_HOME/bin:$PATH
  3. Source the profile to pick the new variables:
  4. To implement further security restrictions on your UrbanCode Deploy agent user, you can also do one or both of the following steps:
    1. Restrict the password request for AGENT_UserName.
    2. Restrict SSH access for AGENT_UserName to your target system. This prevents SSH logins to your target system as AGENT_UserName.

    Note: Further security measures are provided later in the Set up the environment directories on the OS level section of this article.

  5. Confirm that everything under AGENT_HOME_DIR is owned by your AGENT_UserName and AGENT_UserGroup:
    1. Switch to root user using the su command.
    2. Update ownership of the agent home directory:
      chown -R [AGENT_UserName]:[AGENT_UserGroup] [AGENT_HOME_DIR]
  6. Confirm that your UrbanCode Deploy agent is running as its dedicated AGENT_UserName:
    1. Switch to your AGENT_UserName:
      su - [AGENT_UserName]
    2. Navigate to your [AGENT_HOME_DIR]/bin directory:
      cd [AGENT_HOME_DIR]/bin
    3. Run the command:
      ./agent run

As result of these actions, you'll get one of two messages. If the agent is already running, you get the first message telling you that the agent is already running. If the agent is not running, you get the second message telling you that it is starting.

Set up the Sudoers and Groups

To allow User Impersonation to Apache and database users, complete the following steps on your target systems:

Note: These steps must be implemented on both Apache and database systems.

  1. Make sure you are working as the root user.
  2. Add the root user to the AGENT_UserGroup.
  3. Add your APACHE_UserName and DATABASE_UserName to the appropriate AGENT_UserGroup.

Set up Sudo permissions

Update your sudoers file on both the Apache and database systems.

  1. Open sudoers for editing.
    1. If you are not working as the root user, switch to it using the su command.
    2. Open sudoers editor using the visudo command.
  2. For AIX OS systems, add the following two lines to the end of the file:
    [AGENT_UserName] ALL = (root,[Apache_or_DB_User]) NOPASSWD: /usr/bin/ksh -c [AGENT_HOME_DIR]/var/temp/command-script-*.ksh
    [AGENT_UserName] ALL = (root,[Apache_or_DB_User]) NOPASSWD: /usr/bin/bash -c [AGENT_HOME_DIR]/var/temp/command-script-*.sh
  3. For AIX OS systems, set the format of the sudo command to correspond to the sudoers configuration you set in the previous step. Add this line to your [AGENT_HOME_DIR]/conf/agent/ file: -i -n -u %u %c
  4. For Ubuntu OS systems, add the following line to the end of the file:
    [AGENT_UserName] ALL = (root, [Apache_or_DB_User]) NOPASSWD: [AGENT_HOME_DIR]/var/temp/command-script-*.sh

This Sudoers configuration allows your UrbanCode Deploy agent to impersonate, to root, APACHE_UserName and DATABASE_UserName during the execution of an UrbanCode Deploy process without needing to provide a password.

Set up the environment directories on the OS Level

The next step is to update or create a number of directories:

  1. Make sure you are working as the root user using the su command.
  2. Create the following directories:
    mkdir -p [AGENT_HOME_DIR]/var/plugins
    mkdir -p [AGENT_HOME_DIR]/var/temp
    mkdir -p [AGENT_HOME_DIR]/var/work
  3. Confirm that AGENT_UserName and AGENT_UserGroup own the AGENT_HOME_DIR directory and its contents:
    chown -R [AGENT_UserName]:[AGENT_UserGroup] [AGENT_HOME_DIR]
  4. Restrict the AGENT_HOME_DIR and its contents so it can be accessed only by the AGENT_UserName:
    chmod -R u=rwx,go-rwx [AGENT_HOME_DIR]
  5. Update permissions of the following directories. This is required to ensure that highest restrictions are implemented on the AGENT_HOME_DIR, and to enable the UrbanCode Deploy agent to impersonate other users. These are users that are members of the AGENT_UserGroup and allowed by the sudoers configuration.
    chmod u=rwx,g=rx,o-rwx [AGENT_HOME_DIR]/
    chmod u=rwx,g=rx,o-rwx [AGENT_HOME_DIR]/conf
    chmod u=rwx,g=rx,o-rwx [AGENT_HOME_DIR]/conf/agent
    chmod u=rwx,g=rx,o-rwx [AGENT_HOME_DIR]/conf/agent/
    chmod u=rwx,g=rx,o-rwx [AGENT_HOME_DIR]/var
    chmod u=rwx,g=rx,o-rwx [AGENT_HOME_DIR]/var/temp
    chmod -R u=rwx,g=rx,o-rwx [AGENT_HOME_DIR]/opt
    chmod -R u=rwx,g=rx,o-rwx [AGENT_HOME_DIR]/var/plugins
    chmod -R u=rwx,g=rx,o-rwx [AGENT_HOME_DIR]/var/work

The setup of your target system to enable user impersonation with UrbanCode Deploy is now complete. Next, enable debugging for impersonated processes, then set an UrbanCode Deploy component process to be deployed using user impersonation.

Enable debugging of user impersonation

To debug user impersonated processes on UrbanCode Deploy, configure your file located in your [AGENT_HOME_DIR]/conf/agent/ directory. To enable the debugging, add these lines to the end of the file:

# logger level configurations

# special logger configurations for user impersonation debugging

The location of the agent's log file is defined in the [AGENT_HOME_DIR]/var/log/ directory using the following line:


To pick up your updates, restart your agent as described in Start the agent as its dedicated user using these two commands:

./agent stop
./agent start

A debug entry in the log file appears as:

2014-06-27 09:34:24,408 - Executing shell as [APACHE USERNAME]
2014-06-27 09:34:24,442 - Running command as Unix user  [APACHE USERNAME]
2014-06-27 09:34:24,442 - Command: [/bin/sudo, -n, -u,  [APACHE USERNAME], [[PATH TO YOUR AGENT HOME DIRECTORY]/var/temp/]

When finished debugging your user impersonated processes, you should comment out the debug log lines under the line #special logger... and restart your agent. That prevents further user impersonation debug logging, which can add a large amount of information to the log file.

Configure an UrbanCode Deploy component to impersonate a user

The management of UrbanCode Deploy components and processes is handled through the corresponding UrbanCode Deploy server user interface. Follow the example steps in Figures 1 through 4 to set up an UrbanCode Deploy component process to deploy with impersonation. Figures 5 and 6 provide an example of a shell script UrbanCode Deploy process step that is deployed with impersonation and the output of this step.

Figure 1 shows the path to an example component process that is to be edited.

Figure 1. Navigate to the component process editor
navigation path to                     components menu
navigation path to components menu

Navigate to a component process editor screen:

  1. Click the Components tab in the main UrbanCode Deploy menu.
  2. Click the link to the component you want to edit. For this example it is Your uDeploy Component.
  3. Select the Processes tab.
  4. Select the process that you want to edit. In this example it is your uDeploy Component Process.

The component process editor window is shown in Figure 2.

Figure 2. Component process editor
component process                     editor
component process editor

Some steps can be impersonated. Each process step has a pencil icon at its upper right side. Click the pencil to open the process for editing. If the step can be impersonated, the fields in Figure 3 appear in the pop-up window.

Figure 3. UrbanCode Deploy process step editor: Use Impersonation field
fields shown in a pop-up window
fields shown in a pop-up window

By default, the step is not impersonated. To impersonate the step, select the Use Impersonation check box. This updates the Step Editor view as shown in Figure 4.

Figure 4. UrbanCode Deploy process step editor: User Impersonation enabled

When you select the Use Impersonation check box, the User field becomes a required field as shown in Figure 4. You can skip the Group and Password fields because you already set a password-less impersonation in Set up Sudo permissions.

Note: The Use Sudo check box has to be checked.

Example deployment of a user impersonated UrbanCode Deploy component process

This section provides an example of an impersonated UrbanCode Deploy component process step and its output upon deployment on a target system.

Figure 5. Example UrbanCode Deploy component process step of type shell script
a screen capture of the                     component process window of a shell script
a screen capture of the component process window of a shell script

Figure 5 shows a simple shell script that runs as a Bash script (defined in the Interpreter field) and prints a couple of messages (as set up in the Shell script field). The code ${p:agent/} is an UrbanCode Deploy specific code format used to access some process-specific variables. In this case, AGENT_UserName is dedicated to the corresponding UrbanCode Deploy agent. Before the script execution and during the deployment of the above step, the UrbanCode Deploy agent replaces the ${p:agent/} code with its corresponding value. In this example, that is udeployagent.

Figure 6 shows the output of the executed shell script from Figure 5.

Figure 6. Output log from deployment of an impersonated UrbanCode Deploy process step
output log
output log

The script content section highlighted in red in Figure 6, holds the actual shell script with the updated field for the AGENT_UserName. This is run by the corresponding UrbanCode Deploy agent on its target environment.

The actual script result is displayed under the command output line. It's highlighted in blue, shows the dedicated user name of the used UrbanCode Deploy agent and the user name of the impersonated user. In this case, the user name of apache was obtained by the shell command whoami.


The use of specific or customized scripts to facilitate the process of software deployment proved to significantly reduce the time for manual deployments. However, for deployment of more complex applications (where specific features are managed under dedicated users) specific deployment steps need to be executed as these users. The use of customized deployment scripts still requires a reasonable amount of human intervention and observation during a deployment process.

This article showed that the use of UrbanCode Deploy with user Impersonation is a favorable tool for addressing all of the above mentioned difficulties in deployment process. The integration of the tool within a software product deployment process still requires some development time. However, after it is set up and properly configured, the UrbanCode Deploy application can significantly reduce the number of human interventions during deployment. It can even allow one person to trigger and maintain a number of independent deployments on several different systems in just few clicks and thus significantly to reduce deployment in favor of development time.


Table 2. Guide - variables and references (used in User Impersonation Set Up Guide)
No: Variable/Reference Meaning Notes
1AGENT_UserName Reference to UrbanCode Deploy agent - dedicated user.

  • Should be replaced by a proper user name
  • You can have same dedicated user on both of your Apache and database Systems
2AGENT_UserGroup Reference to UrbanCode Deploy agent - dedicated user group.

  • Same as above
  • Will also include groups and users that the UrbanCode Deploy agent will try to impersonate
3AGENT_UserHome Reference to user home directory of AGENT_UserName, above.

Example: /home/ucduser/
4AGENT_HOME_DIR Reference to full path of an UrbanCode Deploy agent's installation directory on a target system.

Example:/opt/UrbanCode Deploy/ucd-agent
5APACHE_UserName Reference to the Apache user on an Apache System.

6DATABASE_UserName Reference to the database user on a database System.

7Apache_or_DB_User Reference to either: #5 or #6, above.
  • Should be replaced by the value (user name) of either Apache or DB Users from above two lines
8${JAVA_HOME} Shell variable, which holds the path to Java binary home directory on your system

  • This variable should be set on each of your (Apache and database) systems

Note: The values of the variables in the above table are only examples and should not be considered as real values.

Downloadable resources

Related topics

ArticleTitle=Increase security when impersonating other users