Securing Vault AppRole Tokens with token_bound_cidrs and RoleID-Only Authentication

Problem

The token_bound_cidrs parameter in HashiCorp Vault AppRole provides a security mechanism that restricts token usage to specified IP ranges, helping to prevent misuse from unexpected locations.

Introduction

The token_bound_cidrs parameter in HashiCorp Vault AppRole is used to restrict which IP addresses are allowed to use tokens generated by that AppRole role. By specifying a list of CIDR blocks (IP ranges), only requests from these IPs can utilize the token, enhancing security against unauthorized requests. When a token is created with AppRole, Vault checks the client’s IP; if it does not match the allowed CIDR, the token cannot be used.

You can also make SecretID optional with bind_secret_id=false. Once token_bound_cidrs is set, authentication only requires the RoleID.

Usage Example

To enable IP restriction and make SecretID optional, add configuration like this:

vault write auth/approle/role/my-role token_bound_cidrs="10.0.0.0/8,192.168.1.0/24" bind_secret_id=false

This ensures only clients from these IP ranges can use tokens issued by this role, and only the RoleID is required for authentication.

Fixing Permission Denied Errors During AppRole Authentication

A common reason for a permission denied error during AppRole authentication occurs when the source IP of the login request is altered—often by a load balancer or proxy—before reaching Vault. This causes token_bound_cidrs validation to fail since the IP does not match the expected CIDR block, resulting in an error.

Example audit log:

{"time":"2025-07-11T03:34:39.377007262Z","type":"request","auth":{"token_type":"default"},"request":{"id":"...","operation":"read","mount_type":"ns_token","client_token":"...","remote_address":"10.23.3.4","remote_port":59123},"error":"permission denied"}

To confirm IP manipulation, check Vault’s audit logs, which include a remote_address field revealing the source IP attempting authentication.

Resolution Steps

• If the IP is changed by load balancer or proxy, organizations must address this at the network level, ensuring the real client IP is preserved and passed to Vault.
• If no manipulation is done and client IPs vary due to deployment architecture, expand the allowed CIDR range in token_bound_cidrs to cover all possible client addresses.

Reference

• AppRole API documentation on token_bound_cidrs.