Documentation

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

16.1. Playbook Access and Information Sharing

By default, Tower’s multi-tenant security prevents playbooks from reading files outside of their project directory. To share information between playbooks or to read files on the file system outside of their project directory, you must edit /etc/tower/settings.py and add the directories that are available to the AWX_PROOT_SHOW_PATHS setting.

The following paths, plus any user specified paths, are hidden by AWX_PROOT_HIDE_PATHS:

  • /etc/tower
  • /var/lib/awx
  • /var/log
  • /tmp
  • /var/lib/awx/projects
  • /var/lib/awx/job_status

The following paths, plus any user specified paths, are shown by AWX_PROOT_SHOW_PATHS:

  • /var/lib/awx/projects/<current_project>
  • /tmp/ansible_tower_xxxxx

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.

16.2. PRoot functionality and variables

The PRoot 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 PRoot settings in some cases. To fine tune your usage of PRoot, there are certain variables that can be set:

# Enable proot support for running jobs (playbook runs only).
AWX_PROOT_ENABLED = False

# Command/path to proot.
AWX_PROOT_CMD = 'proot'

# Additional paths to hide from jobs using proot.
AWX_PROOT_HIDE_PATHS = []

# Additional paths to show for jobs using proot.
AWX_PROOT_SHOW_PATHS = []

To customize your PRoot settings, navigate to the /etc/tower/settings.py file. Once your changes have been saved, restart services with the ansible-tower-service restart command.

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

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

16.3.2. Applying RBAC

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

16.3.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 an Auditor.

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

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

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

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

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

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.

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.

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

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

16.3.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, Projects, Inventory, Projects, Job Templates Manages all aspects of a defined Organization, Project, Inventory, or Job Template
Auditor Role - Organizations, Projects, Inventory, Projects, Job Templates 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 - All Views settings for a defined Organization, Project, Inventory, or Job Template
SCM 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 you can create and is intended for system wide roles.