Auth¶

Auth backends are the components in Vault that perform authentication and are responsible for assigning identity and a set of policies to a user.

Having multiple auth backends enables you to use an auth backend that makes the sense for your use case of Vault and your organization.

API¶

Enabling and configuring app-id backend:

APP = 'foo'
USER = 'bar'
POLICIES = ['dummy']

backend = yield from client.auth.enable('app-id')
yield from backend.write_app(APP, policies=POLICIES)
yield from backend.write_user(USER, app=APP)

Login with app-id:

token = yield from client.login('app-id', app=APP, user=BAR)

Enabling and configuring cert backend:

NAME = 'foo'
CSR_CERT = open('client.csr').read()
POLICIES = ['dummy']

backend = yield from client.auth.enable('cert')
yield from backend.write_cert(NAME,
                              certificate=CSR_CERT,
                              policies=POLICIES)

Login with cert:

token = yield from client.login('cert')

Enabling and configuring github backend:

ORGANIZATION = 'foo'
TEAM = 'bar'

backend = yield from client.auth.enable('github')
yield from backend.configure(organization=ORGANIZATION)
yield from backend.write_team(TEAM, policies=POLICIES)

Login with github:

GITHUB_TOKEN = '1234567890'

token = yield from client.login('github', github_token=GITHUB_TOKEN)

Enabling and configuring ldap backend:

LDAP_URL = 'ldap://ldap.forumsys.com'
USER_ATTR = 'uid'
USER_DN = 'dc=example,dc=com'
GROUP_DN = 'dc=example,dc=com'
GROUP_NAME = 'scientists'
POLICIES = ['foo']

backend = yield from client.auth.enable('ldap')
yield from backend.configure(url=LDAP_URL,
                             userattr=USER_ATTR,
                             userdn=USER_DN,
                             groupdn=GROUP_DN)
yield from backend.write_group(name=GROUP_NAME, policies=POLICIES)

Login with ldap:

USER = 'tesla'
PASSWORD = 'password'

token = yield from client.login('ldap',
                                username=USER,
                                password=PASSWORD)

Enabling and configuring userpass backend:

USER = 'mitchellh'
PASSWORD = 'foo'

backend = yield from client.auth.enable('userpass')
yield from backend.create('mitchellh', 'foo')

Login with userpass:

token = yield from client.auth.login('userpass',
                                     username=USER,
                                     password=PASSWORD)

Internals¶

class AuthEndpoint(req_handler)¶

task items()¶

Lists all the enabled auth backends

Returns:	AuthCollection

load(name, *, type=None)¶

Returns auth backend

Parameters:	name (str) – The auth backend name
Returns:	AuthBackend

task login(name, *, type=None, **credentials)¶

Login

Parameters:	name (str) – The name of mount type (str) – The name of the auth backend type, such as `github` credentials (str) – Login credentials
Returns:	AuthBackend

task enable(name, *, type=None, description=None)¶

Enable and load a new auth backend

Parameters:	name (str) – The name of mount type (str) – The name of the auth backend type, such as `github` description (str) – A human-friendly description of the auth backend
Returns:	AuthBackend

task disable(name)¶

Disable the auth backend at the given mount point

Parameters:	name (str) – The name of mount

task create(*, id=None, policies=None, metadata=None, no_parent=None, lease=None, display_name=None, num_uses=None)¶

Creates a new token.

Certain options are only available to when called by a root token.

Parameters:

id (str) – The ID of the client token. Can only be specified by a root token. Otherwise, the token ID is a randomly generated UUID.
policies (list) – A list of policies for the token. This must be a subset of the policies belonging to the token making the request, unless root. If not specified, defaults to all the policies of the calling token.
metadata (dict) – A map of string to string valued metadata. This is passed through to the audit backends.
no_parent (bool) – If true and set by a root caller, the token will not have the parent token of the caller. This creates a token with no parent.
lease (str) – The lease period of the token, provided as “1h”, where hour is the largest suffix. If not provided, the token is valid indefinitely.
display_name (str) – The display name of the token. Defaults to “token”.
num_uses (int) – The maximum uses for the given token. This can be used to create a one-time-token or limited use token. Defaults to no limit.

