Blog HCP Consul on Azure goes GA, plus more Consul news from HashiConf EU Read more
  • 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
      • What is Cluster Peering
      • Create and Manage Peering Connections
      • Cluster Peering on Kubernetes
    • 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
          • Webhook Certificates
        • WAN Federation
      • 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
    • Compatibility Matrix
    • 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
    • Register Lambda Functions
    • Invoke Lambda Functions
    • Overview
      • Installation
      • Requirements
      • Configure
      • Run Consul-Terraform-Sync
    • Architecture
      • Overview
      • Status
      • Tasks
      • Health
      • Overview
      • task
      • start
    • 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.3.x
      • v0.2.x
      • v0.1.x
      • v0.4.x
      • v0.3.x
      • v0.2.x
      • v0.6.x
      • v0.5.x
    • Overview
    • ACL
  • Guides
Type '/' to Search

»JWT Auth Method

1.8.0+: This feature is available in Consul versions 1.8.0 and newer.

The jwt auth method can be used to authenticate with Consul by providing a JWT directly. The JWT is cryptographically verified using locally-provided keys, or, if configured, an OIDC Discovery service can be used to fetch the appropriate keys.

This page assumes general knowledge of JWTs and the concepts described in the main auth method documentation.

Both the jwt and the oidc auth method types allow additional processing of the claims data in the JWT.

»JWT vs OIDC Auth Methods

Since both the oidc and jwt auth methods ultimately operate on JWTs as bearer tokens, it may be confusing to know which is right for a given use case.

  • JWT: The user or application performing the Consul login must already be in possession of a valid JWT to begin. There is no browser interaction required. This is ideal for machine-oriented headless login where an operator may have already arranged for a valid JWT to be dropped on a VM or provided to a container.

  • OIDC: The user performing the Consul login does not have a JWT nor do they even need to know what that means. This is ideal for human-oriented interactive login where an operator or administrator may have deployed SSO widely and doesn't want to have the burden of tracking and distributing Consul ACL tokens to any authorized coworker who may need to have access to a Consul instance. Browser interaction is required. This is only available in Consul Enterprise.

»Config Parameters

