open-consul/website/source/docs/guides/creating-certificates.html.md

layout	page_title	sidebar_current	description
docs	Creating and Configuring TLS Certificates	docs-guides-creating-certificates	Learn how to create certificates for Consul.

Creating and Configuring TLS Certificates

Setting you cluster up with TLS is an important step towards a secure deployment. Correct TLS configuration is a prerequisite of our Security Model. Correctly configuring TLS can be a complex process however, especially given the wide range of deployment methodologies. This guide will provide you with a production ready TLS configuration.

~> More advanced topics like key management and rotation are not covered by this guide. Vault is the suggested solution for key generation and management.

This guide has the following chapters:

1. Creating Certificates
2. Configuring Agents
3. Configuring the Consul CLI for HTTPS
4. Configuring the Consul UI for HTTPS

This guide is structured in way that you build knowledge with every step. It is recommended to read the whole guide before starting with the actual work, because you can save time if you are aware of some of the more advanced things in Chapter 3 and 4.

Reference Material

• Encryption
• Security Model

Creating Certificates

Estimated Time to Complete

2 minutes

Prerequisites

This guide assumes you have Consul 1.4.1 (or newer) in your PATH.

Introduction

The first step to configuring TLS for Consul is generating certificates. In order to prevent unauthorized cluster access, Consul requires all certificates be signed by the same Certificate Authority (CA). This should be a private CA and not a public one like Let's Encrypt as any certificate signed by this CA will be allowed to communicate with the cluster.

Step 1: Create a Certificate Authority

There are a variety of tools for managing your own CA, like the PKI secret backend in Vault, but for the sake of simplicity this guide will use Consul's builtin TLS helpers:

$ consul tls ca create
==> Saved consul-agent-ca.pem
==> Saved consul-agent-ca-key.pem

The CA certificate (consul-agent-ca.pem) contains the public key necessary to validate Consul certificates and therefore must be distributed to every node that runs a consul agent.

~> The CA key (consul-agent-ca-key.pem) will be used to sign certificates for Consul nodes and must be kept private. Possession of this key allows anyone to run Consul as a trusted server and access all Consul data including ACL tokens.

Step 2: Create individual Server Certificates

Create a server certificate for datacenter dc1 and domain consul, if your datacenter or domain is different please use the appropriate flags:

$ consul tls cert create -server
==> WARNING: Server Certificates grants authority to become a
    server and access all state in the cluster including root keys
    and all ACL tokens. Do not distribute them to production hosts
    that are not server nodes. Store them as securely as CA keys.
==> Using consul-agent-ca.pem and consul-agent-ca-key.pem
==> Saved dc1-server-consul-0.pem
==> Saved dc1-server-consul-0-key.pem

Please repeat this process until there is an individual certificate for each server. The command can be called over and over again, it will automatically add a suffix.

In order to authenticate Consul servers, servers are provided with a special certificate - one that contains server.dc1.consul in the Subject Alternative Name. If you enable verify_server_hostname, only agents that provide such certificate are allowed to boot as a server. Without verify_server_hostname = true an attacker could compromise a Consul client agent and restart the agent as a server in order to get access to all the data in your cluster! This is why server certificates are special, and only servers should have them provisioned.

~> Server keys, like the CA key, must be kept private - they effectively allow access to all Consul data.

Step 3: Create Client Certificates

Create a client certificate:

$ consul tls cert create -client
==> Using consul-agent-ca.pem and consul-agent-ca-key.pem
==> Saved dc1-client-consul-0.pem
==> Saved dc1-client-consul-0-key.pem

Client certificates are also signed by your CA, but they do not have that special Subject Alternative Name which means that if verify_server_hostname is enabled, they cannot start as a server.

Configuring Agents

Prerequisites

For this section you need access to your existing or new Consul cluster and have the certificates from the previous chapters available.

Notes on example configurations

The example configurations from this as well as the following chapters are in json. You can copy each one of the examples in its own file in a directory (-config-dir) from where consul will load all the configuration. This is just one way to do it, you can also put them all into one file if you prefer that.

Introduction

By now you have created the certificates you need to enable TLS in your cluster. The next steps show how to configure TLS for a brand new cluster. If you already have a cluster in production without TLS please see the encryption guide for the steps needed to introduce TLS without downtime.