Returns:

LoginToken – The client token

task lookup_self()¶

Returns information about the current client token.

Returns:	ReadToken – The current client token

task lookup(token)¶

Returns information about a client token.

Parameters:	token (str) – The token ID
Returns:	ReadToken – The client token

task revoke(token)¶

Revokes a token and all child tokens.

When the token is revoked, all secrets generated with it are also revoked.

Parameters:	token (str) – The token ID

task revoke_orphan(token)¶

Revokes a token but not its child tokens.

When the token is revoked, all secrets generated with it are also revoked. All child tokens are orphaned, but can be revoked sub-sequently using revoke().

Parameters:	token (str) – The token ID

task revoke_prefix(prefix)¶

Revokes all tokens generated at a given prefix, along with child tokens, and all secrets generated using those tokens. Uses include revoking all tokens generated by a credential backend during a suspected compromise.

Parameters:	token (str) – The token ID

task renew(token, increment=None)¶

Renews a lease associated with a token.

This is used to prevent the expiration of a token, and the automatic revocation of it.

Parameters:	token (str) – The token ID increment (int) – An optional requested lease increment can be provided. This increment may be ignored.
Returns:	LoginToken – The client token

Backends¶

class AppIDBackend(name, type, req_handler)¶

task login(*, app, user)¶

Returns information about the current client token.

Parameters:	app (str) – The application ID user (str) – The user name
Returns:	LoginToken – The client token

task read_app(app)¶

Read app.

Parameters:	app (str) – The application ID
Returns:	Value

task write_app(app, *, policies=None, display_name=None)¶

Write app.

Parameters:	app (str) – The application ID policies (list) – The policies display_name (str) – The name to be displayed
Returns:	bool

task delete_app(app)¶

Delete app.

Parameters:	app (str) – The application ID
Returns:	bool

task read_user(user)¶

Read user.

Parameters:	user (str) – The user name
Returns:	Value

task write_user(user, app, cidr_block=None)¶

Write user.

Parameters:	user (str) – The user name app (str) – The application ID cidr_block (str) – The CIDR block to limit
Returns:	bool

task delete_user(user)¶

Delete user.

Parameters:	user (str) – The user name
Returns:	bool

disable()¶

Disable backend

Returns:	bool

enable(description=None)¶

Enable backend

Parameters:	description (str) – A human-friendly description of the auth backend
Returns:	bool

class CertBackend(name, type, req_handler)¶

Manage trusted certificates used for authentication.

This endpoint allows you to create, read, update, and delete trusted certificates that are allowed to authenticate.

Deleting a certificate will not revoke auth for prior authenticated connections. To do this, do a revoke on “login”. If you don’t need to revoke login immediately, then the next renew will cause the lease to expire.

task login()¶

Returns:	LoginToken

task write_cert(name, *, certificate, display_name=None, policies=None, lease=None)¶

Write certificate

Parameters:	name (str) – The name of the certificate certificate (str) – The public certificate that should be trusted. Must be x509 PEM encoded display_name (str) – The display name to use for clients using this certificate policies (list) – The policies lease (str) – Lease time in seconds. Defaults to 1 hour

task read_cert(name)¶

Read certificate

Parameters:	name (str) – The name of the certificate

task delete_cert(name)¶

Delete certificate

Parameters:	name (str) – The name of the certificate

disable()¶

Disable backend

Returns:	bool

enable(description=None)¶

Enable backend

Parameters:	description (str) – A human-friendly description of the auth backend
Returns:	bool

class GitHubBackend(name, type, req_handler)¶

task login(*, github_token)¶

Log with github.

Parameters:	github_token (str) – GitHub personal API token
Returns:	LoginToken

task configure(*, organization)¶

Configure github organization.

