hvac.api.auth_methods

Collection of classes for various Vault auth methods.

Classes

AuthMethods(adapter)

Auth Methods.

AppRole(adapter)

USERPASS Auth Method (API).

Azure(adapter)

Azure Auth Method (API).

Gcp(adapter)

Google Cloud Auth Method (API).

Github(adapter)

GitHub Auth Method (API).

JWT(adapter)

JWT auth method which can be used to authenticate with Vault by providing a JWT.

Kubernetes(adapter)

Kubernetes Auth Method (API).

Ldap(adapter)

LDAP Auth Method (API).

Userpass(adapter)

USERPASS Auth Method (API).

Mfa(adapter)

Multi-factor authentication Auth Method (API).

OIDC(adapter)

OIDC auth method which can be used to authenticate with Vault using OIDC.

Okta(adapter)

Okta Auth Method (API).

Radius(adapter)

RADIUS Auth Method (API).

Aws(adapter)

AWS Auth Method (API).

Cert(adapter)

Cert Auth Method (API).

class hvac.api.auth_methods.AppRole(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

USERPASS Auth Method (API). Reference: https://www.vaultproject.io/api-docs/auth/approle/index.html

Methods

create_custom_secret_id(role_name, secret_id)

Generates and issues a new Secret ID on a role in the auth method.

create_or_update_approle(role_name[, …])

Create/update approle.

delete_role(role_name[, mount_point])

Delete role in the auth method.

destroy_secret_id(role_name, secret_id[, …])

Destroys a Secret ID for a role in the auth method.

destroy_secret_id_accessor(role_name, …[, …])

Destroys a Secret ID for a role in the auth method.

generate_secret_id(role_name[, metadata, …])

Generates and issues a new Secret ID on a role in the auth method.

list_roles([mount_point])

List existing roles created in the auth method.

list_secret_id_accessors(role_name[, …])

Lists accessors of all issued Secret IDs for a role in the auth method.

login(role_id[, secret_id, use_token, …])

Login with APPROLE credentials.

read_role(role_name[, mount_point])

Read role in the auth method.

read_role_id(role_name[, mount_point])

Reads the Role ID of a role in the auth method.

read_secret_id(role_name, secret_id[, …])

Read the properties of a Secret ID for a role in the auth method.

read_secret_id_accessor(role_name, …[, …])

Read the properties of a Secret ID for a role in the auth method.

update_role_id(role_name, role_id[, mount_point])

Updates the Role ID of a role in the auth method.

create_custom_secret_id(role_name, secret_id, metadata=None, cidr_list=None, token_bound_cidrs=None, mount_point='approle')[source]

Generates and issues a new Secret ID on a role in the auth method.

Supported methods:

POST: /auth/{mount_point}/role/{role_name}/custom-secret-id. Produces: 200 application/json

Parameters
  • role_name (str | unicode) – The name for the role.

  • secret_id (str | unicode) – The Secret ID to read.

  • metadata (dict) – Metadata to be tied to the Secret ID.

  • cidr_list (list) – Blocks of IP addresses which can perform login operations.

  • token_bound_cidrs (list) – Blocks of IP addresses which can authenticate successfully.

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

Returns

The JSON response of the read_role_id request.

Return type

dict

create_or_update_approle(role_name, bind_secret_id=None, secret_id_bound_cidrs=None, secret_id_num_uses=None, secret_id_ttl=None, enable_local_secret_ids=None, token_ttl=None, token_max_ttl=None, token_policies=None, token_bound_cidrs=None, token_explicit_max_ttl=None, token_no_default_policy=None, token_num_uses=None, token_period=None, token_type=None, mount_point='approle')[source]

Create/update approle.

Supported methods:

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

Parameters
  • role_name (str | unicode) – The name for the approle.

  • bind_secret_id (bool) – Require secret_id to be presented when logging in using this approle.

  • secret_id_bound_cidrs (list) – Blocks of IP addresses which can perform login operations.

  • secret_id_num_uses (int) – Number of times any secret_id can be used to fetch a token. A value of zero allows unlimited uses.

  • secret_id_ttl (str | unicode) – Duration after which a secret_id expires. This can be specified as an integer number of seconds or as a duration value like “5m”.

  • enable_local_secret_ids (bool) – Secret IDs generated using role will be cluster local.

  • token_ttl (str | unicode) – Incremental lifetime for generated tokens. This can be specified as an integer number of seconds or as a duration value like “5m”.

  • token_max_ttl (str | unicode) – Maximum lifetime for generated tokens: This can be specified as an integer number of seconds or as a duration value like “5m”.

  • token_policies (list) – List of policies to encode onto generated tokens.

  • token_bound_cidrs (list) – Blocks of IP addresses which can authenticate successfully.

  • token_explicit_max_ttl (str | unicode) – If set, will encode an explicit max TTL onto the token. This can be specified as an integer number of seconds or as a duration value like “5m”.

  • token_no_default_policy (bool) – Do not add the default policy to generated tokens, use only tokens specified in token_policies.

  • token_num_uses (int) – Maximum number of times a generated token may be used. A value of zero allows unlimited uses.

  • token_period (str | unicode) – The period, if any, to set on the token. This can be specified as an integer number of seconds or as a duration value like “5m”.

  • token_type (str | unicode) – The type of token that should be generated, can be “service”, “batch”, or “default”.

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

delete_role(role_name, mount_point='approle')[source]

Delete role in the auth method.

Supported methods:

DELETE: /auth/{mount_point}/role/{role_name}. Produces: 204 (empty body)

Parameters
  • role_name (str | unicode) – The name for the role.

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

destroy_secret_id(role_name, secret_id, mount_point='approle')[source]

Destroys a Secret ID for a role in the auth method.

Supported methods:

POST: /auth/{mount_point}/role/{role_name}/secret-id/destroy. Produces 204 (empty body)

Parameters
  • role_name (str | unicode) – The name for the role

  • secret_id (str | unicode) – The Secret ID to read.

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

destroy_secret_id_accessor(role_name, secret_id_accessor, mount_point='approle')[source]

Destroys a Secret ID for a role in the auth method.

Supported methods:

POST: /auth/{mount_point}/role/{role_name}/secret-id-accessor/destroy. Produces: 204 (empty body)

Parameters
  • role_name (str | unicode) – The name for the role

  • secret_id_accessor (str | unicode) – The accessor for the Secret ID to read.

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

generate_secret_id(role_name, metadata=None, cidr_list=None, token_bound_cidrs=None, mount_point='approle')[source]

Generates and issues a new Secret ID on a role in the auth method.

Supported methods:

POST: /auth/{mount_point}/role/{role_name}/secret-id. Produces: 200 application/json

Parameters
  • role_name (str | unicode) – The name for the role.

  • metadata (dict) – Metadata to be tied to the Secret ID.

  • cidr_list (list) – Blocks of IP addresses which can perform login operations.

  • token_bound_cidrs (list) – Blocks of IP addresses which can authenticate successfully.

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

Returns

The JSON response of the read_role_id request.

Return type

dict

list_roles(mount_point='approle')[source]

List existing roles created in the auth method.

Supported methods:

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

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The JSON response of the list_roles request.

Return type

dict

list_secret_id_accessors(role_name, mount_point='approle')[source]

Lists accessors of all issued Secret IDs for a role in the auth method.

Supported methods:

LIST: /auth/{mount_point}/role/{role_name}/secret-id. Produces: 200 application/json

Parameters
  • role_name (str | unicode) – The name for the role

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

Returns

The JSON response of the read_role_id request.

Return type

dict

login(role_id, secret_id=None, use_token=True, mount_point='approle')[source]

Login with APPROLE credentials.

Supported methods:

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

Parameters
  • role_id (str | unicode) – Role ID of the role.

  • secret_id (str | unicode) – Secret ID of the role.

  • 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 read_role_id request.

Return type

dict

read_role(role_name, mount_point='approle')[source]

Read role in the auth method.

Supported methods:

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

Parameters
  • role_name (str | unicode) – The name for the role.

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

Returns

The JSON response of the read_role request.

Return type

dict

read_role_id(role_name, mount_point='approle')[source]

Reads the Role ID of a role in the auth method.

Supported methods:

GET: /auth/{mount_point}/role/{role_name}/role-id. Produces: 200 application/json

Parameters
  • role_name (str | unicode) – The name for the role.

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

Returns

The JSON response of the read_role_id request.

Return type

dict

read_secret_id(role_name, secret_id, mount_point='approle')[source]

Read the properties of a Secret ID for a role in the auth method.

Supported methods:

POST: /auth/{mount_point}/role/{role_name}/secret-id/lookup. Produces: 200 application/json

Parameters
  • role_name (str | unicode) – The name for the role

  • secret_id (str | unicode) – The Secret ID to read.

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

Returns

The JSON response of the read_role_id request.

Return type

dict

read_secret_id_accessor(role_name, secret_id_accessor, mount_point='approle')[source]

Read the properties of a Secret ID for a role in the auth method.

Supported methods:

POST: /auth/{mount_point}/role/{role_name}/secret-id-accessor/lookup. Produces: 200 application/json

Parameters
  • role_name (str | unicode) – The name for the role

  • secret_id_accessor (str | unicode) – The accessor for the Secret ID to read.

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

Returns

The JSON response of the read_role_id request.

Return type

dict

update_role_id(role_name, role_id, mount_point='approle')[source]

Updates the Role ID of a role in the auth method.

Supported methods:

POST: /auth/{mount_point}/role/{role_name}/role-id. Produces: 200 application/json

Parameters
  • role_name (str | unicode) – The name for the role.

  • role_id (str | unicode) – New value for the Role ID.

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

Returns

The JSON response of the read_role_id request.

Return type

dict

class hvac.api.auth_methods.AuthMethods(adapter)[source]

Bases: hvac.api.vault_api_category.VaultApiCategory

Auth Methods.

Attributes

implemented_classes

Built-in mutable sequence.

unimplemented_classes

Built-in mutable sequence.

implemented_classes = [<class 'hvac.api.auth_methods.approle.AppRole'>, <class 'hvac.api.auth_methods.azure.Azure'>, <class 'hvac.api.auth_methods.github.Github'>, <class 'hvac.api.auth_methods.gcp.Gcp'>, <class 'hvac.api.auth_methods.jwt.JWT'>, <class 'hvac.api.auth_methods.kubernetes.Kubernetes'>, <class 'hvac.api.auth_methods.ldap.Ldap'>, <class 'hvac.api.auth_methods.userpass.Userpass'>, <class 'hvac.api.auth_methods.mfa.Mfa'>, <class 'hvac.api.auth_methods.oidc.OIDC'>, <class 'hvac.api.auth_methods.okta.Okta'>, <class 'hvac.api.auth_methods.radius.Radius'>, <class 'hvac.api.auth_methods.aws.Aws'>, <class 'hvac.api.auth_methods.cert.Cert'>]
unimplemented_classes = ['AppId', 'AliCloud', 'Token']
class hvac.api.auth_methods.Aws(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

AWS Auth Method (API).

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

Methods

configure([max_retries, access_key, …])

Configure the credentials required to perform API calls to AWS as well as custom endpoints to talk to AWS API.

configure_identity_integration([iam_alias, …])

Configure the way that Vault interacts with the Identity store.

configure_identity_whitelist_tidy([…])

Configure the periodic tidying operation of the whitelisted identity entries.

configure_role_tag_blacklist_tidy([…])

Configure the periodic tidying operation of the blacklisted role tag entries.

create_certificate_configuration(cert_name, …)

Register AWS public key to be used to verify the instance identity documents.

create_role(role[, auth_type, bound_ami_id, …])

Register a role in the method.

create_role_tags(role[, policies, max_ttl, …])

Create a role tag on the role, which helps in restricting the capabilities that are set on the role.

create_sts_role(account_id, sts_role[, …])

Allow the explicit association of STS roles to satellite AWS accounts (i.e.

delete_blacklist_tags(role_tag[, mount_point])

Deletes a blacklisted role tag

delete_certificate_configuration(cert_name)

Remove previously configured AWS public key.

delete_config([mount_point])

Delete previously configured AWS access credentials,

delete_identity_whitelist_entries(instance_id)

Deletes a cache of the successful login from an instance

delete_identity_whitelist_tidy([mount_point])

Delete previously configured periodic whitelist tidying settings.

delete_role(role[, mount_point])

Deletes the previously registered role

delete_role_tag_blacklist_tidy([mount_point])

Delete previously configured periodic blacklist tidying settings.

delete_sts_role(account_id[, mount_point])

Delete a previously configured AWS account/STS role association.

ec2_login(pkcs7[, nonce, role, use_token, …])

Retrieve a Vault token using an AWS authentication method mount’s EC2 role.

iam_login(access_key, secret_key[, …])

Fetch a token

list_blacklist_tags([mount_point])

Lists all the role tags that are blacklisted

list_certificate_configurations([mount_point])

List AWS public certificates that are registered with the method.

list_identity_whitelist([mount_point])

Lists all the instance IDs that are in the whitelist of successful logins

list_roles([mount_point])

Lists all the roles that are registered with the method

list_sts_roles([mount_point])

List AWS Account IDs for which an STS role is registered.

place_role_tags_in_blacklist(role_tag[, …])

Places a valid role tag in a blacklist

read_certificate_configuration(cert_name[, …])

Return previously configured AWS public key.

read_config([mount_point])

Read previously configured AWS access credentials.

read_identity_integration([mount_point])

Return previously configured identity integration configuration.

read_identity_whitelist(instance_id[, …])

Returns an entry in the whitelist.

read_identity_whitelist_tidy([mount_point])

Read previously configured periodic whitelist tidying settings.

read_role(role[, mount_point])

Returns the previously registered role configuration

read_role_tag_blacklist(role_tag[, mount_point])

Returns the blacklist entry of a previously blacklisted role tag

read_role_tag_blacklist_tidy([mount_point])

Read previously configured periodic blacklist tidying settings.

read_sts_role(account_id[, mount_point])

Return previously configured STS role.

tidy_blacklist_tags([saftey_buffer, mount_point])

Cleans up the entries in the blacklist based on expiration time on the entry and safety_buffer

tidy_identity_whitelist_entries([…])

Cleans up the entries in the whitelist based on expiration time and safety_buffer

configure(max_retries=None, access_key=None, secret_key=None, endpoint=None, iam_endpoint=None, sts_endpoint=None, iam_server_id_header_value=None, mount_point='aws')[source]

Configure the credentials required to perform API calls to AWS as well as custom endpoints to talk to AWS API.

The instance identity document fetched from the PKCS#7 signature will provide the EC2 instance ID. The credentials configured using this endpoint will be used to query the status of the instances via DescribeInstances API. If static credentials are not provided using this endpoint, then the credentials will be retrieved from the environment variables AWS_ACCESS_KEY, AWS_SECRET_KEY and AWS_REGION respectively. If the credentials are still not found and if the method is configured on an EC2 instance with metadata querying capabilities, the credentials are fetched automatically

Supported methods:

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

Parameters
  • max_retries (int) – Number of max retries the client should use for recoverable errors. The default (-1) falls back to the AWS SDK’s default behavior

  • access_key (str | unicode) – AWS Access key with permissions to query AWS APIs. The permissions required depend on the specific configurations. If using the iam auth method without inferencing, then no credentials are necessary. If using the ec2 auth method or using the iam auth method with inferencing, then these credentials need access to ec2:DescribeInstances. If additionally a bound_iam_role is specified, then these credentials also need access to iam:GetInstanceProfile. If, however, an alternate sts configuration is set for the target account, then the credentials must be permissioned to call sts:AssumeRole on the configured role, and that role must have the permissions described here

  • secret_key (str | unicode) – AWS Secret key with permissions to query AWS APIs

  • endpoint (str | unicode) – URL to override the default generated endpoint for making AWS EC2 API calls

  • iam_endpoint (str | unicode) – URL to override the default generated endpoint for making AWS IAM API calls

  • sts_endpoint (str | unicode) – URL to override the default generated endpoint for making AWS STS API calls

  • iam_server_id_header_value (str | unicode) – The value to require in the X-Vault-AWS-IAM-Server-ID header as part of GetCallerIdentity requests that are used in the iam auth method. If not set, then no value is required or validated. If set, clients must include an X-Vault-AWS-IAM-Server-ID header in the headers of login requests, and further this header must be among the signed headers validated by AWS. This is to protect against different types of replay attacks, for example a signed request sent to a dev server being resent to a production server

  • mount_point (str | unicode) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

configure_identity_integration(iam_alias=None, ec2_alias=None, mount_point='aws')[source]

Configure the way that Vault interacts with the Identity store.

The default (as of Vault 1.0.3) is role_id for both values.

Supported methods:

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

Parameters
  • iam_alias (str | unicode) – How to generate the identity alias when using the iam auth method. Valid choices are role_id, unique_id, and full_arn When role_id is selected, the randomly generated ID of the role is used. When unique_id is selected, the IAM Unique ID of the IAM principal (either the user or role) is used as the identity alias name. When full_arn is selected, the ARN returned by the sts:GetCallerIdentity call is used as the alias name. This is either arn:aws:iam::<account_id>:user/<optional_path/><user_name> or arn:aws:sts::<account_id>:assumed-role/<role_name_without_path>/<role_session_name>. Note: if you select full_arn and then delete and recreate the IAM role, Vault won’t be aware and any identity aliases set up for the role name will still be valid

  • ec2_alias (str | unicode) – Configures how to generate the identity alias when using the ec2 auth method. Valid choices are role_id, instance_id, and image_id. When role_id is selected, the randomly generated ID of the role is used. When instance_id is selected, the instance identifier is used as the identity alias name. When image_id is selected, AMI ID of the instance is used as the identity alias name

  • mount_point (str | unicode) – The path the AWS auth method was mounted on.

Returns

The response of the request

Return type

request.Response

configure_identity_whitelist_tidy(safety_buffer=None, disable_periodic_tidy=None, mount_point='aws')[source]

Configure the periodic tidying operation of the whitelisted identity entries.

Parameters
  • safety_buffer (str) – The amount of extra time that must have passed beyond the roletag expiration, before it is removed from the method storage.

  • disable_periodic_tidy (bool) – If set to ‘true’, disables the periodic tidying of the identity-whitelist/<instance_id> entries.

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

configure_role_tag_blacklist_tidy(safety_buffer=None, disable_periodic_tidy=None, mount_point='aws')[source]

Configure the periodic tidying operation of the blacklisted role tag entries.

Parameters
  • safety_buffer (str) – The amount of extra time that must have passed beyond the roletag expiration, before it is removed from the method storage.

  • disable_periodic_tidy (bool) – If set to ‘true’, disables the periodic tidying of the roletag-blacklist/<instance_id> entries.

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

create_certificate_configuration(cert_name, aws_public_cert, document_type=None, mount_point='aws')[source]

Register AWS public key to be used to verify the instance identity documents.

While the PKCS#7 signature of the identity documents have DSA digest, the identity signature will have RSA digest, and hence the public keys for each type varies respectively. Indicate the type of the public key using the “type” parameter

Supported methods:

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

Parameters
  • cert_name (string | unicode) – Name of the certificate

  • aws_public_cert – Base64 encoded AWS Public key required to verify PKCS7 signature of the EC2 instance metadata

  • document_type (string | unicode) – Takes the value of either “pkcs7” or “identity”, indicating the type of document which can be verified using the given certificate

  • mount_point (str | unicode) – The path the AWS auth method was mounted on.

Returns

The response of the request

Return type

request.Response

create_role(role, auth_type=None, bound_ami_id=None, bound_account_id=None, bound_region=None, bound_vpc_id=None, bound_subnet_id=None, bound_iam_role_arn=None, bound_iam_instance_profile_arn=None, bound_ec2_instance_id=None, role_tag=None, bound_iam_principal_arn=None, inferred_entity_type=None, inferred_aws_region=None, resolve_aws_unique_ids=None, ttl=None, max_ttl=None, period=None, policies=None, allow_instance_migration=None, disallow_reauthentication=None, mount_point='aws')[source]

Register a role in the method.

Parameters
  • role

  • auth_type

  • bound_ami_id

  • bound_account_id

  • bound_region

  • bound_vpc_id

  • bound_subnet_id

  • bound_iam_role_arn

  • bound_iam_instance_profile_arn

  • bound_ec2_instance_id

  • role_tag

  • bound_iam_principal_arn

  • inferred_entity_type

  • inferred_aws_region

  • resolve_aws_unique_ids

  • ttl

  • max_ttl

  • period

  • policies

  • allow_instance_migration

  • disallow_reauthentication

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

create_role_tags(role, policies=None, max_ttl=None, instance_id=None, allow_instance_migration=None, disallow_reauthentication=None, mount_point='aws')[source]

Create a role tag on the role, which helps in restricting the capabilities that are set on the role.

Role tags are not tied to any specific ec2 instance unless specified explicitly using the instance_id parameter. By default, role tags are designed to be used across all instances that satisfies the constraints on the role. Regardless of which instances have role tags on them, capabilities defined in a role tag must be a strict subset of the given role’s capabilities. Note that, since adding and removing a tag is often a widely distributed privilege, care needs to be taken to ensure that the instances are attached with correct tags to not let them gain more privileges than what were intended. If a role tag is changed, the capabilities inherited by the instance will be those defined on the new role tag. Since those must be a subset of the role capabilities, the role should never provide more capabilities than any given instance can be allowed to gain in a worst-case scenario

Parameters
  • role (str) – Name of the role.

  • policies (list) – Policies to be associated with the tag. If set, must be a subset of the role’s policies. If set, but set to an empty value, only the ‘default’ policy will be given to issued tokens.

  • max_ttl (str) – The maximum allowed lifetime of tokens issued using this role.

  • instance_id (str) – Instance ID for which this tag is intended for. If set, the created tag can only be used by the instance with the given ID.

  • disallow_reauthentication (bool) – If set, only allows a single token to be granted per instance ID. This can be cleared with the auth/aws/identity-whitelist endpoint. Defaults to ‘false’. Mutually exclusive with allow_instance_migration.

  • allow_instance_migration (bool) – If set, allows migration of the underlying instance where the client resides. This keys off of pendingTime in the metadata document, so essentially, this disables the client nonce check whenever the instance is migrated to a new host and pendingTime is newer than the previously-remembered time. Use with caution. Defaults to ‘false’. Mutually exclusive with disallow_reauthentication.

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The create role tag response.

Return type

dict

create_sts_role(account_id, sts_role, mount_point='aws')[source]
Allow the explicit association of STS roles to satellite AWS accounts (i.e. those which are not the

account in which the Vault server is running.)

Vault will use credentials obtained by assuming these STS roles when validating IAM principals or EC2 instances in the particular AWS account

Supported methods:

POST: /v1/auth/{mount_point}/config/sts/:account_id Produces: 204 (empty body)

Parameters
  • account_id (str) – AWS account ID to be associated with STS role. If set, Vault will use assumed credentials to verify any login attempts from EC2 instances in this account.

  • sts_role (str) – AWS ARN for STS role to be assumed when interacting with the account specified. The Vault server must have permissions to assume this role.

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_blacklist_tags(role_tag, mount_point='aws')[source]

Deletes a blacklisted role tag

Parameters
  • role_tag

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_certificate_configuration(cert_name, mount_point='aws')[source]

Remove previously configured AWS public key.

Supported methods:

DELETE: /auth/{mount_point}/config/certificate/:cert_name Produces: 204 (empty body)

Parameters
  • cert_name (str | unicode) – Name of the certificate

  • mount_point (str | unicode) – The path the AWS auth method was mounted on.

Returns

The response of the request

Return type

request.Response

delete_config(mount_point='aws')[source]

Delete previously configured AWS access credentials,

Supported methods:

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

Parameters

mount_point (str | unicode) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_identity_whitelist_entries(instance_id, mount_point='aws')[source]

Deletes a cache of the successful login from an instance

Parameters
  • instance_id

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_identity_whitelist_tidy(mount_point='aws')[source]

Delete previously configured periodic whitelist tidying settings.

Parameters

mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_role(role, mount_point='aws')[source]

Deletes the previously registered role

Parameters
  • role

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_role_tag_blacklist_tidy(mount_point='aws')[source]

Delete previously configured periodic blacklist tidying settings.

Parameters

mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_sts_role(account_id, mount_point='aws')[source]

Delete a previously configured AWS account/STS role association.

Parameters
  • account_id

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

ec2_login(pkcs7, nonce=None, role=None, use_token=True, mount_point='aws')[source]

Retrieve a Vault token using an AWS authentication method mount’s EC2 role.

Parameters
  • pkcs7 (str) – PKCS7 signature of the identity document with all newline characters removed.

  • nonce (str) – The nonce to be used for subsequent login requests.

  • role (str) – Name of the role against which the login is being attempted.

  • 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) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

iam_login(access_key, secret_key, session_token=None, header_value=None, role=None, use_token=True, region='us-east-1', mount_point='aws')[source]

Fetch a token

This endpoint verifies the pkcs7 signature of the instance identity document or the signature of the signed GetCallerIdentity request. With the ec2 auth method, or when inferring an EC2 instance, verifies that the instance is actually in a running state. Cross checks the constraints defined on the role with which the login is being performed. With the ec2 auth method, as an alternative to pkcs7 signature, the identity document along with its RSA digest can be supplied to this endpoint

Parameters
  • role (str) – Name of the role against which the login is being attempted.

  • 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) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

list_blacklist_tags(mount_point='aws')[source]

Lists all the role tags that are blacklisted

Parameters

mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

list_certificate_configurations(mount_point='aws')[source]

List AWS public certificates that are registered with the method.

Supported methods

LIST: /auth/{mount_point}/config/certificates Produces: 200 application/json

Parameters

mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

list_identity_whitelist(mount_point='aws')[source]

Lists all the instance IDs that are in the whitelist of successful logins

Parameters

mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

list_roles(mount_point='aws')[source]

Lists all the roles that are registered with the method

Parameters

mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

list_sts_roles(mount_point='aws')[source]

List AWS Account IDs for which an STS role is registered.

Parameters

mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

place_role_tags_in_blacklist(role_tag, mount_point='aws')[source]

Places a valid role tag in a blacklist

This ensures that the role tag cannot be used by any instance to perform a login operation again. Note that if the role tag was previously used to perform a successful login, placing the tag in the blacklist does not invalidate the already issued token

Parameters
  • role_tag

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

read_certificate_configuration(cert_name, mount_point='aws')[source]

Return previously configured AWS public key.

Supported methods:

GET: /v1/auth/{mount_point}/config/certificate/:cert_name Produces: 200 application/json

Parameters
  • cert_name (str | unicode) – Name of the certificate

  • mount_point – The path the AWS auth method was mounted on.

Returns

The data key from the JSON response of the request.

Return type

dict

read_config(mount_point='aws')[source]

Read previously configured AWS access credentials.

Supported methods:

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

Parameters

mount_point (str | unicode) – The path the AWS auth method was mounted on.

Returns

The data key from the JSON response of the request.

Return type

dict

read_identity_integration(mount_point='aws')[source]

Return previously configured identity integration configuration.

Supported methods:

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

Parameters

mount_point (str | unicode) – The path the AWS auth method was mounted on.

Returns

The data key from the JSON response of the request.

Return type

dict

read_identity_whitelist(instance_id, mount_point='aws')[source]

Returns an entry in the whitelist. An entry will be created/updated by every successful login

Parameters
  • instance_id

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

read_identity_whitelist_tidy(mount_point='aws')[source]

Read previously configured periodic whitelist tidying settings.

Parameters

mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

read_role(role, mount_point='aws')[source]

Returns the previously registered role configuration

Parameters
  • role

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

read_role_tag_blacklist(role_tag, mount_point='aws')[source]

Returns the blacklist entry of a previously blacklisted role tag

Parameters
  • role_tag

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

read_role_tag_blacklist_tidy(mount_point='aws')[source]

Read previously configured periodic blacklist tidying settings.

Parameters

mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

read_sts_role(account_id, mount_point='aws')[source]

Return previously configured STS role.

Parameters
  • account_id (str) – AWS account ID that has been previously associated with STS role.

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

tidy_blacklist_tags(saftey_buffer='72h', mount_point='aws')[source]

Cleans up the entries in the blacklist based on expiration time on the entry and safety_buffer

Parameters
  • saftey_buffer

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

tidy_identity_whitelist_entries(saftey_buffer='72h', mount_point='aws')[source]

Cleans up the entries in the whitelist based on expiration time and safety_buffer

Parameters
  • saftey_buffer

  • mount_point (str) – The path the AWS auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

class hvac.api.auth_methods.Azure(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Azure Auth Method (API).

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

Methods

configure(tenant_id, resource[, …])

Configure the credentials required for the plugin to perform API calls to Azure.

create_role(name[, policies, ttl, max_ttl, …])

Create a role in the method.

delete_config([mount_point])

Delete the previously configured Azure config and credentials.

delete_role(name[, mount_point])

Delete the previously registered role.

list_roles([mount_point])

List all the roles that are registered with the plugin.

login(role, jwt[, subscription_id, …])

Fetch a token.

read_config([mount_point])

Return the previously configured config, including credentials.

read_role(name[, mount_point])

Read the previously registered role configuration.

configure(tenant_id, resource, environment=None, client_id=None, client_secret=None, mount_point='azure')[source]

Configure the credentials required for the plugin to perform API calls to Azure.

These credentials will be used to query the metadata about the virtual machine.

Supported methods:

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

Parameters
  • tenant_id (str | unicode) – The tenant id for the Azure Active Directory organization.

  • resource (str | unicode) – The configured URL for the application registered in Azure Active Directory.

  • environment (str | unicode) – The Azure cloud environment. Valid values: AzurePublicCloud, AzureUSGovernmentCloud, AzureChinaCloud, AzureGermanCloud.

  • client_id (str | unicode) – The client id for credentials to query the Azure APIs. Currently read permissions to query compute resources are required.

  • client_secret (str | unicode) – The client secret for credentials to query the Azure APIs.

  • mount_point (str | unicode) – The “path” the azure auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

create_role(name, policies=None, ttl=None, max_ttl=None, period=None, bound_service_principal_ids=None, bound_group_ids=None, bound_locations=None, bound_subscription_ids=None, bound_resource_groups=None, bound_scale_sets=None, num_uses=None, mount_point='azure')[source]

Create a role in the method.

Role types have specific entities that can perform login operations against this endpoint. Constraints specific to the role type must be set on the role. These are applied to the authenticated entities attempting to login.

Supported methods:

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

Parameters
  • name (str | unicode) – Name of the role.

  • policies (str | list) – Policies to be set on tokens issued using this role.

  • num_uses (int) – Number of uses to set on a token produced by this role.

  • ttl (str | unicode) – The TTL period of tokens issued using this role in seconds.

  • max_ttl (str | unicode) – The maximum allowed lifetime of tokens issued in seconds using this role.

  • period (str | unicode) – If set, indicates that the token generated using this role should never expire. The token should be renewed within the duration specified by this value. At each renewal, the token’s TTL will be set to the value of this parameter.

  • bound_service_principal_ids (list) – The list of Service Principal IDs that login is restricted to.

  • bound_group_ids (list) – The list of group ids that login is restricted to.

  • bound_locations (list) – The list of locations that login is restricted to.

  • bound_subscription_ids (list) – The list of subscription IDs that login is restricted to.

  • bound_resource_groups (list) – The list of resource groups that login is restricted to.

  • bound_scale_sets (list) – The list of scale set names that the login is restricted to.

  • mount_point (str | unicode) – The “path” the azure auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_config(mount_point='azure')[source]

Delete the previously configured Azure config and credentials.

Supported methods:

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

Parameters

mount_point (str | unicode) – The “path” the azure auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_role(name, mount_point='azure')[source]

Delete the previously registered role.

Supported methods:

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

Parameters
  • name (str | unicode) – Name of the role.

  • mount_point (str | unicode) – The “path” the azure auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

list_roles(mount_point='azure')[source]

List all the roles that are registered with the plugin.

Supported methods:

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

Parameters

mount_point (str | unicode) – The “path” the azure auth method was mounted on.

Returns

The “data” key from the JSON response of the request.

Return type

dict

login(role, jwt, subscription_id=None, resource_group_name=None, vm_name=None, vmss_name=None, use_token=True, mount_point='azure')[source]

Fetch a token.

This endpoint takes a signed JSON Web Token (JWT) and a role name for some entity. It verifies the JWT signature to authenticate that entity and then authorizes the entity for the given role.

Supported methods:

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

Parameters
  • role (str | unicode) – Name of the role against which the login is being attempted.

  • jwt (str | unicode) – Signed JSON Web Token (JWT) from Azure MSI.

  • subscription_id (str | unicode) – The subscription ID for the machine that generated the MSI token. This information can be obtained through instance metadata.

  • resource_group_name (str | unicode) – The resource group for the machine that generated the MSI token. This information can be obtained through instance metadata.

  • vm_name (str | unicode) – The virtual machine name for the machine that generated the MSI token. This information can be obtained through instance metadata. If vmss_name is provided, this value is ignored.

  • vmss_name (str | unicode) – The virtual machine scale set name for the machine that generated the MSI token. This information can be obtained through instance metadata.

  • 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 azure auth method was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_config(mount_point='azure')[source]

Return the previously configured config, including credentials.

Supported methods:

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

Parameters

mount_point (str | unicode) – The “path” the azure auth method was mounted on.

Returns

The data key from the JSON response of the request.

Return type

dict

read_role(name, mount_point='azure')[source]

Read the previously registered role configuration.

Supported methods:

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

Parameters
  • name (str | unicode) – Name of the role.

  • mount_point (str | unicode) – The “path” the azure auth method was mounted on.

Returns

The “data” key from the JSON response of the request.

Return type

dict

class hvac.api.auth_methods.Cert(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Cert Auth Method (API).

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

Miscellaneous

CertificateAuthError

Methods

configure_tls_certificate([mount_point, …])

Configure options for the method.

create_ca_certificate_role(name, certificate)

Create CA Certificate Role Sets a CA cert and associated parameters in a role name.

delete_certificate_role(name[, mount_point])

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

list_certificate_roles([mount_point])

Lists configured certificate names.

login([name, cacert, cert_pem, key_pem, …])

Log in and fetch a token.

read_ca_certificate_role(name[, mount_point])

Gets information associated with the named role.

exception CertificateAuthError[source]

Bases: Exception

configure_tls_certificate(mount_point='cert', disable_binding=False)[source]

Configure options for the method.

Supported methods:

POST: /auth/<mount point>/config. Produces: 204 (empty body)

Parameters
  • disable_binding (bool) – If set, during renewal, skips the matching of presented client identity with the client identity used during login.

  • mount_point

create_ca_certificate_role(name, certificate, allowed_common_names='', allowed_dns_sans='', allowed_email_sans='', allowed_uri_sans='', allowed_organizational_units='', required_extensions='', display_name='', token_ttl=0, token_max_ttl=0, token_policies=[], token_bound_cidrs=[], token_explicit_max_ttl=0, token_no_default_policy=False, token_num_uses=0, token_period=0, token_type='', mount_point='cert')[source]

Create CA Certificate Role Sets a CA cert and associated parameters in a role name.

Supported methods:

POST: /auth/<mount point>/certs/:name. Produces: 204 (empty body)

»Parameters :param name: The name of the certificate role. :type name: str :param certificate: The PEM-format CA certificate. :type certificate: str :param allowed_common_names: Constrain the Common Names in the client certificate with a globbed pattern. Value is a comma-separated list of patterns. Authentication requires at least one Name matching at least one pattern. If not set, defaults to allowing all names. :type allowed_common_names: str | list :param allowed_dns_sans: Constrain the Alternative Names in the client certificate with a globbed pattern. Value is a comma-separated list of patterns. Authentication requires at least one DNS matching at least one pattern. If not set, defaults to allowing all dns. :type allowed_dns_sans: str | list :param allowed_email_sans: Constrain the Alternative Names in the client certificate with a globbed pattern. Value is a comma-separated list of patterns. Authentication requires at least one Email matching at least one pattern. If not set, defaults to allowing all emails. :type allowed_email_sans: str | list :param allowed_uri_sans: Constrain the Alternative Names in the client certificate with a globbed pattern. Value is a comma-separated list of URI patterns. Authentication requires at least one URI matching at least one pattern. If not set, defaults to allowing all URIs. :type allowed_uri_sans: str | list :param allowed_organizational_units: Constrain the Organizational Units (OU) in the client certificate with a globbed pattern. Value is a comma-separated list of OU patterns. Authentication requires at least one OU matching at least one pattern. If not set, defaults to allowing all OUs. :type allowed_organizational_units: str | list :param required_extensions: Require specific Custom Extension OIDs to exist and match the pattern. Value is a comma separated string or array of oid:value. Expects the extension value to be some type of ASN1 encoded string. All conditions must be met. Supports globbing on value. :type required_extensions: str | list :param display_name: The display_name to set on tokens issued when authenticating against this CA certificate. If not set, defaults to the name of the role. :type display_name: str | unicode :param token_ttl: The incremental lifetime for generated tokens. This current value of this will be referenced at renewal time. :type token_ttl: int | str :param token_max_ttl: The maximum lifetime for generated tokens. This current value of this will be referenced at renewal time. :type token_max_ttl: int | str :param token_policies: List of policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values. :type token_policies: list | str :param token_bound_cidrs: List of CIDR blocks; if set, specifies blocks of IP addresses which can authenticate successfully, and ties the resulting token to these blocks as well. :type token_bound_cidrs: list | str :param token_explicit_max_ttl: If set, will encode an explicit max TTL onto the token. This is a hard cap even if token_ttl and token_max_ttl would otherwise allow a renewal. :type token_explicit_max_ttl: int | str :param token_no_default_policy: If set, the default policy will not be set on generated tokens; otherwise it will be added to the policies set in token_policies. :type token_no_default_policy: bool :param token_num_uses: The maximum number of times a generated token may be used (within its lifetime); 0 means unlimited. If you require the token to have the ability to create child tokens, you will need to set this value to 0. :type token_num_uses: int :param token_period: The period, if any, to set on the token. :type token_period: int | str :param token_type: The type of token that should be generated. Can be service, batch, or default to use the mount’s tuned default (which unless changed will be service tokens). For token store roles, there are two additional possibilities: default-service and default-batch which specify the type to return unless the client requests a different type at generation time. :type token_type: str :param mount_point: :type mount_point:

delete_certificate_role(name, mount_point='cert')[source]

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

Supported methods:

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

Parameters
  • name (str | unicode) – The name of the certificate role.

  • mount_point

list_certificate_roles(mount_point='cert')[source]

Lists configured certificate names.

Supported methods:

LIST: /auth/<mount point>/certs. Produces: 200 application/json

Parameters

mount_point

Returns

The response of the list_certificate request.

Return type

requests.Response

login(name='', cacert=False, cert_pem='', key_pem='', mount_point='cert', use_token=True)[source]
Log in and fetch a token. If there is a valid chain to a CA configured in the method and all role constraints

are matched, a token will be issued. If the certificate has DNS SANs in it, each of those will be verified. If Common Name is required to be verified, then it should be a fully qualified DNS domain name and must be duplicated as a DNS SAN

Supported methods:

POST: /auth/<mount point>/login Produces: 200 application/json

Parameters
  • name (str | unicode) – Authenticate against only the named certificate role, returning its policy list if successful. If not set, defaults to trying all certificate roles and returning any one that matches.

  • cacert (str | bool) – The value used here is for the Vault TLS Listener CA certificate, not the CA that issued the client authentication certificate. This can be omitted if the CA used to issue the Vault server certificate is trusted by the local system executing this command.

  • cert_pem – Location of the cert.pem used to authenticate the host.

  • key_pem – Location of the public key.pem used to authenticate the host.

  • key_pem – str | unicode

  • mount_point

  • use_token – If the returned token is stored in the client

  • use_token – bool

Tupe cert_pem

str | unicode

Returns

The response of the login request.

Return type

requests.Response

read_ca_certificate_role(name, mount_point='cert')[source]

Gets information associated with the named role.

Supported methods:

GET: /auth/<mount point>/certs/{name}. Produces: 200 application/json

Parameters
  • name (str | unicode) – The name of the certificate role

  • mount_point

Returns

The JSON response of the read_ca_certificate_role request.

Return type

dict

class hvac.api.auth_methods.Gcp(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Google Cloud Auth Method (API).

Reference: https://www.vaultproject.io/api/auth/{mount_point}/index.html

Methods

configure([credentials, …])

Configure the credentials required for the GCP auth method to perform API calls to Google Cloud.

create_role(name, role_type, project_id[, …])

Register a role in the GCP auth method.

delete_config([mount_point])

Delete all GCP configuration data.

delete_role(role[, mount_point])

Delete the previously registered role.

edit_labels_on_gce_role(name[, add, remove, …])

Edit labels for an existing GCE role in the backend.

edit_service_accounts_on_iam_role(name[, …])

Edit service accounts for an existing IAM role in the GCP auth method.

list_roles([mount_point])

List all the roles that are registered with the plugin.

login(role, jwt[, use_token, mount_point])

Login to retrieve a Vault token via the GCP auth method.

read_config([mount_point])

Read the configuration, if any, including credentials.

read_role(name[, mount_point])

Read the previously registered role configuration.

configure(credentials=None, google_certs_endpoint='https://www.googleapis.com/oauth2/v3/certs', mount_point='gcp')[source]

Configure the credentials required for the GCP auth method to perform API calls to Google Cloud.

These credentials will be used to query the status of IAM entities and get service account or other Google public certificates to confirm signed JWTs passed in during login.

Supported methods:

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

Parameters
  • credentials (str | unicode) – A JSON string containing the contents of a GCP credentials file. The credentials file must have the following permissions: iam.serviceAccounts.get, iam.serviceAccountKeys.get. If this value is empty, Vault will try to use Application Default Credentials from the machine on which the Vault server is running. The project must have the iam.googleapis.com API enabled.

  • google_certs_endpoint (str | unicode) – The Google OAuth2 endpoint from which to obtain public certificates. This is used for testing and should generally not be set by end users.

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

Returns

The response of the request.

Return type

requests.Response

create_role(name, role_type, project_id, ttl=None, max_ttl=None, period=None, policies=None, bound_service_accounts=None, max_jwt_exp=None, allow_gce_inference=None, bound_zones=None, bound_regions=None, bound_instance_groups=None, bound_labels=None, mount_point='gcp')[source]

Register a role in the GCP auth method.

Role types have specific entities that can perform login operations against this endpoint. Constraints specific

to the role type must be set on the role. These are applied to the authenticated entities attempting to login.

Supported methods:

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

Parameters
  • name (str | unicode) – The name of the role.

  • role_type (str | unicode) – The type of this role. Certain fields correspond to specific roles and will be rejected otherwise.

  • project_id (str | unicode) – The GCP project ID. Only entities belonging to this project can authenticate with this role.

  • ttl (str | unicode) – The TTL period of tokens issued using this role. This can be specified as an integer number of seconds or as a duration value like “5m”.

  • max_ttl (str | unicode) – The maximum allowed lifetime of tokens issued in seconds using this role. This can be specified as an integer number of seconds or as a duration value like “5m”.

  • period (str | unicode) – If set, indicates that the token generated using this role should never expire. The token should be renewed within the duration specified by this value. At each renewal, the token’s TTL will be set to the value of this parameter. This can be specified as an integer number of seconds or as a duration value like “5m”.

  • policies (list) – The list of policies to be set on tokens issued using this role.

  • bound_service_accounts (list) – <required for iam> A list of service account emails or IDs that login is restricted to. If set to *, all service accounts are allowed (role will still be bound by project). Will be inferred from service account used to issue metadata token for GCE instances.

  • max_jwt_exp (str | unicode) – <iam only> The number of seconds past the time of authentication that the login param JWT must expire within. For example, if a user attempts to login with a token that expires within an hour and this is set to 15 minutes, Vault will return an error prompting the user to create a new signed JWT with a shorter exp. The GCE metadata tokens currently do not allow the exp claim to be customized.

  • allow_gce_inference (bool) – <iam only> A flag to determine if this role should allow GCE instances to authenticate by inferring service accounts from the GCE identity metadata token.

  • bound_zones (list) – <gce only> The list of zones that a GCE instance must belong to in order to be authenticated. If bound_instance_groups is provided, it is assumed to be a zonal group and the group must belong to this zone.

  • bound_regions (list) – <gce only> The list of regions that a GCE instance must belong to in order to be authenticated. If bound_instance_groups is provided, it is assumed to be a regional group and the group must belong to this region. If bound_zones are provided, this attribute is ignored.

  • bound_instance_groups (list) – <gce only> The instance groups that an authorized instance must belong to in order to be authenticated. If specified, either bound_zones or bound_regions must be set too.

  • bound_labels (list) – <gce only> A list of GCP labels formatted as “key:value” strings that must be set on authorized GCE instances. Because GCP labels are not currently ACL’d, we recommend that this be used in conjunction with other restrictions.

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

Returns

The data key from the JSON response of the request.

Return type

requests.Response

delete_config(mount_point='gcp')[source]

Delete all GCP configuration data. This operation is idempotent.

Supported methods:

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

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_role(role, mount_point='gcp')[source]

Delete the previously registered role.

Supported methods:

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

Parameters
  • role (str | unicode) – The name of the role to delete.

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

Returns

The response of the request.

Return type

requests.Response

edit_labels_on_gce_role(name, add=None, remove=None, mount_point='gcp')[source]

Edit labels for an existing GCE role in the backend.

This allows you to add or remove labels (keys, values, or both) from the list of keys on the role.

Supported methods:

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

Parameters
  • name (str | unicode) – The name of an existing gce role. This will return an error if role is not a gce type role.

  • add (list) – The list of key:value labels to add to the GCE role’s bound labels.

  • remove (list) – The list of label keys to remove from the role’s bound labels. If any of the specified keys do not exist, no error is returned (idempotent).

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

Returns

The response of the edit_labels_on_gce_role request.

Return type

requests.Response

edit_service_accounts_on_iam_role(name, add=None, remove=None, mount_point='gcp')[source]

Edit service accounts for an existing IAM role in the GCP auth method.

This allows you to add or remove service accounts from the list of service accounts on the role.

Supported methods:

POST: /auth/{mount_point}/role/{name}/service-accounts. Produces: 204 (empty body)

Parameters
  • name (str | unicode) – The name of an existing iam type role. This will return an error if role is not an iam type role.

  • add (list) – The list of service accounts to add to the role’s service accounts.

  • remove (list) – The list of service accounts to remove from the role’s service accounts.

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

Returns

The response of the request.

Return type

requests.Response

list_roles(mount_point='gcp')[source]

List all the roles that are registered with the plugin.

Supported methods:

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

Parameters

mount_point (str | unicode) – The “path” the method/backend was mounted on.

Returns

The data key from the JSON response of the request.

Return type

dict

login(role, jwt, use_token=True, mount_point='gcp')[source]

Login to retrieve a Vault token via the GCP auth method.

This endpoint takes a signed JSON Web Token (JWT) and a role name for some entity. It verifies the JWT

signature with Google Cloud to authenticate that entity and then authorizes the entity for the given role.

Supported methods:

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

Parameters
  • role (str | unicode) – The name of the role against which the login is being attempted.

  • jwt (str | unicode) – A signed JSON web 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 request.

Return type

dict

read_config(mount_point='gcp')[source]

Read the configuration, if any, including credentials.

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 data key from the JSON response of the request.

Return type

dict

read_role(name, mount_point='gcp')[source]

Read the previously registered role configuration.

Supported methods:

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

Parameters
  • name (str | unicode) – The name of the role to read.

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

Returns

The data key from the JSON response of the read_role request.

Return type

JSON

class hvac.api.auth_methods.Github(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

GitHub Auth Method (API).

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

Methods

configure(organization[, base_url, ttl, …])

Configure the connection parameters for GitHub.

login(token[, use_token, mount_point])

Login using GitHub access token.

map_team(team_name[, policies, mount_point])

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

map_user(user_name[, policies, mount_point])

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

read_configuration([mount_point])

Read the GitHub configuration.

read_team_mapping(team_name[, mount_point])

Read the GitHub team policy mapping.

read_user_mapping(user_name[, mount_point])

Read the GitHub user policy mapping.

configure(organization, base_url=None, ttl=None, max_ttl=None, 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[str]) – 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 (List[str]) – 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_methods.JWT(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

JWT auth method which can be used to authenticate with Vault by providing a JWT.

The OIDC method allows authentication via a configured OIDC provider using the user’s web browser. This method may be initiated from the Vault UI or the command line. Alternatively, a JWT can be provided directly. The JWT is cryptographically verified using locally-provided keys, or, if configured, an OIDC Discovery service can be used to fetch the appropriate keys. The choice of method is configured per role.

Reference: https://www.vaultproject.io/api/auth/jwt

Attributes

DEFAULT_PATH

str(object=’’) -> str

Methods

configure([oidc_discovery_url, …])

Configure the validation information to be used globally across all roles.

create_role(name, user_claim, …[, …])

Register a role in the JWT method.

delete_role(name[, path])

Delete the previously registered role.

jwt_login(role, jwt[, path])

Fetch a token.

list_roles([path])

List all the roles that are registered with the plugin.

oidc_authorization_url_request(role, …[, path])

Obtain an authorization URL from Vault to start an OIDC login flow.

oidc_callback(state, nonce, code[, path])

Exchange an authorization code for an OIDC ID Token.

read_config([path])

Read the previously configured config.

read_role(name[, path])

Read the previously registered role configuration.

resolve_path(path)

Return the class’s default path if no explicit path is specified.

DEFAULT_PATH = 'jwt'
configure(oidc_discovery_url=None, oidc_discovery_ca_pem=None, oidc_client_id=None, oidc_client_secret=None, oidc_response_mode=None, oidc_response_types=None, jwks_url=None, jwks_ca_pem=None, jwt_validation_pubkeys=None, bound_issuer=None, jwt_supported_algs=None, default_role=None, provider_config=None, path=None)[source]

Configure the validation information to be used globally across all roles.

One (and only one) of oidc_discovery_url and jwt_validation_pubkeys must be set.

Supported methods:

POST: /auth/{path}/config.

Parameters
  • oidc_discovery_url (str | unicode) – The OIDC Discovery URL, without any .well-known component (base path). Cannot be used with “jwks_url” or “jwt_validation_pubkeys”.

  • oidc_discovery_ca_pem (str | unicode) – The CA certificate or chain of certificates, in PEM format, to use to validate connections to the OIDC Discovery URL. If not set, system certificates are used.

  • oidc_client_id (str | unicode) – The OAuth Client ID from the provider for OIDC roles.

  • oidc_client_secret (str | unicode) – The OAuth Client Secret from the provider for OIDC roles.

  • oidc_response_mode (str | unicode) – The response mode to be used in the OAuth2 request. Allowed values are “query” and form_post”. Defaults to “query”.

  • oidc_response_types (str | unicode) – The response types to request. Allowed values are “code” and “id_token”. Defaults to “code”. Note: “id_token” may only be used if “oidc_response_mode” is set to “form_post”.

  • jwks_url (str | unicode) – JWKS URL to use to authenticate signatures. Cannot be used with “oidc_discovery_url” or “jwt_validation_pubkeys”.

  • jwks_ca_pem (str | unicode) – The CA certificate or chain of certificates, in PEM format, to use to validate connections to the JWKS URL. If not set, system certificates are used.

  • jwt_validation_pubkeys (str | unicode) – A list of PEM-encoded public keys to use to authenticate signatures locally. Cannot be used with “jwks_url” or “oidc_discovery_url”.

  • bound_issuer (str | unicode) – in a JWT.

  • jwt_supported_algs (str | unicode) – A list of supported signing algorithms. Defaults to [RS256].

  • default_role (str | unicode) – The default role to use if none is provided during login.

  • provider_config (map) – TypeError

  • path (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the configure request.

Return type

requests.Response

create_role(name, user_claim, allowed_redirect_uris, role_type='jwt', bound_audiences=None, clock_skew_leeway=None, expiration_leeway=None, not_before_leeway=None, bound_subject=None, bound_claims=None, groups_claim=None, claim_mappings=None, oidc_scopes=None, bound_claims_type='string', verbose_oidc_logging=False, token_ttl=None, token_max_ttl=None, token_policies=None, token_bound_cidrs=None, token_explicit_max_ttl=None, token_no_default_policy=None, token_num_uses=None, token_period=None, token_type=None, path=None)[source]

Register a role in the JWT method.

Role types have specific entities that can perform login operations against this endpoint. Constraints specific to the role type must be set on the role. These are applied to the authenticated entities attempting to login. At least one of the bound values must be set.

Supported methods:

POST: /auth/{path}/role/:name.

Parameters
  • name (str | unicode) – Name of the role.

  • role_type (str | unicode) – Type of role, either “oidc” or “jwt” (default).

  • bound_audiences (list) – List of aud claims to match against. Any match is sufficient. Required for “jwt” roles, optional for “oidc” roles.

  • user_claim (str | unicode) – The claim to use to uniquely identify the user; this will be used as the name for the Identity entity alias created due to a successful login. The claim value must be a string.

  • clock_skew_leeway (int) – Only applicable with “jwt” roles.

  • expiration_leeway (int) – Only applicable with “jwt” roles.

  • not_before_leeway (int) – Only applicable with “jwt” roles.

  • bound_subject (str | unicode) – If set, requires that the sub claim matches this value.

  • bound_claims (dict) – If set, a dict of claims (keys) to match against respective claim values (values). The expected value may be a single string or a list of strings. The interpretation of the bound claim values is configured with bound_claims_type. Keys support JSON pointer syntax for referencing claims.

  • groups_claim (str | unicode) – The claim to use to uniquely identify the set of groups to which the user belongs; this will be used as the names for the Identity group aliases created due to a successful login. The claim value must be a list of strings. Supports JSON pointer syntax for referencing claims.

  • claim_mappings (map) – If set, a map of claims (keys) to be copied to specified metadata fields (values). Keys support JSON pointer syntax for referencing claims.

  • oidc_scopes (list) – If set, a list of OIDC scopes to be used with an OIDC role. The standard scope “openid” is automatically included and need not be specified.

  • allowed_redirect_uris (list) – The list of allowed values for redirect_uri during OIDC logins.

  • bound_claims_type (str | unicode) – Configures the interpretation of the bound_claims values. If “string” (the default), the values will treated as string literals and must match exactly. If set to “glob”, the values will be interpreted as globs, with * matching any number of characters.

  • verbose_oidc_logging (bool) – Log received OIDC tokens and claims when debug-level logging is active. Not recommended in production since sensitive information may be present in OIDC responses.

  • token_ttl (int | str) – The incremental lifetime for generated tokens. This current value of this will be referenced at renewal time.

  • token_max_ttl (int | str) – The maximum lifetime for generated tokens. This current value of this will be referenced at renewal time.

  • token_policies (list[str]) – List of policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.

  • token_bound_cidrs (list[str]) – List of CIDR blocks; if set, specifies blocks of IP addresses which can authenticate successfully, and ties the resulting token to these blocks as well.

  • token_explicit_max_ttl (int | str) – If set, will encode an explicit max TTL onto the token. This is a hard cap even if token_ttl and token_max_ttl would otherwise allow a renewal.

  • token_no_default_policy (bool) – If set, the default policy will not be set on generated tokens; otherwise it will be added to the policies set in token_policies.

  • token_num_uses (str | unicode) – The maximum number of times a generated token may be used (within its lifetime); 0 means unlimited. If you require the token to have the ability to create child tokens, you will need to set this value to 0.

  • token_period (int | str) – The period, if any, to set on the token.

  • token_type (str) – The type of token that should be generated. Can be service, batch, or default.

  • path (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the create_role request.

Return type

dict

delete_role(name, path=None)[source]

Delete the previously registered role.

Supported methods:

DELETE: /auth/{path}/role/:name.

Parameters
  • name (str | unicode) – Name of the role.

  • path (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the delete_role request.

Return type

requests.Response

jwt_login(role, jwt, path=None)[source]

Fetch a token.

This endpoint takes a signed JSON Web Token (JWT) and a role name for some entity. It verifies the JWT signature to authenticate that entity and then authorizes the entity for the given role.

Supported methods:

POST: /auth/{path}/login.

Parameters
  • role (str | unicode) – not provided.

  • jwt (str | unicode) – Signed JSON Web Token (JWT).

  • path (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the jwt_login request.

Return type

requests.Response

list_roles(path=None)[source]

List all the roles that are registered with the plugin.

Supported methods:

LIST: /auth/{path}/role.

Parameters

path (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the list_roles request.

Return type

dict

oidc_authorization_url_request(role, redirect_uri, path=None)[source]

Obtain an authorization URL from Vault to start an OIDC login flow.

Supported methods:

POST: /auth/{path}/auth_url.

Parameters
  • role (str | unicode) – not provided.

  • redirect_uri (str | unicode) – more information.

  • path (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the _authorization_url_request request.

Return type

requests.Response

oidc_callback(state, nonce, code, path=None)[source]

Exchange an authorization code for an OIDC ID Token.

The ID token will be further validated against any bound claims, and if valid a Vault token will be returned.

Supported methods:

GET: /auth/{path}/callback.

Parameters
  • state (str | unicode) – Opaque state ID that is part of the Authorization URL and will be included in the the redirect following successful authentication on the provider.

  • nonce (str | unicode) – Opaque nonce that is part of the Authorization URL and will be included in the the redirect following successful authentication on the provider.

  • code (str | unicode) – Provider-generated authorization code that Vault will exchange for an ID token.

  • path (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the _callback request.

Return type

requests.Response

read_config(path=None)[source]

Read the previously configured config.

Supported methods:

GET: /auth/{path}/config.

Returns

The response of the read_config request.

Return type

dict

read_role(name, path=None)[source]

Read the previously registered role configuration.

Supported methods:

GET: /auth/{path}/role/:name.

Parameters
  • name (str | unicode) – Name of the role.

  • path (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the read_role request.

Return type

dict

resolve_path(path)[source]

Return the class’s default path if no explicit path is specified.

Parameters

path (str | unicode) – The “path” the method/backend was mounted on.

Returns

The default path for this auth method if no explicit path is specified.

Return type

str

class hvac.api.auth_methods.Kubernetes(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Kubernetes Auth Method (API).

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

Methods

configure(kubernetes_host[, …])

Configure the connection parameters for Kubernetes.

create_role(name, …[, ttl, max_ttl, …])

Create a role in the method.

delete_role(name[, mount_point])

Delete the previously registered role.

list_roles([mount_point])

List all the roles that are registered with the plugin.

login(role, jwt[, use_token, mount_point])

Fetch a token.

read_config([mount_point])

Return the previously configured config, including credentials.

read_role(name[, mount_point])

Returns the previously registered role configuration.

configure(kubernetes_host, kubernetes_ca_cert=None, token_reviewer_jwt=None, pem_keys=None, issuer=None, mount_point='kubernetes')[source]

Configure the connection parameters for Kubernetes.

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
  • kubernetes_host (str | unicode) – Host must be a host string, a host:port pair, or a URL to the base of the Kubernetes API server. Example: https://k8s.example.com:443

  • kubernetes_ca_cert (str | unicode) – PEM encoded CA cert for use by the TLS client used to talk with the Kubernetes API. NOTE: Every line must end with a newline:

  • token_reviewer_jwt (str | unicode) – A service account JWT used to access the TokenReview API to validate other JWTs during login. If not set the JWT used for login will be used to access the API.

  • pem_keys (list) – Optional list of PEM-formatted public keys or certificates used to verify the signatures of Kubernetes service account JWTs. If a certificate is given, its public key will be extracted. Not every installation of Kubernetes exposes these keys.

  • issuer – Optional JWT issuer.

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

Returns

The response of the configure_method request.

Return type

requests.Response

create_role(name, bound_service_account_names, bound_service_account_namespaces, ttl=None, max_ttl=None, period=None, policies=None, mount_point='kubernetes')[source]

Create a role in the method.

Registers a role in the auth method. Role types have specific entities that can perform login operations against this endpoint. Constraints specific to the role type must be set on the role. These are applied to the authenticated entities attempting to login.

Supported methods:

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

Parameters
  • name (str | unicode) – Name of the role.

  • bound_service_account_names (list | str | unicode) – List of service account names able to access this role. If set to “*” all names are allowed.

  • bound_service_account_namespaces (list | str | unicode) – List of namespaces allowed to access this role. If set to “*” all namespaces are allowed.

  • ttl (str | unicode) – The TTL period of tokens issued using this role in seconds.

  • max_ttl (str | unicode) – The maximum allowed lifetime of tokens issued in seconds using this role.

  • period (str | unicode) – If set, indicates that the token generated using this role should never expire. The token should be renewed within the duration specified by this value. At each renewal, the token’s TTL will be set to the value of this parameter.

  • policies (list | str | unicode) – Policies to be set on tokens issued using this role.

  • mount_point (str | unicode) – The “path” the azure auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

delete_role(name, mount_point='kubernetes')[source]

Delete the previously registered role.

Supported methods:

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

Parameters
  • name (str | unicode) – Name of the role.

  • mount_point (str | unicode) – The “path” the kubernetes auth method was mounted on.

Returns

The response of the request.

Return type

requests.Response

list_roles(mount_point='kubernetes')[source]

List all the roles that are registered with the plugin.

Supported methods:

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

Parameters

mount_point (str | unicode) – The “path” the kubernetes auth method was mounted on.

Returns

The “data” key from the JSON response of the request.

Return type

dict

login(role, jwt, use_token=True, mount_point='kubernetes')[source]

Fetch a token.

This endpoint takes a signed JSON Web Token (JWT) and a role name for some entity. It verifies the JWT signature to authenticate that entity and then authorizes the entity for the given role.

Supported methods:

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

Parameters
  • role (str | unicode) – Name of the role against which the login is being attempted.

  • jwt (str | unicode) – Signed JSON Web Token (JWT) from Azure MSI.

  • 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 azure auth method was mounted on.

Returns

The JSON response of the request.

Return type

dict

read_config(mount_point='kubernetes')[source]

Return the previously configured config, including credentials.

Supported methods:

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

Parameters

mount_point (str | unicode) – The “path” the kubernetes auth method was mounted on.

Returns

The data key from the JSON response of the request.

Return type

dict

read_role(name, mount_point='kubernetes')[source]

Returns the previously registered role configuration.

Supported methods:

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

Parameters
  • name (str | unicode) – Name of the role.

  • mount_point (str | unicode) – The “path” the kubernetes auth method was mounted on.

Returns

The “data” key from the JSON response of the request.

Return type

dict

class hvac.api.auth_methods.Ldap(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

LDAP Auth Method (API).

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

Methods

configure([user_dn, group_dn, url, …])

Configure the LDAP auth method.

create_or_update_group(name[, policies, …])

Create or update LDAP group policies.

create_or_update_user(username[, policies, …])

Create or update LDAP users policies and group associations.

delete_group(name[, mount_point])

Delete a LDAP group and policy association.

delete_user(username[, mount_point])

Delete a LDAP user and policy association.

list_groups([mount_point])

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

list_users([mount_point])

List existing users in the method.

login(username, password[, use_token, …])

Log in with LDAP credentials.

read_configuration([mount_point])

Retrieve the LDAP configuration for the auth method.

read_group(name[, mount_point])

Read policies associated with a LDAP group.

read_user(username[, mount_point])

Read policies associated with a LDAP user.

configure(user_dn=None, group_dn=None, url=None, case_sensitive_names=None, starttls=None, tls_min_version=None, tls_max_version=None, insecure_tls=None, certificate=None, bind_dn=None, bind_pass=None, user_attr=None, discover_dn=None, deny_null_bind=True, upn_domain=None, group_filter=None, group_attr=None, use_token_groups=None, 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.

  • use_token_groups (bool) – If true, groups are resolved through Active Directory tokens. This may speed up nested group membership resolution in large directories.

  • 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_methods.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.

Methods

configure(mount_point[, mfa_type, force])

Configure MFA for a supported method.

configure_duo_access(mount_point, host, …)

Configure the access keys and host for Duo API connections.

configure_duo_behavior(mount_point[, …])

Configure Duo second factor behavior.

read_configuration(mount_point)

Read the MFA configuration.

read_duo_behavior_configuration(mount_point)

Read the Duo second factor behavior configuration.

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

class hvac.api.auth_methods.OIDC(adapter)[source]

Bases: hvac.api.auth_methods.jwt.JWT

OIDC auth method which can be used to authenticate with Vault using OIDC.

The OIDC method allows authentication via a configured OIDC provider using the user’s web browser. This method may be initiated from the Vault UI or the command line. Alternatively, a JWT can be provided directly. The JWT is cryptographically verified using locally-provided keys, or, if configured, an OIDC Discovery service can be used to fetch the appropriate keys. The choice of method is configured per role.

Note: this class is duplicative of the JWT class (as both JWT and OIDC share the same family of Vault API routes).

Reference: https://www.vaultproject.io/api/auth/jwt

Attributes

DEFAULT_PATH

str(object=’’) -> str

Methods

create_role(name, user_claim, …[, …])

Register a role in the OIDC method.

DEFAULT_PATH = 'oidc'
create_role(name, user_claim, allowed_redirect_uris, role_type='oidc', bound_audiences=None, clock_skew_leeway=None, expiration_leeway=None, not_before_leeway=None, bound_subject=None, bound_claims=None, groups_claim=None, claim_mappings=None, oidc_scopes=None, bound_claims_type='string', verbose_oidc_logging=False, token_ttl=None, token_max_ttl=None, token_policies=None, token_bound_cidrs=None, token_explicit_max_ttl=None, token_no_default_policy=None, token_num_uses=None, token_period=None, token_type=None, path=None)[source]

Register a role in the OIDC method.

Role types have specific entities that can perform login operations against this endpoint. Constraints specific to the role type must be set on the role. These are applied to the authenticated entities attempting to login. At least one of the bound values must be set.

Supported methods:

POST: /auth/{path}/role/:name.

Parameters
  • name (str | unicode) – Name of the role.

  • role_type (str | unicode) – Type of role, either “oidc” or “jwt” (default).

  • bound_audiences (list) – List of aud claims to match against. Any match is sufficient. Required for “jwt” roles, optional for “oidc” roles.

  • user_claim (str | unicode) – The claim to use to uniquely identify the user; this will be used as the name for the Identity entity alias created due to a successful login. The claim value must be a string.

  • clock_skew_leeway (int) – Only applicable with “jwt” roles.

  • expiration_leeway (int) – Only applicable with “jwt” roles.

  • not_before_leeway (int) – Only applicable with “jwt” roles.

  • bound_subject (str | unicode) – If set, requires that the sub claim matches this value.

  • bound_claims (dict) – If set, a dict of claims (keys) to match against respective claim values (values). The expected value may be a single string or a list of strings. The interpretation of the bound claim values is configured with bound_claims_type. Keys support JSON pointer syntax for referencing claims.

  • groups_claim (str | unicode) – The claim to use to uniquely identify the set of groups to which the user belongs; this will be used as the names for the Identity group aliases created due to a successful login. The claim value must be a list of strings. Supports JSON pointer syntax for referencing claims.

  • claim_mappings (map) – If set, a map of claims (keys) to be copied to specified metadata fields (values). Keys support JSON pointer syntax for referencing claims.

  • oidc_scopes (list) – If set, a list of OIDC scopes to be used with an OIDC role. The standard scope “openid” is automatically included and need not be specified.

  • allowed_redirect_uris (list) – The list of allowed values for redirect_uri during OIDC logins.

  • bound_claims_type (str | unicode) – Configures the interpretation of the bound_claims values. If “string” (the default), the values will treated as string literals and must match exactly. If set to “glob”, the values will be interpreted as globs, with * matching any number of characters.

  • verbose_oidc_logging (bool) – Log received OIDC tokens and claims when debug-level logging is active. Not recommended in production since sensitive information may be present in OIDC responses.

  • token_ttl (int | str) – The incremental lifetime for generated tokens. This current value of this will be referenced at renewal time.

  • token_max_ttl (int | str) – The maximum lifetime for generated tokens. This current value of this will be referenced at renewal time.

  • token_policies (list[str]) – List of policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.

  • token_bound_cidrs (list[str]) – List of CIDR blocks; if set, specifies blocks of IP addresses which can authenticate successfully, and ties the resulting token to these blocks as well.

  • token_explicit_max_ttl (int | str) – If set, will encode an explicit max TTL onto the token. This is a hard cap even if token_ttl and token_max_ttl would otherwise allow a renewal.

  • token_no_default_policy (bool) – If set, the default policy will not be set on generated tokens; otherwise it will be added to the policies set in token_policies.

  • token_num_uses (str | unicode) – The maximum number of times a generated token may be used (within its lifetime); 0 means unlimited. If you require the token to have the ability to create child tokens, you will need to set this value to 0.

  • token_period (int | str) – The period, if any, to set on the token.

  • token_type (str) – The type of token that should be generated. Can be service, batch, or default.

  • path (str | unicode) – The “path” the method/backend was mounted on.

Returns

The response of the create_role request.

Return type

dict

class hvac.api.auth_methods.Okta(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

Okta Auth Method (API).

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

Methods

configure(org_name[, api_token, base_url, …])

Configure the connection parameters for Okta.

delete_group(name[, mount_point])

Delete an existing group from the method.

delete_user(username[, mount_point])

Delete an existing username from the method.

list_groups([mount_point])

List the groups configured in the Okta method.

list_users([mount_point])

List the users configured in the Okta method.

login(username, password[, use_token, …])

Login with the username and password.

read_config([mount_point])

Read the Okta configuration.

read_group(name[, mount_point])

Read the properties of an existing group.

read_user(username[, mount_point])

Read the properties of an existing username.

register_group(name[, policies, mount_point])

Register a new group and maps a set of policies to it.

register_user(username[, groups, policies, …])

Register a new user and maps a set of policies to it.

configure(org_name, api_token=None, base_url=None, ttl=None, max_ttl=None, bypass_okta_mfa=None, mount_point='okta')[source]

Configure the connection parameters for Okta.

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
  • org_name (str | unicode) – Name of the organization to be used in the Okta API.

  • api_token (str | unicode) – Okta API token. This is required to query Okta for user group membership. If this is not supplied only locally configured groups will be enabled.

  • base_url (str | unicode) – If set, will be used as the base domain for API requests. Examples are okta.com, oktapreview.com, and okta-emea.com.

  • ttl (str | unicode) – Duration after which authentication will be expired.

  • max_ttl (str | unicode) – Maximum duration after which authentication will be expired.

  • bypass_okta_mfa (bool) – Whether to bypass an Okta MFA request. Useful if using one of Vault’s built-in MFA mechanisms, but this will also cause certain other statuses to be ignored, such as PASSWORD_EXPIRED.

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

Returns

The response of the request.

Return type

requests.Response

delete_group(name, mount_point='okta')[source]

Delete an existing group from the method.

Supported methods:

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

Parameters
  • name (str | unicode) – The name for the group.

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

Returns

The response of the request.

Return type

requests.Response

delete_user(username, mount_point='okta')[source]

Delete an existing username from the method.

Supported methods:

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

Parameters
  • username (str | unicode) – Username for this user.

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

Returns

The response of the request.

Return type

requests.Response

list_groups(mount_point='okta')[source]

List the groups configured in the Okta 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 request.

Return type

dict

list_users(mount_point='okta')[source]

List the users configured in the Okta 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 request.

Return type

dict

login(username, password, use_token=True, mount_point='okta')[source]

Login with the username and password.

Supported methods:

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

Parameters
  • username (str | unicode) – Username for this user.

  • password (str | unicode) – Password for the authenticating 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 request.

Return type

dict

read_config(mount_point='okta')[source]

Read the Okta 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 request.

Return type

dict

read_group(name, mount_point='okta')[source]

Read the properties of an existing group.

Supported methods:

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

Parameters
  • name (str | unicode) – The name for the group.

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

Returns

The JSON response of the request.

Return type

dict

read_user(username, mount_point='okta')[source]

Read the properties of an existing username.

Supported methods:

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

Parameters
  • username (str | unicode) – Username for this user.

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

Returns

The JSON response of the request.

Return type

dict

register_group(name, policies=None, mount_point='okta')[source]

Register a new group and maps a set of policies to it.

Supported methods:

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

Parameters
  • name (str | unicode) – The name of the group.

  • policies (list) – The list or comma-separated string of policies associated with the group.

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

Returns

The response of the request.

Return type

requests.Response

register_user(username, groups=None, policies=None, mount_point='okta')[source]

Register a new user and maps a set of policies to it.

Supported methods:

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

Parameters
  • username (str | unicode) – Name of the user.

  • groups (list) – List or comma-separated string of groups associated with the user.

  • policies (list) – List or comma-separated string of policies associated with the user.

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

Returns

The response of the request.

Return type

requests.Response

class hvac.api.auth_methods.Radius(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

RADIUS Auth Method (API).

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

Methods

configure(host, secret[, port, …])

Configure the RADIUS auth method.

delete_user(username[, mount_point])

Delete a RADIUS user and policy association.

list_users([mount_point])

List existing users in the method.

login(username, password[, use_token, …])

Log in with RADIUS credentials.

read_configuration([mount_point])

Retrieve the RADIUS configuration for the auth method.

read_user(username[, mount_point])

Read policies associated with a RADIUS user.

register_user(username[, policies, mount_point])

Create or update RADIUS user with a set of policies.

configure(host, secret, port=None, unregistered_user_policies=None, dial_timeout=None, nas_port=None, mount_point='radius')[source]

Configure the RADIUS auth method.

Supported methods:

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

Parameters
  • host (str | unicode) – The RADIUS server to connect to. Examples: radius.myorg.com, 127.0.0.1

  • secret (str | unicode) – The RADIUS shared secret.

  • port (int) – The UDP port where the RADIUS server is listening on. Defaults is 1812.

  • unregistered_user_policies (list) – A comma-separated list of policies to be granted to unregistered users.

  • dial_timeout (int) – Number of second to wait for a backend connection before timing out. Default is 10.

  • nas_port (int) – The NAS-Port attribute of the RADIUS request. Defaults is 10.

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

Returns

The response of the configure request.

Return type

requests.Response

delete_user(username, mount_point='radius')[source]

Delete a RADIUS user and policy association.

Supported methods:

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

Parameters
  • username (str | unicode) – The username of the RADIUS 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_users(mount_point='radius')[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='radius')[source]

Log in with RADIUS credentials.

Supported methods:

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

Parameters
  • username (str | unicode) – The username of the RADIUS user

  • password (str | unicode) – The password for the RADIUS 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='radius')[source]

Retrieve the RADIUS 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_user(username, mount_point='radius')[source]

Read policies associated with a RADIUS user.

Supported methods:

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

Parameters
  • username (str | unicode) – The username of the RADIUS 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

register_user(username, policies=None, mount_point='radius')[source]

Create or update RADIUS user with a set of policies.

Supported methods:

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

Parameters
  • username (str | unicode) – Username for this RADIUS user.

  • policies (list) – List of policies 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 register_user request.

Return type

requests.Response

class hvac.api.auth_methods.Userpass(adapter)[source]

Bases: hvac.api.vault_api_base.VaultApiBase

USERPASS Auth Method (API). Reference: https://www.vaultproject.io/api/auth/userpass/index.html

Methods

create_or_update_user(username, password[, …])

Create/update user in userpass.

delete_user(username[, mount_point])

Delete user in the auth method.

list_user([mount_point])

List existing users that have been created in the auth method

login(username, password[, mount_point])

Log in with USERPASS credentials.

read_user(username[, mount_point])

Read user in the auth method.

update_password_on_user(username, password)

update password for the user in userpass.

create_or_update_user(username, password, policies=None, mount_point='userpass')[source]

Create/update user in userpass.

Supported methods:

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

Parameters
  • username (str | unicode) – The username for the user.

  • password (str | unicode) – The password for the user. Only required when creating the user.

  • policies (str | unicode) – The list of policies to be set on username created.

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

delete_user(username, mount_point='userpass')[source]

Delete user in the auth method.

Supported methods:

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

Parameters
  • username – The username for the user.

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

Returns

The JSON response of the read_group request.

Return type

dict

list_user(mount_point='userpass')[source]

List existing users that have been created in the auth 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_groups request.

Return type

dict

login(username, password, mount_point='userpass')[source]

Log in with USERPASS credentials.

Supported methods:

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

Parameters
  • username (str | unicode) – The username for the user.

  • password (str | unicode) – The password for the user. Only required when creating the user.

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

read_user(username, mount_point='userpass')[source]

Read user in the auth method.

Supported methods:

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

Parameters
  • username – The username for the user.

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

Returns

The JSON response of the read_group request.

Return type

dict

update_password_on_user(username, password, mount_point='userpass')[source]

update password for the user in userpass.

Supported methods:

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

Parameters
  • username (str | unicode) – The username for the user.

  • password (str | unicode) – The password for the user. Only required when creating the user.

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