com.bettercloud.vault.api

Class Auth

java.lang.Object

com.bettercloud.vault.api.Auth

public class Auth
extends java.lang.Object

The implementing class for operations on Vault's /v1/auth/* REST endpoints.

This class is not intended to be constructed directly. Rather, it is meant to used by way of Vault in a DSL-style builder pattern. See the Javadoc comments of each public method for usage examples.

See Also:

Vault.auth()

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Auth.TokenRequest A container for all of the options that can be passed to the createToken(TokenRequest) method, to avoid that method having an excessive number of parameters (with null typically passed to most of them).

Constructor Summary

Constructors

Constructor and Description
Auth(VaultConfig config)

Method Summary

Modifier and Type	Method and Description
AuthResponse	createToken(Auth.TokenRequest tokenRequest) Operation to create an authentication token.
AuthResponse	createToken(Auth.TokenRequest tokenRequest, java.lang.String tokenAuthMount) Operation to create an authentication token.
AuthResponse	loginByAppID(java.lang.String path, java.lang.String appId, java.lang.String userId) Deprecated.
AuthResponse	loginByAppRole(java.lang.String roleId, java.lang.String secretId) Basic login operation to authenticate to an app-role backend.
AuthResponse	loginByAppRole(java.lang.String path, java.lang.String roleId, java.lang.String secretId) Basic login operation to authenticate to an app-role backend.
AuthResponse	loginByAwsEc2(java.lang.String role, java.lang.String pkcs7, java.lang.String nonce, java.lang.String awsAuthMount) Basic login operation to authenticate to a AWS backend using EC2 authentication.
AuthResponse	loginByAwsEc2(java.lang.String role, java.lang.String identity, java.lang.String signature, java.lang.String nonce, java.lang.String awsAuthMount) Basic login operation to authenticate to a AWS backend using EC2 authentication.
AuthResponse	loginByAwsIam(java.lang.String role, java.lang.String iamRequestUrl, java.lang.String iamRequestBody, java.lang.String iamRequestHeaders, java.lang.String awsAuthMount) Basic login operation to authenticate to a AWS backend using IAM authentication.
AuthResponse	loginByCert() Basic login operation to authenticate using Vault's TLS Certificate auth backend.
AuthResponse	loginByCert(java.lang.String certAuthMount) Basic login operation to authenticate using Vault's TLS Certificate auth backend.
AuthResponse	loginByGCP(java.lang.String role, java.lang.String jwt) Basic login operation to authenticate to an GCP backend.
AuthResponse	loginByGithub(java.lang.String githubToken) Basic login operation to authenticate to an github backend.
AuthResponse	loginByGithub(java.lang.String githubToken, java.lang.String githubAuthMount) Basic login operation to authenticate to an github backend.
AuthResponse	loginByLDAP(java.lang.String username, java.lang.String password) Basic login operation to authenticate to a LDAP backend.
AuthResponse	loginByLDAP(java.lang.String username, java.lang.String password, java.lang.String ldapAuthMount) Basic login operation to authenticate to a LDAP backend.
AuthResponse	loginByUserPass(java.lang.String username, java.lang.String password) Basic login operation to authenticate to a Username & Password backend.
AuthResponse	loginByUserPass(java.lang.String username, java.lang.String password, java.lang.String userpassAuthMount) Basic login operation to authenticate to a Username & Password backend.
LookupResponse	lookupSelf() Returns information about the current client token.
LookupResponse	lookupSelf(java.lang.String tokenAuthMount) Returns information about the current client token.
LogicalResponse	lookupWrap() Returns information about the current client token for a wrapped token, for which the lookup endpoint is different at "sys/wrapping/lookup".
AuthResponse	renewSelf() Renews the lease associated with the calling token.
AuthResponse	renewSelf(long increment) Renews the lease associated with the calling token.
AuthResponse	renewSelf(long increment, java.lang.String tokenAuthMount) Renews the lease associated with the calling token.
void	revokeSelf() Revokes current client token.
void	revokeSelf(java.lang.String tokenAuthMount) Revokes current client token.
AuthResponse	unwrap() Returns the original response inside the wrapped auth token.
AuthResponse	unwrap(java.lang.String wrappedToken) Returns the original response inside the given wrapped auth token.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Auth

public Auth(VaultConfig config)

Method Detail

createToken

public AuthResponse createToken(Auth.TokenRequest tokenRequest)
                         throws VaultException

Operation to create an authentication token. Relies on another token already being present in the VaultConfig instance. Example usage:

 final VaultConfig config = new VaultConfig().address(...).token(...).build();
 final Vault vault = new Vault(config);
 final AuthResponse response = vault.auth().createToken(new TokenRequest().withTtl("1h"));

 final String token = response.getAuthClientToken();
 

Parameters:

tokenRequest - A container of optional configuration parameters

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

createToken

public AuthResponse createToken(Auth.TokenRequest tokenRequest,
                                java.lang.String tokenAuthMount)
                         throws VaultException

Operation to create an authentication token. Relies on another token already being present in the VaultConfig instance. Example usage:

 final VaultConfig config = new VaultConfig().address(...).token(...).build();
 final Vault vault = new Vault(config);
 final AuthResponse response = vault.auth().createToken(new TokenRequest().withTtl("1h"));

 final String token = response.getAuthClientToken();
 

Parameters:

tokenRequest - A container of optional configuration parameters

tokenAuthMount - The mount name of the token authentication back end. If null, defaults to "token"

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByAppID

@Deprecated
public AuthResponse loginByAppID(java.lang.String path,
                                             java.lang.String appId,
                                             java.lang.String userId)
                                      throws VaultException

Deprecated.

Basic login operation to authenticate to an app-id backend. Example usage:

 final AuthResponse response = vault.auth().loginByAppID("app-id/login", "app_id", "user_id");

 final String token = response.getAuthClientToken();
 

NOTE: As of Vault 0.6.1, Hashicorp has deprecated the App ID authentication backend in favor of AppRole. This method will be removed at some point after this backend has been eliminated from Vault.

Parameters:

path - The path on which the authentication is performed (e.g. auth/app-id/login)

appId - The app-id used for authentication

userId - The user-id used for authentication

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByAppRole

public AuthResponse loginByAppRole(java.lang.String roleId,
                                   java.lang.String secretId)
                            throws VaultException

Basic login operation to authenticate to an app-role backend. This version of the overloaded method assumes that the auth backend is mounted on the default path (i.e. "/v1/auth/approle"). Example usage:

 final AuthResponse response = vault.auth().loginByAppRole(9e1aede8-dcc6-a293-8223-f0d824a467ed", "9ff4b26e-6460-834c-b925-a940eddb6880");

 final String token = response.getAuthClientToken();
 

Parameters:

roleId - The role-id used for authentication

secretId - The secret-id used for authentication

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByAppRole

public AuthResponse loginByAppRole(java.lang.String path,
                                   java.lang.String roleId,
                                   java.lang.String secretId)
                            throws VaultException

Basic login operation to authenticate to an app-role backend. This version of the overloaded method requires you to explicitly specify the path on which the auth backend is mounted, following the "/v1/auth/" prefix. Example usage:

 final AuthResponse response = vault.auth().loginByAppRole("approle", "9e1aede8-dcc6-a293-8223-f0d824a467ed", "9ff4b26e-6460-834c-b925-a940eddb6880");

 final String token = response.getAuthClientToken();
 

NOTE: I hate that this method takes the custom mount path as its first parameter, while all of the other methods in this class take it as the last parameter (a better practice). I just didn't think about it during code review. Now it's difficult to deprecate this, since a version of the method with path as the final parameter would have the same method signature. I may or may not change this in some future breaking-change major release, especially if we keep adding similar overloaded methods elsewhere and need the global consistency. At any rate, going forward no new methods should take a custom path as the first parameter.

Parameters:

path - The path on which the authentication is performed, following the "/v1/auth/" prefix (e.g. "approle")

roleId - The role-id used for authentication

secretId - The secret-id used for authentication

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByUserPass

public AuthResponse loginByUserPass(java.lang.String username,
                                    java.lang.String password)
                             throws VaultException

Basic login operation to authenticate to a Username & Password backend. Example usage:

 final AuthResponse response = vault.auth().loginByUserPass("test", "password");

 final String token = response.getAuthClientToken();
 

Parameters:

username - The username used for authentication

password - The password used for authentication

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByUserPass

public AuthResponse loginByUserPass(java.lang.String username,
                                    java.lang.String password,
                                    java.lang.String userpassAuthMount)
                             throws VaultException

Basic login operation to authenticate to a Username & Password backend. Example usage:

 final AuthResponse response = vault.auth().loginByUserPass("test", "password");

 final String token = response.getAuthClientToken();
 

Parameters:

username - The username used for authentication

password - The password used for authentication

userpassAuthMount - The mount name of the userpass authentication back end. If null, defaults to "userpass"

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByLDAP

public AuthResponse loginByLDAP(java.lang.String username,
                                java.lang.String password)
                         throws VaultException

Basic login operation to authenticate to a LDAP backend. Example usage:

 final AuthResponse response = vault.auth().loginByLDAP("test", "password");

 final String token = response.getAuthClientToken();
 

Parameters:

username - The username used for authentication

password - The password used for authentication

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByLDAP

public AuthResponse loginByLDAP(java.lang.String username,
                                java.lang.String password,
                                java.lang.String ldapAuthMount)
                         throws VaultException

Basic login operation to authenticate to a LDAP backend. Example usage:

 final AuthResponse response = vault.auth().loginByLDAP("test", "password");

 final String token = response.getAuthClientToken();
 

Parameters:

username - The username used for authentication

password - The password used for authentication

ldapAuthMount - The mount name of the ldap authentication back end. If null, defaults to "ldap"

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByAwsEc2

public AuthResponse loginByAwsEc2(java.lang.String role,
                                  java.lang.String identity,
                                  java.lang.String signature,
                                  java.lang.String nonce,
                                  java.lang.String awsAuthMount)
                           throws VaultException

Basic login operation to authenticate to a AWS backend using EC2 authentication. Example usage:

 final AuthResponse response = vault.auth().loginByAwsEc2("my-role", "identity", "signature", "nonce", null);

 final String token = response.getAuthClientToken();
 

Parameters:

role - Name of the role against which the login is being attempted. If role is not specified, then the login endpoint looks for a role bearing the name of the AMI ID of the EC2 instance that is trying to login if using the ec2 auth method, or the "friendly name" (i.e., role name or username) of the IAM principal authenticated. If a matching role is not found, login fails.

identity - Base64 encoded EC2 instance identity document.

signature - Base64 encoded SHA256 RSA signature of the instance identity document.

nonce - Client nonce used for authentication. If null, a new nonce will be generated by Vault

awsAuthMount - AWS auth mount

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByAwsEc2

public AuthResponse loginByAwsEc2(java.lang.String role,
                                  java.lang.String pkcs7,
                                  java.lang.String nonce,
                                  java.lang.String awsAuthMount)
                           throws VaultException

Basic login operation to authenticate to a AWS backend using EC2 authentication. Example usage:

 final AuthResponse response = vault.auth().loginByAwsEc2("my-role", "pkcs7", "nonce", null);

 final String token = response.getAuthClientToken();
 

Parameters:

role - Name of the role against which the login is being attempted. If role is not specified, then the login endpoint looks for a role bearing the name of the AMI ID of the EC2 instance that is trying to login if using the ec2 auth method, or the "friendly name" (i.e., role name or username) of the IAM principal authenticated. If a matching role is not found, login fails.

pkcs7 - PKCS7 signature of the identity document with all \n characters removed.

nonce - Client nonce used for authentication. If null, a new nonce will be generated by Vault

awsAuthMount - AWS auth mount

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByAwsIam

public AuthResponse loginByAwsIam(java.lang.String role,
                                  java.lang.String iamRequestUrl,
                                  java.lang.String iamRequestBody,
                                  java.lang.String iamRequestHeaders,
                                  java.lang.String awsAuthMount)
                           throws VaultException

Basic login operation to authenticate to a AWS backend using IAM authentication. Example usage:

 final AuthResponse response = vault.auth().loginByAwsIam("my-role", "pkcs7", "nonce", null);

 final String token = response.getAuthClientToken();
 

Parameters:

role - Name of the role against which the login is being attempted. If role is not specified, then the login endpoint looks for a role bearing the name of the AMI ID of the EC2 instance that is trying to login if using the ec2 auth method, or the "friendly name" (i.e., role name or username) of the IAM principal authenticated. If a matching role is not found, login fails.

iamRequestUrl - PKCS7 signature of the identity document with all \n characters removed.Base64-encoded HTTP URL used in the signed request. Most likely just aHR0cHM6Ly9zdHMuYW1hem9uYXdzLmNvbS8= (base64-encoding of https://sts.amazonaws.com/) as most requests will probably use POST with an empty URI.

iamRequestBody - Base64-encoded body of the signed request. Most likely QWN0aW9uPUdldENhbGxlcklkZW50aXR5JlZlcnNpb249MjAxMS0wNi0xNQ== which is the base64 encoding of Action=GetCallerIdentity&Version=2011-06-15.

iamRequestHeaders - Request headers

awsAuthMount - AWS auth mount

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByGithub

public AuthResponse loginByGithub(java.lang.String githubToken)
                           throws VaultException

Basic login operation to authenticate to an github backend. Example usage:

 final AuthResponse response = vault.auth().loginByGithub("githubToken");

 final String token = response.getAuthClientToken();
 

Parameters:

githubToken - The app-id used for authentication

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByGithub

public AuthResponse loginByGithub(java.lang.String githubToken,
                                  java.lang.String githubAuthMount)
                           throws VaultException

Basic login operation to authenticate to an github backend. Example usage:

 final AuthResponse response = vault.auth().loginByGithub("githubToken");

 final String token = response.getAuthClientToken();
 

Parameters:

githubToken - The app-id used for authentication

githubAuthMount - The mount name of the github authentication back end. If null, defaults to "github"

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByGCP

public AuthResponse loginByGCP(java.lang.String role,
                               java.lang.String jwt)
                        throws VaultException

Basic login operation to authenticate to an GCP backend. Example usage:

 final AuthResponse response = vault.auth().loginByGCP("dev", "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...");

 final String token = response.getAuthClientToken();
 

Parameters:

role - The gcp role used for authentication

jwt - The JWT token for the role

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByCert

public AuthResponse loginByCert()
                         throws VaultException

Basic login operation to authenticate using Vault's TLS Certificate auth backend. Example usage:

 final SslConfig sslConfig = new SslConfig()
                                  .keystore("keystore.jks")
                                  .truststore("truststore.jks")
                                  .build();
 final VaultConfig vaultConfig = new VaultConfig()
                                  .address("https://127.0.0.1:8200")
                                  .sslConfig(sslConfig)
                                  .build();
 final Vault vault = new Vault(vaultConfig);

 final AuthResponse response = vault.auth().loginByCert();
 final String token = response.getAuthClientToken();
 

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

loginByCert

public AuthResponse loginByCert(java.lang.String certAuthMount)
                         throws VaultException

Basic login operation to authenticate using Vault's TLS Certificate auth backend. Example usage:

 final SslConfig sslConfig = new SslConfig()
                                  .keystore("keystore.jks")
                                  .truststore("truststore.jks")
                                  .build();
 final VaultConfig vaultConfig = new VaultConfig()
                                  .address("https://127.0.0.1:8200")
                                  .sslConfig(sslConfig)
                                  .build();
 final Vault vault = new Vault(vaultConfig);

 final AuthResponse response = vault.auth().loginByCert();
 final String token = response.getAuthClientToken();
 

Parameters:

certAuthMount - The mount name of the cert authentication back end. If null, defaults to "cert"

Returns:

The auth token, with additional response metadata

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

renewSelf

public AuthResponse renewSelf()
                       throws VaultException

Renews the lease associated with the calling token. This version of the method tells Vault to use the default lifespan for the new lease.

Returns:

The response information returned from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

renewSelf

public AuthResponse renewSelf(long increment)
                       throws VaultException

Renews the lease associated with the calling token. This version of the method accepts a parameter to explicitly declare how long the new lease period should be (in seconds). The Vault documentation suggests that this value may be ignored, however.

Parameters:

increment - The number of seconds requested for the new lease lifespan

Returns:

The response information returned from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

renewSelf

public AuthResponse renewSelf(long increment,
                              java.lang.String tokenAuthMount)
                       throws VaultException

Renews the lease associated with the calling token. This version of the method accepts a parameter to explicitly declare how long the new lease period should be (in seconds). The Vault documentation suggests that this value may be ignored, however.

Parameters:

increment - The number of seconds requested for the new lease lifespan

tokenAuthMount - The mount name of the token authentication back end. If null, defaults to "token"

Returns:

The response information returned from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

lookupSelf

public LookupResponse lookupSelf()
                          throws VaultException

Returns information about the current client token.

Returns:

The response information returned from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

lookupSelf

public LookupResponse lookupSelf(java.lang.String tokenAuthMount)
                          throws VaultException

Returns information about the current client token.

Parameters:

tokenAuthMount - The mount name of the token authentication back end. If null, defaults to "token"

Returns:

The response information returned from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

lookupWrap

public LogicalResponse lookupWrap()
                           throws VaultException

Returns information about the current client token for a wrapped token, for which the lookup endpoint is different at "sys/wrapping/lookup". Example usage:

 final String wrappingToken = "...";
 final VaultConfig config = new VaultConfig().address(...).token(wrappingToken).build();
 final Vault vault = new Vault(config);
 final LogicalResponse response = vault.auth().lookupWarp();
 // Then you can validate "path" for example ...
 final String path = response.getData().get("path");
 

Returns:

The response information returned from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

revokeSelf

public void revokeSelf()
                throws VaultException

Revokes current client token.

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

revokeSelf

public void revokeSelf(java.lang.String tokenAuthMount)
                throws VaultException

Revokes current client token.

Parameters:

tokenAuthMount - The mount name of the token authentication back end. If null, defaults to "token"

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

unwrap

public AuthResponse unwrap()
                    throws VaultException

Returns the original response inside the wrapped auth token. This method is useful if you need to unwrap a token without being authenticated. See unwrap(String) if you need to do that authenticated.

In the example below, you cannot use twice the VaultConfig, since after the first usage of the wrappingToken, it is not usable anymore. You need to use the unwrappedToken in a new vault configuration to continue. Example usage:

 final String wrappingToken = "...";
 final VaultConfig config = new VaultConfig().address(...).token(wrappingToken).build();
 final Vault vault = new Vault(config);
 final AuthResponse response = vault.auth().unwrap();
 final String unwrappedToken = response.getAuthClientToken();
 

Returns:

The response information returned from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

See Also:

unwrap(String)

unwrap

public AuthResponse unwrap(java.lang.String wrappedToken)
                    throws VaultException

Returns the original response inside the given wrapped auth token. This method is useful if you need to unwrap a token, while being already authenticated. Do NOT authenticate in vault with your wrapping token, since it will both fail authentication and invalidate the wrapping token at the same time. See unwrap() if you need to do that without being authenticated.

In the example below, authToken is NOT your wrapped token, and should have unwrapping permissions. The unwrapped token in unwrappedToken. Example usage:

 final String authToken = "...";
 final String wrappingToken = "...";
 final VaultConfig config = new VaultConfig().address(...).token(authToken).build();
 final Vault vault = new Vault(config);
 final AuthResponse response = vault.auth().unwrap(wrappingToken);
 final String unwrappedToken = response.getAuthClientToken();
 

Parameters:

wrappedToken - Specifies the wrapping token ID, do NOT also put this in your VaultConfig.token, if token is null, this method will unwrap the auth token in VaultConfig.token

Returns:

The response information returned from Vault

Throws:

VaultException - If any error occurs, or unexpected response received from Vault

See Also:

unwrap()