hvac.api.auth

Collection of classes for various Vault auth methods.

class hvac.api.auth.Github(adapter)

Bases: hvac.api.vault_api_base.VaultApiBase

GitHub Auth Method (API).

Reference: https://www.vaultproject.io/api/auth/github/index.html

configure(organization, base_url='', ttl='', max_ttl='', mount_point='github')

Configure the connection parameters for GitHub.

This path honors the distinction between the create and update capabilities inside ACL policies.

Supported methods:

POST: /auth/{mount_point}/config. Produces: 204 (empty body)

Parameters:

• organization (str | unicode) – The organization users must be part of.
• base_url (str | unicode) – The API endpoint to use. Useful if you are running GitHub Enterprise or an API-compatible authentication server.
• ttl (str | unicode) – Duration after which authentication will be expired.
• max_ttl (str | unicode) – Maximum duration after which authentication will be expired.
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The response of the configure_method request.

Return type:

requests.Response

login(token, use_token=True, mount_point='github')

Login using GitHub access token.

Supported methods:

POST: /auth/{mount_point}/login. Produces: 200 application/json

Parameters:

• token (str | unicode) – GitHub personal API token.
• use_token (bool) – if True, uses the token in the response received from the auth request to set the “token” attribute on the the hvac.adapters.Adapter() instance under the _adapater Client attribute.
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The JSON response of the login request.

Return type:

dict

map_team(team_name, policies=None, mount_point='github')

Map a list of policies to a team that exists in the configured GitHub organization.

Supported methods:

POST: /auth/{mount_point}/map/teams/{team_name}. Produces: 204 (empty body)

Parameters:

• team_name (str | unicode) – GitHub team name in “slugified” format
• policies (list) – Comma separated list of policies to assign
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The response of the map_github_teams request.

Return type:

requests.Response

map_user(user_name, policies=None, mount_point='github')

Map a list of policies to a specific GitHub user exists in the configured organization.

Supported methods:

POST: /auth/{mount_point}/map/users/{user_name}. Produces: 204 (empty body)

Parameters:

• user_name (str | unicode) – GitHub user name
• policies (str | unicode) – Comma separated list of policies to assign
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The response of the map_github_users request.

Return type:

requests.Response

read_configuration(mount_point='github')

Read the GitHub configuration.

Supported methods:

GET: /auth/{mount_point}/config. Produces: 200 application/json

Parameters:mount_point (str | unicode) – The “path” the method/backend was mounted on. Returns:The JSON response of the read_configuration request. Return type:dict

read_team_mapping(team_name, mount_point='github')

Read the GitHub team policy mapping.

Supported methods:

GET: /auth/{mount_point}/map/teams/{team_name}. Produces: 200 application/json

Parameters:

• team_name (str | unicode) – GitHub team name
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The JSON response of the read_team_mapping request.

Return type:

dict

read_user_mapping(user_name, mount_point='github')

Read the GitHub user policy mapping.

Supported methods:

GET: /auth/{mount_point}/map/users/{user_name}. Produces: 200 application/json

Parameters:

• user_name (str | unicode) – GitHub user name
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The JSON response of the read_user_mapping request.

Return type:

dict

class hvac.api.auth.Ldap(adapter)

Bases: hvac.api.vault_api_base.VaultApiBase

LDAP Auth Method (API).

Reference: https://www.vaultproject.io/api/auth/ldap/index.html

configure(user_dn, group_dn, url='ldap://127.0.0.1', case_sensitive_names=False, starttls=False, tls_min_version='tls12', tls_max_version='tls12', insecure_tls=False, certificate=None, bind_dn=None, bind_pass=None, user_attr='cn', discover_dn=False, deny_null_bind=True, upn_domain=None, group_filter='(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))', group_attr='cn', mount_point='ldap')

Configure the LDAP auth method.

Supported methods:

POST: /auth/{mount_point}/config. Produces: 204 (empty body)

Parameters:

• user_dn (str | unicode) – Base DN under which to perform user search. Example: ou=Users,dc=example,dc=com
• group_dn (str | unicode) – LDAP search base to use for group membership search. This can be the root containing either groups or users. Example: ou=Groups,dc=example,dc=com
• url (str | unicode) – The LDAP server to connect to. Examples: ldap://ldap.myorg.com, ldaps://ldap.myorg.com:636. Multiple URLs can be specified with commas, e.g. ldap://ldap.myorg.com,ldap://ldap2.myorg.com; these will be tried in-order.
• case_sensitive_names (bool) – If set, user and group names assigned to policies within the backend will be case sensitive. Otherwise, names will be normalized to lower case. Case will still be preserved when sending the username to the LDAP server at login time; this is only for matching local user/group definitions.
• starttls (bool) – If true, issues a StartTLS command after establishing an unencrypted connection.
• tls_min_version (str | unicode) – Minimum TLS version to use. Accepted values are tls10, tls11 or tls12.
• tls_max_version (str | unicode) – Maximum TLS version to use. Accepted values are tls10, tls11 or tls12.
• insecure_tls (bool) – If true, skips LDAP server SSL certificate verification - insecure, use with caution!
• certificate (str | unicode) – CA certificate to use when verifying LDAP server certificate, must be x509 PEM encoded.
• bind_dn (str | unicode) – Distinguished name of object to bind when performing user search. Example: cn=vault,ou=Users,dc=example,dc=com
• bind_pass (str | unicode) – Password to use along with binddn when performing user search.
• user_attr (str | unicode) – Attribute on user attribute object matching the username passed when authenticating. Examples: sAMAccountName, cn, uid
• discover_dn (bool) – Use anonymous bind to discover the bind DN of a user.
• deny_null_bind (bool) – This option prevents users from bypassing authentication when providing an empty password.
• upn_domain (str | unicode) – The userPrincipalDomain used to construct the UPN string for the authenticating user. The constructed UPN will appear as [username]@UPNDomain. Example: example.com, which will cause vault to bind as username@example.com.
• group_filter (str | unicode) – Go template used when constructing the group membership query. The template can access the following context variables: [UserDN, Username]. The default is (|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}})), which is compatible with several common directory schemas. To support nested group resolution for Active Directory, instead use the following query: (&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}})).
• group_attr (str | unicode) – LDAP attribute to follow on objects returned by groupfilter in order to enumerate user group membership. Examples: for groupfilter queries returning group objects, use: cn. For queries returning user objects, use: memberOf. The default is cn.
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The response of the configure request.

Return type:

requests.Response

create_or_update_group(name, policies=None, mount_point='ldap')

Create or update LDAP group policies.

Supported methods:

POST: /auth/{mount_point}/groups/{name}. Produces: 204 (empty body)

Parameters:

• name (str | unicode) – The name of the LDAP group
• policies (list) – List of policies associated with the group. This parameter is transformed to a comma-delimited string before being passed to Vault.
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The response of the create_or_update_group request.

Return type:

requests.Response

create_or_update_user(username, policies=None, groups=None, mount_point='ldap')

Create or update LDAP users policies and group associations.

Supported methods:

POST: /auth/{mount_point}/users/{username}. Produces: 204 (empty body)

Parameters:

• username (str | unicode) – The username of the LDAP user
• policies (str | unicode) – List of policies associated with the user. This parameter is transformed to a comma-delimited string before being passed to Vault.
• groups (str | unicode) – List of groups associated with the user. This parameter is transformed to a comma-delimited string before being passed to Vault.
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The response of the create_or_update_user request.

Return type:

requests.Response

delete_group(name, mount_point='ldap')

Delete a LDAP group and policy association.

Supported methods:

DELETE: /auth/{mount_point}/groups/{name}. Produces: 204 (empty body)

Parameters:

• name (str | unicode) – The name of the LDAP group
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The response of the delete_group request.

Return type:

requests.Response

delete_user(username, mount_point='ldap')

Delete a LDAP user and policy association.

Supported methods:

DELETE: /auth/{mount_point}/users/{username}. Produces: 204 (empty body)

Parameters:

• username (str | unicode) – The username of the LDAP user
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The response of the delete_user request.

Return type:

requests.Response

list_groups(mount_point='ldap')

List existing LDAP existing groups that have been created in this auth method.

Supported methods:

LIST: /auth/{mount_point}/groups. Produces: 200 application/json

Parameters:mount_point (str | unicode) – The “path” the method/backend was mounted on. Returns:The JSON response of the list_groups request. Return type:dict

list_users(mount_point='ldap')

List existing users in the method.

Supported methods:

LIST: /auth/{mount_point}/users. Produces: 200 application/json

Parameters:mount_point (str | unicode) – The “path” the method/backend was mounted on. Returns:The JSON response of the list_users request. Return type:dict

login(username, password, use_token=True, mount_point='ldap')

Log in with LDAP credentials.

Supported methods:

POST: /auth/{mount_point}/login/{username}. Produces: 200 application/json

Parameters:

• username (str | unicode) – The username of the LDAP user
• password (str | unicode) – The password for the LDAP user
• use_token (bool) – if True, uses the token in the response received from the auth request to set the “token” attribute on the the hvac.adapters.Adapter() instance under the _adapater Client attribute.
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The response of the login_with_user request.

Return type:

requests.Response

read_configuration(mount_point='ldap')

Retrieve the LDAP configuration for the auth method.

Supported methods:

GET: /auth/{mount_point}/config. Produces: 200 application/json

Parameters:mount_point (str | unicode) – The “path” the method/backend was mounted on. Returns:The JSON response of the read_configuration request. Return type:dict

read_group(name, mount_point='ldap')

Read policies associated with a LDAP group.

Supported methods:

GET: /auth/{mount_point}/groups/{name}. Produces: 200 application/json

Parameters:

• name (str | unicode) – The name of the LDAP group
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The JSON response of the read_group request.

Return type:

dict

read_user(username, mount_point='ldap')

Read policies associated with a LDAP user.

Supported methods:

GET: /auth/{mount_point}/users/{username}. Produces: 200 application/json

Parameters:

• username (str | unicode) – The username of the LDAP user
• mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The JSON response of the read_user request.

Return type:

dict

class hvac.api.auth.Mfa(adapter)

Bases: hvac.api.vault_api_base.VaultApiBase

Multi-factor authentication Auth Method (API).

Warning

This class’s methods correspond to a legacy / unsupported set of Vault API routes. Please see the reference link for additional context.

Reference: https://www.vaultproject.io/docs/auth/mfa.html

configure(mount_point, mfa_type='duo', force=False)

Configure MFA for a supported method.

This endpoint allows you to turn on multi-factor authentication with a given backend. Currently only Duo is supported.

Supported methods:

POST: /auth/{mount_point}/mfa_config. Produces: 204 (empty body)

Parameters:

• mount_point (str | unicode) – The “path” the method/backend was mounted on.
• mfa_type (str | unicode) – Enables MFA with given backend (available: duo)
• force (bool) – If True, make the “mfa_config” request regardless of circumstance. If False (the default), verify the provided mount_point is available and one of the types of methods supported by this feature.

Returns:

The response of the configure MFA request.

Return type:

requests.Response

configure_duo_access(mount_point, host, integration_key, secret_key)

Configure the access keys and host for Duo API connections.

To authenticate users with Duo, the backend needs to know what host to connect to and must authenticate with an integration key and secret key. This endpoint is used to configure that information.

Supported methods:

POST: /auth/{mount_point}/duo/access. Produces: 204 (empty body)

Parameters:

• mount_point (str | unicode) – The “path” the method/backend was mounted on.
• host (str | unicode) – Duo API host
• integration_key (Duo secret key) – Duo integration key
• secret_key (str | unicode) – The “path” the method/backend was mounted on.

Returns:

The response of the configure_duo_access request.

Return type:

requests.Response

configure_duo_behavior(mount_point, push_info=None, user_agent=None, username_format='%s')

Configure Duo second factor behavior.

This endpoint allows you to configure how the original auth method username maps to the Duo username by providing a template format string.

Supported methods:

POST: /auth/{mount_point}/duo/config. Produces: 204 (empty body)

Parameters:

• mount_point (str | unicode) – The “path” the method/backend was mounted on.
• push_info (str | unicode) – A string of URL-encoded key/value pairs that provides additional context about the authentication attempt in the Duo Mobile app
• user_agent (str | unicode) – User agent to connect to Duo (default “”)
• username_format (str | unicode) – Format string given auth method username as argument to create Duo username (default ‘%s’)

Returns:

The response of the configure_duo_behavior request.

Return type:

requests.Response

read_configuration(mount_point)

Read the MFA configuration.

Supported methods:

GET: /auth/{mount_point}/mfa_config. Produces: 200 application/json

Parameters:mount_point (str | unicode) – The “path” the method/backend was mounted on. Returns:The JSON response of the read_configuration request. Return type:dict

read_duo_behavior_configuration(mount_point)

Read the Duo second factor behavior configuration.

Supported methods:

GET: /auth/{mount_point}/duo/config. Produces: 200 application/json

Parameters:mount_point (str | unicode) – The “path” the method/backend was mounted on. Returns:The JSON response of the read_duo_behavior_configuration request. Return type:dict