Configuring TOTP MFA with HCP Vault Using the Identity Endpoint

Avatar
Lyubo Ivanov
  • Updated

Introduction

This article demonstrates how to configure Time-Based One-Time Password (TOTP) Multi-Factor Authentication (MFA) using the identity endpoint in HashiCorp HCP Vault Dedicated to securely enforce TOTP-based MFA for Vault users. While the official documentation commonly uses the sys endpoint for TOTP MFA configuration, leveraging the identity endpoint offers namespace-aware management, making it more flexible for multi-tenant environments.

Below is the step-by-step configuration guide using Vault CLI.

Prerequisites

  • Access to an HCP Vault instance.
  • A namespace-enabled Vault setup (in this case using the admin namespace).
  • Installed Vault CLI.
  • Basic understanding of Vault concepts like policies and authentication methods.

Steps to Configure TOTP MFA Using the Identity Endpoint

 

Set Up Environment Variables

Configure your Vault environment variables:

export VAULT_ADDR=<hcp_vault_address>
export VAULT_TOKEN=<token>
export VAULT_NAMESPACE=admin

 

Enable Userpass Authentication method

vault auth enable userpass

 

Verify Authentication Methods

List all enabled authentication methods to confirm the userpass method is active:

vault auth list -detailed

 

Configure TOTP MFA Method

vault write identity/mfa/method/totp \
issuer=Vault \
period=30 \
key_size=30 \
algorithm=SHA1 \
digits=6

(Note the method_id from the output you will need it later)

  • issuer: Identifies the Vault instance (appears in your authenticator app).
  • period: Time period (in seconds) for OTP expiration.
  • digits: Number of digits in the OTP.
  • algorithm: Hashing algorithm (default: SHA1).

Create a Policy
Write a policy to grant access to a secret:

vault policy write totp-policy -<<EOF
path "secret/foo" {
    capabilities = ["read"]
}
EOF


Add a User to Userpass Authentication

Create a user with the policy attached:

vault write auth/userpass/users/testuser \
password=testpassword \
policies=totp-policy


Log In as the User

Authenticate the user to retrieve their initial token:

vault write auth/userpass/login/testuser \
password=testpassword


Retrieve Entity and Method IDs

Use the token from the login response to look up the user entity and method IDs:

vault token lookup <place_the_token_here>

(Note the entity_id from the output you will need it for the next command).

Generate the TOTP Secret

Generate a TOTP secret for the user:

vault write identity/mfa/method/totp/admin-generate \
entity_id=<entity_id> \
method_id=<method_id>

The admin-generate is base64 encoded png barcode. Use the generated URL in the Google Authenticator configuration (or in another app like 1Password compatible with SHA256 hashing algorithm). You can also use a QR code reader to read the generated barcode and use it in the Auth app.


Enforce MFA for Login

Link the TOTP method to enforce MFA during login:

vault write identity/mfa/login-enforcement/my_enforcement \
mfa_method_ids=<method_id> \
identity_entity_ids=<entity_id> \
enforced_on="auth" \
auth_methods="userpass"
  • enforced_on: Specifies the scope of MFA (auth for authentication).
  • auth_methods: Restricts enforcement to specific authentication methods.
  •  

Configure Google Authenticator

  • Open the Google Authenticator app.
  • Navigate to Settings > Edit (Pencil)> Add (+).
  • Select Import OTP URLs and then choose Import Text Backup.
  • Paste the generated URL into the provided input box.
  • Click Import Text Backup to complete the setup.

Testing MFA Configuration

Test the MFA setup by attempting to log in with the user credentials:

vault login -method=userpass username=testuser (or log in using the UI directly).

You will be prompted to provide the OTP from your authenticator app.


Namespace Awareness

When using the identity endpoint, MFA methods and login enforcements are namespace-aware. This allows you to manage MFA configurations separately for each namespace, providing greater flexibility in multi-tenant setups.

 

Summary

Using the identity endpoint for TOTP MFA configuration provides several advantages, including namespace awareness and fine-grained control over MFA methods. By following the steps above, you can securely enforce TOTP-based MFA for your Vault users using the CLI.

For further details, refer to the following resources:

Vault MFA Documentation

Supported MFA Types

MFA Login Enforcement

Articles in this section

See more

Related articles