Wednesday, November 19, 2025

HashiCorp Vault Leases

HashiCorp Vault Leases - Complete Lifecycle Management Guide

HashiCorp Vault Leases - Complete Lifecycle Management Guide

🎯 Prerequisites: Vault Fundamentals → Authentication Methods → Policies & Access Control → Token Management → Secrets Engines
📚 What You'll Master:
Complete lease lifecycle management: renewal strategies, revocation patterns, TTL inheritance, prefix operations, production use cases

Vault Leases Overview

What Are Vault Leases?

One of the key features of dynamic secrets is their limited lifetime. But how is that lifetime enforced by Vault? Through vault leases - the mechanism that controls the lifecycle of dynamically generated credentials.

🔑 Core Purpose:
Leases control the lifecycle of dynamic secrets by either:
  • Renewing - Extending the lifetime of a dynamic secret
  • Revoking - Terminating the dynamic secret before expiration

Leases Apply to Both Secrets and Tokens

Leases are a construct that exists for both dynamic secrets and service tokens:

Aspect Dynamic Secrets Service Tokens
Terminology Leases TTL (Time to Live)
Lifecycle Managed via lease commands Managed via token commands
Common Feature Both have limited lifetime and managed lifecycle
📊 Key Difference:
Same concept, different language. Dynamic secrets use "lease" terminology while service tokens use "TTL" terminology, but both represent a limited lifetime that you can manage through renewal or revocation.

Lease Properties & Metadata

Three Core Lease Properties

Every lease includes metadata that defines its characteristics and behavior:

✅ Lease Metadata Components:
  1. lease_id - Unique identifier constructed from path + unique ID
  2. lease_duration - Countdown timer showing remaining validity period
  3. renewable - Boolean indicating whether lease can be extended

Lease ID Structure

The lease_id is a construct that combines:

Format: <path_to_secret>/<unique_id>

Example: consul/creds/web/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Components:
• Path: consul/creds/web
• Unique ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Lease Duration

Lease duration functions as a countdown timer:

  • Initial Value - Set from default TTL at creation time
  • Countdown - Continuously decreases until expiration
  • Example - Starts at 30 minutes, counts down to zero
  • Expiration Behavior - When duration reaches zero, lease and secret are revoked

Renewable Property

The renewable Boolean determines lease extension capability:

  • true - Lease can be renewed/extended before expiration
  • false - Fixed lifetime from creation, cannot be extended
  • Configuration - Set at object level (role, group, user) within secrets engine
⚠️ No Direct Lookup Command:
Unlike tokens which have vault token lookup, there is no vault lease lookup command. You must use the special path /sys/leases/lookup to retrieve lease information.

Lease Duration & TTL Inheritance

Understanding Lease Duration

Lease duration is essentially the Time to Live (TTL) for a dynamic secret. Just like tokens have TTLs, dynamic secrets have lease durations that determine their validity period.

TTL Value Sources

When a dynamic secret or token is created, it inherits TTL values from multiple potential sources. The lease derives two critical values:

  • Default TTL - Initial lease duration when secret is created
  • Max TTL - Maximum allowable lifetime for the lease

TTL Inheritance Hierarchy

TTL values are inherited in a specific precedence order, from most general to most specific:

🎯 TTL Precedence (Lowest to Highest):
  1. System-Wide Defaults - Vault server configuration settings
  2. Mount Point Configuration - Secrets engine mount settings
  3. Object-Level Settings - Role, group, or user configuration

1. System-Wide Default TTL

Definition: Global default and max TTL defined in Vault server configuration

Scope: Applies to all leases and tokens unless overridden

Priority: Lowest - Used only when no other TTL is specified

Configuration: Set in Vault server config file

2. Mount Point TTL

Definition: Default and max TTL configured on secrets engine mount

Scope: Applies to all secrets from that specific engine

Priority: Medium - Overrides system-wide settings

Configuration: Set during engine enablement or via tune command

Example: vault secrets tune -default-lease-ttl=30m aws

3. Object-Level TTL

Definition: TTL configured on specific objects within secrets engine

Scope: Applies only to secrets generated from that object

Priority: Highest - Overrides both system and mount settings

Object Types: Roles, groups, users (depends on engine type)

Example: vault write consul/roles/web ttl=1h max_ttl=2h

TTL Inheritance Example

Level Default TTL Max TTL Applied?
System 32 days 32 days ❌ Overridden
Mount Point 30 minutes 2 hours ❌ Overridden
Role (Object) 1 hour 4 hours ✅ Applied
🎯 Key Concept:
The most specific configuration wins. Object-level settings override mount settings, which override system settings. This allows granular control over lease lifetimes for different use cases.

Renewable Property Configuration

The renewable property is set at the object level within the secrets engine:

Configuration Example:
vault write consul/roles/web \
    policies="web" \
    ttl=1h \
    max_ttl=2h \
    renewable=false

Result: Secrets from this role cannot be renewed

Lease Actions: Renewal & Revocation

Two Primary Lease Operations

When working with leases, you can perform two fundamental operations:

  1. Renew - Extend the lease lifetime
  2. Revoke - Terminate the lease before expiration

Lease Renewal

Renewal Characteristics:

✅ How Renewal Works:
  • Time Basis - Renewal is based on current time, not creation time
  • Increment Specification - Request renewal for specific duration (e.g., 30 minutes)
  • Countdown Reset - Lease duration resets to specified increment from now
  • Max TTL Constraint - Total duration from creation cannot exceed max TTL

Renewal Example:

Initial State:
• Created: 12:00 PM
• Default TTL: 1 hour
• Max TTL: 2 hours
• Current Time: 12:30 PM (30 minutes elapsed)
• Remaining: 30 minutes

Renewal Request at 12:30 PM:
vault lease renew -increment=30m <lease_id>

Result:
• New expiration: 1:00 PM (30 minutes from now)
• Total lifetime: 1 hour (within max TTL of 2 hours) ✅

Invalid Renewal Request at 12:30 PM:
vault lease renew -increment=2h <lease_id>

Result:
• Requested expiration: 2:30 PM (2 hours from now)
• Total lifetime: 2.5 hours (exceeds max TTL) ❌
• Vault response: Lease extended to max available (1:30 PM)
⚠️ Max TTL Enforcement:
If your renewal request would push the total lease lifetime beyond the max TTL (calculated from creation time), Vault will extend the lease only to the maximum allowable duration.

Lease Revocation

Revocation Process:

🔴 Revocation Sequence:
  1. Lease Revocation - Vault immediately invalidates the lease
  2. Queue Deletion Request - Vault queues request to secrets engine
  3. External Cleanup - Secrets engine deletes credential in external system

Example Scenario:

AWS Secrets Engine:
1. You revoke AWS credentials lease
2. Vault immediately marks lease as invalid
3. Vault queues deletion request to AWS
4. AWS secrets engine contacts AWS API
5. IAM credentials deleted from AWS account

Note: Add -sync flag to wait for external confirmation

Token Revocation Cascade

🎯 Important Behavior:
When you revoke a token, Vault automatically revokes all dynamic secrets generated by that token.

Example:
• Token generates 5 AWS credentials
• Token generates 3 database credentials
• Revoke the token
• Result: All 8 credentials are automatically revoked

Prefix Revocation

Prefix revocation allows mass revocation of all leases matching a specific path prefix.

🚨 Critical Warnings:
  • Requires Elevated Permissions - Sudo capability needed
  • Extremely Destructive - Revokes ALL leases on path
  • No Confirmation Prompt - Immediate execution
  • Use Case - Security breach response, credential rotation
Prefix Revocation Example:
vault lease revoke -prefix consul/creds/web/

Effect: Revokes all Consul credentials from web role
Impact: All applications using these credentials lose access
Recovery: Applications must request new credentials

CLI Commands for Lease Management

Lease Command Overview

All lease management at the CLI uses the vault lease command set.

Renew a Lease

Syntax:
vault lease renew [options] <lease_id>

Example:
vault lease renew -increment=30m consul/creds/web/a1b2c3d4

Options:
• -increment=<duration> - Requested extension duration
• -format=json - Output in JSON format

Revoke a Single Lease

Syntax:
vault lease revoke [options] <lease_id>

Example:
vault lease revoke consul/creds/web/a1b2c3d4

Options:
• -sync - Wait for external system confirmation

Revoke by Prefix

Syntax:
vault lease revoke -prefix <path_prefix>

Example:
vault lease revoke -prefix consul/creds/web/

Effect: Revokes ALL leases starting with specified prefix

⚠️ Warning: Requires sudo permissions, extremely destructive

List Leases

Syntax:
vault list sys/leases/lookup/<path>

Example:
vault list sys/leases/lookup/consul/creds/web/

Output: List of active lease IDs at specified path

Note: Returns unique IDs only, prepend path to get full lease_id

Lookup Lease Properties

Syntax:
vault write sys/leases/lookup lease_id=<lease_id>

Example:
vault write sys/leases/lookup lease_id=consul/creds/web/a1b2c3d4

Output Properties:
• expire_time - When lease expires (calculated from last renewal)
• issue_time - Original creation timestamp
• last_renewal - Most recent renewal timestamp
• renewable - Boolean indicating if lease can be renewed
• ttl - Current remaining time to live
⚠️ Lookup Command Quirk:
Unlike most operations, lease lookup requires vault write (not vault read) because you must submit data (the lease_id) as part of the request.

Complete Command Reference

Operation Command Purpose
Renew vault lease renew -increment=30m <id> Extend lease lifetime
Revoke vault lease revoke <id> Terminate single lease
Prefix Revoke vault lease revoke -prefix <path> Mass revocation by path
List vault list sys/leases/lookup/<path> Get active lease IDs
Lookup vault write sys/leases/lookup lease_id=<id> Get lease properties

Production Use Cases

Use Case 1: AWS Credentials with Auto-Renewal

🎯 Globomantics Scenario:
Requirement: Application needs AWS resource access with automatic credential lifecycle management.

Requirements:
  • On-demand credential generation
  • Automatic revocation after 12 hours of inactivity
  • Application remains active with credential renewal

Solution Architecture:

  1. Enable AWS Secrets Engine
    vault secrets enable aws
  2. Configure Role with 12-Hour Lease
    vault write aws/roles/app-role \
        credential_type=iam_user \
        policy_document=@policy.json \
        default_ttl=12h \
        max_ttl=24h
  3. Application Behavior
    • Request AWS credentials at startup
    • Renew credentials every 11 hours (before expiration)
    • If inactive for 12 hours, credentials auto-revoke
    • On activity resume, request new credentials
🎯 Benefits:
  • No permanent credentials stored in application
  • Automatic cleanup of inactive application credentials
  • Active applications maintain access through renewal
  • 12-hour inactivity threshold ensures security

Use Case 2: Consul Tokens with Fixed Expiration

🎯 Globomantics Scenario:
Requirement: Multiple users need Consul tokens with strict expiration and breach response capability.

Requirements:
  • Regular Consul token access for multiple users
  • Fixed 60-minute token lifetime (non-renewable)
  • Ability to revoke all tokens instantly if breach detected

Solution Architecture:

  1. Enable Consul Secrets Engine
    vault secrets enable consul
  2. Configure Role with Non-Renewable 60-Minute TTL
    vault write consul/roles/user-role \
        policies="user-policy" \
        ttl=60m \
        max_ttl=60m \
        renewable=false
  3. Normal Operations
    • Users request Consul tokens as needed
    • Tokens expire after exactly 60 minutes
    • Users request new tokens when needed
  4. Breach Response
    vault lease revoke -prefix consul/creds/user-role/
    • Instantly revokes ALL user tokens
    • Users request new tokens after incident resolution
