Ansible allows you to ‘become’ another user, different from the user that logged into the machine (remote user). This is done using existing privilege escalation tools such as sudo, su, pfexec, doas, pbrun, dzdo, ksu, runas, machinectl and others.

Note

Prior to version 1.9, Ansible mostly allowed the use of sudo and a limited use of su to allow a login/remote user to become a different user and execute tasks and create resources with the second user’s permissions. As of Ansible version 1.9, become supersedes the old sudo/su, while still being backwards compatible. This new implementation also makes it easier to add other privilege escalation tools, including pbrun (Powerbroker), pfexec, dzdo (Centrify), and others.

Note

Become vars and directives are independent. For example, setting become_user does not set become.

For those using old playbooks will not need to be changed, even though they are deprecated, sudo and su directives, variables and options
will continue to work. It is recommended to move to become as they may be retired at one point.
You cannot mix directives on the same object (become and sudo) though, Ansible will complain if you try to.

Become will default to using the old sudo/su configs and variables if they exist, but will override them if you specify any of the new ones.

Ansible 2.0.x and below has a limitation with regards to becoming an
unprivileged user that can be a security risk if users are not aware of it.
Ansible modules are executed on the remote machine by first substituting the
parameters into the module file, then copying the file to the remote machine,
and finally executing it there.

Everything is fine if the module file is executed without using become,
when the become_user is root, or when the connection to the remote machine
is made as root. In these cases the module file is created with permissions
that only allow reading by the user and root.

The problem occurs when the become_user is an unprivileged user. Ansible
2.0.x and below make the module file world readable in this case, as the module
file is written as the user that Ansible connects as, but the file needs to
be readable by the user Ansible is set to become.

Note

In Ansible 2.1, this window is further narrowed: If the connection
is made as a privileged user (root), then Ansible 2.1 and above will use
chown to set the file’s owner to the unprivileged user being switched to.
This means both the user making the connection and the user being switched
to via become must be unprivileged in order to trigger this problem.

If any of the parameters passed to the module are sensitive in nature, then
those pieces of data are located in a world readable module file for the
duration of the Ansible module execution. Once the module is done executing,
Ansible will delete the temporary file. If you trust the client machines then
there’s no problem here. If you do not trust the client machines then this is
a potential danger.

Ways to resolve this include:

Use pipelining. When pipelining is enabled, Ansible doesn’t save the
module to a temporary file on the client. Instead it pipes the module to
the remote python interpreter’s stdin. Pipelining does not work for
python modules involving file transfer (for example: copy,
fetch, template), or for non-python modules.

(Available in Ansible 2.1) Install POSIX.1e filesystem acl support on the
managed host. If the temporary directory on the remote host is mounted with
POSIX acls enabled and the setfacl tool is in the remote PATH
then Ansible will use POSIX acls to share the module file with the second
unprivileged user instead of having to make the file readable by everyone.

Don’t perform an action on the remote machine by becoming an unprivileged
user. Temporary files are protected by UNIX file permissions when you
become root or do not use become. In Ansible 2.1 and above, UNIX
file permissions are also secure if you make the connection to the managed
machine as root and then use become to an unprivileged account.

Warning

Although the Solaris ZFS filesystem has filesystem ACLs, the ACLs
are not POSIX.1e filesystem acls (they are NFSv4 ACLs instead). Ansible
cannot use these ACLs to manage its temp file permissions so you may have
to resort to allow_world_readable_tmpfiles if the remote machines use ZFS.

Changed in version 2.1.

In addition to the additional means of doing this securely, Ansible 2.1 also
makes it harder to unknowingly do this insecurely. Whereas in Ansible 2.0.x
and below, Ansible will silently allow the insecure behaviour if it was unable
to find another way to share the files with the unprivileged user, in Ansible
2.1 and above Ansible defaults to issuing an error if it can’t do this
securely. If you can’t make any of the changes above to resolve the problem,
and you decide that the machine you’re running on is secure enough for the
modules you want to run there to be world readable, you can turn on
allow_world_readable_tmpfiles in the ansible.cfg file. Setting
allow_world_readable_tmpfiles will change this from an error into
a warning and allow the task to run as it did prior to 2.1.

