The page provides reference information for the auto_config parameters in a Consul agent configuration file.

When you enable auto_config, the client agent upon startup makes an RPC to the configured server addresses to request configuration settings, such as ACL token, TLS certificates, and Gossip encryption key. These configuration settings get merged in as defaults with any user-supplied configuration on the client agent able to override them. The initial RPC uses a JWT specified with either intro_token, intro_token_file or the CONSUL_INTRO_TOKEN environment variable to authorize the request. How the JWT token is verified is controlled by the auto_config.authorizer object available for use on Consul servers.

Enabling this option also enables service mesh because it is vital for auto_config, more specifically the service mesh CA and certificates infrastructure.

Parameters

• auto_config This object allows setting options for the auto_config feature.

  • enabled (Defaults to false) This option enables auto_config on a client agent.

  • intro_token (Defaults to "") This specifies the JWT to use for the initial auto_config RPC to the Consul servers. This can be overridden with the CONSUL_INTRO_TOKEN environment variable

  • intro_token_file (Defaults to "") This specifies a file containing the JWT to use for the initial auto_config RPC to the Consul servers. This token from this file is only loaded if the intro_token configuration is unset as well as the CONSUL_INTRO_TOKEN environment variable

  • server_addresses (Defaults to []) This specifies the addresses of servers in the local datacenter to use for the initial RPC. These addresses support Cloud Auto-Joining and can optionally include a port to use when making the outbound connection. If no port is provided, the server_port will be used.

  • dns_sans (Defaults to []) This is a list of extra DNS SANs to request in the client agent's TLS certificate. The localhost DNS SAN is always requested.

  • ip_sans (Defaults to []) This is a list of extra IP SANs to request in the client agent's TLS certificate. The ::1 and 127.0.0.1 IP SANs are always requested.

  • authorization This object controls how a Consul server will authorize auto_config requests and in particular how to verify the JWT intro token.

    • enabled (Defaults to false) This option enables auto_config authorization capabilities on the server.

    • static This object controls configuring the static authorizer setup in the Consul configuration file. Almost all sub-keys are identical to those provided by the JWT Auth Method.

      • jwt_validation_pub_keys (Defaults to []) A list of PEM-encoded public keys to use to authenticate signatures locally.

        Exactly one of jwks_url jwt_validation_pub_keys, or oidc_discovery_url is required.

      • oidc_discovery_url (Defaults to "") The OIDC Discovery URL, without any .well-known component (base path).

        Exactly one of jwks_url jwt_validation_pub_keys, or oidc_discovery_url is required.

      • oidc_discovery_ca_cert (Defaults to "") PEM encoded CA cert for use by the TLS client used to talk with the OIDC Discovery URL. NOTE: Every line must end with a newline (\n). If not set, system certificates are used.

      • jwks_url (Defaults to "") The JWKS URL to use to authenticate signatures.

        Exactly one of jwks_url jwt_validation_pub_keys, or oidc_discovery_url is required.

      • jwks_ca_cert (Defaults to "") PEM encoded CA cert for use by the TLS client used to talk with the JWKS URL. NOTE: Every line must end with a newline (\n). If not set, system certificates are used.

      • claim_mappings (Defaults to (map[string]string)) Mappings of claims (key) that will be copied to a metadata field (value). Use this if the claim you are capturing is singular (such as an attribute).

        When mapped, the values can be any of a number, string, or boolean and will all be stringified when returned.

      • list_claim_mappings (Defaults to (map[string]string)) Mappings of claims (key) will be copied to a metadata field (value). Use this if the claim you are capturing is list-like (such as groups).

        When mapped, the values in each list can be any of a number, string, or boolean and will all be stringified when returned.

      • jwt_supported_algs (Defaults to ["RS256"]) JWTSupportedAlgs is a list of supported signing algorithms.

      • bound_audiences (Defaults to []) List of aud claims that are valid for login; any match is sufficient.

      • bound_issuer (Defaults to "") The value against which to match the iss claim in a JWT.

      • expiration_leeway (Defaults to "0s") Duration of leeway when validating expiration of a token to account for clock skew. Defaults to 150s (2.5 minutes) if set to 0s and can be disabled if set to -1ns.

      • not_before_leeway (Defaults to "0s") Duration of leeway when validating not before values of a token to account for clock skew. Defaults to 150s (2.5 minutes) if set to 0s and can be disabled if set to -1.

      • clock_skew_leeway (Defaults to "0s") Duration of leeway when validating all claims to account for clock skew. Defaults to 60s (1 minute) if set to 0s and can be disabled if set to -1ns.

      • claim_assertions (Defaults to []) List of assertions about the mapped claims required to authorize the incoming RPC request. The syntax uses github.com/hashicorp/go-bexpr which is shared with the API filtering feature. The assertions are lightly templated using HIL syntax to interpolate some values from the RPC request. The list of variables that can be interpolated are:

        • node - The node name the client agent is requesting.
        • segment EnterpriseEnterprise - The network segment name the client is requesting.
        • partition EnterpriseEnterprise - The admin partition name the client is requesting.

        Refer to the claim assertions example for more information.

Examples

The following examples demonstrate common configurations for a Consul agent's auto config settings.

Claim assertions

When combines, the following configurations ensure that the JWT sub matches the node name requested by the client.

claim_mappings {
  sub = "node_name"
}
claim_assertions = [
  "value.node_name == \"${node}\""
]

{
  "claim_mappings": {
    "sub": "node_name"
  },
  "claim_assertions": ["value.node_name == \"${node}\""]
}