Configure custom TLS certificates

Red Hat Ansible Automation Platform uses X.509 certificate and key pairs to secure traffic. These certificates secure internal traffic between Ansible Automation Platform components and external traffic for public UI and API connections.

There are two primary ways to manage TLS certificates for your Ansible Automation Platform deployment:

  1. Ansible Automation Platform generated certificates (this is the default)
  2. User-provided certificates

Ansible Automation Platform generated certificates
Copy link

By default, the installation program creates a self-signed Certificate Authority (CA) and uses it to generate self-signed TLS certificates for all Ansible Automation Platform services.

The self-signed CA certificate and key are generated on one node under the ~/aap/tls/ directory and copied to the same location on all other nodes. This CA is valid for 10 years after the initial creation date.

Self-signed certificates are not part of any public chain of trust. The installation program creates a certificate truststore that includes the self-signed CA certificate under ~/aap/tls/extracted/ and bind-mounts that directory to each Ansible Automation Platform service container under /etc/pki/ca-trust/extracted/. This allows each Ansible Automation Platform component to validate the self-signed certificates of the other Ansible Automation Platform services. The CA certificate can also be added to the truststore of other systems or browsers as needed.

User-provided certificates
Copy link

Set specific variables in your inventory file to replace self-signed certificates with your own TLS certificates and keys. These must be generated by a public or organizational CA before beginning the installation.

Use a custom CA to generate all TLS certificates
Copy link

Use this method when you want Ansible Automation Platform to generate all of the certificates, but you want them signed by a custom CA rather than the default self-signed certificates.

About this task
Copy link

When you use ca_tls_cert and ca_tls_key, the installation program automatically creates TLS certificates for each Ansible Automation Platform service using your provided CA certificate. You do not need to define individual service certificate variables (such as gateway_tls_cert, controller_tls_cert, or hub_tls_cert) because the installation program generates these certificates for you.

Procedure
Copy link

To use a custom Certificate Authority (CA) to generate TLS certificates for all Ansible Automation Platform services, set the following variables in your inventory file: 
ca_tls_cert=<path_to_ca_tls_certificate>
ca_tls_key=<path_to_ca_tls_key>

Where:

ca_tls_cert
is the path to your custom CA certificate file.
ca_tls_key
is the path to the key file for your custom CA certificate.

Provide custom TLS certificates for each service
Copy link

Use this method if your organization manages TLS certificates outside of Ansible Automation Platform and requires manual provisioning.

Procedure
Copy link

  • To manually provide TLS certificates for each individual service (for example, automation controller, automation hub, and Event-Driven Ansible), set the following variables in your inventory file: 
    # Platform gateway
gateway_tls_cert=<path_to_tls_certificate>
gateway_tls_key=<path_to_tls_key>
gateway_pg_tls_cert=<path_to_tls_certificate>
gateway_pg_tls_key=<path_to_tls_key>
gateway_redis_tls_cert=<path_to_tls_certificate>
gateway_redis_tls_key=<path_to_tls_key>

# Automation controller
controller_tls_cert=<path_to_tls_certificate>
controller_tls_key=<path_to_tls_key>
controller_pg_tls_cert=<path_to_tls_certificate>
controller_pg_tls_key=<path_to_tls_key>

# Automation hub
hub_tls_cert=<path_to_tls_certificate>
hub_tls_key=<path_to_tls_key>
hub_pg_tls_cert=<path_to_tls_certificate>
hub_pg_tls_key=<path_to_tls_key>

# Event-Driven Ansible
eda_tls_cert=<path_to_tls_certificate>
eda_tls_key=<path_to_tls_key>
eda_pg_tls_cert=<path_to_tls_certificate>
eda_pg_tls_key=<path_to_tls_key>
eda_redis_tls_cert=<path_to_tls_certificate>
eda_redis_tls_key=<path_to_tls_key>

# PostgreSQL
postgresql_tls_cert=<path_to_tls_certificate>
postgresql_tls_key=<path_to_tls_key>

# Receptor
receptor_tls_cert=<path_to_tls_certificate>
receptor_tls_key=<path_to_tls_key>