Step 1: Setup Consul servers with certificates

This step describes how to setup one of your consul servers, you want to make sure to repeat the process for the other ones as well with their individual certificates.

The following files need to be copied to your Consul server:

• consul-agent-ca.pem: CA public certificate.
• dc1-server-consul-0.pem: Consul server node public certificate for the dc1 datacenter.
• dc1-server-consul-0-key.pem: Consul server node private key for the dc1 datacenter.

Here is an example agent TLS configuration for Consul servers which mentions the copied files:

{
  "verify_incoming": true,
  "verify_outgoing": true,
  "verify_server_hostname": true,
  "ca_file": "consul-agent-ca.pem",
  "cert_file": "dc1-server-consul-0.pem",
  "key_file": "dc1-server-consul-0-key.pem",
  "ports": {
    "http": -1,
    "https": 8501
  }
}

This configuration disables the HTTP port to make sure there is only encryted communication. Existing clients that are not yet prepared to talk HTTPS won't be able to connect afterwards. This also affects builtin tooling like consul members and the UI. The next chapters will demonstrate how to setup secure access.

After a Consul agent restart, your servers should be only talking TLS.

Step 2: Setup Consul clients with certificates

Now copy the following files to your Consul clients:

• consul-agent-ca.pem: CA public certificate.
• dc1-client-consul-0.pem: Consul client node public certificate.
• dc1-client-consul-0-key.pem: Consul client node private key.

Here is an example agent TLS configuration for Consul agents which mentions the copied files:

{
  "verify_incoming": true,
  "verify_outgoing": true,
  "verify_server_hostname": true,
  "ca_file": "consul-agent-ca.pem",
  "cert_file": "dc1-client-consul-0.pem",
  "key_file": "dc1-client-consul-0-key.pem",
  "ports": {
    "http": -1,
    "https": 8501
  }
}

This configuration disables the HTTP port to make sure there is only encryted communication. Existing clients that are not yet prepared to talk HTTPS won't be able to connect afterwards. This also affects builtin tooling like consul members and the UI. The next chapters will demonstrate how to setup secure access.

After a Consul agent restart, your agents should be only talking TLS.

Configuring the Consul CLI for HTTPS

If your cluster is configured to only communicate via HTTPS, you will need to create additional certificates in order to be able to continue to access the API and the UI:

$ consul tls cert create -cli
==> Using consul-agent-ca.pem and consul-agent-ca-key.pem
==> Saved dc1-cli-consul-0.pem
==> Saved dc1-cli-consul-0-key.pem

If you are trying to get members of you cluster, the CLI will return an error:

$ consul members
Error retrieving members:
  Get http://127.0.0.1:8500/v1/agent/members?segment=_all:
  dial tcp 127.0.0.1:8500: connect: connection refused
$ consul members -http-addr="https://localhost:8501"
Error retrieving members:
  Get https://localhost:8501/v1/agent/members?segment=_all:
  x509: certificate signed by unknown authority

But it will work again if you provide the certificates you provided:

$ consul members -ca-file=consul-agent-ca.pem -client-cert=dc1-cli-consul-0.pem \
  -client-key=dc1-cli-consul-0-key.pem -http-addr="https://localhost:8501"
  Node     Address         Status  Type    Build     Protocol  DC   Segment
  ...

This process can be cumbersome to type each time, so the Consul CLI also searches environment variables for default values. Set the following environment variables in your shell:

$ export CONSUL_HTTP_ADDR=https://localhost:8501
$ export CONSUL_CACERT=consul-agent-ca.pem
$ export CONSUL_CLIENT_CERT=dc1-cli-consul-0.pem
$ export CONSUL_CLIENT_KEY=dc1-cli-consul-0-key.pem

• CONSUL_HTTP_ADDR is the URL of the Consul agent and sets the default for -http-addr.
• CONSUL_CACERT is the location of your CA certificate and sets the default for -ca-file.
• CONSUL_CLIENT_CERT is the location of your CLI certificate and sets the default for -client-cert.
• CONSUL_CLIENT_KEY is the location of your CLI key and sets the default for -client-key.

After these environment variables are correctly configured, the CLI will respond as expected.

