Documentation

20. Security

The following sections will help you gain an understanding of how Ansible Tower handles and lets you control file system security.

All playbooks are executed via the awx file system user. For running jobs, Ansible Tower defaults to offering job isolation via Linux namespacing and chroots. This projection ensures jobs can only access playbooks and roles from the Project directory for that job template and common locations such as /opt. Playbooks are not able to access roles, playbooks, or data from other Projects by default.

If you need to disable this protection (not recommended), you can edit /etc/tower/settings.py and set AWX_PROOT_ENABLED to False.

Note

In this scenario, playbooks have access to the file system and all that that implies; therefore, users who have access to edit playbooks must be trusted.

For credential security, users may choose to upload locked SSH keys and set the unlock password to “ask”. You can also choose to have the system prompt them for SSH credentials or sudo passwords rather than having the system store them in the database.

20.1. Playbook Access and Information Sharing

By default, Tower’s multi-tenant security prevents playbooks from reading files outside of their project directory. In older version of Ansible Tower a system called proot was used to isolate tower job processes from the rest of the system. For Tower version 3.1 and later, bubblewrap is used instead, due to its light weight and maintained process isolation system.

By default bubblewrap is enabled, but can be turned off via the Configure Tower screen in the Tower User Interface or from the tower settings file.

_images/ug-configure-tower-jobs-process-isolation.png

To access the Configure Tower screen, refer to the Tower Configuration section. To customize your bubblewrap settings through the settings file, navigate to the /etc/tower/settings.py file.

Process isolation, when enabled, will be used for the following Job types:

  • Job Templates - Launching jobs from regular job templates
  • Ad-hoc Commands - Launching ad-hoc commands against one or more hosts in an inventory

By default, process isolation hides the following directories from the above tasks:

  • /etc/tower - to prevent exposing Tower configuration
  • /var/lib/awx - with the exception of the current project being used (for regular job templates)
  • /var/log
  • /tmp (or whatever the system temp directory is) - with the exception of the processes’ own temp files.

You can customize what to hide or expose when running playbooks, using the Configure Tower screen or the settings file. Refer the next section, Bubblewrap functionality and variables for more information.

20.1.1. Bubblewrap functionality and variables

The bubblewrap functionality in Ansible Tower limits which directories on the Tower file system are available for playbooks to see and use during playbook runs. You may find that you need to customize your bubblewrap settings in some cases. To fine tune your usage of bubblewrap, there are certain variables that can be set.

To disable bubblewrap support for running jobs (playbook runs only):

AWX_PROOT_ENABLED = False

To enable bubblewrap support for running jobs (playbook runs only):

AWX_PROOT_ENABLED = True

By default, the Tower will use the system’s tmp directory (/tmp by default) as its staging area. This can be changed in the Job Isolation Execution Path field of the Configure tower screen, or by updating the following entry in the settings file:

AWX_PROOT_BASE_PATH = "/opt/tmp"

If there is other information on the system that is sensitive and should be hidden, you can specify those in the Configure Tower screen in the Paths to Hide to Isolated Jobs or by updating the following entry in the settings file:

AWX_PROOT_HIDE_PATHS = ['/list/of/', '/paths']

If there are any directories that should specifically be exposed, you can specify those in the Configure Tower screen in the Paths to Expose to Isolated Jobs or by updating the following entry in the settings file:

AWX_PROOT_SHOW_PATHS = ['/list/of/', '/paths']

Note

The primary file you may want to add to AWX_PROOT_SHOW_PATHS is /var/lib/awx/.ssh, if your playbooks need to use keys or settings defined there.

If you made changes in the settings file, be sure to restart services with the ansible-tower-service restart command after your changes have been saved.

20.2. Role-Based Access Controls

Role-Based Access Controls (RBAC) are built into Tower and allow Tower administrators to delegate access to server inventories, organizations, and more. Administrators can also centralize the management of various credentials, allowing end users to leverage a needed secret without ever exposing that secret to the end user. RBAC controls allow Tower to help you increase security and streamline management.

RBACs are easiest to think of in terms of Roles which define precisely who or what can see, change, or delete an “object” for which a specific capability is being set. In releases prior to Ansible Tower version 3.0, RBAC was thought of in terms of granting permissions to users or teams. Starting with Tower 3.0, RBAC is best thought of as granting roles to users or teams, which is a more intuitive approach.

There are a few main concepts that you should become familiar with regarding Tower’s RBAC design–roles, resources, and users. Users can be members of a role, which gives them certain access to any resources associated with that role, or any resources associated with “descendant” roles.

A role is essentially a collection of capabilities. Users are granted access to these capabilities and Tower’s resources through the roles to which they are assigned or through roles inherited through the role hierarchy.

Roles associate a group of capabilities with a group of users. All capabilities are derived from membership within a role. Users receive capabilities only through the roles to which they are assigned or through roles they inherit through the role hierarchy. All members of a role have all capabilities granted to that role. Within an organization, roles are relatively stable, while users and capabilities are both numerous and may change rapidly. Users can have many roles.

20.2.1. Role Hierarchy and Access Inheritance

Imagine that you have an organization named “SomeCompany” and want to allow two people, “Josie” and “Carter”, access to manage all the settings associated with that organization. You should made both people members of the organization’s admin_role.

user-role-relationship

Often, you will have many Roles in a system and you will want some roles to include all of the capabilities of other roles. For example, you may want a System Administrator to have access to everything that an Organization Administrator has access to, who has everything that a Project Administrator has access to, and so on.

This concept is referred to as the ‘Role Hierarchy’:

  • Parent roles get all capabilities bestowed on any child roles
  • Members of roles automatically get all capabilities for the role they are a member of, as well as any child roles.

