Authentication
Authentication Method
components that perform authentication and manage identities
Responsible for assigning identity and policies to a user
Multiple authenticaiton methods can be enabled depending on your use case, can be differentiated by human vs system methods
Once authenticated, Vault will issue a client token used to make all subsequent Vault requests (read/write)
The fundamental goal of all auth methods is to obtain a token
Each token has an associated policy (or policies) and a TTL
Token auth method cannot be disabled
Authenticating with external identity ( LDAP, OIDC) will generate a token
If no token is provided for non-authentication requests, there are no redirects for authentication - no hints or suggestions - A 403 Access Denied will be returned
Choosing an Auth method
Certain auth methods are ideal for different use cases
Many auth methods may satisfy the requirements, but often there's one that works the best for a situation
In contrast, just because you are usin a certain platform does not mean you need to use the related auth method
Example: Azure VM can authenticate using the Azure auth method, but AppRole, Userpass, TLS, OIDC, etc would still be a posibility. So Azure might be the best, but it is not limited to only Azure
Key words when choosing an auth method:
Frequently Rotated
generally means a dynamic credential:
meet the requirements: AWS, LDAP, Azure, GCP, K8s
does not meet the requirements: Userpass, TLS, AppRole
Remove Secrets from process or pipeline
generally means a dynamic or integrated credential
meets the requirements: AWS, Azure, GCP, K8s
does not meet the requirements: Userpass, LDAP
Use existing user credentials:
generally means it should integrate with an existing identity provider
meets the requirement: OIDC, LDAP, Okta, Github
Does not meet requirement: Userpass, Azure, AWS, GCP
Human vs System Auth Methods
List of Auth Methods: AppRole, Kubernetes, Github, Token, Cloudfoundry, AWS, Azure, GCP, Oracle Cloud, JWT/OIDC, Okta, kerberos, Radius, TLS, Userpass, Alibaba Cloud
Human-based auth methods: userpass, radius, okta, jwt/OIDC, github
integrates with an existing identity provider
requires a hands-on approach to use
Logging via prompt or pop-up
Often configured with the platforms integrated MFA
System-based auth methods: the rest
users non-human friendly methodologies (not easy to remember)
usually integrates with an existing platform
vault validates credentials with the platform
Working with Auth Methods
Most auth method must be enabled before they can be used
The token auth method is enabled by default, and cannot be enabled nor disabled
New vault deployment will use a token for authentication
Only method of authentication for a new Vault deployment is a root token
Each auth method is enabled at a path, a path can be chosen when ( and only when) it is enabled
If a path is not provided, the auth method will be enabled at its default path which is equal to the type of auth method (e.g aws is mounted at "aws", approle is mounted at "approle")
Configuring Auth Methods using CLI
vault auth {enable|disable|list|tune|help}
vault auth enable -path=vault-course -description=Myapp approle
vault write auth/$path_name/$option
vault write auth/approle/role/vault-course secret_id_ttl=10m token_num_uses=10 token_ttl=20m token_max_ttl=30m secret_id_num_users=40
vault auth tune -default-lease-ttl=24h hat/
vault write auth/hat/users/usera password=vault policies=hat
vault list auth/hat/users
vault read auth/hat/users/usera
Configuring Auth Methods using API
curl --header "X-Vault-Token: $token" --request POST --data @auth.json http://$host/v1/sys/auth/approle
curl --header "X-Vault-Token: $token" --request POST --data @policies.json http://$host/v1/auth/approle/role/vaultcourse: create an approle vaultcourse
curl --header "X-Vault-Token: $token" http://$host/v1/auth/approle/role/vaultcourse/role-id | jq: get role id
curl --header "X-Vault-Token: $token" http://$host/v1/auth/approle/role/vaultcourse/secret-id | jq: get role id
Configuring AppRole Auth Method
vault auth enable approle: enable approle at default path approle/
vault write auth/approle/role/hatrole policies=hat token_ttl=20m: set policy and options
vault list auth/approle/role: list approle
vault read auth/approle/role/hatrole/role-id: get role id
vault write -force auth/approle/role/hatrole/secret-id: set secret id for approle hatrole
vault write auth/approle/login role_id=$role_id_from_get_role_id_command secret_id=$secret_id_from_set_secret_id_command: login usin approle
Configuring Okta Auth Method
Login to Okta dashboard, create an API Key: Security > API, then copy it
vault auth enable okta: enable okta auth method
vault write auth/okta/config base_url="okta.com" "org_name="$orgname" api_token="$tokenfromoktadashboard": configure okta config
vault read auth/okta/config: read config
vault write auth/okta/users/[email protected] policies=hat: create a user (using the email created in okta)
Configuring Userpass Auth Method
vault auth enable userpass
vault write auth/userpass/users/hat password=$password policies=hat: create users
vault list auth/userpass/users: list users
vault read auth/userpass/users/hat: read config of user hat
vault login -method=userpass username=hat: login with user hat
Vault Authentication (Consuming the Auth method)
There are a few ways to authenticate to Vault when using the CLI
Use the vault login command
Authenticate using a token or another auth method
Makes use of a token helper
Use VAULT_TOKEN environment variable
Use if already have a token
Vault Authentication using CLI
vault login: login using token
Can use token helper which stores token in .vault-token file
vault login -method=userpass username=hat: used to obtain a token
Paring the JSON Response to obtain a vault token
Vault Authentication using API
Authentication requests to the Vault HTTP API return a JSON response that include
the token: auth.client_token
the token accessor: auth.accessor
information about attached policies
curl --request POST --data @auth.json https:\$vaultsite/v1/auth/approle/login: auth.json contains role_id and secret_id
To access API explorer, login to UI and open CLI, then type in API
Vault Token
Token are the core method for authentication
Most operations in Vault require an existing token (not all, though)
Accessing a login path doesn't for example
The token auth method is responsible for creating and storing tokens
The token auth method cannot be disabled
Tokens can be used directly, or they can be used with another auth method
Authenticating with an external identity (e.g LDAP) dynamically generate tokens
Tokens have one or more policies attached to control what the token is allowed to perform
Types of Tokens
service token are the default token type in Vault
They are persisted to storage (heavy storage read/write)
can be renewed, revoked, and create child tokens
Mostly work with service tokens
batch tokens are encrypted binary large object (blobs)
Designed to be lightweight & scalable
They are not persisted to storage but they are fully-featured
Ideal for high-volume operations, such as encryption
Can be used for DR replication cluster promotion as well
Comparing Token Types
Can be Root Tokens
Y
N
Can create child Tokens
Y
N
Renewable
Y
N
Can be periodic
Y
N
Can have explicit Max TTL
Y
N
Has an accessor
Y
N
Has Cubbyhole
Y
N
Revoked with Parent (if not orphan)
Y
Stop working
Dynamic Secrets Lease Assignment
Self
Parent (if not orphan)
Can be used across performance replication clusters
N
Y
Creation scales with performance standby node count
N
Y
Performance Cost
Heavyweight (Multiple writes per token creation)
Lightweight (No storage cost for token creation)
Token Hierarchy
Each token has a TTL, except root token
Tokens are revoked once reached its TTL unless renewed
Once a token reaches its max TTL, it gets revoked
May be revoked early by manually revoking the token
When a parent token is revoked, all of its children are revoked as well
Controlling Token Lifecycle
I have a long-running app which cannot handle the regeneration of a token or secret
Periodic Service Token
I need a token that gets revoked automatically after one use
Service Token with use Limit
My app can't use a token where its expiration is infuenced by its parent
Orphan service token
Periodic Token
When having a token be revoked would be problematic
Root or sudo users have the ability to generate periodic tokens
Periodic tokens have a TTL, but no max TTL
Periodic tokens have live for an infinite amount of time, so long as they are renewed within their TTL
Service Token with Use Limits
When you want to limit the number of requests coming to Vault from a particular token:
Limit the token's number of uses in addition to TTL and Max TTL
Use limit tokens expire at the end of their last use, regardless of their remaining TTLs
Use limit tokens expire at the end of their TTLs, regardless of their remaining uses
Orphan Token
When the token hierarchy behavior is not desirable:
Root or sudo users have the ability to generate orphan tokens
Orphan tokens are not children of their parent; therefore, do not expire when their parent does
Orphan tokens still expire when their own Max TTL is reached
Managing Token using CLI
vault token {capabilities|create|lookup|renew|revoke}
vault token lookup $token
vault token create -display_name=jenkins -policy=training,certs -ttl=24h -explicit-max-ttl=72h
vault token create -ttl=5m -policy=training
vault token create -policy="training" -period="24h": periodic token
vault token create -policy="training" -use-limit=2: service token with use limit
vault token create -policy="training" -orphan: orphan token
Configure AppRole auth method to generate batch tokens:
Configure the approle auth method to generate periodic tokens:
vault token capabilities $token kv/data/apps/webapp: lookup capabilities of a token on a particular path
Managing Tokens using API
Authenticating to Vault with an auth method will result in a response that includes a token
Response is in json
Use jq to parse .auth.client_token
Future requests to Vault such as requests for a secret or to make a configuration change should include this token
Token is sent via X-Vault-Token header
Authorization Bearer is also a valid header
Root Token
Root token is a superuser that has unlimited access to Vault
It does not have a TTL
Attached to the root policy
Root tokens can create other root tokens that DO have a TTL
Root tokens should not be used on a day-to-day basis
In fact, rarely should a token even exist
Once a root token have been used, it should be revoked
Initial root token comes from Vault initialization
Only method of authentication when first deploying Vault
Used for initial configuration - such as auth methods or audit devices
Once new method is configured and tested, the root token should be revoked: vault token revoke $token
Create a root token using unseal/recovery keys
Helpful if you need to generate a root token in an emergency or a root token is needed for a particular task
A quorum of unseal key holders can generate a new root token
Enforces the "no single person has complete access to Vault"
Step 1: initialize the root generation: vault operator generate-root -init
Step 2: Each key holder runs "generate root" with their unseal key: vault operator generate-root
Step 3: Decode the generated root token: vault operator generate-root -otp=$otpinstep1 -decode=$codeinstep2
Token Accessors
Every token has a token accessor that is used as a reference to the token
Token accessors can be used to perform limited actions
Look up token properties: vault token lookup -accessor $tokenaccessor
Look up the capabilities of a token
Renew the token: vault token renew -accessor $tokenaccessor
Revoke the token: vault token revoke $tokenaccessor
Token accessors cannot be used for authentication to Vault or to perform additional requests
Time to Live
A token can have a TTL and a Max TTL
Once the token hits the Max TTL, it cannot be renewed further
when a token's TTL expires, the token is revoked and is no longer valid and cannot be used for authentication -> renewal must take place before the TTL expires
Default TTL in Vault is 768h (32 days)
Set TTL for tokens
Set the TTL explicitly when creating a token
vault token create -policy=training -ttl=60m
Configuration of an Auth method that results in token with a specific TTL
vault write auth/approle/role/training-role token_ttl=1h token_max_ttl=24h
The default TTL for Vault will be applied to tokens that are created without explicitly providing a TTL
vault token create -policy=training
Token Use Cases
Periodic Token
You have a long-running app which cannot handle the regeneration of a token or secret
You need a token that can be renewed idefinitely
Service Token with use limit
You want to limit the token to be used only 3 times regardless of remaining TTL
Orphan Token
You need a token that isn't impacted by the lifecycle of its parent
You want a token that has an expiration beyond the token that created it
CIDR-Bound Token
You want a token that can only be used by a specific host or within a certain network block
This is basically a regular service token with additional CIDR-bound configuration
Resource
Last updated