15. Secret handling and connection security
This document distinguishes platform operational Secrets from the automation credentials stored by automation controller, and describes the connections that use them.
15.1. Secret Handling
Koios Automation Platform uses three categories of secrets:
user passwords for local users of the platform (stored by the platform gateway)
secrets for automation controller operational use (database password, message bus password, etc.)
secrets for automation use (SSH keys, cloud credentials, external password vault credentials, etc.)
15.1.1. User passwords for local users
Local users log in through the platform gateway, which stores their passwords hashed with Argon2 (OWASP-recommended parameters); passwords hashed earlier with PBKDF2 are still accepted. The platform does not store the passwords that users enter in an external provider (LDAP, SAML, OIDC and others).
15.1.2. Secret handling for operational use
The gateway, automation controller, Event-Driven Ansible and automation hub have separate application keys and database connections. A gateway key is not a substitute for the controller’s credential-encryption key or for the keys of the other services.
In the names below, <platform> is the KoiosPlatform name. <controller> is
spec.controller.name, or <platform>-controller by default. The following defaults are
created only when the corresponding user-supplied Secret is not configured:
Component / purpose |
Configuration |
Default Secret name |
|---|---|---|
Platform gateway initial administrator password |
|
|
Platform gateway application/encryption key |
|
|
Automation controller credential-encryption key |
|
|
Gateway database connection |
|
|
Controller database connection |
|
|
An adopted controller can retain its existing database Secret. With external databases, the administrator supplies the connection Secrets; the operator does not generate replacements for them. Event-Driven Ansible and automation hub also require their own connections and keys; see Configure the platform and KoiosPlatform for component configuration.
Public TLS certificates belong to the platform’s Route or Ingress configuration, not to an
independent controller ingress. spec.route_tls_secret and spec.ingress_tls_secret name
Secrets supplied by the administrator; there is no single generated name to assume for either.
See External Access below.
Operational Secrets are in the platform namespace and are mounted into the containers that need them. Restrict Kubernetes permissions to read or modify Secrets and to execute commands in pods. Do not print their data in diagnostics or issue reports.
Preserve all component keys with their database backups; see Backup and Restore. Replacing an encryption key independently of its database can make stored credentials unreadable. Treat a suspected compromise as a recovery and rotation operation, not as a routine edit of a Secret.
15.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:
all secret fields of all credential types (passwords, secret keys, authentication tokens, secret cloud credentials)
secret tokens and passwords for external services defined in automation controller settings
“password” type survey fields 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/decryption process derives the AES-256 bit encryption key
from the SECRET_KEY (described above), the field name of the model field
and the database assigned auto-incremented record ID. Thus, if any
attribute used in the key generation process changes, automation controller fails to
correctly decrypt the secret. Automation controller is designed such that the
SECRET_KEY is never readable in playbooks automation controller launches, that
these secrets are never readable by automation controller users, and no secret field values
are ever made available via the automation controller REST API. If a secret value is
used in a playbook, we recommend using no_log on the task so that
it is not accidentally logged.
15.2. Connection Security
15.2.1. Internal Services
Automation controller connects to the following services as part of internal operation:
PostgreSQL database
A Valkey key/value store
The controller connects to its Valkey sidecar over a local Unix socket, restricted to the awx service user. The gateway has its own Redis/Valkey connection; this local-socket description does not apply to every component.
Database connections use password authentication over TCP. The managed PostgreSQL database has no TLS. For an external database, configure the component’s connection Secret with the required sslmode and provide its trusted CA through spec.bundle_cacert_secret when needed; see Configure the platform.
15.2.2. External Access
The platform gateway is the shared entry point for the UI and service APIs. With HTTPS exposure, TLS terminates at the OpenShift Route (edge termination) or the Kubernetes Ingress controller before the request reaches the gateway. Configure route_tls_secret or ingress_tls_secret on KoiosPlatform; see Configure the platform and KoiosPlatform. The operator keeps the child controller’s ingress_type set to none: a separate controller ingress certificate does not configure the platform address.
The cluster’s Route or Ingress configuration controls the public TLS profile. Change declarative configuration, not files inside generated pods, which the operator replaces.
15.2.3. Managed Nodes
Automation controller also connects to managed machines and services as part of automation. All connections to managed machines are done via standard secure mechanism as specified such as SSH, WinRM, SSL/TLS, and so on - each of these inherits configuration from the system configuration for the feature in question (such as the system OpenSSL configuration).