Chapter 32. Security
The following sections describe how automation controller handles and enables you to control file system security.
All playbooks are executed through the awx file system user. For running jobs, automation controller offers job isolation through the use of Linux containers. This protection ensures that jobs can only access playbooks, roles, and data from the Project directory for that job template.
For credential security, you can choose to upload locked SSH keys and set the unlock password to "ask". You can also choose to have the system prompt for SSH credentials or sudo passwords rather than having the system store them in the database.
32.1. Playbook Access and Information Sharing
Automation controller’s use of automation execution environments and Linux containers prevents playbooks from reading files outside of their project directory.
By default, the only data exposed to the ansible-playbook process inside the container is the current project being used.
You can customize this in the Job Settings and expose additional directories from the host into the container.
32.1.1. Isolation functionality and variables
Automation controller uses container technology to isolate jobs from each other. By default, only the current project is exposed to the container running a job template.
If you need to expose additional directories, you must customize your playbook runs. To configure job isolation, you can set variables.
By default, automation controller uses the system’s tmp directory (/tmp by default) as its staging area. This can be changed in the Job Execution Path field of the Jobs settings page, or in the REST API at /api/v2/settings/jobs:
AWX_ISOLATION_BASE_PATH = "/opt/tmp"
If there are any additional directories that should specifically be exposed from the host to the container that playbooks run in, you can specify those in the Paths to Expose to Isolated Jobs field of the Jobs settings page, or in the REST API at /api/v2/settings/jobs:
AWX_ISOLATION_SHOW_PATHS = ['/list/of/', '/paths']
If your playbooks need to use keys or settings defined in AWX_ISOLATION_SHOW_PATHS, then add this file to /var/lib/awx/.ssh.
The fields described here can be found on the Jobs settings page:
32.2. Role-Based Access Controls
Role-Based Access Controls (RBAC) are built into automation controller and enable administrators to delegate access to server inventories, organizations, and more. Administrators can also centralize the management of various credentials, enabling users to use a required secret without exposing that secret to the user. You can use RBAC to enable automation controller to increase security and streamline management.
RBAC is the practice of granting roles to users or teams. RBACs can be thought 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.
The main concepts of automation controller’s RBAC design roles, resources, and users are as follows:
- 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 a collection of capabilities.
- Users are granted access to these capabilities and the automation controller’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.
32.2.1. Role hierarchy and access inheritance
Imagine that you have an organization named "SomeCompany" and want to give two people, "Josie" and "Carter", access to manage all the settings associated with that organization. To do this, you must make both people members of the organization’s admin_role.
There are frequently many Roles in a system, some of which you want to include all of the capabilities of other roles. For example, you might 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.
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 permitting Roles to have "Parent Roles". Any capability that a Role has is implicitly granted to any parent roles (or parents of those parents).
Roles can have more than one parent, and capabilities are implicitly granted to all parents.
RBACs also enable you to explicitly permit Users 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. With automation controller, 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.
32.2.1.1. Use of RBAC
The following describes how to apply automation controller’s RBAC system in your environment.
32.2.1.1.1. Edit Users
When editing a user, an automation controller system administrator can 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 (read/write/execute) for all objects within the environment.
- System Auditors implicitly inherit the read-only capability for all objects within the environment.
32.2.1.1.2. Edit Organizations
When editing an organization, system administrators can specify the following roles:
- One or more users as organization administrators
- One or more users as organization auditors
- One or more users (or teams) as organization members
Users and 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 organization.
Users who are organization auditors implicitly inherit the read-only capability for all objects within that organization.
32.2.1.1.3. Edit Projects in an Organization
When editing a project in an organization for which they are the administrator, system administrators and organization administrators can specify:
- One or more users or teams that are project administrators
- One or more users or teams that are project members
- One or more users or teams that can update the project from SCM, from among the users and 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 or teams (from those that are members of that project) that can use that project in a job template.
32.2.1.1.4. Create Inventories and Credentials within an Organization
All access that is granted to use, read, or write credentials is handled through roles, which use automation controller’s RBAC system to grant ownership, auditor, or usage roles.
System administrators and organization administrators can create inventories and credentials within organizations under their administrative capabilities.
Whether editing an inventory or a credential, System administrators and organization administrators can specify one or more users or 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 can specify one or more users or 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.
32.2.1.1.5. Edit Job Templates
System administrators, organization administrators, and project administrators, within a project under their administrative capabilities, can create and modify new job templates for that project.
When editing a job template, administrators (automation controller, organization, and project) can select inventory and credentials in the organization for which they have usage capabilities, or they can leave those fields blank so that they are selected at runtime.
Additionally, they can specify one or more users or 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 or team have been granted against the inventory or credential specified in the job template.
32.2.1.1.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 for which a user has been granted execution capabilities does not specify an inventory or credential, the user is 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 change to the inventory, project, playbook, credentials, or instance groups used in the job template, the user must also have the "Use" role for the project and inventory currently being used or being set.
32.2.1.2. Roles
All access that is granted to use, read, or write credentials is handled through roles, and roles are defined for a resource.
32.2.1.2.1. Built-in roles
The following table lists the RBAC system roles with a brief description of how that role is defined with regard to privileges in automation controller:
| 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, IGs, CGs | Uses the Credential, Inventory, Project, IGs, or CGs in a Job Template |
A Singleton Role is a special role that grants system-wide permissions. Automation controller currently provides two built-in Singleton Roles but the ability to create or customize a Singleton Role is not supported at this time.
32.2.1.3. Common Team Roles - "Personas"
Automation controller support personnel typically works to ensure that automation controller is available, and manage it in a way as to balance supportability and ease-of-use for users. Automation controller support personnel often assign Organization Owner or Administrator roles to users to enable them to create a new Organization or add members from their team that the respective access requires. This minimizes the number of supporting individuals and focuses more on maintaining uptime of the service and assisting users who are using automation controller.
The following table lists some common roles managed by the automation controller Organization:
| System Role (for Organizations) | Common User Roles | Description |
|---|---|---|
| Owner | Team Lead - Technical Lead | This user can control access for other users in their organization. They can add, remove and grant users specific access to projects, inventories, and job templates. This type of user can also create, remove or modify any aspect of an organization’s projects, templates, inventories, teams, and credentials. |
| Auditor | Security Engineer - Project Manager | This account can view all aspects of the organization in read-only mode. This might be a good role for a user who checks in and maintains compliance. This might also be a good role for a service account who manages or ships job data from automation controller to some other data collector. |
| Member - Team | All other users | By default, these users as an organization member do not receive any access to any aspect of the organization. To grant them access the respective organization owner must add them to their respective team and grant them Administrator, Execute, Use, Update, and Ad-hoc permissions to each component of the organization’s projects, inventories, and job templates. |
| Member - Team "Owner" | Power users - Lead Developer | Organization Owners can provide "admin" through the team interface, over any component of their organization including projects, inventories, and job templates. These users are able to modify and use the respective component given access. |
| Member - Team "Execute" | Developers - Engineers | This is the most common role and enables the organization member to execute job templates and read permission to the specific components. This permission applies to templates. |
| Member - Team "Use" | Developers - Engineers | This permission applies to an organization’s credentials, inventories, and projects. This permission enables a user to use the respective component within their job template. |
| Member - Team "Update" | Developers - Engineers | This permission applies to projects. Enables the user to run an SCM update on a project. |
32.3. Function of roles: editing and creating
Organization "resource roles" functionality are specific to a certain resource type - such as workflows. Being a member of such a role usually provides two types of permissions. If a user is given a "workflow admin role" for the organization "Default", then they have the following permissions:
- This user can create new workflows in the organization "Default"
- This user can edit all workflows in the "Default" organization
One exception is job templates, where having the role is independent of creation permission. For more information, see Job Templates.
32.3.1. Independence of resource roles and organization membership roles
Resource-specific organization roles are independent of the organization roles of administrator and member. Having the "workflow administrator role" for the "Default" organization does not enable a user to view all users in the organization, but having a "member" role in the "Default" organization does. The two types of roles are delegated independently of each other.
32.3.1.1. Necessary permissions to edit job templates
Users can edit fields not impacting job runs (non-sensitive fields) with a Job Template administrator role alone. However, to edit fields that impact job runs in a job template, a user must have the following:
- An admin role for the job template and container groups
- A use role for related projects
- A use role for related inventories
- A use role for related instance groups
An "organization job template admin" role was introduced, but having this role is not sufficient by itself to edit a job template within the organization if the user does not have a use role for the project, inventory, or instance group, or an administrator role to the container group that a job template uses.
To delegate full job template control (within an organization) to a user or team, you must grant the team or user all three organization-level roles:
- job template administrator
- project administrator
- inventory administrator
This ensures that the user (or all users who are members of the team with these roles) has full access to modify job templates in the organization. If a job template uses an inventory or project from another organization, the user with these organization roles can still not have permission to modify that job template. For clarity of permission management, do not mix projects or inventories from different organizations.
32.3.1.2. RBAC permissions
Each role must have a content object, for instance, the organization administrator role has a content object of the organization. To delegate a role, you must have administrator permission for the content object, with some exceptions that would result in you being able to reset a user’s password.
Parent is the organization.
Allow is what this new permission will explicitly allow.
Scope is the parent resource that this new role is created on. For example: Organization.project_create_role.
It is assumed that the creator of the resource is given the administrator role for that resource. Instances where resource creation does not also imply resource administration are explicitly called out.
The rules associated with each administrator type are as follows:
Project Admin
- Allow: Create, read, update, delete any project
- Scope: Organization
- User Interface: Project Add Screen - Organizations
Inventory Admin
- Parent: Org admin
- Allow: Create, read, update, delete any inventory
- Scope: Organization
- User Interface: Inventory Add Screen - Organizations
As with the Use role, if you assign Project Administrator and Inventory Administrator roles to a user, it enables them to create Job Templates (not workflows) for your organization.
Credential Admin
- Parent: Org admin
- Allow: Create, read, update, delete shared credentials
- Scope: Organization
- User Interface: Credential Add Screen - Organizations
Notification Admin
- Parent: Org admin
- Allow: Assignment of notifications
- Scope: Organization
Workflow Admin
- Parent: Org admin
- Allow: Create a workflow
- Scope: Organization
Org Execute
- Parent: Org admin
- Allow: Executing job templates and workflow job templates
- Scope: Organization
The following is a sample scenario showing an organization with its roles and which resources each have access to:
