VaultAppRoleCredential (Jervis 2.0 API)

net.gleske.jervis.remotes.creds.VaultAppRoleCredential

All Implemented Interfaces and Traits:: ReadonlyTokenCredential, SimpleRestServiceSupport, VaultCredential

class VaultAppRoleCredential
extends Object

This provides HashiCorp Vault AppRole Authentication which issues rotating ephemeral tokens automatically. HashiCorp recommends using AppRole authentication for applications and services. The high level operation of this class is the following.

Provide seamless Vault API authentication for VaultService.
Use Role ID and Secret ID to issue, renew, rotate, and revoke Vault tokens automatically. See examples in VaultRoleIdCredential and VaultRoleIdCredentialImpl.
Automatically injects issued Vault tokens as authentication headers.
Tracks token expiration and automatically renews or rotates tokens transparent to VaultService.
Can revoke issued tokens.

Vault Policy

If you decide to use renable tokens and allow all features provided by this class, then you'll need the following Vault policy.


# Allow tokens to look up their own properties
path "auth/token/lookup-self" {
    capabilities = ["read"]
}

# Allow tokens to renew themselves
path "auth/token/renew-self" {
    capabilities = ["update"]
}

# Allow tokens to revoke themselves
path "auth/token/revoke-self" {
    capabilities = ["update"]
}

Bear in mind the above policy is just for this class for its credential management. You'll want other policy rules for accessing secrets.

Recommended Vault Policy

In general, you'll want to use the most limited Vault Policy you can for your application. For example, in this section you only need a two rule policy.


# Allow tokens to revoke themselves
path "auth/token/revoke-self" {
    capabilities = ["update"]
}

# Read only KV v2 Permissions
path "kv/*" {
    capabilities = ["read"]
}

You can use the VaultService API client to apply this policy. Alternately, you can do this in the Vault UI.


import net.gleske.jervis.remotes.interfaces.TokenCredential
import net.gleske.jervis.remotes.VaultService

Map data = [policy: '''\
# Allow tokens to revoke themselves
path "auth/token/revoke-self" {
    capabilities = ["update"]
}

# Read only KV v2 Permissions
path "kv/*" {
    capabilities = ["read"]
}
''']

// Create an API client using an admin human user vault token
TokenCredential creds = [getToken: {-> 'your admin token' }] as TokenCredential
VaultService myvault = new VaultService('https://vault.example.com/', creds)

// Upload policy
myvault.apiFetch('sys/policy/jenkins-limited', [:], 'POST', data)

Initializing AppRole

This section discusses how to enable AppRole authentication in Vault as well as generate an application secret for a service such as Jenkins.

Enable AppRole authentication engine

You can enable AppRole via the Vault UI and set it up via Vault CLI. This example illustrates how to do the same thing with the VaultService API client. The example includes recommended service role settings with a short TTL (1 minute) and non-renewable tokens. This class will automatically manage obtaining new tokens if a token it uses expires.


import net.gleske.jervis.remotes.interfaces.TokenCredential
import net.gleske.jervis.remotes.VaultService
import net.gleske.jervis.tools.YamlOperator

// Create an API client using an admin human user vault token
TokenCredential creds = [getToken: {-> 'your admin token' }] as TokenCredential
VaultService myvault = new VaultService('https://vault.example.com/', creds)

// Recommended AppRole settings
Map approle_settings = [
    token_ttl: "1m",
    token_explicit_max_ttl: "1m",
    token_policies: ["jenkins-limited"],
    token_no_default_policy: true,
    token_type: "service"
]

// Enable AppRole Authentication Engine
myvault.apiFetch('sys/auth/approle', [:], 'POST', [type: 'approle'])

// Create an application Role 'jenkins'
myvault.apiFetch('auth/approle/role/jenkins', [:], 'POST', approle_settings)

// Generate an AppRole Role ID and Secret ID for the 'jenkins' Role
Map role_data = [:]
role_data.role_id = myvault.apiFetch('auth/approle/role/jenkins/role-id').data.role_id
role_data.secret_id = myvault.apiFetch('auth/approle/role/jenkins/secret-id', [:], 'POST')?.data?.secret_id
println(YamlOperator.writeObjToYaml(role_data))

Take the role_id and secret_id, and use it to instantiate examples for this class.

Sample usage

To run this example, clone Jervis and execute ./gradlew console to bring up a Groovy Console with the classpath set up.

The following offers basic usage. However, there are better and more secure examples in VaultRoleIdCredential.


import net.gleske.jervis.remotes.creds.VaultAppRoleCredential
import net.gleske.jervis.remotes.VaultService

VaultAppRoleCredential approle = new VaultAppRoleCredential('https://vault.example.com', 'app role id', 'app secret id')

// Instantiate vault API client with approle
VaultService vault = new VaultService(approle)

// Set mount kv/ to be KV v2 secrets engine
vault.mountVersions = [kv: 2]

// Ready to perform secrets operations
vault.getSecret('kv/path/to/secret')

// When your application is done using Vault it can proceed to revoke its active
// token.
approle.revokeToken()

Properties Summary

Properties
Type	Name and description
`String`	`approle_mount` The name of the mount for the AppRole authentication backend.
`Map<String, String>`	`headers` Customizable HTTP headers which get sent to Vault in addition to authentication headers.
`Long`	`renew_buffer` The time buffer before a renewal is forced.

Constructor Summary

Constructors
Constructor and description
`VaultAppRoleCredential (String vault_url, String role_id, String secret_id)` A simple way to establish an authenticated session with Vault.
`VaultAppRoleCredential (String vault_url, VaultRoleIdCredential credential)` The recommended way to establish a secured authenticated session with Vault.

Methods Summary

Methods
Type Params	Return Type	Name and description
	`String`	`baseUrl()` Returns the Vault URL.
	`Long`	`getRenew_buffer()` Returns renew buffer.
	`String`	`getToken()` This will lease a new token via AppRole and return the leased token.
	`String`	`getVault_url()` Returns the Vault URL.
	`Map`	`header(Map headers = [:])` Returns authentication headers used for API requests to Vault.
	`Map`	`lookupToken()` Performs a lookup of the currently leased token and returns the response from Vault.
	`Boolean`	`renewToken()` Force a token renewal.
	`void`	`revokeToken()` Revokes the current token in use by this auth client.
	`void`	`setApprole_mount(String mount)` Sets the approle_mount property and trims leading or trailing slash.

Inherited Methods Summary

Inherited Methods
Methods inherited from class	Name
`class Object`	`wait, wait, wait, equals, toString, hashCode, getClass, notify, notifyAll`

- Property Detail
  - String approle_mount
    
    The name of the mount for the AppRole authentication backend. By default, this is approle.
  - Map<String, String> headers
    
    Customizable HTTP headers which get sent to Vault in addition to authentication headers.
  - Long renew_buffer
    
    The time buffer before a renewal is forced. This is to account for clock drift and is customizable by the client. By default the value is 5 seconds. All time-based calculations around token renewal assume this is set correctly by the caller. If it is incorrectly set then renew_buffer is 0 seconds.
- Constructor Detail
  - VaultAppRoleCredential(String vault_url, String role_id, String secret_id)
    
    A simple way to establish an authenticated session with Vault. In general, this is less secure. Favor using VaultAppRoleCredential(java.lang.String, net.gleske.jervis.remotes.interfaces.VaultRoleIdCredential), instead.
  - VaultAppRoleCredential(String vault_url, VaultRoleIdCredential credential)
    
    The recommended way to establish a secured authenticated session with Vault. Refer to the API documentation of VaultRoleIdCredential for detailed examples on how this credential should be instantiated.
- Method Detail
  - String baseUrl()
    
    Returns the Vault URL. This method is used internally by this class establish Vault connectivity.
    Returns:
    Returns the Vault API URL.
  - Long getRenew_buffer()
    
    Returns renew buffer. Does not allow renew buffer to be undefined or go below zero.
    Returns:
    0 or a renew_buffer greater than 0.
  - String getToken()
    
    This will lease a new token via AppRole and return the leased token. If the token is use is due for renewal it will automatically be renewed. If the token is expired or needs renewal but is non-renewable, then a new token lease will automatically be created.
    Returns:
    Always returns a valid token with at least a 5 second lease. If you require the minimum lease to be longer, then adjust renew_buffer.
  - String getVault_url()
    
    Returns the Vault URL. This method is used internally by the VaultService class to establish Vault connectivity.
    Returns:
    Returns the Vault API URL.
  - Map header(Map headers = [:])
    
    Returns authentication headers used for API requests to Vault.
    Returns:
    Returns a Map of HTTP headers.
  - Map lookupToken()
    
    Performs a lookup of the currently leased token and returns the response from Vault.
    Returns:
    Returns the JSON response from Vault parsed as a Map.
  - Boolean renewToken()
    
    Force a token renewal. It is unlikely this method will ever need to be called because getToken() will manage token renewal.
    Returns:
    Returns true if the token renewal was successful. Otherwise, returns false.
  - void revokeToken()
    
    Revokes the current token in use by this auth client. Please note, if more API communication occurs this auth client will automatically lease a new token.
  - void setApprole_mount(String mount)
    
    Sets the approle_mount property and trims leading or trailing slash.
    Parameters:
    mount - The name of the mount for the AppRole authentication backend.

Summary:
Property
Constructor
Method

| Detail:
Property
Constructor
Method

Jervis API documentation.

[Groovy] Class VaultAppRoleCredential

Vault Policy

Recommended Vault Policy

Initializing AppRole

Enable AppRole authentication engine

Sample usage

Properties Summary

Constructor Summary

Methods Summary

Inherited Methods Summary

Property Detail

String approle_mount

Map<String, String> headers

Long renew_buffer

Constructor Detail

VaultAppRoleCredential(String vault_url, String role_id, String secret_id)

VaultAppRoleCredential(String vault_url, VaultRoleIdCredential credential)

Method Detail

String baseUrl()

Long getRenew_buffer()

String getToken()

String getVault_url()

Map header(Map headers = [:])

Map lookupToken()

Boolean renewToken()

void revokeToken()

void setApprole_mount(String mount)