dubzland.vault.vault_auth_method module – Manages HashiCorp Vault authentication methods

Note

This module is part of the dubzland.vault collection (version 1.0.1).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install dubzland.vault. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: dubzland.vault.vault_auth_method.

Synopsis

  • When the auth method does not exist, it will be created.

  • When the auth method does exist and state=absent, the auth method will be deleted.

  • When changes are made to the auth method, the auth method will be updated.

Requirements

The below requirements are needed on the host that executes this module.

  • python >= 3.8

  • hvac >= 7.1.4

Parameters

Parameter

Comments

auth_method

string

Authentication method to be used.

Choices:

  • "approle"

  • "aws_iam"

  • "azure"

  • "cert"

  • "jwt"

  • "ldap"

  • "token" ← (default)

  • "userpass"

  • "none"

aws_access_key

aliases: aws_access_key_id

string

The AWS access key to use.

aws_iam_server_id

string

If specified, sets the value to use for the X-Vault-AWS-IAM-Server-ID header as part of GetCallerIdentity request.

aws_profile

aliases: boto_profile

string

The AWS profile

aws_secret_key

aliases: aws_secret_access_key

string

The AWS secret key that corresponds to the access key.

aws_security_token

string

The AWS security token if using temporary access and secret keys.

azure_client_id

string

The client ID (also known as application ID) of the Azure AD service principal or managed identity. Should be a UUID.

If not specified, will use the system assigned managed identity.

azure_client_secret

string

The client secret of the Azure AD service principal.

azure_resource

string

The resource URL for the application registered in Azure Active Directory. Usually should not be changed from the default.

Default: "https://management.azure.com/"

azure_tenant_id

string

The Azure Active Directory Tenant ID (also known as the Directory ID) of the service principal. Should be a UUID.

Required when using a service principal to authenticate to Vault, e.g. required when both azure_client_id and azure_client_secret are specified.

Optional when using managed identity to authenticate to Vault.

cert_auth_private_key

path

For cert auth, path to the private key file to authenticate with, in PEM format.

cert_auth_public_key

path

For cert auth, path to the certificate file to authenticate with, in PEM format.

config

dictionary

Configuration provided to the authentication method.

allowed_response_headers

list / elements=string

List of headers to allow, allowing a plugin to include them in the response.

audit_non_hmac_request_keys

list / elements=string

List of keys that will not be HMAC’d by audit devices in the request data object.

audit_non_hmac_response_keys

list / elements=string

List of keys that will not be HMAC’d by audit devices in the response data object.

default_lease_ttl

string

The default lease duration, specified as a string duration like “5s” or “30m”.

identity_token_key

string

The key to use for signing plugin workload identity tokens. If not provided, this will default to Vault’s OIDC default key.

listing_visibility

list / elements=string

Specifies whether to show this mount in the UI-specific listing endpoint. Valid values are “unauth” or “hidden”, with the default “” being equivalent to “hidden”.

max_lease_ttl

string

The maximum lease duration, specified as a string duration like “5s” or “30m”.

passthrough_request_headers

list / elements=string

List of headers to allow and pass from the request to the plugin.

plugin_version

string

Specifies the semantic version of the plugin to use, e.g. “v1.0.0”.

If unspecified, the server will select any matching unversioned plugin that may have been registered, the latest versioned plugin registered, or a built-in plugin in that order of precedence.

description

string

Human readable description for the authentication method.

jwt

string

The JSON Web Token (JWT) to use for JWT authentication to Vault.

method_type

string / required

Type of authentication method to be created

Choices:

  • "token"

  • "userpass"

  • "approle"

mount_point

string

Vault mount point.

If not specified, the default mount point for a given auth method is used.

Does not apply to token authentication.

password

string

Authentication password.

path

string

Path to the authentication method to be enabled.

region

string

The AWS region for which to create the connection.

role_id

string

Vault Role ID or name. Used in approle, aws_iam, azure and cert auth methods.

For cert auth, if no role_id is supplied, the default behavior is to try all certificate roles and return any one that matches.

For azure auth, role_id is required.

secret_id

string

Secret ID to be used for Vault AppRole authentication.

state

string

Indicates the desired authentication method state.

present ensures the authentication method is present.

absent ensures the authentication method is absent.

Choices:

  • "present" ← (default)

  • "absent"

token

string

Vault token. Token may be specified explicitly, through the listed [env] vars, and also through the VAULT_TOKEN env var.

If no token is supplied, explicitly or through env, then the plugin will check for a token file, as determined by token_path and token_file.

The order of token loading (first found wins) is token param -> ansible var -> ANSIBLE_HASHI_VAULT_TOKEN -> VAULT_TOKEN -> token file.

token_filename

string

If no token is specified, will try to read the token from this file in token_path.

Default: ".vault-token"

token_path

string

If no token is specified, will try to read the token_filename from this path.

token_validate

boolean

For token auth, will perform a lookup-self operation to determine the token’s validity before using it.

Disable if your token does not have the lookup-self capability.

Choices:

  • false ← (default)

  • true

url

string / required

The resolvable endpoint for the Vault API.

username

string

Authentication user name.

Attributes

Attribute

Support

Description

check_mode

Support: full

Can run in check_mode and return changed status prediction without modifying target.

diff_mode

Support: none

Will return details on what has changed (or possibly needs changing in check_mode), when in diff mode.

Examples

- name: Enable AppRole authentication
  dubzland.vault.vault_auth_method:
    method_type: approle
    description: AppRole authentication
    state: present
    url: http://localhost:8200
    token: "{{ _root_token }}"

Return Values

Common return values are documented here, the following are the fields unique to this module:

Key

Description

auth_method

dictionary

Details about the authentication method

Returned: success

Authors

  • Josh Williams (@t3hpr1m3)