Foreman does a great job of providing SSL support out-of-the-box, it does this by using the SSL certificates generated by your puppet-ca. Unless your users web browsers all trust the puppet CA (unlikely), any human user of Foreman is going to get SSL warnings. Replacing Foremans SSL certificate with one that’s signed by a default trusted CA requires some care for 2 reasons:

  • Other components apart from humans using web browsers, need to validate the Foreman server. Therefore we need to make sure these components validate the Forman server against the correct CA.
  • Foreman uses SSL client authentication to authenticate various components via their puppet-ca certificates. We need to make sure we do not change the CA that foreman uses to authenticate these components.

The following diagram shows the various components talking to the Forman server and which communications require the SSL keys changing.

Foreman SSL Communications

For the following examples, the new certificates live in the following locations:

  • SSL Certificate: /etc/pki/tls/certs/puppet.example.com.crt
  • SSL Private Key: /etc/pki/tls/private/puppet.example.com.key
  • SSL CA Chain: /etc/pki/tls/certs/cachain.crt

Foreman

Foreman is presented via mod_passenger on Apache, so the SSL keys need to be changed in your apache VirtualHost. For me this was /etc//httpd/conf.d/05-foreman-ssl.conf.

The following options need to be changed: SSLCertificateFile, SSLCertificateKeyFile and SSLCertificateChainFile. It is important that you do not change SSLCACertificateFile or SSLCARevocationFile, as these are used for client authentication. Your final config should look like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

## SSL directives
SSLEngine on
SSLCertificateFile      "/etc/pki/tls/certs/puppet.example.com.crt"
SSLCertificateKeyFile   "/etc/pki/tls/private/puppet.example.com.key"
SSLCertificateChainFile "/etc/pki/tls/certs/cachain.crt"
SSLCACertificatePath    "/etc/pki/tls/certs"
SSLCACertificateFile    "/var/lib/puppet/ssl/certs/ca.pem"
SSLCARevocationFile     "/var/lib/puppet/ssl/ca/ca_crl.pem"
SSLVerifyClient         optional
SSLVerifyDepth          3
SSLOptions +StdEnvVars

If you use the Console feasture for foreman, you will also want to change the websockets_ssl_key and websockets_ssl_cert keys in /etc/foreman/settings.yaml. For example:

1
2

:websockets_ssl_key:  /etc/pki/tls/private/puppet.example.com.key
:websockets_ssl_cert: /etc/pki/tls/certs/puppet.example.com.crt

Smart Proxy

If you have your smart proxies running on the same box as foreman, make sure foreman_ssl_ca is not defined in /etc/foreman-proxy/settings.yaml and it will read the CA from the main foreman settings.

Puppet

Change ssl_ca in /etc/puppet/foreman.yaml, do not change ssl_cert or ssl_key. For example:

1
2
3

:ssl_ca: "/etc/pki/tls/certs/cachain.crt"
:ssl_cert: "/var/lib/puppet/ssl/certs/puppet.example.com.pem"
:ssl_key: "/var/lib/puppet/ssl/private_keys/puppet.example.com.pem"

Managing with puppet

If you use manage your foreman and puppet install with the theforeman/puppet and theforeman/foreman modules, you can configure all the above with the following hiera data:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

foreman::ssl: true
puppet::server_foreman_ssl_ca: '/etc/pki/tls/certs/cachain.crt'
puppet::server_foreman_url: 'https://puppet.example.com'
foreman::server_ssl_key: '/etc/pki/tls/private/puppet.example.com.key'
foreman::server_ssl_cert: '/etc/pki/tls/certs/puppet.example.com.crt'
foreman::server_ssl_chain: '/etc/pki/tls/certs/cachain.crt'
foreman::servername: 'puppet.example.com'
foreman::foreman_url: 'https://puppet.example.com'
foreman::websockets_ssl_key: '/etc/pki/tls/private/puppet.example.key'
foreman::websockets_ssl_cert: '/etc/pki/tls/certs/puppet.example.crt'