Note on SANs for Server and Client Certificates

Using localhost and 127.0.0.1 as Subject Alternative Names in server and client certificates allows tools like curl to be able to communicate with Consul's HTTPS API when run on the same host. Other SANs may be added during server/client certificates creation with -additional-dnsname to allow remote HTTPS requests from other hosts.

Configuring the Consul UI for HTTPS

If your servers and clients are configured now like above, you won't be able to access the builtin UI anymore. We recommend that you pick one (or two for availability) Consul agent you want to run the UI on and follow the instructions to get the UI up and running again.

Step 1: Which interface to bind to?

Depending on your setup you might need to change to which interface you are binding because thats 127.0.0.1 by default for the UI. Either via the addresses.https or client_addr option which also impacts the DNS server. The Consul UI is unproteced which means you need to put some auth in front of it if you want to make it publicly available!

Binding to 0.0.0.0 should work:

{
  "ui": true,
  "client_addr": "0.0.0.0",
  "enable_script_checks": false,
  "disable_remote_exec": true
}

~> Since your Consul agent is now available to the network, please make sure that enable_script_checks is set to false and disable_remote_exec is set to true.

Step 2: verify_incoming_rpc

Your Consul agent will deny the connection straight away because verify_incoming is enabled.

If set to true, Consul requires that all incoming connections make use of TLS and that the client provides a certificate signed by a Certificate Authority from the ca_file or ca_path. This applies to both server RPC and to the HTTPS API.

Since the browser doesn't present a certificate signed by our CA, you cannot access the UI. If you curl your HTTPS UI the following happens:

$ curl https://localhost:8501/ui/ -k -I
curl: (35) error:14094412:SSL routines:SSL3_READ_BYTES:sslv3 alert bad certificate

This is the Consul HTTPS server denying your connection because you are not presenting a client certificate signed by your Consul CA. There is a combination of options however that allows us to keep using verify_incoming for RPC, but not for HTTPS:

{
  "verify_incoming": false,
  "verify_incoming_rpc": true
}

~> This is the only time we are changing the value of the existing option verify_incoming to false. Make sure to only change it on the agent running the UI!

With the new configuration, it should work:

$ curl https://localhost:8501/ui/ -k -I
HTTP/2 200
...

Step 3: Subject Alternative Name

This step will take care of setting up the domain you want to use to access the Consul UI. Unless you only need to access the UI over localhost or 127.0.0.1 you will need to go complete this step.

$ curl https://consul.example.com:8501/ui/ \
  --resolve 'consul.example.com:8501:127.0.0.1' \
  --cacert consul-agent-ca.pem
curl: (51) SSL: no alternative certificate subject name matches target host name 'consul.example.com'
...

The above command simulates a request a browser is making when you are trying to use the domain consul.example.com to access your UI. The problem this time is that your domain is not in Subject Alternative Name of the Certificate. We can fix that by creating a certificate that has our domain:

$ consul tls cert create -server -additional-dnsname consul.example.com
...

And if you put your new cert into the configuration of the agent you picked to serve the UI and restart Consul, it works now:

$ curl https://consul.example.com:8501/ui/ \
  --resolve 'consul.example.com:8501:127.0.0.1' \
  --cacert consul-agent-ca.pem -I
HTTP/2 200
...

Step 4: Trust the Consul CA

So far we have provided curl with our CA so that it can verify the connection, but if we stop doing that it will complain and so will our browser if you visit your UI on https://consul.example.com:

$ curl https://consul.example.com:8501/ui/ \
  --resolve 'consul.example.com:8501:127.0.0.1'
curl: (60) SSL certificate problem: unable to get local issuer certificate
...

You can fix that by trusting your Consul CA (consul-agent-ca.pem) on your machine, please use Google to find out how to do that on your OS.

$ curl https://consul.example.com:8501/ui/ \
  --resolve 'consul.example.com:8501:127.0.0.1' -I
HTTP/2 200
...

Summary

When you have completed this guide, your Consul cluster will have TLS enabled and will encrypt all RPC and HTTP traffic (assuming you disabled the HTTP port). The other pre-requisites for a secure Consul deployment are:

• Enable gossip encryption
• Configure ACLs with default deny