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

spec.admin_password_secret

<platform>-admin-password

Platform gateway application/encryption key

spec.db_fields_encryption_secret

<platform>-db-fields-encryption

Automation controller credential-encryption key

spec.controller.secret_key_secret

<controller>-secret-key

Gateway database connection

spec.database.database_secret for an external database

<platform>-gateway-postgres-configuration with the managed database

Controller database connection

spec.controller.database_secret for an external database

<platform>-controller-postgres-configuration with the managed database

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