Chapter 12. Secret handling and connection security
Automation controller handles secrets and connections securely.
12.1. Secret handling
Automation controller manages three sets of secrets:
- User passwords for local automation controller users.
- Secrets for automation controller operational use, such as database password or message bus password.
- Secrets for automation use, such as SSH keys, cloud credentials, or external password vault credentials.
You must have 'local' user access for the following users:
- postgres
- awx
- redis
- receptor
- nginx
12.1.1. User passwords for local users
Automation controller hashes local automation controller user passwords with the PBKDF2 algorithm using a SHA256 hash. Users who authenticate by external account mechanisms, such as LDAP, SAML, and OAuth, do not have any password or secret stored.
12.1.2. Secret handling for operational use
The operational secrets found in automation controller are as follows:
-
/etc/tower/SECRET_KEY
: A secret key used for encrypting automation secrets in the database. If theSECRET_KEY
changes or is unknown, you cannot access encrypted fields in the database. -
/etc/tower/tower.{cert,key}
: An SSL certificate and key for the automation controller web service. A self-signed certificate or key is installed by default; you can provide a locally appropriate certificate and key. -
A database password in
/etc/tower/conf.d/postgres.py
and a message bus password in/etc/tower/conf.d/channels.py
.
These secrets are stored unencrypted on the automation controller server, because they are all needed to be read by the automation controller service at startup in an automated fashion. All secrets are protected by UNIX permissions, and restricted to root and the automation controller awx service user.
If you need to hide these secrets, the files that these secrets are read from are interpreted by Python. You can adjust these files to retrieve these secrets by some other mechanism anytime a service restarts. This is a customer provided modification that might need to be reapplied after every upgrade. Red Hat Support and Red Hat Consulting have examples of such modifications.
If the secrets system is down, automation controller cannot get the information and can fail in a way that is recoverable once the service is restored. Using some redundancy on that system is highly recommended.
If you believe the SECRET_KEY
that automation controller generated for you has been compromised and needs to be regenerated, you can run a tool from the installer that behaves much like the automation controller backup and restore tool.
Ensure that you backup your automation controller database before you generate a new secret key.
To generate a new secret key:
- Follow the procedure described in the Backing up and Restoring section.
Use the inventory from your install (the same inventory with which you run backups and restores), and run the following command:
setup.sh -k.
A backup copy of the previous key is saved in /etc/tower/
.
12.1.3. Secret handling for automation use
Automation controller stores a variety of secrets in the database that are either used for automation or are a result of automation.
These secrets include the following:
- All secret fields of all credential types, including passwords, secret keys, authentication tokens, and secret cloud credentials.
- Secret tokens and passwords for external services defined automation controller settings.
- "password" type survey field entries.
To encrypt secret fields, automation controller uses AES in CBC mode with a 256-bit key for encryption, PKCS7 padding, and HMAC using SHA256 for authentication.
The encryption or decryption process derives the AES-256 bit encryption key from the SECRET_KEY
, the field name of the model field and the database assigned auto-incremented record ID. Therefore, if any attribute used in the key generation process changes, the automation controller fails to correctly decrypt the secret.
Automation controller is designed so that:
-
The
SECRET_KEY
is never readable in playbooks that automation controller launches. - These secrets are never readable by automation controller users.
- No secret field values are ever made available by the automation controller REST API.
If a secret value is used in a playbook, it is recommended that you use no_log
on the task so that it is not accidentally logged.
12.2. Connection security
Automation controller allows for connections to internal services, external access, and managed nodes.
You must have 'local' user access for the following users:
- postgres
- awx
- redis
- receptor
- nginx
12.2.1. Internal services
Automation controller connects to the following services as part of internal operation:
- PostgreSQL database
- The connection to the PostgreSQL database is done by password authentication over TCP, either through localhost or remotely (external database). This connection can use PostgreSQL’s built-in support for SSL/TLS, as natively configured by the installer support. SSL/TLS protocols are configured by the default OpenSSL configuration.
- A Redis key or value store
- The connection to Redis is over a local UNIX socket, restricted to the awx service user.
12.2.2. External access
Automation controller is accessed via standard HTTP/HTTPS on standard ports, provided by Nginx. A self-signed certificate or key is installed by default; you can provide a locally appropriate certificate and key. SSL/TLS algorithm support is configured in the /etc/nginx/nginx.conf
configuration file. An "intermediate" profile is used by default, that you can configure. You must reapply changes after each update.
12.2.3. Managed nodes
Automation controller connects to managed machines and services as part of automation. All connections to managed machines are done by standard secure mechanisms, such as SSH, WinRM, or SSL/TLS. Each of these inherits configuration from the system configuration for the feature in question, such as the system OpenSSL configuration.