June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Overview
    • Consul on Kubernetes
    • Control access with Consul API Gateway
    • Discover Services with Consul
    • Enforce Zero Trust Networking with Consul
    • Load Balancing with Consul
    • Manage Traffic with Consul
    • Multi-Platform Service Mesh with Consul
    • Network Infrastructure Automation with Consul
    • Observability with Consul
  • Enterprise
  • Tutorials
  • Docs
  • API
  • CLI
  • Community
GitHub
Download
Try HCP Consul
    • v1.12.x (latest)
    • v1.11.x
    • v1.10.x
    • v1.9.x
    • v1.8.x
    • Overview
      • Overview
      • What is a Service Mesh?
      • Overview
      • Chef, Puppet, etc.
      • Nagios
      • SkyDNS
      • SmartStack
      • Serf
      • Eureka
      • Istio
      • Envoy and Other Proxies
      • Custom Solutions
    • Overview
    • Manual Bootstrap
    • Consul Agent
    • Glossary
    • Required Ports
    • Bootstrapping a Datacenter
    • Cloud Auto-join
    • Server Performance
    • Kubernetes
  • API
  • Commands (CLI)
    • Register Services - Service Definitions
    • Find Services - DNS Interface
    • Monitor Services - Check Definitions
    • Overview
    • How Service Mesh Works
    • Configuration
      • Overview
      • Ingress Gateway
      • Mesh
      • Exported Services
      • Proxy Defaults
      • Service Defaults
      • Service Intentions
      • Service Resolver
      • Service Router
      • Service Splitter
      • Terminating Gateway
      • Overview
      • Envoy
      • Built-in Proxy
      • Proxy Integration
      • Managed (Deprecated)
      • Overview
      • Proxy Service Registration
      • Sidecar Service Registration
    • Service-to-service permissions - Intentions
    • Service-to-service permissions - Intentions (Legacy Mode)
    • Transparent Proxy
      • Overview
      • UI Visualization
      • Overview
      • Discovery Chain
    • Connectivity Tasks
    • Distributed Tracing
      • Overview
        • WAN Federation
        • Enabling Service-to-service Traffic Across Datacenters
        • Enabling Service-to-service Traffic Across Admin Partitions
      • Ingress Gateways
      • Terminating Gateways
    • Nomad
    • Kubernetes
      • Overview
      • Go Integration
      • Overview
      • Built-In CA
      • Vault
      • ACM Private CA
    • Develop and Debug
    • Security
    • Overview
    • Installation
    • Technical Specifications
    • Common Errors
    • Upgrades
    • Overview
    • Architecture
      • Installing Consul on Kubernetes
      • Installing Consul K8s CLI
        • Minikube
        • Kind
        • AKS (Azure)
        • EKS (AWS)
        • GKE (Google Cloud)
        • Red Hat OpenShift
        • Self Hosted Kubernetes
        • Consul Clients Outside Kubernetes
        • Consul Servers Outside Kubernetes
        • Single Consul Datacenter in Multiple Kubernetes Clusters
        • Consul Enterprise
        • Overview
        • Federation Between Kubernetes Clusters
        • Federation Between VMs and Kubernetes
        • Overview
        • Systems Integration
          • Overview
          • Bootstrap Token
          • Enterprise License
          • Gossip Encryption Key
          • Partition Token
          • Replication Token
          • Server TLS
          • Service Mesh Certificates
          • Snapshot Agent Config
        • WAN Federation
      • Compatibility Matrix
      • Overview
      • Transparent Proxy
      • Ingress Gateways
      • Terminating Gateways
      • Ingress Controllers
      • Configuring a Connect CA Provider
      • Health Checks
        • Metrics
    • Service Sync
      • Overview
      • Upgrade An Existing Cluster to CRDs
    • Annotations and Labels
    • Consul DNS
      • Upgrading Consul on Kubernetes
      • Upgrading Consul K8s CLI
      • Uninstall
      • Certificate Rotation
      • Gossip Encryption Key Rotation
      • Configure TLS on an Existing Cluster
      • Common Error Messages
      • FAQ
    • Helm Chart Configuration
    • Consul K8s CLI Reference
    • Overview
    • Requirements
    • Task Resource Usage
      • Installation
      • Secure Configuration
      • Migrate Existing Tasks
      • Installation
      • Secure Configuration
      • ACL Controller
    • Architecture
    • Consul Enterprise
    • Configuration Reference
    • Overview
      • Installation
      • Requirements
      • Configure
      • Run Consul-Terraform-Sync
    • Architecture
      • Overview
      • Status
      • Tasks
      • Overview
      • task
    • Configuration
    • Tasks
    • Terraform Modules
      • Overview
      • License
      • Terraform Cloud Driver
      • Overview
      • Terraform
      • Terraform Cloud
    • Compatibility
    • Consul KV
    • Sessions
    • Watches
    • Overview
      • General
      • CLI Reference
      • Configuration Reference
    • Configuration Entries
    • Telemetry
    • Sentinel
    • RPC
    • Overview
      • ACL System Overview
      • Tokens
      • Policies
      • Roles
      • Rules Reference
      • Legacy Mode
      • Token Migration
      • ACLs in Federated Datacenters
        • Overview
        • Kubernetes
        • JWT
        • OIDC
        • AWS IAM
    • Encryption
      • Overview
      • Core
      • Network Infrastructure Automation
    • Overview
    • Admin Partitions
    • Audit Logging
    • Automated Backups
    • Automated Upgrades
    • Enhanced Read Scalability
    • Single sign-on - OIDC
    • Redundancy Zones
    • Advanced Federation
    • Network Segments
    • Namespaces
    • NIA with TFE
    • Sentinel
      • Overview
      • FAQ
    • Overview
    • Improving Consul Resilience
    • Anti-Entropy
    • Consensus Protocol
    • Gossip Protocol
    • Jepsen Testing
    • Network Coordinates
    • Consul Integration Program
    • NIA Integration Program
    • Vault Integration
    • Proxy Integration
  • Consul Tools
    • Overview
    • Compatibility Promise
    • Specific Version Details
      • Overview
      • General Process
      • Upgrading to 1.2.4
      • Upgrading to 1.6.9
      • Upgrading to 1.8.13
      • Upgrading to 1.10.0
    • Common Error Messages
    • FAQ
    • Overview
      • v1.11.x
      • v1.10.x
      • v1.9.x
      • v0.1.x
      • v0.2.x
      • v0.4.x
      • v0.3.x
      • v0.2.x
      • v0.5.x
      • v0.6.0-beta
    • Overview
    • ACL
  • Guides