# Redis
redis_tls_cert=<path_to_tls_certificate>
redis_tls_key=<path_to_tls_key>
  • If all components share the same fully qualified domain name (FQDN), use the same certificate and key for each service: 
    gateway_tls_cert=/home/user/certs/myhost.example.com.crt
gateway_tls_key=/home/user/certs/myhost.example.com.key
controller_tls_cert=/home/user/certs/myhost.example.com.crt
controller_tls_key=/home/user/certs/myhost.example.com.key
hub_tls_cert=/home/user/certs/myhost.example.com.crt
hub_tls_key=/home/user/certs/myhost.example.com.key
eda_tls_cert=/home/user/certs/myhost.example.com.crt
eda_tls_key=/home/user/certs/myhost.example.com.key
postgresql_tls_cert=/home/user/certs/myhost.example.com.crt
postgresql_tls_key=/home/user/certs/myhost.example.com.key
  • If components are deployed on separate hosts with different FQDNs, provide a unique certificate for each service: 
    
gateway_tls_cert=/home/user/certs/gateway.example.com.crt
gateway_tls_key=/home/user/certs/gateway.example.com.key
controller_tls_cert=/home/user/certs/controller.example.com.crt
controller_tls_key=/home/user/certs/controller.example.com.key
hub_tls_cert=/home/user/certs/hub.example.com.crt
hub_tls_key=/home/user/certs/hub.example.com.key
eda_tls_cert=/home/user/certs/eda.example.com.crt
eda_tls_key=/home/user/certs/eda.example.com.key
postgresql_tls_cert=/home/user/certs/postgresql.example.com.crt
postgresql_tls_key=/home/user/certs/postgresql.example.com.key

Considerations for certificates provided per service
Copy link

When providing custom TLS certificates for each individual service, consider the following:

  • Each service has its own _tls_cert and _tls_key variables. You can provide unique certificates for each service, or use the same certificate across multiple services if they share a fully qualified domain name (FQDN). If you do not define a certificate for a service, the installation program generates a self-signed certificate for that service.
  • For services deployed across many nodes (for example, when following the enterprise topology), the provided certificate for that service must include the FQDN of all associated nodes in its Subject Alternative Name (SAN) field.
  • If an external-facing service (such as automation controller or platform gateway) is deployed behind a load balancer that performs SSL/TLS offloading, the service’s certificate must include the load balancer’s FQDN in its SAN field, in addition to the FQDNs of the individual service nodes.

Provide a custom CA certificate
Copy link

When you manually provide TLS certificates for Ansible Automation Platform services (such as gateway_tls_cert, controller_tls_cert, or hub_tls_cert), those certificates might be signed by a custom CA.

About this task
Copy link

Use the custom_ca_cert variable to add your CA certificate to the environment for proper authentication and trust of the manually provided certificates.

Procedure
Copy link

If any of the TLS certificates you manually provided are signed by a custom CA, specify the CA certificate by using the following variable in your inventory file: 
custom_ca_cert=<path_to_custom_ca_certificate>

If you have more than one CA certificate, combine them into a single file and reference the combined certificate with the custom_ca_cert variable.

Receptor certificate considerations
Copy link

When using a custom certificate for Receptor nodes, the certificate requires the otherName field specified in the Subject Alternative Name (SAN) of the certificate with the value 1.3.6.1.4.1.2312.19.1.

Receptor does not support the usage of wildcard certificates. Additionally, each Receptor certificate must have the host FQDN specified in its SAN for TLS hostname validation to be correctly performed.

Redis certificate considerations
Copy link

When using custom TLS certificates for Redis-related services, consider the following for mutual TLS (mTLS) communication if specifying Extended Key Usage (EKU):

  • The Redis server certificate (redis_tls_cert) should include the serverAuth (web server authentication) and clientAuth (client authentication) EKU.
  • The Redis client certificates (gateway_redis_tls_cert, eda_redis_tls_cert) should include the clientAuth (client authentication) EKU.

Use custom Receptor signing keys
Copy link

Receptor signing is enabled by default unless receptor_disable_signing=true is set, and an RSA key pair (public and private) is generated by the installation program. However, you can set custom RSA public and private keys by using the following variables:

receptor_signing_private_key=<full_path_to_private_key>
receptor_signing_public_key=<full_path_to_public_key>