New Vault OSS Now Includes Multi-factor Authentication! Learn more
  • Overview
    • Automated PKI Infrastructure
    • Data Encryption & Tokenization
    • Database Credential Rotation
    • Dynamic Secrets
    • Identity-based Access
    • Key Management
    • Kubernetes Secrets
    • Secrets Management
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Community
GitHubTry Cloud
Download
    • v1.10.x (latest)
    • v1.9.x
    • v1.8.x
    • v1.7.x
    • v1.6.x
    • v1.5.x
    • v1.4.x
  • What is Vault?
  • Use Cases
    • CLI Quick Start
    • HCP Quick Start
    • Developer Quick Start

  • Browser Support
  • Installing Vault
    • Overview
    • Architecture
    • High Availability
    • Integrated Storage
    • Security Model
    • Telemetry
    • Token Authentication
    • Key Rotation
    • Replication
    • Limits and Maximums
    • Overview
    • 'Dev' Server
    • Seal/Unseal
    • Namespace API Lock
    • Lease, Renew, and Revoke
    • Authentication
    • Tokens
    • Identity
    • OIDC Provider
    • Response Wrapping
    • Policies
    • Password Policies
    • Username Templating
    • High Availability
    • Storage
      • Overview
      • Autopilot
    • PGP, GnuPG, and Keybase
    • Recovery Mode
    • Resource Quotas
      • Overview
      • FAQ
    • Transform
    • Mount Migration
    • Overview
      • Overview
      • TCP
    • replication
      • Overview
      • AliCloud KMS
      • AWS KMS
      • Azure Key Vault
      • GCP Cloud KMS
      • OCI KMS
      • HSM PKCS11 ENT
      • Vault Transit
    • sentinel
      • Overview
      • Consul
      • Kubernetes
      • Overview
      • Aerospike
      • Alicloud OSS
      • Azure
      • Cassandra
      • CockroachDB
      • Consul
      • CouchDB
      • DynamoDB
      • Etcd
      • Filesystem
      • FoundationDB
      • Google Cloud Spanner
      • Google Cloud Storage
      • In-Memory
      • Manta
      • MSSQL
      • MySQL
      • OCI Object Storage
      • PostgreSQL
      • Integrated Storage (Raft)
      • S3
      • Swift
      • Zookeeper
    • telemetry
    • ui
    • Log Completed Requests
    • Entropy Augmentation ENT
    • kms_library ENT
    • Overview
    • agent
      • Overview
      • disable
      • enable
      • list
      • Overview
      • disable
      • enable
      • help
      • list
      • move
      • tune
    • debug
    • delete
      • Overview
      • delete
      • destroy
      • enable-versioning
      • get
      • list
      • metadata
      • patch
      • put
      • rollback
      • undelete
      • Overview
      • lookup
      • renew
      • revoke
      • Overview
      • get
      • inspect
    • list
    • login
    • monitor
    • namespace
      • Overview
      • diagnose
      • generate-root
      • init
      • key-status
      • members
      • migrate
      • raft
      • rekey
      • rotate
      • seal
      • step-down
      • unseal
      • usage
    • path-help
      • Overview
      • deregister
      • info
      • list
      • register
      • reload
      • Overview
      • delete
      • fmt
      • list
      • read
      • write
    • read
      • Overview
      • disable
      • enable
      • list
      • move
      • tune
    • server
    • ssh
    • status
      • Overview
      • capabilities
      • create
      • lookup
      • renew
      • revoke
    • unwrap
    • version
    • version-history
    • write
    • Token Helpers
    • Overview
      • Overview
        • Overview
        • AliCloud
        • AppRole
        • AWS
        • Azure
        • Cert
        • CF
        • GCP
        • JWT
        • Kerberos
        • Kubernetes
        • Overview
        • File
      • Overview
        • Overview
        • Kubernetes
    • Templates
    • Windows service

    • Overview
    • Active Directory
    • AliCloud
    • AWS
    • Azure
    • Consul
    • Cubbyhole
      • Overview
      • Cassandra
      • Couchbase
      • Elasticsearch
      • HanaDB
      • IBM Db2
      • InfluxDB
      • MongoDB
      • MongoDB Atlas
      • MSSQL
      • MySQL/MariaDB
      • Oracle
      • PostgreSQL
      • Redshift
      • Snowflake
      • Custom
    • Google Cloud
    • Google Cloud KMS
      • Overview
      • Azure Key Vault
      • AWS KMS
      • GCP Cloud KMS
    • KMIP ENTERPRISE
      • Overview
      • K/V Version 1
      • K/V Version 2
      • Overview
      • Identity Tokens
      • OIDC Identity Provider
    • MongoDB Atlas
    • Nomad
    • OpenLDAP
    • PKI (Certificates)
    • RabbitMQ
      • Overview
      • Signed Certificates
      • SSH OTP
      • Dynamic Key
    • Terraform Cloud
    • TOTP
      • Overview
      • FF3-1 Tweak Usage
      • Tokenization Transform ENTERPRISE
    • Transit
    • Venafi (Certificates)
    • Overview
    • AppRole
    • AliCloud
    • AWS
    • Azure
    • Cloud Foundry
    • GitHub
    • Google Cloud
      • Overview
      • OIDC Providers
    • Kerberos
    • Kubernetes
    • LDAP
      • Overview
      • FAQ
    • Oracle Cloud Infrastructure
    • Okta
    • RADIUS
    • TLS Certificates
    • Tokens
    • Username & Password

    • App ID DEPRECATED
    • MFA LEGACY / UNSUPPORTED
    • Overview
    • File
    • Syslog
    • Socket
    • Overview
    • Plugin Architecture
    • Plugin Development
    • Plugin Management
    • Plugin Portal
  • Vault Integration Program
  • Troubleshoot

    • Overview
      • Overview
      • Agent Injector vs. Vault CSI Provider
        • Overview
        • Running Vault
        • Enterprise Licensing
        • Running Vault on OpenShift
        • Configuration
          • Overview
          • Development
          • Standalone with Load Balanced UI
          • Standalone with TLS
          • Standalone with Audit Storage
          • External Vault
          • Using Kubernetes Auth Method
          • HA Cluster with Consul
          • HA Cluster with Raft
          • HA Enterprise Cluster with Raft
          • HA Enterprise DR Clusters with Raft
          • HA Enterprise Performance Clusters with Raft
          • Vault Agent Injector TLS Configuration
          • Vault Agent Injector TLS with Cert-Manager
        • Overview
        • Annotations
        • Installation
        • Examples
        • Overview
        • Installation
        • Configurations
        • Examples
      • Overview
      • Vault Lambda Extension
      • Running Vault
      • Overview
      • Installation
      • Configuration
      • Troubleshooting
      • Overview
      • Installation
      • Troubleshooting

    • Overview
    • Upgrade Plugins
    • Upgrade to 1.10.x
    • Upgrade to 1.9.x
    • Upgrade to 1.8.x
    • Upgrade to 1.7.x
    • Upgrade to 1.6.3
    • Upgrade to 1.6.2
    • Upgrade to 1.6.1
    • Upgrade to 1.6.0
    • Upgrade to 1.5.3
    • Upgrade to 1.5.2
    • Upgrade to 1.5.1
    • Upgrade to 1.5.0
    • Upgrade to 1.4.6
    • Upgrade to 1.4.5
    • Upgrade to 1.4.4
    • Upgrade to 1.4.1
    • Upgrade to 1.4.0
    • Upgrade to 1.3.10
    • Upgrade to 1.3.9
    • Upgrade to 1.3.8
    • Upgrade to 1.3.5
    • Upgrade to 1.3.4
    • Upgrade to 1.3.3
    • Upgrade to 1.3.2
    • Upgrade to 1.3.0
    • Upgrade to 1.2.7
    • Upgrade to 1.2.6
    • Upgrade to 1.2.5
    • Upgrade to 1.2.4
    • Upgrade to 1.2.1
    • Upgrade to 1.2.0
    • Upgrade to 1.1.2
    • Upgrade to 1.1.1
    • Upgrade to 1.1.0
    • Upgrade to 1.0.0
    • Upgrade to 0.11.6
    • Upgrade to 0.11.2
    • Upgrade to 0.11.0
    • Upgrade to 0.10.4
    • Upgrade to 0.10.2
    • Upgrade to 0.10.0
    • Upgrade to 0.9.6
    • Upgrade to 0.9.3
    • Upgrade to 0.9.2
    • Upgrade to 0.9.1
    • Upgrade to 0.9.0
    • Upgrade to 0.8.0
    • Upgrade to 0.7.0
    • Upgrade to 0.6.4
    • Upgrade to 0.6.3
    • Upgrade to 0.6.2
    • Upgrade to 0.6.1
    • Upgrade to 0.6.0
    • Upgrade to 0.5.1
    • Upgrade to 0.5.0

    • Overview
    • 1.10.0
    • 1.9.0
    • 1.8.0
    • 1.7.0
    • 1.6.0
    • 1.5.0

    • Overview
    • FAQ

    • Overview
    • Feature Deprecation Notice and Plans
    • License
    • Client Count
    • Login MFA
    • Server Side Consistent Token

  • Glossary

    • Overview
      • Overview
      • Autoloading
      • FAQ
    • Replication
      • Overview
      • Behavioral Changes
      • Security
    • Automated Integrated Storage Snapshots
    • Lease Count Quotas
    • Entropy Augmentation
    • Seal Wrap / FIPS 140-2
    • Namespaces
    • Performance Standbys
    • Eventual Consistency
    • Control Groups
    • Managed Keys
      • Overview
      • Duo MFA
      • Okta MFA
      • PingID MFA
      • TOTP MFA
      • Overview
      • Examples
      • Properties
    • HCP Vault
