Module vault.java.driver
Package io.github.jopenlibs.vault.api

Class Auth

java.lang.Object
io.github.jopenlibs.vault.api.OperationsBase
io.github.jopenlibs.vault.api.Auth
public class Auth extends OperationsBase

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:

  • Constructor Details

  • Method Details

    • withNameSpace

      public Auth withNameSpace(String nameSpace)

    • 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 = Vault.create(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, 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 = Vault.create(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(String path, String appId, 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(String roleId, 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(String path, String roleId, 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(String username, 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(String username, String password, 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(String username, 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(String username, String password, 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(String role, String identity, String signature, String nonce, 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(String role, String pkcs7, String nonce, 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(String role, String iamRequestUrl, String iamRequestBody, String iamRequestHeaders, 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(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(String githubToken, 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

    • loginByJwt

      public AuthResponse loginByJwt(String provider, String role, String jwt) throws VaultException

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

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

 final String token = response.getAuthClientToken();
      Parameters:
      provider - Provider of JWT token.
      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

    • loginByJwt

      public AuthResponse loginByJwt(String provider, String role, String jwt, String authPath) throws VaultException

      Basic login operation to authenticate to an JWT backend with custom authentication path. Example usage:

      
 final AuthResponse response = vault.auth().loginByJwt("kubernetes", "dev", "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "custom/path");

 final String token = response.getAuthClientToken();
      Parameters:
      provider - Provider of JWT token.
      role - The gcp role used for authentication
      jwt - The JWT token for the role
      authPath - The Authentication Path for Vault
      Returns:
      The auth token, with additional response metadata
      Throws:
      VaultException - If any error occurs, or unexpected response received from Vault

    • loginByGCP

      public AuthResponse loginByGCP(String role, 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

    • loginByKubernetes

      public AuthResponse loginByKubernetes(String role, String jwt) throws VaultException
      Basic login operation to authenticate to a kubernetes backend. Example usage: 
      
 final AuthResponse response =
     vault.auth().loginByKubernetes("dev", "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...");

 final String token = response.getAuthClientToken();
      Parameters:
      role - The kubernetes role used for authentication
      jwt - The JWT token for the role, typically read from /var/run/secrets/kubernetes.io/serviceaccount/token
      Returns:
      The auth token, with additional response metadata
      Throws:
      VaultException - If any error occurs, or unexpected response received from Vault

    • loginByKubernetes

      public AuthResponse loginByKubernetes(String role, String jwt, String authPath) throws VaultException
      Basic login operation to authenticate to a kubernetes backend with custom path. Example usage: 
      
 final AuthResponse response =
     vault.auth().loginByKubernetes("dev", "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "customAuthPath");

 final String token = response.getAuthClientToken();
      Parameters:
      role - The kubernetes role used for authentication
      jwt - The JWT token for the role, typically read from /var/run/secrets/kubernetes.io/serviceaccount/token
      authPath - The Authentication Path for Vault
      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 = Vault.create(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(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 = Vault.create(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, 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(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
      Deprecated.
      This method is deprecated and in future it will be removed
      Throws:
      VaultException
      See Also:

    • lookupWrap

      public LogicalResponse lookupWrap(String wrappedToken) throws VaultException
      Deprecated.
      This method is deprecated and in future it will be removed
      Throws:
      VaultException
      See Also:

    • lookupWrap

      public LogicalResponse lookupWrap(String wrappedToken, boolean inBody) throws VaultException
      Deprecated.
      This method is deprecated and in future it will be removed
      Throws:
      VaultException
      See Also:

    • 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(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 UnwrapResponse unwrap() throws VaultException
      Deprecated.
      This method is deprecated and in future it will be removed
      Throws:
      VaultException
      See Also:

    • unwrap

      public UnwrapResponse unwrap(String wrappedToken) throws VaultException
      Deprecated.
      This method is deprecated and in future it will be removed
      Throws:
      VaultException
      See Also:

    • unwrap

      public UnwrapResponse unwrap(String wrappedToken, boolean inBody) throws VaultException
      Deprecated.
      This method is deprecated and in future it will be removed
      Throws:
      VaultException
      See Also:

    • wrap

      public WrapResponse wrap(JsonObject jsonObject, int ttlInSec) throws VaultException
      Deprecated.
      This method is deprecated and in future it will be removed
      Throws:
      VaultException
      See Also:

    • rewrap

      public WrapResponse rewrap(String wrappedToken) throws VaultException
      Deprecated.
      This method is deprecated and in future it will be removed
      Throws:
      VaultException
      See Also: