Skip to main content
Gå til innhold

Let's Encrypt

We use the external Puppet module letsencrypt from Puppet Forge to issue Let's Encrypt certificates. The underlying client used for managing certificates is called Certbot. Currently this module only supports Debian- and RedHat-based OS. Please read the Usage page and Reference page of puppet-letsencrypt for advanced documentation.

caution

Remember that your underlying webserver must be possible to access on the standard ports of HTTP (80) and HTTPS (443) from the internet or more specifically the Let's Encrypt ACME v2 endpoint. Otherwise, the ACME server will not be able to validate your domain ownership as it won't be able to access the web challenge. If you need a certificate for another type of service than a webserver, consider issuing the certificate through the standalone option instead.

Installing and configuring Certbot for your role/hostgroup​

Provide the ACME v2 endpoint of Let's Encrypt to the module and an e-mail to notify your team / service of any impending events. Warnings will be generated if certificates are expiring which can indicate that a certificate was not revoked correctly or there is an error, and the module is unable to renew your certificate.

EPEL should be set to disabled on Amazon Linux 2.0 as this is provided by default and should not be managed by Puppet directly. Do not use a default contact e-mail of Sikt as this may only generate noise for Sikt Service Center.

We want to use the latest version of the Certbot package and we have enabled automatic renewal of certificates using cerbot renew and cron.

  class { 'letsencrypt':
    config            => {
      email  => 'fornavn.etternavn@sikt.no',
      server => 'https://acme-v02.api.letsencrypt.org/directory',
    },
    package_ensure    => 'latest',
    configure_epel    => false,
    renew_cron_ensure => 'present',
  }

Please note that by default certificate renewal will occur every day at a random time given by a seeded hour and minute. You can for example specify it to instead run certificate renewals every 7 days at ca. 3 AM:

  class { 'letsencrypt':
    config              => {
      email  => 'fornavn.etternavn@sikt.no',
      server => 'https://acme-v02.api.letsencrypt.org/directory',
    },
    package_ensure      => 'latest',
    configure_epel      => false,
    renew_cron_ensure   => 'present',
    renew_cron_minute   => '0',
    renew_cron_hour     => '3',
    renew_cron_monthday => '1-31/7',
  }

Installing Certbot plugins​

To order certificates for nginx or apache, Certbot relies on plugins specific for the used webserver.

To install the specific plugin to the node include extra_packages to the <node-name>.yaml file in hieradata -> nodes.

extra_packages:
  - python3-certbot-nginx

Issue certificates through Nginx and Apache "httpd" webserver authenticator plugin​

You only have to specify the authenticator plugin of the webserver you are using, and the authenticator will take care of serving the ACME challenge correctly from the webserver and reload the webserver configuration afterwards. If you do not specify a valid domain name in the title field you would have to specify the domain key. Do also note that this title field decides the path/name of your issued certificate on the local machine. If you need multiple domains specify the domains key with a list as an addition, this is most commonly used when you need www.* and not only the naked domain.

Example: Issue a certificate only (certonly) for Nginx by using the Nginx authenticator plugin and specifying a single domain.

  letsencrypt::certonly { 'example.no':
    plugin        => 'nginx',
    #domains       => ['example.no', 'www.example.no'],
  }

Issue certificates through webroot for any local webserver (advanced)​

This option is only recommended for advanced users. You will have to provide the webroot location for your unsupported webserver and for example a command to reload your desired webserver so it can apply the changes to your certificate bundle.

Example: Issue certonly for a webroot path. Nginx is used here just as an illustration and should be used with the Nginx authenticator directly.

  letsencrypt::certonly { 'example.no':
    domains              => ['example.no', 'www.example.no'],
    plugin               => 'webroot',
    webroot_paths        => ['/usr/share/nginx/html'],
    cron_success_command => '/bin/systemctl reload nginx.service',
  }

Using the issued certificate​

The title field given to the certonly installer decides the path to your certificate located at: /etc/letsencrypt/live/TITLE/*

The certbot will generate following files:

  • cert.pem - The signed public certificate
  • chain.pem - The intermediate certificates
  • fullchain.pem - The signed public certificate + the intermediate certificates
  • privkey.pem - The private key

To use the generated certificate you have to point your webserver (in this case nginx) to the location where certificates are stored.

Example: A standard Nginx configuration using an issued certificate with fullchain.pem, privkey.pem and chain.pem.

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;

    ssl_certificate "/etc/letsencrypt/live/example.no/fullchain.pem";
    ssl_certificate_key "/etc/letsencrypt/live/example.no/privkey.pem"
    ssl_session_timeout 1d;
    ssl_session_cache shared:MozSSL:10m;  # about 40000 sessions
    ssl_session_tickets off;

    # intermediate configuration
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
    ssl_prefer_server_ciphers off;

    # HSTS (ngx_http_headers_module is required) (63072000 seconds)
    add_header Strict-Transport-Security "max-age=63072000" always;

    # OCSP stapling
    ssl_stapling on;
    ssl_stapling_verify on;

    # verify chain of trust of OCSP response using Root CA and Intermediate certs
    ssl_trusted_certificate /etc/letsencrypt/live/example.no/chain.pem;

    # replace with the IP address of your resolver
    resolver 1.1.1.1;
}

Other use cases​

It is possible to issue a certificate for other software than a webserver through the standalone option. There is also a DNS Plugin option which is required for issuing wildcard certificates. Check out the User Guide of Certbot as well as the Usage page and Reference page of puppet-letsencrypt.