🎯 Benefits:
  • Fixed 60-minute maximum exposure window
  • No token renewal prevents indefinite access
  • Prefix revocation enables rapid breach response
  • Forces regular credential rotation through expiration

Complete Hands-On Lab

Lab Environment Setup

Terminal 1 - Start Vault Server:
vault server -dev

Terminal 2 - Configure Environment:
export VAULT_ADDR='http://127.0.0.1:8200'
export VAULT_TOKEN='<root_token>'
vault login ${VAULT_TOKEN}

Terminal 3 - Start Consul Agent:
consul agent -dev -config-dir=./config

Lab Prerequisites

This lab assumes you have already completed the Consul secrets engine setup from the previous module:

  • Consul agent running with ACL enabled
  • Consul secrets engine enabled in Vault
  • Consul role configured with 1h TTL and 2h max TTL

Lab 1: Generate Leases

Generate Multiple Consul Credentials:

# Generate first credential
vault read consul/creds/web

# Output shows:
# lease_id: consul/creds/web/a1b2c3d4-e5f6-7890...
# lease_duration: 3600 (1 hour)
# lease_renewable: true
# token: <consul_token>

# Generate three more credentials
vault read consul/creds/web
vault read consul/creds/web
vault read consul/creds/web
📊 Lease ID Structure:
consul/creds/web/a1b2c3d4-e5f6-7890-abcd-ef1234567890
• Path: consul/creds/web
• Unique ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Lab 2: Renew a Lease

Standard Renewal:

# Renew with 30-minute increment
vault lease renew -increment=30m consul/creds/web/a1b2c3d4...

# Output:
# lease_id: consul/creds/web/a1b2c3d4...
# lease_duration: 1800 (30 minutes)
# lease_renewable: true

# Note: Original 1-hour lease shortened to 30 minutes!
⚠️ Renewal Behavior:
Specifying -increment=30m sets the lease duration to 30 minutes from NOW, not adding 30 minutes to remaining time. This can actually shorten the lease if the increment is less than remaining duration.

Lookup Lease Properties:

# Check lease details
vault write sys/leases/lookup lease_id=consul/creds/web/a1b2c3d4...

# Output shows:
# expire_time: 2025-11-20T13:30:00Z (calculated from last renewal)
# issue_time: 2025-11-20T12:00:00Z (original creation)
# last_renewal: 2025-11-20T13:00:00Z (most recent renewal)
# renewable: true
# ttl: 1757 (29 minutes, 17 seconds remaining)

# Run again to see countdown
vault write sys/leases/lookup lease_id=consul/creds/web/a1b2c3d4...
# ttl: 1719 (28 minutes, 39 seconds remaining)

Lab 3: Exceed Max TTL

Attempt to Exceed Maximum:

# Try to renew for 2 hours
vault lease renew -increment=2h consul/creds/web/a1b2c3d4...

# Vault response:
# WARNING: Request could not be honored
# Effective max TTL less than requested increment
# Max available from creation time: 2 hours
# Requested from renewal time: 2 hours
# Result: Lease capped at maximum available (1h 57m)

# lease_id: consul/creds/web/a1b2c3d4...
# lease_duration: 7020 (1 hour, 57 minutes)
# lease_renewable: true
🎯 Max TTL Calculation:
• Original creation: 12:00 PM
• Max TTL: 2 hours (expires at 2:00 PM)
• Renewal request at: 12:03 PM
• Requested increment: 2 hours (would expire at 2:03 PM)
• Vault caps at: 1:57 minutes remaining (expires at 2:00 PM exactly)

Lab 4: List Active Leases

# Get list of active lease IDs
vault list sys/leases/lookup/consul/creds/web/

# Output (unique IDs only):
# Keys
# ----
# a1b2c3d4-e5f6-7890-abcd-ef1234567890
# b2c3d4e5-f6a7-8901-bcde-f12345678901
# c3d4e5f6-a7b8-9012-cdef-123456789012
# d4e5f6a7-b8c9-0123-def1-234567890123

# Note: Prepend "consul/creds/web/" for full lease_id

Lab 5: Revoke Single Lease

# Revoke specific lease
vault lease revoke consul/creds/web/a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Output:
# Success! Revoked lease: consul/creds/web/a1b2c3d4...
# (queued for deletion in Consul)

# Verify revocation
vault list sys/leases/lookup/consul/creds/web/

# Output (first ID now missing):
# Keys
# ----
# b2c3d4e5-f6a7-8901-bcde-f12345678901
# c3d4e5f6-a7b8-9012-cdef-123456789012
# d4e5f6a7-b8c9-0123-def1-234567890123

Lab 6: Prefix Revocation

# Revoke ALL leases at path
vault lease revoke -prefix consul/creds/web/

# Output:
# Success! Revoked leases (queued for deletion):
# consul/creds/web/b2c3d4e5...
# consul/creds/web/c3d4e5f6...
# consul/creds/web/d4e5f6a7...

# Verify all leases gone
vault list sys/leases/lookup/consul/creds/web/

# Output:
# No value found at sys/leases/lookup/consul/creds/web/
🚨 Production Warning:
Prefix revocation immediately invalidates ALL credentials at the specified path. In production:
  • Verify path before executing
  • Coordinate with application teams
  • Plan for credential reissuance
  • Document as part of incident response

Lab 7: Verify Consul Token Revocation

# List Consul ACL tokens
consul acl token list -format json | jq -r '.[].AccessorID'

# Before revocation: Shows multiple tokens
# After revocation: Vault-generated tokens removed

# Demonstrates end-to-end lifecycle:
# 1. Vault generates Consul token
# 2. Vault manages lease
# 3. Vault revokes lease
# 4. Vault deletes token in Consul

Production Best Practices

🎯 Deployment Guidelines:
  1. Renewal Strategy - Implement renewal before 75% of lease duration expires
  2. Error Handling - Handle renewal failures gracefully, request new credentials
  3. TTL Configuration - Set appropriate defaults for application types:
    • Short-lived: User sessions (30m-1h)
    • Medium-lived: Application credentials (4h-12h)
    • Long-lived: Service accounts (24h max)
  4. Max TTL Enforcement - Always set max TTL to enforce credential rotation
  5. Monitoring - Track lease expiration patterns and renewal failures
  6. Incident Response - Document prefix revocation procedures
  7. Testing - Test renewal and revocation in staging before production
  8. Automation - Automate lease renewal in application code

Key Takeaways

  • Universal Leases - All dynamic secrets and service tokens have leases/TTLs
  • Renewal Timing - Based on current time, not creation time
  • Max TTL Constraint - Total lifetime from creation cannot exceed max TTL
  • Revocation Process - Immediate lease invalidation, queued external deletion
  • Token Cascade - Revoking a token revokes all associated dynamic secrets
  • Prefix Power - Mass revocation requires sudo, use with extreme caution
  • No Direct Lookup - Use /sys/leases/lookup path for lease properties
  • Lifecycle Management - Implement automated renewal and error handling

What's Next?

With lease management mastered, you now have complete control over the Vault ecosystem: authentication, authorization, secrets storage and generation, and credential lifecycle management. The next steps involve production deployment topics like high availability, disaster recovery, and enterprise features.

🎯 Practice Challenge:
Build a complete credential lifecycle system:
  1. Configure multiple secrets engines with different TTL strategies
  2. Implement automated lease renewal in application code
  3. Create monitoring for lease expiration patterns
  4. Design incident response plan with prefix revocation procedures
  5. Test renewal failures and credential reacquisition
  6. Build dashboard showing active leases and expiration timeline

Congratulations! You've completed the HashiCorp Vault Associate certification learning path covering fundamentals, authentication, policies, tokens, secrets engines, and lease management. You're now equipped to implement enterprise-grade secrets management with complete lifecycle control!

By at

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)