Type '/' to Search

»Consul Secrets Engine

The Consul secrets engine generates Consul API tokens dynamically based on Consul ACL policies.

»Setup

Most secrets engines must be configured in advance before they can perform their functions. These steps are usually completed by an operator or configuration management tool.

  1. Enable the Consul secrets engine:

    $ vault secrets enable consul
    Success! Enabled the consul secrets engine at: consul/
    
    $ vault secrets enable consul
    Success! Enabled the consul secrets engine at: consul/
    

    By default, the secrets engine will mount at the name of the engine. To enable the secrets engine at a different path, use the -path argument.

  2. Bootstrap the Consul ACL system if not already done. To begin configuring the secrets engine, we must give Vault the necessary credentials to manage Consul.

    In Consul versions below 1.4, acquire a management token from Consul using the acl_master_token from your Consul configuration file, or another management token:

    $ curl \
        --header "X-Consul-Token: my-management-token" \
        --request POST \
        --data '{"Name": "sample", "Type": "management"}' \
        https://consul.rocks/v1/acl/create
    
    $ curl \
        --header "X-Consul-Token: my-management-token" \
        --request POST \
        --data '{"Name": "sample", "Type": "management"}' \
        https://consul.rocks/v1/acl/create
    

    Vault must have a "management" type token so that it can create and revoke ACL tokens. The response will return a new token:

    {
      "ID": "7652ba4c-0f6e-8e75-5724-5e083d72cfe4"
    }
    
    {
      "ID": "7652ba4c-0f6e-8e75-5724-5e083d72cfe4"
    }
    

    For Consul 1.4 and above, use the command line to generate a token with the appropriate policy:

    $ CONSUL_HTTP_TOKEN="<management-token>" consul acl token create -policy-name="global-management"
    AccessorID:   865dc5e9-e585-3180-7b49-4ddc0fc45135
    SecretID:     ef35f0f1-885b-0cab-573c-7c91b65a7a7e
    Description:
    Local:        false
    Create Time:  2018-10-22 17:40:24.128188 -0700 PDT
    Policies:
        00000000-0000-0000-0000-000000000001 - global-management
    
    $ CONSUL_HTTP_TOKEN="<management-token>" consul acl token create -policy-name="global-management"
    AccessorID:   865dc5e9-e585-3180-7b49-4ddc0fc45135
    SecretID:     ef35f0f1-885b-0cab-573c-7c91b65a7a7e
    Description:
    Local:        false
    Create Time:  2018-10-22 17:40:24.128188 -0700 PDT
    Policies:
        00000000-0000-0000-0000-000000000001 - global-management
    
  3. Configure Vault to connect and authenticate to Consul:

    $ vault write consul/config/access \
        address="127.0.0.1:8500" \
        token="7652ba4c-0f6e-8e75-5724-5e083d72cfe4"
    Success! Data written to: consul/config/access
    
    $ vault write consul/config/access \
        address="127.0.0.1:8500" \
        token="7652ba4c-0f6e-8e75-5724-5e083d72cfe4"
    Success! Data written to: consul/config/access
    
  4. Configure a role that maps a name in Vault to a Consul ACL policy. Depending on your Consul version, you will either provide a policy document and a token_type, or a set of policies. When users generate credentials, they are generated against this role.

    For Consul versions below 1.4, the policy must be base64-encoded. The policy language is documented by Consul.

    Write a policy and proceed to link it to the role:

    $ vault write consul/roles/my-role policy="$(base64 <<< 'key "" { policy = "read" }')"
    Success! Data written to: consul/roles/my-role
    
    $ vault write consul/roles/my-role policy="$(base64 <<< 'key "" { policy = "read" }')"
    Success! Data written to: consul/roles/my-role
    

    For Consul versions 1.4 and above, generate a policy in Consul, and proceed to link it to the role:

    $ vault write consul/roles/my-role policies="readonly"
    Success! Data written to: consul/roles/my-role
    
    $ vault write consul/roles/my-role policies="readonly"
    Success! Data written to: consul/roles/my-role
    

    For Consul versions 1.5 and above, generate a role in Consul, and proceed to link it to the role:

    $ vault write consul/roles/my-role consul_roles="api-server"
    Success! Data written to: consul/roles/my-role
    
    $ vault write consul/roles/my-role consul_roles="api-server"
    Success! Data written to: consul/roles/my-role
    

    Token lease duration: If you do not specify a value for ttl (or lease for Consul versions below 1.4) the tokens created using Vault's Consul secrets engine are created with a Time To Live (TTL) of 30 days. You can change the lease duration by passing -ttl=<duration> to the command above with "duration" being a string with a time suffix like "30s" or "1h".

  5. For Enterprise users, you may further limit a role's access by adding the optional parameters consul_namespace and/or partition. Please refer to Consul's namespace documentation and admin partition documentation for further information about these features.

    For Consul versions 1.7 and above, link a Consul namespace to the role:

    $ vault write consul/roles/my-role consul_roles="namespace-management" consul_namespace="ns1"
    Success! Data written to: consul/roles/my-role
    
    $ vault write consul/roles/my-role consul_roles="namespace-management" consul_namespace="ns1"
    Success! Data written to: consul/roles/my-role
    

    For Consul version 1.11 and above, link an admin partition to a role:

    $ vault write consul/roles/my-role consul_roles="admin-management" partition="admin1"
    Success! Data written to: consul/roles/my-role
    
    $ vault write consul/roles/my-role consul_roles="admin-management" partition="admin1"
    Success! Data written to: consul/roles/my-role
    