Privilege escalation methods must also be supported by the connection plugin
used. Most connection plugins will warn if they do not support become. Some
will just ignore it as they always run as root (jail, chroot, etc).

Methods cannot be chained. You cannot use sudo/bin/su- to become a user,
you need to have privileges to run the command as that user in sudo or be able
to su directly to it (the same for pbrun, pfexec or other supported methods).

Privilege escalation permissions have to be general. Ansible does not always
use a specific command to do something but runs modules (code) from
a temporary file name which changes every time. If you have ‘/sbin/service’
or ‘/bin/chmod’ as the allowed commands this will fail with ansible as those
paths won’t match with the temporary file that ansible creates to run the
module.

For most Linux distributions using systemd as their init, the default
methods used by become do not open a new “session”, in the sense of
systemd. Because the pam_systemd module will not fully initialize a new
session, you might have surprises compared to a normal session opened through
ssh: some environment variables set by pam_systemd, most notably
XDG_RUNTIME_DIR, are not populated for the new user and instead inherited
or just emptied.

This might cause trouble when trying to invoke systemd commands that depend on
XDG_RUNTIME_DIR to access the bus:

As of version 2.6, Ansible supports become for privilege escalation (entering enable mode or privileged EXEC mode) on all Ansible-maintained platforms that support enable mode: eos`, ios, and nxos. Using become replaces the authorize and auth_pass options in a provider dictionary.

You must set the connection type to either connection:network_cli or connection:httpapi to use become for privilege escalation on network devices. Check the Platform Options and Network modules documentation for details.

You can use escalated privileges on only the specific tasks that need them, on an entire play, or on all plays. Adding become:yes and become_method:enable instructs Ansible to enter enable mode before executing the task, play, or playbook where those parameters are set.

If you see this error message, the task that generated it requires enable mode to succeed:

We recommend updating your playbooks to use become for network-device enable mode consistently. The use of authorize and of provider dictionaries will be deprecated in future. Check the Platform Options and Network modules documentation for details.

Since Ansible 2.3, become can be used on Windows hosts through the
runas method. Become on Windows uses the same inventory setup and
invocation arguments as become on a non-Windows host, so the setup and
variable names are the same as what is defined in this document.

While become can be used to assume the identity of another user, there are other uses for
it with Windows hosts. One important use is to bypass some of the
limitations that are imposed when running on WinRM, such as constrained network
delegation or accessing forbidden system calls like the WUA API. You can use
become with the same user as ansible_user to bypass these limitations
and run commands that are not normally accessible in a WinRM session.

Note

Prior to Ansible 2.4, become would only work when ansible_winrm_transport was
set to either basic or credssp, but since Ansible 2.4 become now works on
all transport types.

Many tasks in Windows require administrative privileges to complete. When using
the runas become method, Ansible will attempt to run the module with the
full privileges that are available to the remote user. If it fails to elevate
the user token, it will continue to use the limited token during execution.

Before Ansible 2.5, a token was only able to be elevated when UAC was disabled
or the remote user had the SeTcbPrivilege assigned. This restriction has
been lifted in Ansible 2.5 and a user that is a member of the
BUILTIN\Administrators group should have an elevated token during the
module execution.

To determine the type of token that Ansible was able to get, run the following
task and check the output:

-win_whoami:become:yes

Under the GROUPINFORMATION section, the MandatoryLabel entry
determines whether the user has Administrative rights. Here are the labels that
can be returned and what they mean:

Medium: Ansible failed to get an elevated token and ran under a limited
token. Only a subset of the privileges assigned to user are available during
the module execution and the user does not have administrative rights.

High: An elevated token was used and all the privileges assigned to the
user are available during the module execution.

System: The NTAUTHORITY\System account is used and has the highest
level of privileges available.

The output will also show the list of privileges that have been granted to the
user. When State==Disabled, the privileges have not been enabled but can be
if required. In most scenarios these privileges are automatically enabled when
required.

If running on a version of Ansible that is older than 2.5 or the normal
runas escalation process fails, an elevated token can be retrieved by:

Set the become_user to System which has full control over the
operating system.

Grant SeTcbPrivilege to the user Ansible connects with on
WinRM. SeTcbPrivilege is a high-level privilege that grants
full control over the operating system. No user is given this privilege by
default, and care should be taken if you grant this privilege to a user or group.
For more information on this privilege, please see
Act as part of the operating system.
You can use the below task to set this privilege on a Windows host:

Turn UAC off on the host and reboot before trying to become the user. UAC is
a security protocol that is designed to run accounts with the
leastprivilege principle. You can turn UAC off by running the following
tasks:

Prior to Ansible version 2.5, become only worked with a local or domain
user account. Local service accounts like System or NetworkService
could not be used as become_user in these older versions. This restriction
has been lifted since the 2.5 release of Ansible. The three service accounts
that can be set under become_user are:

System

NetworkService

LocalService

Because local service accounts do not have passwords, the
ansible_become_password parameter is not required and is ignored if
specified.

As a general security best practice, you should avoid allowing accounts without passwords.

Ansible can be used to become an account that does not have a password (like the
Guest account). To become an account without a password, set up the
variables like normal but either do not define ansible_become_pass or set
ansible_become_pass:''.

Ansible 2.5 adds the become_flags parameter to the runas become method.
This parameter can be set using the become_flags task directive or set in
Ansible’s configuration using ansible_become_flags. The two valid values
that are initially supported for this parameter are logon_type and
logon_flags.

Note

These flags should only be set when becoming a normal user account, not a local service account like LocalSystem.

The key logon_type sets the type of logon operation to perform. The value
can be set to one of the following:

interactive: The default logon type. The process will be run under a
context that is the same as when running a process locally. This bypasses all
WinRM restrictions and is the recommended method to use.

batch: Runs the process under a batch context that is similar to a
scheduled task with a password set. This should bypass most WinRM
restrictions and is useful if the become_user is not allowed to log on
interactively.

new_credentials: Runs under the same credentials as the calling user, but
outbound connections are run under the context of the become_user and
become_password, similar to runas.exe/netonly. The logon_flags
flag should also be set to netcredentials_only. Use this flag if
the process needs to access a network resource (like an SMB share) using a
different set of credentials.

network: Runs the process under a network context without any cached
credentials. This results in the same type of logon session as running a
normal WinRM process without credential delegation, and operates under the same
restrictions.

network_cleartext: Like the network logon type, but instead caches
the credentials so it can access network resources. This is the same type of
logon session as running a normal WinRM process with credential delegation.

The logon_flags key specifies how Windows will log the user on when creating
the new process. The value can be set to none or multiple of the following:

with_profile: The default logon flag set. The process will load the
user’s profile in the HKEY_USERS registry key to HKEY_CURRENT_USER.

netcredentials_only: The process will use the same token as the caller
but will use the become_user and become_password when accessing a remote
resource. This is useful in inter-domain scenarios where there is no trust
relationship, and should be used with the new_credentialslogon_type.

By default logon_flags=with_profile is set, if the profile should not be
loaded set logon_flags= or if the profile should be loaded with
netcredentials_only, set logon_flags=with_profile,netcredentials_only.

-name:copy a file from a fileshare with custom credentialswin_copy:src:\\server\share\data\file.txtdest:C:\temp\file.txtremote_src:yexvars:ansible_become:yesansible_become_method:runasansible_become_user:DOMAIN\useransible_become_pass:Password01ansible_become_flags:logon_type=new_credentials logon_flags=netcredentials_only-name:run a command under a batch logonwin_whoami:become:yesbecome_flags:logon_type=batch-name:run a command and not load the user profilewin_whomai:become:yesbecome_flags:logon_flags=

Running a task with async and become on Windows Server 2008, 2008 R2
and Windows 7 does not work.

By default, the become user logs on with an interactive session, so it must
have the right to do so on the Windows host. If it does not inherit the
SeAllowLogOnLocally privilege or inherits the SeDenyLogOnLocally
privilege, the become process will fail. Either add the privilege or set the
logon_type flag to change the logon type used.

Prior to Ansible version 2.3, become only worked when
ansible_winrm_transport was either basic or credssp. This
restriction has been lifted since the 2.4 release of Ansible for all hosts
except Windows Server 2008 (non R2 version).