The Role Hierarchy is represented by allowing Roles to have “Parent Roles”. Any capability that a Role has is implicitly granted to any parent roles (or parents of those parents, and so on).

rbac-role-hierarchy

Often, you will have many Roles in a system and you will want some roles to include all of the capabilities of other roles. For example, you may want a System Administrator to have access to everything that an Organization Administrator has access to, who has everything that a Project Administrator has access to, and so on. We refer to this concept as the ‘Role Hierarchy’ and it is represented by allowing Roles to have “Parent Roles”. Any capability that a Role has is implicitly granted to any parent roles (or parents of those parents, and so on). Of course Roles can have more than one parent, and capabilities are implicitly granted to all parents.

rbac-heirarchy-morecomplex

RBAC controls also give you the capability to explicitly permit User and Teams of Users to run playbooks against certain sets of hosts. Users and teams are restricted to just the sets of playbooks and hosts to which they are granted capabilities. And, with Tower, you can create or import as many Users and Teams as you require–create users and teams manually or import them from LDAP or Active Directory.

RBACs are easiest to think of in terms of who or what can see, change, or delete an “object” for which a specific capability is being determined.

20.2.2. Applying RBAC

The following sections cover how to apply Tower’s RBAC system in your environment.

20.2.2.1. Editing Users

When editing a user, a Tower system administrator may specify the user as being either a System Administrator (also referred to as the Superuser) or a System Auditor.

  • System administrators implicitly inherit all capabilities for all objects (read/write/execute) within the Tower environment.
  • System Auditors implicitly inherit the read-only capability for all objects within the Tower environment.

20.2.2.2. Editing Organizations

When editing an organization, system administrators may specify the following roles:

  • One or more users as organization administrators
  • One or more users as organization auditors
  • And one or more users (or teams) as organization members

Users/teams that are members of an organization can view their organization administrator.

Users who are organization administrators implicitly inherit all capabilities for all objects within that Tower organization.

Users who are organization auditors implicitly inherit the read-only capability for all objects within that Tower organization.

20.2.2.3. Editing Projects in an Organization

When editing a project in an organization for which they are the administrator, system administrators and organization administrators may specify:

  • One or more users/teams that are project administrators
  • One or more users/teams that are project members
  • And one or more users/teams that may update the project from SCM, from among the users/teams that are members of that organization.

Users who are members of a project can view their project administrators.

Project administrators implicitly inherit the capability to update the project from SCM.

Administrators can also specify one or more users/teams (from those that are members of that project) that can use that project in a job template.

20.2.2.4. Creating Inventories and Credentials within an Organization

All access that is granted to use, read, or write credentials is now handled through roles. You no longer set the “team” or “user” for a credential. Instead, you use Tower’s RBAC system to grant ownership, auditor, or usage roles.

System administrators and organization administrators may create inventories and credentials within organizations under their administrative capabilities.

Whether editing an inventory or a credential, System administrators and organization administrators may specify one or more users/teams (from those that are members of that organization) to be granted the usage capability for that inventory or credential.

System administrators and organization administrators may specify one or more users/teams (from those that are members of that organization) that have the capabilities to update (dynamic or manually) an inventory. Administrators can also execute ad hoc commands for an inventory.

20.2.2.5. Editing Job Templates

System administrators, organization administrators, and project administrators, within a project under their administrative capabilities, may create and modify new job templates for that project.

When editing a job template, administrators (Tower, organization, and project) can select among the inventory and credentials in the organization for which they have usage capabilities or they may leave those fields blank so that they will be selected at runtime.

Additionally, they may specify one or more users/teams (from those that are members of that project) that have execution capabilities for that job template. The execution capability is valid regardless of any explicit capabilities the user/team may have been granted against the inventory or credential specified in the job template.

20.2.2.6. User View

A user can:

  • See any organization or project for which they are a member
  • Create their own credential objects which only belong to them
  • See and execute any job template for which they have been granted execution capabilities

If a job template a user has been granted execution capabilities on does not specify an inventory or credential, the user will be prompted at run-time to select among the inventory and credentials in the organization they own or have been granted usage capabilities.

Users that are job template administrators can make changes to job templates; however, to make changes to the inventory, project, playbook, or credentials used in the job template, the user must also have the “Use” role for the project, inventory, and all credentials currently being used or being set.

20.2.3. Roles

As stated earlier in this documentation, all access that is granted to use, read, or write credentials is now handled through roles, and roles are defined for a resource.

20.2.3.1. Built-in roles

The following table lists the RBAC system roles and a brief description of the how that role is defined with regard to privileges in Tower.

System Role What it can do
System Administrator - System wide singleton Manages all aspects of the system
System Auditor - System wide singleton Views all aspects of the system
Ad Hoc Role - Inventory Runs ad hoc commands on an Inventory
Admin Role - Organizations, Teams, Inventory, Projects, Job Templates Manages all aspects of a defined Organization, Team, Inventory, Project, or Job Template
Auditor Role - All Views all aspects of a defined Organization, Project, Inventory, or Job Template
Execute Role - Job Templates Runs assigned Job Template
Member Role - Organization, Team User is a member of a defined Organization or Team
Read Role - Organizations, Teams, Inventory, Projects, Job Templates Views all aspects of a defined Organization, Team, Inventory, Project, or Job Template
Update Role - Project Updates the Project from the configured source control management system
Update Role - Inventory Updates the Inventory using the cloud source update system
Owner Role - Credential Owns and manages all aspects of this Credential
Use Role - Credential, Inventory, Project Uses the Credential, Inventory, or Project in a Job Template

A Singleton Role is a special role that grants system-wide permissions. Ansible Tower currently provides two built-in Singleton Roles but the ability to create or customize a Singleton Role is not supported at this time.