»Usage

After the secrets engine is configured and a user/machine has a Vault token with the proper permission, it can generate credentials.

Generate a new credential by reading from the /creds endpoint with the name of the role:

$ vault read consul/creds/my-role
Key                 Value
---                 -----
lease_id            consul/creds/my-role/b2469121-f55f-53c5-89af-a3ba52b1d6d8
lease_duration      768h
lease_renewable     true
accessor            c81b9cf7-2c4f-afc7-1449-4e442b831f65
consul_namespace    ns1
local               false
partition           admin1
token               642783bf-1540-526f-d4de-fe1ac1aed6f0
$ vault read consul/creds/my-role
Key                 Value
---                 -----
lease_id            consul/creds/my-role/b2469121-f55f-53c5-89af-a3ba52b1d6d8
lease_duration      768h
lease_renewable     true
accessor            c81b9cf7-2c4f-afc7-1449-4e442b831f65
consul_namespace    ns1
local               false
partition           admin1
token               642783bf-1540-526f-d4de-fe1ac1aed6f0

Expired token rotation: Once a token's TTL expires, then Consul operations will no longer be allowed with it. This requires you to have an external process to rotate tokens. At this time, the recommended approach for operators is to rotate the tokens manually by creating a new token using the vault read consul/creds/my-role command. Once the token is synchronized with Consul, apply the token to the agents using the Consul API or CLI.

»Learn

Refer to Administer Consul Access Control Tokens with Vault for a step-by-step tutorial.

»API

The Consul secrets engine has a full HTTP API. Please see the Consul secrets engine API for more details.

github logoEdit this page
DocsAPILearnCommunityPrivacySecurityPress KitConsent Manager