HashiCorp Vault Token Management

HashiCorp Vault Token Management - Complete Lifecycle Guide

🎯 Prerequisites: Vault Fundamentals → Authentication Methods → Policies & Access Control
📚 What You'll Master:
Complete token lifecycle management from creation to revocation with service/batch patterns, TTL optimization, and hierarchy design

Table of Contents

1. Token Overview & Architecture
2. Token Properties & Attributes
3. Token Types: Service vs Batch
4. Token Lifecycle & TTL Management
5. Root Tokens & Emergency Access
6. Periodic Tokens & Long-Running Services
7. Token Hierarchy & Parent-Child Relationships
8. Complete Implementation Guide

Token Overview & Architecture

What Are Vault Tokens?

Tokens are the fundamental currency of Vault operations. Every interaction with Vault requires a token - they're not just authentication artifacts, they're the primary mechanism for accessing any Vault functionality.

🔑 Core Concept:
Without a token, there's virtually nothing you can do with Vault. When you initialize Vault, the first thing generated is a root token because you need some way to access the system initially.

Token Creation Methods

There are three primary ways tokens are created in Vault:

• Authentication Methods - After successful authentication (userpass, AppRole, etc.), the method returns a token
• Existing Token Generation - Use an existing token (like root) to create child tokens
• Root Token Generation - Special operator process using unseal/recovery keys

Token Access Patterns

# Authentication method creates token
vault login -method=userpass username=alice
# Returns: Token for subsequent operations

# Existing token creates child token
vault token create -policy=accounting
# Uses current token to generate new token

# Root token generation (emergency)
vault operator generate-root
# Requires unseal keys, multiple operators

Token Properties & Attributes

Essential Token Properties

Token ID - The actual value submitted for Vault operations

• Primary credential for API calls
• Required for all vault CLI operations
• Sensitive value that must be protected

Accessor - Management handle without operational access

• View token properties without using the token
• Check capabilities on specific paths
• Renew or revoke tokens safely
• Audit logging without exposing token ID

Type - Defines token behavior (service or batch)

• Service tokens: Full-featured, persistent storage
• Batch tokens: Limited features, memory-only

Policies - Associated access control policies

• Assigned during token creation
• Can be continuously evaluated
• Define what the token can access

TTL (Time to Live) - Token validity duration

• Defines how long token remains valid
• Can be renewed (for service tokens)
• Maximum TTL constraints apply

Orphaned Status - Parent-child relationship indicator

• Orphaned: No parent token
• Child: Has parent token dependency
• Affects revocation behavior

Token ID vs Accessor Pattern

🎯 Use Case Example:
Parent process manages worker tokens but shouldn't have operational access to those tokens. Solution: Store accessors in parent process, give token IDs to workers. Parent can monitor, renew, and revoke without being able to access secrets.

# Token operations using ID
vault auth -method=token token=s.xyz123
vault kv get secrets/myapp

# Management operations using accessor
vault token lookup -accessor 8fb95528-57c6-c0a4-514b-42066aae6d39
vault token renew -accessor 8fb95528-57c6-c0a4-514b-42066aae6d39
vault token revoke -accessor 8fb95528-57c6-c0a4-514b-42066aae6d39

Token Types: Service vs Batch

Service Tokens - Full-Featured Default

Characteristics:

• Persistent Storage - Written to storage backend
• Full Feature Set - All token capabilities available
• Accessor Support - Can be managed via accessor
• Renewable - TTL can be extended
• Child Token Creation - Can spawn additional tokens
• Token Prefix - Always begins with s.

Trade-offs:

• Higher storage overhead
• Slower creation/revocation
• Better for long-lived services

Batch Tokens - High-Performance Limited

Characteristics:

• Memory-Only - Not written to persistent storage
• Limited Features - Reduced capability set
• No Accessor - Cannot be managed externally
• Non-Renewable - Fixed TTL, cannot be extended
• No Child Tokens - Cannot create additional tokens
• Token Prefix - Always begins with b.

Trade-offs:

• Minimal storage overhead
• Fast creation/automatic cleanup
• Perfect for high-volume, short-lived operations

Service vs Batch Decision Matrix

✅ Choose Service Tokens When:

• Long-running services requiring token renewal
• Parent processes needing to create child tokens
• Operations requiring accessor-based management
• Interactive user sessions
• CI/CD pipelines with complex workflows

⚡ Choose Batch Tokens When:

• High-volume, short-lived container workloads
• Horizontally scaling applications (100s-1000s of instances)
• Limited lifetime jobs (processing, batch operations)
• No token renewal requirements
• Minimal security exposure needed

Real-World Scenario: Container Scaling

Scenario: Horizontally-scaling containerized job processor
Requirements:

• Scales from 10 to 1000+ instances dynamically
• Each container needs secrets access for job duration only
• Tokens should automatically expire with container lifecycle
• No token abuse if container is compromised

Solution: Authentication method configured for batch tokens

# Configure auth method for batch tokens
vault write auth/kubernetes/role/job-processor \
    bound_service_account_names=job-processor \
    bound_service_account_namespaces=production \
    policies=job-secrets \
    token_type=batch \
    ttl=30m

# Result: High-performance tokens for scaling workloads

Token Lifecycle & TTL Management

Token Lifetime Properties

Understanding token TTL involves several interconnected properties:

• creation_time - UNIX timestamp of token creation
• creation_ttl - Initial TTL set during creation
• ttl - Current remaining time (computed value)
• expire_time - Projected expiration time
• explicit_max_ttl - Hard maximum limit (if set)
• issue_time - Human-readable creation time

TTL Hierarchy & Effective Max TTL

Token maximum lifetime is determined by multiple factors in order of precedence:

1. Explicit Max TTL - Set during token creation, overrides everything
2. Auth Method Object Max TTL - Set on users/roles within auth method
3. Mount Max TTL - Set on auth method mount
4. System Max TTL - Global default (32 days if not configured)

⚠️ Important Rule:
Auth method object max TTL cannot exceed mount max TTL or system max TTL. However, mount max TTL can exceed system max TTL, providing more flexibility at the auth method level.

Token Lifecycle Commands

Create Token with TTL:

vault token create -policy=accounting -ttl=60m

Look Up Token Properties:

# Using token ID
vault token lookup s.xyz123

# Using accessor
vault token lookup -accessor 8fb95528-57c6-c0a4-514b-42066aae6d39

Renew Token:

# Renew current token
vault token renew -increment=60m

# Renew specific token
vault token renew s.xyz123 -increment=30m

Check Token Capabilities:

vault token capabilities s.xyz123 secrets/apikeys

Revoke Token:

# Revoke using token ID
vault token revoke s.xyz123

# Revoke using accessor
vault token revoke -accessor 8fb95528-57c6-c0a4-514b-42066aae6d39

# Revoke current token
vault token revoke -self

Root Tokens & Emergency Access

Root Token Characteristics

🚨 Critical Security Properties:

• Unlimited Access - Can perform any operation in Vault
• No Expiration - Only token type that doesn't expire
• Dangerous - Can create additional root tokens
• Emergency Use Only - Should be revoked immediately after use

Root Token Creation Methods

1. Vault Initialization:

vault operator init
# Returns: Unseal keys + initial root token

2. Existing Root Token:

vault token create -policy=root
# Creates new root token from existing root token

3. Emergency Generation Process:

# Multi-operator process
vault operator generate-root -init
vault operator generate-root [OTP] [unseal-key]
# Requires quorum of unseal keys

Root Token Use Cases

🎯 Legitimate Root Token Scenarios:

• Initial Setup - Configuring first auth methods and policies
• Auth Method Failure - Primary authentication system unavailable
• Emergency Recovery - Critical system maintenance requiring full access
• Disaster Recovery - Restoring Vault configuration from backup

Root Token Best Practices

⚠️ Security Protocol:

1. Multiple Witnesses - Never use root tokens alone
2. Immediate Revocation - Revoke as soon as task is complete
3. Audit Everything - Log all root token activities
4. No Persistence - Don't store root tokens anywhere
5. Regular Review - Check for unexpected root tokens

# Always revoke root tokens immediately
vault token revoke -self

# Check for unexpected root tokens
vault list auth/token/accessors | \
  xargs -I {} vault token lookup -accessor {} | \
  grep -A 5 -B 5 "policies.*root"

Periodic Tokens & Long-Running Services

Periodic Token Concept

Periodic tokens solve the problem of long-running services that need persistent access but can't dynamically update their credentials.

Key Properties

• No Max TTL - Can be renewed indefinitely
• Period-Based Renewal - Must be renewed within defined period
• Requires Sudo - Elevated permissions needed for creation
• Service Token Type - Full-featured with persistent storage

How Periodic Renewal Works

Renewal Behavior:
When you renew a periodic token, Vault ignores your requested increment and always sets the TTL to the defined period. This ensures consistent renewal intervals regardless of the renewal request.

# Create periodic token with 2-hour period
vault token create -policy=database -period=2h

# Renewal always sets TTL to 2 hours
vault token renew s.xyz123 -increment=3h
# Result: TTL set to 2h (period), not 3h (requested)

Real-World Use Case: Legacy Database System

Scenario: Legacy database system integration
Challenge:

• Database system can't dynamically update token values
• Restarting database service is operationally expensive
• Token must remain static for database lifetime
• Regular token renewal required for security

Solution: Periodic token with automated renewal

# Create periodic token for database
vault token create -policy=database-secrets -period=10m

# Database configuration
VAULT_TOKEN=s.xyz123-periodic-token

# Automated renewal script (cron job)
*/5 * * * * vault token renew s.xyz123-periodic-token

Periodic Token Safety Features

Explicit Max TTL Override:

# Periodic token with absolute maximum
vault token create -policy=database \
    -period=10m \
    -explicit-max-ttl=30d

# Can be renewed every 10 minutes for max 30 days

Natural Expiration:

• If renewal process stops, token expires after one period
• Service shutdown automatically ends token lifecycle
• No manual cleanup required for terminated services

Token Hierarchy & Parent-Child Relationships

Token Hierarchy Purpose

Token hierarchies prevent token escape attacks where users try to avoid revocation by creating child tokens with similar permissions.

Hierarchy Rules

• Child Dependency - Child tokens depend on parent token
• Cascade Revocation - Revoking parent revokes all children
• Service Tokens Only - Batch tokens cannot create children
• Unlimited Depth - Can create multi-level hierarchies

Orphan Tokens

Orphan tokens have no parent dependency and are created in three ways:

1. Explicit Creation - Using -orphan flag
2. Auth Method Tokens - First token from auth method is orphan
3. Orphaning on Revocation - Convert children to orphans during parent revocation

Hierarchy Management Examples

Create Child Token:

# Child inherits parent relationship
vault token create -policy=worker

Create Orphan Token:

# No parent dependency
vault token create -policy=service -orphan

Revoke with Orphaning:

# Revoke parent, make children orphans
vault token revoke -mode=orphan s.parent-token

Hierarchy Visualization

Root Token (orphan)
├── Management Token (child)
│   ├── Operator Token (grandchild)
│   └── Audit Token (grandchild)
├── Service Token (child)
│   ├── Worker Token #1 (grandchild)
│   └── Worker Token #2 (grandchild)
└── Auth Method Token (orphan)
    ├── User Token (child)
    └── App Token (child)

Complete Implementation Guide

Environment Setup

# Start Vault development server
vault server -dev

# Configure environment
export VAULT_ADDR="http://127.0.0.1:8200"
export ROOT_TOKEN="dev-only-token"

# Login with root token
vault login $ROOT_TOKEN

Service Token Management

Create and Inspect Service Token:

# Create service token
vault token create -policy=default -ttl=60m

# Store token ID and accessor
TOKEN_ID="s.xyz123"
ACCESSOR="8fb95528-57c6-c0a4-514b-42066aae6d39"

# Inspect token properties
vault token lookup $TOKEN_ID

# Inspect via accessor (no ID in output)
vault token lookup -accessor $ACCESSOR

Token Renewal and Capabilities:

# Check current TTL
vault token lookup $TOKEN_ID | grep ttl

# Renew token
vault token renew $TOKEN_ID -increment=30m

# Check capabilities on specific path
vault token capabilities $TOKEN_ID secrets/myapp

# Revoke using accessor
vault token revoke -accessor $ACCESSOR

Batch Token Implementation

# Create batch token
vault token create -type=batch -policy=default -ttl=30m

# Store long batch token ID
BATCH_TOKEN="b.very-long-batch-token-string"

# Inspect batch token (note: no accessor)
vault token lookup $BATCH_TOKEN

# Try to renew (will fail)
vault token renew $BATCH_TOKEN
# Error: batch tokens cannot be renewed

Authentication Method with TTL Configuration

# Enable userpass with custom max TTL
vault auth enable -max-lease-ttl=776h userpass

# Create user with specific token max TTL
vault write auth/userpass/users/alice \
    password=secret123 \
    token_policies=default \
    token_max_ttl=784h

# Login as user
vault login -method=userpass username=alice
# Password: secret123

# Check inherited TTL (will be limited by mount max)
vault token lookup | grep ttl

Periodic Token Creation and Management

