Auto-Config is a highly scalable method to distribute secure properties and other configuration settings to all Consul agents in a datacenter.
HashiCorp Consul includes several built-in security features that protect against eavesdropping, tampering, and spoofings, such as access control lists (ACLs), TLS encryption, and gossip encryption. These security features require configuration on the server cluster as well as each client. This includes configurations for various properties including secure generation and distribution.
Configuring these security features can be a challenge for many teams. As a result, Consul engineering created the
auto-config method for Consul.
auto-config is a highly scalable method used to distribute secure properties and other configuration settings to all Consul agents in a datacenter, which greatly reduces the technical overhead associated with securing an environment.
This article gives an overview on how the
auto-config feature functions and as a result, reduces manual security configuration overhead throughout a Consul datacenter.
Consul clients configured with
auto-config use JSON web tokens (JWTs) to securely retrieve gossip encryption keys, TLS certificates, ACL settings, and other configuration properties from Consul servers. JSON web tokens are an open, industry-standard method for representing claims securely between two parties. With
auto-config, the Consul server cluster acts as the JWT authorizer for Consul clients. The Consul server cluster can authorize JWTs using an OIDC URL endpoint, PEM-encoded public certificates, or a JWKS URL endpoint.
For generating and validating secure JWTs, we recommend using a production-grade tool such as HashiCorp Vault. With Vault’s identity engine, an authorized user/application can request a token that encapsulates identity information for their associated entity. These tokens are signed JWTs following the OIDC ID token structure. The public keys used to authenticate the tokens are published by Vault on an unauthenticated endpoint following OIDC discovery and JWKS conventions, which are directly usable for
To learn more about JSON web tokens, feel free to explore the jwt.io documentation.
auto-config feature is simple to set up and utilize. First, your Consul servers must be configured to act as a JWT authorizer. The authorization service is used to validate client requests for security settings.
Next, you must generate a JWT using Vault or another third-party, production-grade secrets management platform. The JWT should contain claims data such as the issuer (
iss), audience (
aud), subject (
sub), and expiration time (
The JWT value can then be set in the Consul client
auto-config configuration file. When the Consul agent is restarted, and the configuration is read, the Consul client will submit an
auto-config request to the Consul server cluster for validation.
Once the Consul server cluster successfully validates the Consul client
auto-config request, it will send all respective security settings to the Consul client. Upon receiving these security settings, the Consul client will merge this information into any existing client settings.
To get started, check out the Automate Consul Agent Security with
auto-config tutorial. This tutorial will guide you through deploying a Consul datacenter with Docker and utilizing
auto-config to secure the environment. Docker is light on system resources, easy to deploy on any operating system, and highly customizable. While this tutorial uses elements that are not suitable for large-scale production environments, it will teach you the core concepts for deploying and interacting with a secure Consul datacenter using
For even more news about our latest tutorials added to HashiCorp Learn, follow @HashiCorp on Twitter.
Our tests show Consul servers remain healthy under all test configurations and that splitting up a large LAN gossip pool cuts the risk of gossip instability.
The new global management plane for Consul is now available as a free public beta. Try it out to gain full visibility for both self-managed and HCP Consul clusters.
Before we ring in the new year, here’s a look back at some of the most important moments in 2022 for HashiCorp.