The following auth method Config parameters are required to properly configure an auth method of type jwt:

  • JWTValidationPubKeys (array<string>) - A list of PEM-encoded public keys to use to authenticate signatures locally.

    Exactly one of JWKSURL JWTValidationPubKeys, or OIDCDiscoveryURL is required.

  • OIDCDiscoveryURL (string: "") - The OIDC Discovery URL, without any .well-known component (base path).

    Exactly one of JWKSURL JWTValidationPubKeys, or OIDCDiscoveryURL is required.

  • OIDCDiscoveryCACert (string: "") - 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.

  • JWKSURL (string: "") - The JWKS URL to use to authenticate signatures.

    Exactly one of JWKSURL JWTValidationPubKeys, or OIDCDiscoveryURL is required.

  • JWKSCACert (string: "") - 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.

  • ClaimMappings (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.

  • ListClaimMappings (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.

  • JWTSupportedAlgs (array<string>) - JWTSupportedAlgs is a list of supported signing algorithms. Defaults to RS256.

  • BoundAudiences (array<string>) - List of aud claims that are valid for login; any match is sufficient.

  • BoundIssuer (string: "") - The value against which to match the iss claim in a JWT.

  • ExpirationLeeway (duration: 0s) - Duration in seconds of leeway when validating expiration of a token to account for clock skew. Defaults to 150 (2.5 minutes) if set to 0 and can be disabled if set to -1.

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

  • ClockSkewLeeway (duration: 0s) - Duration in seconds of leeway when validating all claims to account for clock skew. Defaults to 60 (1 minute) if set to 0 and can be disabled if set to -1.

»Sample Configs

»Static Keys

{
    ...other fields...
    "Config": {
        "BoundIssuer": "corp-issuer",
        "JWTValidationPubKeys": [
            "<public key PEM>"
        ],
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}
{
    ...other fields...
    "Config": {
        "BoundIssuer": "corp-issuer",
        "JWTValidationPubKeys": [
            "<public key PEM>"
        ],
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}

»JWKS

{
    ...other fields...
    "Config": {
        "JWKSURL": "https://my-corp-jwks-url.example.com/",
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}
{
    ...other fields...
    "Config": {
        "JWKSURL": "https://my-corp-jwks-url.example.com/",
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}

»OIDC Discovery

{
    ...other fields...
    "Config": {
        "BoundAudiences": [
            "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
        ],
        "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}
{
    ...other fields...
    "Config": {
        "BoundAudiences": [
            "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt"
        ],
        "OIDCDiscoveryURL": "https://my-corp-app-name.auth0.com/",
        "ClaimMappings": {
            "http://example.com/first_name": "first_name",
            "http://example.com/last_name": "last_name"
        },
        "ListClaimMappings": {
            "http://example.com/groups": "groups"
        }
    }
}

»JWT Verification

JWT signatures will be verified against public keys from the issuer. This process can be done one of three ways:

  • Static Keys - A set of public keys is stored directly in the configuration.

  • JWKS - A JSON Web Key Set (JWKS) URL (and optional certificate chain) is configured. Keys will be fetched from this endpoint during authentication.

  • OIDC Discovery - An OIDC Discovery URL (and optional certificate chain) is configured. Keys will be fetched from this URL during authentication. When OIDC Discovery is used, OIDC validation criteria (e.g. iss, aud, etc.) will be applied.

If multiple methods are needed, another auth method of this type may be created with a different name.

»Trusted Identity Attributes via Claim Mappings

Data from JWT claims can be returned from the authentication step as trusted identity attributes for use in binding rule selectors and bind name interpolation.

Control of which claims are mapped to which identity attributes is governed by the ClaimMappings and ListClaimMappings. These are both maps of items to copy with elements of the form: "<JWT claim>":"<attribute suffix>".

The only difference between these two types of mappings is that ClaimMappings is used to map singular values (such as a name, department, or team) while ListClaimMappings is used to map lists of values.

The singular values mapped by ClaimMappings can be interpolated in a binding rule, and the lists of values mapped by ListClaimMappings cannot.

Assume this is your config snippet:

{ ...other fields...
  "ClaimMappings": {
    "givenName": "first_name",
    "surname": "last_name"
  },
  "ListClaimMappings": {
    "groups": "groups"
  }
}
{ ...other fields...
  "ClaimMappings": {
    "givenName": "first_name",
    "surname": "last_name"
  },
  "ListClaimMappings": {
    "groups": "groups"
  }
}

This specifies that the values in the JWT claims "givenName" and "surname" should be copied to attributes named "value.first_name" and "value.last_name" respectively. Additionally the list of values in the JWT claim "groups" should be copied to an attribute named "list.groups".

The following table shows the resulting attributes that will be extracted, and the ways they may be used in Rule Bindings:

AttributesSupported Selector OperationsCan be Interpolated
value.first_nameEqual, Not Equal, In, Not In, Matches, Not Matchesyes
value.last_nameEqual, Not Equal, In, Not In, Matches, Not Matchesyes
list.groupsIn, Not In, Is Empty, Is Not Emptyno

»Claim Specifications and JSON Pointer

The ClaimMappings and ListClaimMappings fields are used to point to data within the JWT. If the desired key is at the top of level of the JWT, the name can be provided directly. If it is nested at a lower level, a JSON Pointer may be used.

Assume the following JWT claims are decoded:

{
  "division": "North America",
  "groups": {
    "primary": "Engineering",
    "secondary": "Software"
  },
  "iss": "https://my-corp-app-name.auth0.com/",
  "sub": "auth0|eiw7OWoh5ieSh7ieyahC3ief0uyuraphaengae9d",
  "aud": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
  "iat": 1589224148,
  "exp": 1589260148,
  "nonce": "eKiihooH3Fah8Ieshah4leeti6ien3"
}
{
  "division": "North America",
  "groups": {
    "primary": "Engineering",
    "secondary": "Software"
  },
  "iss": "https://my-corp-app-name.auth0.com/",
  "sub": "auth0|eiw7OWoh5ieSh7ieyahC3ief0uyuraphaengae9d",
  "aud": "V1RPi2MYptMV1RPi2MYptMV1RPi2MYpt",
  "iat": 1589224148,
  "exp": 1589260148,
  "nonce": "eKiihooH3Fah8Ieshah4leeti6ien3"
}

A parameter of "division" will reference "North America", as this is a top level key. A parameter "/groups/primary" uses JSON Pointer syntax to reference "Engineering" at a lower level. Any valid JSON Pointer can be used as a selector. Refer to the JSON Pointer RFC for a full description of the syntax

github logoEdit this page
IntroGuidesDocsCommunityPrivacySecurityBrandConsent Manager