Type '/' to Search

»ACL Auth Methods

1.5.0+: Auth methods only exist in Consul versions 1.5.0 and newer.

An auth method is a component in Consul that performs authentication against a trusted external party to authorize the creation of an ACL tokens usable within the local datacenter.

»Overview

Without an auth method a trusted operator is critically involved in the creation and secure introduction of each ACL token to every application that needs one, while ensuring that the policies assigned to these tokens follow the principle of least-privilege.

When running in environments such as a public cloud or when supervised by a cluster scheduler, applications may already have access to uniquely identifying credentials that were delivered securely by the platform. Consul auth method integrations allow for these credentials to be used to create ACL tokens with properly-scoped policies without additional operator intervention.

In Consul 1.5.0 the focus is around simplifying the creation of tokens with the privileges necessary to participate in a Connect service mesh with minimal operator intervention.

»Supported Types

TypesConsul Version
kubernetes1.5.0+
jwt1.8.0+
oidc1.8.0+
Enterprise
aws-iam1.12.0+

»Operator Configuration

An operator needs to configure each auth method that is to be trusted by using the API or command line before they can be used by applications.

  • Authentication - One or more auth methods should be configured with details about how to authenticate application credentials. Successful validation of application credentials will return a set of trusted identity attributes (such as a username). These can be managed with the consul acl auth-method subcommands or the corresponding API endpoints. The specific details of configuration are type dependent and described in their own documentation pages.

  • Authorization - One or more binding rules must be configured to define how to translate trusted identity attributes from each auth method into privileges assigned to the ACL token that is created. These can be managed with the consul acl binding-rule subcommands or the corresponding API endpoints.

Note - To configure auth methods in any connected secondary datacenter, ACL token replication must be enabled. Auth methods require the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled.

»Binding Rules

Binding rules allow an operator to express a systematic way of automatically linking roles and service identities to newly created tokens without operator intervention.

Successful authentication with an auth method returns a set of trusted identity attributes corresponding to the authenticated identity. Those attributes are matched against all configured binding rules for that auth method to determine what privileges to grant the the Consul ACL token it will ultimately create.

Each binding rule is composed of two portions:

  • Selector - A logical query that must match the trusted identity attributes for the binding rule to be applicable to a given login attempt. The syntax uses github.com/hashicorp/go-bexpr which is shared with the API filtering feature. For example: "serviceaccount.namespace==default and serviceaccount.name!=vault"

  • Bind Type and Name - A binding rule can bind a token to a role or to a service identity by name. The name can be specified with a plain string or the bind name can be lightly templated using HIL syntax to interpolate the same values that are usable by the Selector syntax. For example: "dev-${serviceaccount.name}"

When multiple binding rules match, then all roles and service identities are jointly linked to the token created by the login process.

»Overall Login Process

Applications are responsible for exchanging their auth method specific secret bearer token for a Consul ACL token by using the login process:

diagram of auth method login

  1. Applications use the consul login subcommand or the login API endpoint to authenticate to a specific auth method using their local Consul client. Applications provide both the name of the auth method and a secret bearer token during login.

  2. The Consul client forwards login requests to the leading Consul server.

  3. The Consul leader then uses auth method specific mechanisms to validate the provided bearer token credentials.

  4. Successful validation returns trusted identity attributes to the Consul leader.

  5. The Consul leader consults the configured set of binding rules associated with the specified auth method and selects only those rules that match the trusted identity attributes.

  6. The Consul leader uses the matching binding rules to generate a list of roles and service identities and assigns them to a token created exclusively in the local datacenter. If none are generated the login attempt fails.

  7. The relevant SecretID and remaining details about the token are returned to the originating Consul client.

  8. The Consul client returns the token details back to the application.

  9. (later) Applications SHOULD use the consul logout subcommand or the logout API endpoint to destroy their token when it is no longer required.

For more details about specific auth methods and how to configure them, click on the name of the auth method type in the sidebar.

github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager