hvac.api.auth¶
Collection of classes for various Vault auth methods.
-
class
hvac.api.auth.
Github
(adapter)[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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)[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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')[source]¶ 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)[source]¶ 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)[source]¶ 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)[source]¶ 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')[source]¶ 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)[source]¶ 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)[source]¶ 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
-