Parameters:	organization (str) – The organization name a user must be a part of to authenticate
Returns:	bool

task write_team(name, policies)¶

Configure github team.

Parameters:	name (str) – The team name policies (list) – The team policies
Returns:	bool

disable()¶

Disable backend

Returns:	bool

enable(description=None)¶

Enable backend

Parameters:	description (str) – A human-friendly description of the auth backend
Returns:	bool

class LDAPBackend(name, type, req_handler)¶

task login(*, username, password)¶

Log with ldap.

Parameters:	username (str) – DN (distinguished name) to be used for login password (str) – Password for this user
Returns:	LoginToken

task configure(url, userattr, userdn, groupdn)¶

Configure the LDAP server to connect to.

This endpoint allows you to configure the LDAP server to connect to, and give basic information of the schema of that server.

The LDAP URL can use either the “ldap://” or “ldaps://” schema. In the former case, an unencrypted connection will be done, with default port 389; in the latter case, a SSL connection will be done, with default port 636.

Parameters:	url (str) – ldap URL to connect to (default: ldap://127.0.0.1) userattr (str) – Attribute used for users (default: cn) userdn (str) – LDAP domain to use for users (eg: ou=People,dc=example,dc=org) groupdn (str) – LDAP domain to use for groups (eg: ou=Groups,dc=example,dc=org)
Returns:	bool

task read_group(name)¶

Show group.

Parameters:	name (str) – Name of the LDAP group
Returns:	Value

task write_group(name, policies)¶

Manage users allowed to authenticate.

This endpoint allows you to set configuration for a LDAP group that is allowed to authenticate, and associate policies to them.

Parameters:	name (str) – Name of the LDAP group policies (list) – Comma-separated list of policies associated to the group
Returns:	bool

task delete_group(name)¶

Delete group.

Deleting group will not revoke auth for prior authenticated users in that group. To do this, do a revoke on “login/<username>” for the usernames you want revoked.

Parameters:	name (str) – Name of the LDAP group
Returns:	bool

disable()¶

Disable backend

Returns:	bool

enable(description=None)¶

Enable backend

Parameters:	description (str) – A human-friendly description of the auth backend
Returns:	bool

class UserPassBackend(name, type, req_handler)¶

Log in with a username and password.

The “userpass” credential provider allows authentication using a combination of a username and password. No additional factors are supported.

The username/password combination is configured using the “users/” endpoints by a user with root access. Authentication is then done by suppying the two fields for “login”.

task login(*, username, password)¶

Returns information about the current client token.

Parameters:	username (str) – The username password (str) – The password
Returns:	LoginToken

task create(username, password, policies=None)¶

The above creates a new user.

Parameters:	username (str) – The username password (str) – The password policies (list) – The policies associated with the user

disable()¶

Disable backend

Returns:	bool

enable(description=None)¶

Enable backend

Parameters:	description (str) – A human-friendly description of the auth backend
Returns:	bool

Objects¶

class LoginToken(*, auth, data, lease_duration, lease_id, renewable)¶

Vault response is like this one:

{
  "auth": {
    "client_token": "95aeacef-5e5a-e436-96f7-4c9a9837f36a",
    "lease_duration": 0,
    "metadata": null,
    "policies": ["root"],
    "renewable": false
  },
  "data": null,
  "lease_duration": 0,
  "lease_id": "",
  "renewable": false
}

id¶: Returns token id

class ReadToken(*, auth, renewable, data, lease_duration, lease_id)¶

Vault response is like this one:

{
  "auth": null,
  "data": {
    "display_name": "token",
    "id": "95aeacef-5e5a-e436-96f7-4c9a9837f36a",
    "meta": null,
    "num_uses": 0,
    "path": "auth/token/create",
    "policies": ["root"]
  },
  "lease_duration": 0,
  "lease_id": "",
  "renewable": false
}

id¶: Returns token id

Auth¶

API¶

Internals¶

Backends¶

Objects¶

AIO Vault

Navigation