# Login as root (required for sudo)
vault login $ROOT_TOKEN

# Create periodic token
vault token create -policy=default -period=2h

# Store periodic token
PERIODIC_TOKEN="s.periodic-token-id"

# Inspect periodic token properties
vault token lookup $PERIODIC_TOKEN

# Renew with large increment (limited to period)
vault token renew $PERIODIC_TOKEN -increment=3h

# Verify TTL is set to period (2h), not increment (3h)
vault token lookup $PERIODIC_TOKEN | grep ttl

Token Hierarchy Testing

# Create parent token
vault token create -policy=default -ttl=1h
PARENT_TOKEN="s.parent-token-id"

# Login with parent token
vault login $PARENT_TOKEN

# Create child token
vault token create -policy=default -ttl=30m
CHILD_TOKEN="s.child-token-id"

# Create orphan token
vault token create -policy=default -orphan -ttl=30m
ORPHAN_TOKEN="s.orphan-token-id"

# Revoke parent (child should be revoked, orphan survives)
vault token revoke $PARENT_TOKEN

# Test child token (should fail)
vault login $CHILD_TOKEN
# Error: token not found

# Test orphan token (should work)
vault login $ORPHAN_TOKEN
# Success: orphan tokens survive parent revocation

Advanced Token Management

List All Token Accessors:

# List all token accessors
vault list auth/token/accessors

# Inspect each token
for accessor in $(vault list -format=json auth/token/accessors | jq -r '.[]'); do
  echo "Accessor: $accessor"
  vault token lookup -accessor $accessor | grep -E "(policies|ttl|type)"
  echo "---"
done

Token Audit and Monitoring:

# Enable audit logging
vault audit enable file file_path=/tmp/vault-audit.log

# Check audit log for accessor usage
tail -f /tmp/vault-audit.log | jq '.auth.accessor'

# Monitor token activities by accessor
grep "8fb95528-57c6-c0a4-514b-42066aae6d39" /tmp/vault-audit.log

Production Token Strategies

Token Type Selection Guidelines

🎯 Decision Framework:

• Interactive Users → Service tokens with reasonable TTL
• Long-Running Services → Service tokens with renewal automation
• Legacy Systems → Periodic tokens with external renewal
• Container Workloads → Batch tokens from auth methods
• CI/CD Jobs → Service tokens with job-specific TTL
• High-Volume APIs → Batch tokens for performance

TTL Configuration Best Practices

⚠️ TTL Strategy Guidelines:

• Short TTLs - Reduce exposure window, require renewal automation
• Appropriate Max TTLs - Set sensible limits at system/mount/object levels
• Renewal Monitoring - Alert on renewal failures for critical tokens
• Grace Periods - Renew tokens before 80% of TTL expires
• Emergency Access - Maintain break-glass root token procedures

Token Security Checklist

🔒 Security Controls:

• Accessor Management - Use accessors for token administration
• Hierarchical Revocation - Leverage parent-child relationships
• Regular Auditing - Monitor unexpected long-lived tokens
• Root Token Governance - Multi-person approval and immediate revocation
• Automated Cleanup - Remove unused tokens via accessor enumeration

Key Takeaways

• Tokens Are Everything - All Vault operations require tokens; they're the primary access mechanism
• Choose Token Types Wisely - Service tokens for flexibility, batch tokens for performance
• Manage TTLs Strategically - Balance security (short TTLs) with operational efficiency
• Root Tokens Are Dangerous - Use only for emergencies, always with multiple operators, revoke immediately
• Accessors Enable Safe Management - Monitor and control tokens without operational access
• Hierarchies Prevent Escape - Parent revocation cascades to children unless explicitly orphaned
• Periodic Tokens Solve Legacy Problems - Enable indefinite renewal for systems that can't update credentials

What's Next?

With authentication, policies, and token management mastered, you're ready to explore Vault secrets engines - the core functionality that makes Vault valuable. Learn about static secrets (KV), dynamic secrets (databases, cloud providers), and advanced patterns like secrets rotation and leasing.

🎯 Practice Challenge:
Build a complete token management system:

1. Create hierarchical token structure for different service tiers
2. Implement batch tokens for high-volume container workloads
3. Configure periodic tokens for legacy system integration
4. Build automated renewal and monitoring for production tokens
5. Establish root token emergency procedures with multi-operator approval

Ready for secrets management? Your Vault security foundation is complete - authentication methods for identity, policies for authorization, and tokens for access control. Time to put it all together with comprehensive secrets engine implementation!