luxolus
/
open-vault
2
0
Fork 0
Code Issues 1 Pull Requests Releases Activity

Standardize on "auth method" 

This removes all references I could find to:

- credential provider
- authentication backend
- authentication provider
- auth provider
- auth backend

in favor of the unified:

- auth method
This commit is contained in:
Seth Vargo 2017-09-12 21:48:52 -04:00
parent 3bbeace911
commit c5665920f6
No known key found for this signature in database
GPG Key ID: C921994F9C27E0FF
94 changed files with 1840 additions and 2507 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
CHANGELOG.md
View File

@ -64,14 +64,14 @@ IMPROVEMENTS:
(PID) in a file [GH-3321]
* mfa (Enterprise): Add the ability to use identity metadata in username format
* mfa/okta (Enterprise): Add support for configuring base_url for API calls
* secret/pki: `sign-intermediate` will now allow specifying a `ttl` value
* secret/pki: `sign-intermediate` will now allow specifying a `ttl` value
longer than the signing CA certificate's NotAfter value. [GH-3325]
* sys/raw: Raw storage access is now disabled by default [GH-3329]
BUG FIXES:
* auth/okta: Fix regression that removed the ability to set base_url [GH-3313]
* core: Fix panic while loading leases at startup on ARM processors
* core: Fix panic while loading leases at startup on ARM processors
[GH-3314]
* secret/pki: Fix `sign-self-issued` encoding the wrong subject public key
[GH-3325]
@ -121,7 +121,7 @@ IMPROVEMENTS:
* auth/okta: Compare groups case-insensitively since Okta is only
case-preserving [GH-3240]
* auth/okta: Standardize Okta configuration APIs across backends [GH-3245]
* cli: Add subcommand autocompletion that can be enabled with
* cli: Add subcommand autocompletion that can be enabled with
`vault -autocomplete-install` [GH-3223]
* cli: Add ability to handle wrapped responses when using `vault auth`. What
is output depends on the other given flags; see the help output for that

4
README.md
View File

@ -100,9 +100,9 @@ $ make test TEST=./vault
### Acceptance Tests
Vault has comprehensive [acceptance tests](https://en.wikipedia.org/wiki/Acceptance_testing)
covering most of the features of the secret and auth backends.
covering most of the features of the secret and auth methods.
If you're working on a feature of a secret or auth backend and want to
If you're working on a feature of a secret or auth method and want to
verify it is functioning (and also hasn't broken anything else), we recommend
running the acceptance tests.

611
api/SPEC.md
View File

@ -1,611 +0,0 @@
FORMAT: 1A
# vault
The Vault API gives you full access to the Vault project.
If you're browsing this API specifiction in GitHub or in raw
format, please excuse some of the odd formatting. This document
is in api-blueprint format that is read by viewers such as
Apiary.
## Sealed vs. Unsealed
Whenever an individual Vault server is started, it is started
in the _sealed_ state. In this state, it knows where its data
is located, but the data is encrypted and Vault doesn't have the
encryption keys to access it. Before Vault can operate, it must
be _unsealed_.
**Note:** Sealing/unsealing has no relationship to _authentication_
which is separate and still required once the Vault is unsealed.
Instead of being sealed with a single key, we utilize
[Shamir's Secret Sharing](http://en.wikipedia.org/wiki/Shamir%27s_Secret_Sharing)
to shard a key into _n_ parts such that _t_ parts are required
to reconstruct the original key, where `t <= n`. This means that
Vault itself doesn't know the original key, and no single person
has the original key (unless `n = 1`, or `t` parts are given to
a single person).
Unsealing is done via an unauthenticated
[unseal API](#reference/seal/unseal/unseal). This API takes a single
master shard and progresses the unsealing process. Once all shards
are given, the Vault is either unsealed or resets the unsealing
process if the key was invalid.
The entire seal/unseal state is server-wide. This allows multiple
distinct operators to use the unseal API (or more likely the
`vault unseal` command) from separate computers/networks and never
have to transmit their key in order to unseal the vault in a
distributed fashion.
## Transport
The API is expected to be accessed over a TLS connection at
all times, with a valid certificate that is verified by a well
behaved client.
## Authentication
Once the Vault is unsealed, every other operation requires
authentication. There are multiple methods for authentication
that can be enabled (see
[authentication](#reference/authentication)).
Authentication is done with the login endpoint. The login endpoint
returns an access token that is set as the `X-Vault-Token` header.
## Help
To retrieve the help for any API within Vault, including mounted
backends, credential providers, etc. then append `?help=1` to any
URL. If you have valid permission to access the path, then the help text
will be returned with the following structure:
{
"help": "help text"
}
## Error Response
A common JSON structure is always returned to return errors:
{
"errors": [
"message",
"another message"
]
}
This structure will be sent down for any non-20x HTTP status.
## HTTP Status Codes
The following HTTP status codes are used throughout the API.
- `200` - Success with data.
- `204` - Success, no data returned.
- `400` - Invalid request, missing or invalid data.
- `403` - Forbidden, your authentication details are either
incorrect or you don't have access to this feature.
- `404` - Invalid path. This can both mean that the path truly
doesn't exist or that you don't have permission to view a
specific path. We use 404 in some cases to avoid state leakage.
- `429` - Rate limit exceeded. Try again after waiting some period
of time.
- `500` - Internal server error. An internal error has occurred,
try again later. If the error persists, report a bug.
- `503` - Vault is down for maintenance or is currently sealed.
Try again later.
# Group Initialization
## Initialization [/sys/init]
### Initialization Status [GET]
Returns the status of whether the vault is initialized or not. The
vault doesn't have to be unsealed for this operation.
+ Response 200 (application/json)
{
"initialized": true
}
### Initialize [POST]
Initialize the vault. This is an unauthenticated request to initially
setup a new vault. Although this is unauthenticated, it is still safe:
data cannot be in vault prior to initialization, and any future
authentication will fail if you didn't initialize it yourself.
Additionally, once initialized, a vault cannot be reinitialized.
This API is the only time Vault will ever be aware of your keys, and
the only time the keys will ever be returned in one unit. Care should
be taken to ensure that the output of this request is never logged,
and that the keys are properly distributed.
The response also contains the initial root token that can be used
as authentication in order to initially configure Vault once it is
unsealed. Just as with the unseal keys, this is the only time Vault is
ever aware of this token.
+ Request (application/json)
{
"secret_shares": 5,
"secret_threshold": 3,
}
+ Response 200 (application/json)
{
"keys": ["one", "two", "three"],
"root_token": "foo"
}
# Group Seal/Unseal
## Seal Status [/sys/seal-status]
### Seal Status [GET]
Returns the status of whether the vault is currently
sealed or not, as well as the progress of unsealing.
The response has the following attributes:
- sealed (boolean) - If true, the vault is sealed. Otherwise,
it is unsealed.
- t (int) - The "t" value for the master key, or the number
of shards needed total to unseal the vault.
- n (int) - The "n" value for the master key, or the total
number of shards of the key distributed.
- progress (int) - The number of master key shards that have
been entered so far towards unsealing the vault.
+ Response 200 (application/json)
{
"sealed": true,
"t": 3,
"n": 5,
"progress": 1
}
## Seal [/sys/seal]
### Seal [PUT]
Seal the vault.
Sealing the vault locks Vault from any future operations on any
secrets or system configuration until the vault is once again
unsealed. Internally, sealing throws away the keys to access the
encrypted vault data, so Vault is unable to access the data without
unsealing to get the encryption keys.
+ Response 204
## Unseal [/sys/unseal]
### Unseal [PUT]
Unseal the vault.
Unseal the vault by entering a portion of the master key. The
response object will tell you if the unseal is complete or
only partial.
If the vault is already unsealed, this does nothing. It is
not an error, the return value just says the vault is unsealed.
Due to the architecture of Vault, we cannot validate whether
any portion of the unseal key given is valid until all keys
are inputted, therefore unsealing an already unsealed vault
is still a success even if the input key is invalid.
+ Request (application/json)
{
"key": "value"
}
+ Response 200 (application/json)
{
"sealed": true,
"t": 3,
"n": 5,
"progress": 1
}
# Group Authentication
## List Auth Methods [/sys/auth]
### List all auth methods [GET]
Lists all available authentication methods.
This returns the name of the authentication method as well as
a human-friendly long-form help text for the method that can be
shown to the user as documentation.
+ Response 200 (application/json)
{
"token": {
"type": "token",
"description": "Token authentication"
},
"oauth": {
"type": "oauth",
"description": "OAuth authentication"
}
}
## Single Auth Method [/sys/auth/{id}]
+ Parameters
+ id (required, string) ... The ID of the auth method.
### Enable an auth method [PUT]
Enables an authentication method.
The body of the request depends on the authentication method
being used. Please reference the documentation for the specific
authentication method you're enabling in order to determine what
parameters you must give it.
If an authentication method is already enabled, then this can be
used to change the configuration, including even the type of
the configuration.
+ Request (application/json)
{
"type": "type",
"key": "value",
"key2": "value2"
}
+ Response 204
### Disable an auth method [DELETE]
Disables an authentication method. Previously authenticated sessions
are immediately invalidated.
+ Response 204
# Group Policies
Policies are named permission sets that identities returned by
credential stores are bound to. This separates _authentication_
from _authorization_.
## Policies [/sys/policy]
### List all Policies [GET]
List all the policies.
+ Response 200 (application/json)
{
"policies": ["root"]
}
## Single Policy [/sys/policy/{id}]
+ Parameters
+ id (required, string) ... The name of the policy
### Upsert [PUT]
Create or update a policy with the given ID.
+ Request (application/json)
{
"rules": "HCL"
}
+ Response 204
### Delete [DELETE]
Delete a policy with the given ID. Any identities bound to this
policy will immediately become "deny all" despite already being
authenticated.
+ Response 204
# Group Mounts
Logical backends are mounted at _mount points_, similar to
filesystems. This allows you to mount the "aws" logical backend
at the "aws-us-east" path, so all access is at `/aws-us-east/keys/foo`
for example. This enables multiple logical backends to be enabled.
## Mounts [/sys/mounts]
### List all mounts [GET]
Lists all the active mount points.
+ Response 200 (application/json)
{
"aws": {
"type": "aws",
"description": "AWS"
},
"pg": {
"type": "postgresql",
"description": "PostgreSQL dynamic users"
}
}
## Single Mount [/sys/mounts/{path}]
### New Mount [POST]
Mount a logical backend to a new path.
Configuration for this new backend is done via the normal
read/write mechanism once it is mounted.
+ Request (application/json)
{
"type": "aws",
"description": "EU AWS tokens"
}
+ Response 204
### Unmount [DELETE]
Unmount a mount point.
+ Response 204
## Remount [/sys/remount]
### Remount [POST]
Move an already-mounted backend to a new path.
+ Request (application/json)
{
"from": "aws",
"to": "aws-east"
}
+ Response 204
# Group Audit Backends
Audit backends are responsible for shuttling the audit logs that
Vault generates to a durable system for future querying. By default,
audit logs are not stored anywhere.
## Audit Backends [/sys/audit]
### List Enabled Audit Backends [GET]
List all the enabled audit backends
+ Response 200 (application/json)
{
"file": {
"type": "file",
"description": "Send audit logs to a file",
"options": {}
}
}
## Single Audit Backend [/sys/audit/{path}]
+ Parameters
+ path (required, string) ... The path where the audit backend is mounted
### Enable [PUT]
Enable an audit backend.
+ Request (application/json)
{
"type": "file",
"description": "send to a file",
"options": {
"path": "/var/log/vault.audit.log"
}
}
+ Response 204
### Disable [DELETE]
Disable an audit backend.
+ Request (application/json)
+ Response 204
# Group Secrets
## Generic [/{mount}/{path}]
This group documents the general format of reading and writing
to Vault. The exact structure of the keyspace is defined by the
logical backends in use, so documentation related to
a specific backend should be referenced for details on what keys
and routes are expected.
The path for examples are `/prefix/path`, but in practice
these will be defined by the backends that are mounted. For
example, reading an AWS key might be at the `/aws/root` path.
These paths are defined by the logical backends.
+ Parameters
+ mount (required, string) ... The mount point for the
logical backend. Example: `aws`.
+ path (optional, string) ... The path within the backend
to read or write data.
### Read [GET]
Read data from vault.
The data read from the vault can either be a secret or
arbitrary configuration data. The type of data returned
depends on the path, and is defined by the logical backend.
If the return value is a secret, then the return structure
is a mixture of arbitrary key/value along with the following
fields which are guaranteed to exist:
- `lease_id` (string) - A unique ID used for renewal and
revocation.
- `renewable` (bool) - If true, then this key can be renewed.
If a key can't be renewed, then a new key must be requested
after the lease duration period.
- `lease_duration` (int) - The time in seconds that a secret is
valid for before it must be renewed.
- `lease_duration_max` (int) - The maximum amount of time in
seconds that a secret is valid for. This will always be
greater than or equal to `lease_duration`. The difference
between this and `lease_duration` is an overlap window
where multiple keys may be valid.
If the return value is not a secret, then the return structure
is an arbitrary JSON object.
+ Response 200 (application/json)
{
"lease_id": "UUID",
"lease_duration": 3600,
"key": "value"
}
### Write [PUT]
Write data to vault.
The behavior and arguments to the write are defined by
the logical backend.
+ Request (application/json)
{
"key": "value"
}
+ Response 204
# Group Lease Management
## Renew Key [/sys/renew/{id}]
+ Parameters
+ id (required, string) ... The `lease_id` of the secret
to renew.
### Renew [PUT]
+ Response 200 (application/json)
{
"lease_id": "...",
"lease_duration": 3600,
"access_key": "foo",
"secret_key": "bar"
}
## Revoke Key [/sys/revoke/{id}]
+ Parameters
+ id (required, string) ... The `lease_id` of the secret
to revoke.
### Revoke [PUT]
+ Response 204
# Group Backend: AWS
## Root Key [/aws/root]
### Set the Key [PUT]
Set the root key that the logical backend will use to create
new secrets, IAM policies, etc.
+ Request (application/json)
{
"access_key": "key",
"secret_key": "key",
"region": "us-east-1"
}
+ Response 204
## Policies [/aws/policies]
### List Policies [GET]
List all the policies that can be used to create keys.
+ Response 200 (application/json)
[{
"name": "root",
"description": "Root access"
}, {
"name": "web-deploy",
"description": "Enough permissions to deploy the web app."
}]
## Single Policy [/aws/policies/{name}]
+ Parameters
+ name (required, string) ... Name of the policy.
### Read [GET]
Read a policy.
+ Response 200 (application/json)
{
"policy": "base64-encoded policy"
}
### Upsert [PUT]
Create or update a policy.
+ Request (application/json)
{
"policy": "base64-encoded policy"
}
+ Response 204
### Delete [DELETE]
Delete the policy with the given name.
+ Response 204
## Generate Access Keys [/aws/keys/{policy}]
### Create [GET]
This generates a new keypair for the given policy.
+ Parameters
+ policy (required, string) ... The policy under which to create
the key pair.
+ Response 200 (application/json)
{
"lease_id": "...",
"lease_duration": 3600,
"access_key": "foo",
"secret_key": "bar"
}

2
builtin/credential/aws/backend.go
View File

@ -275,7 +275,7 @@ func getAnyRegionForAwsPartition(partitionId string) *endpoints.Region {
}
const backendHelp = `
aws-ec2 auth backend takes in PKCS#7 signature of an AWS EC2 instance and a client
aws-ec2 auth method takes in PKCS#7 signature of an AWS EC2 instance and a client
created nonce to authenticates the EC2 instance with Vault.
Authentication is backed by a preconfigured role in the backend. The role

2
builtin/credential/aws/cli.go
View File

@ -110,7 +110,7 @@ func (h *CLIHandler) Help() string {
help := `
Usage: vault login -method=aws [CONFIG K=V...]
The AWS authentication method allows users to authenticate with AWS IAM
The AWS auth method allows users to authenticate with AWS IAM
credentials. The AWS IAM credentials may be specified in a number of ways,
listed in order of precedence below:

2
builtin/credential/aws/path_config_client.go
View File

@ -264,7 +264,7 @@ Configure AWS IAM credentials that are used to query instance and role details f
`
const pathConfigClientHelpDesc = `
The aws-ec2 auth backend makes AWS API queries to retrieve information
The aws-ec2 auth method makes AWS API queries to retrieve information
regarding EC2 instances that perform login operations. The 'aws_secret_key' and
'aws_access_key' parameters configured here should map to an AWS IAM user that
has permission to make the following API queries:

4
builtin/credential/cert/cli.go
View File

@ -42,10 +42,10 @@ func (h *CLIHandler) Help() string {
help := `
Usage: vault login -method=cert [CONFIG K=V...]
The certificate authentication method allows uers to authenticate with a
The certificate auth method allows uers to authenticate with a
client certificate passed with the request. The -client-cert and -client-key
flags are included with the "vault login" command, NOT as configuration to the
authentication method.
auth method.
Authenticate using a local client certificate:

2
builtin/credential/github/cli.go
View File

@ -41,7 +41,7 @@ func (h *CLIHandler) Help() string {
help := `
Usage: vault login -method=github [CONFIG K=V...]
The GitHub authentication method allows users to authenticate using a GitHub
The GitHub auth method allows users to authenticate using a GitHub
personal access token. Users can generate a personal access token from the
settings page on their GitHub account.

2
builtin/credential/ldap/backend_test.go
View File

@ -102,7 +102,7 @@ func TestLdapAuthBackend_UserPolicies(t *testing.T) {
}
/*
* Acceptance test for LDAP Auth Backend
* Acceptance test for LDAP Auth Method
*
* The tests here rely on a public LDAP server:
* [http://www.forumsys.com/tutorials/integration-how-to/ldap/online-ldap-test-server/]

2
builtin/credential/ldap/cli.go
View File

@ -64,7 +64,7 @@ func (h *CLIHandler) Help() string {
help := `
Usage: vault login -method=ldap [CONFIG K=V...]
The LDAP authentication method allows users to authenticate using LDAP or
The LDAP auth method allows users to authenticate using LDAP or
Active Directory.
If MFA is enabled, a "method" and/or "passcode" may be required depending on

6
builtin/credential/okta/backend.go
View File

@ -53,7 +53,7 @@ func (b *backend) Login(req *logical.Request, username string, password string)
return nil, nil, err
}
if cfg == nil {
return nil, logical.ErrorResponse("Okta backend not configured"), nil
return nil, logical.ErrorResponse("Okta auth method not configured"), nil
}
client := cfg.OktaClient()
@ -80,7 +80,7 @@ func (b *backend) Login(req *logical.Request, username string, password string)
return nil, logical.ErrorResponse(fmt.Sprintf("Okta auth failed: %v", err)), nil
}
if rsp == nil {
return nil, logical.ErrorResponse("okta auth backend unexpected failure"), nil
return nil, logical.ErrorResponse("okta auth method unexpected failure"), nil
}
oktaResponse := &logical.Response{
@ -154,7 +154,7 @@ func (b *backend) getOktaGroups(client *okta.Client, user *okta.User) ([]string,
return nil, err
}
if rsp == nil {
return nil, fmt.Errorf("okta auth backend unexpected failure")
return nil, fmt.Errorf("okta auth method unexpected failure")
}
oktaGroups := make([]string, 0, len(user.Groups))
for _, group := range user.Groups {

2
builtin/credential/okta/cli.go
View File

@ -55,7 +55,7 @@ func (h *CLIHandler) Help() string {
help := `
Usage: vault login -method=okta [CONFIG K=V...]
The OKTA authentication method allows users to authenticate using OKTA.
The OKTA auth method allows users to authenticate using OKTA.
Authenticate as "sally":

2
builtin/credential/radius/path_config.go
View File

@ -159,7 +159,7 @@ func (b *backend) pathConfigCreateUpdate(
policies = strings.Split(unregisteredUserPoliciesStr, ",")
for _, policy := range policies {
if policy == "root" {
return logical.ErrorResponse("root policy cannot be granted by an authentication backend"), nil
return logical.ErrorResponse("root policy cannot be granted by an auth method"), nil
}
}
}

2
builtin/credential/radius/path_users.go
View File

@ -114,7 +114,7 @@ func (b *backend) pathUserWrite(
var policies = policyutil.ParsePolicies(d.Get("policies"))
for _, policy := range policies {
if policy == "root" {
return logical.ErrorResponse("root policy cannot be granted by an authentication backend"), nil
return logical.ErrorResponse("root policy cannot be granted by an auth method"), nil
}
}

6
builtin/credential/token/cli.go
View File

@ -92,7 +92,7 @@ func (h *CLIHandler) Auth(c *api.Client, m map[string]string) (*api.Secret, erro
return nil, fmt.Errorf("Empty response from lookup-self")
}
// Return an auth struct that "looks" like the response from an auth backend.
// Return an auth struct that "looks" like the response from an auth method.
// lookup and lookup-self return their data in data, not auth. We try to
// mirror that data here.
return &api.Secret{
@ -113,9 +113,9 @@ func (h *CLIHandler) Help() string {
help := `
Usage: vault login TOKEN [CONFIG K=V...]
The token authentication method allows logging in directly with a token. This
The token auth method allows logging in directly with a token. This
can be a token from the "token-create" command or API. There are no
configuration options for this authentication method.
configuration options for this auth method.
Authenticate using a token:

2
builtin/credential/userpass/cli.go
View File

@ -68,7 +68,7 @@ func (h *CLIHandler) Help() string {
help := `
Usage: vault login -method=userpass [CONFIG K=V...]
The userpass authentication method allows users to authenticate using Vault's
The userpass auth method allows users to authenticate using Vault's
internal user database.
If MFA is enabled, a "method" and/or "passcode" may be required depending on

29
command/login.go
View File

@ -47,24 +47,23 @@ Usage: vault login [options] [AUTH K=V...]
a session token on a website. By default, this token is cached on the local
machine for future requests.
The default authentication method is "token". If not supplied via the CLI,
The default auth method is "token". If not supplied via the CLI,
Vault will prompt for input. If the argument is "-", the values are read
from stdin.
The -method flag allows using other authentication methods, such as userpass,
github, or cert. For these, additional "K=V" pairs may be required. For
example, to authenticate to the userpass auth method:
The -method flag allows using other auth methods, such as userpass, github, or
cert. For these, additional "K=V" pairs may be required. For example, to
authenticate to the userpass auth method:
$ vault login -method=userpass username=my-username
For more information about the list of configuration parameters available
for a given authentication method, use the "vault auth help TYPE". You can
also use "vault auth list" to see the list of enabled authentication methods.
For more information about the list of configuration parameters available for
a given auth method, use the "vault auth help TYPE". You can also use "vault
auth list" to see the list of enabled auth methods.
If an authentication method is enabled at a non-standard path, the -method
flag still refers to the canonical type, but the -path flag refers to the
enabled path. If a github authentication method was enabled at "github-ent",
authenticate like this:
If an auth method is enabled at a non-standard path, the -method flag still
refers to the canonical type, but the -path flag refers to the enabled path.
If a github auth method was enabled at "github-ent", authenticate like this:
$ vault login -method=github -path=github-prod
@ -102,7 +101,7 @@ func (c *LoginCommand) Flags() *FlagSets {
Target: &c.flagPath,
Default: "",
Completion: c.PredictVaultAuths(),
Usage: "Remote path in Vault where the authentication method is enabled. " +
Usage: "Remote path in Vault where the auth method is enabled. " +
"This defaults to the TYPE of method (e.g. userpass -> userpass/).",
})
@ -210,9 +209,9 @@ func (c *LoginCommand) Run(args []string) int {
authHandler, ok := c.Handlers[authMethod]
if !ok {
c.UI.Error(wrapAtLength(fmt.Sprintf(
"Unknown authentication method: %s. Use \"vault auth list\" to see the "+
"complete list of authentication methods. Additionally, some "+
"authentication methods are only available via the HTTP API.",
"Unknown auth method: %s. Use \"vault auth list\" to see the "+
"complete list of auth methods. Additionally, some "+
"auth methods are only available via the HTTP API.",
authMethod)))
return 1
}

6
helper/mfa/duo/path_duo_config.go
View File

@ -18,7 +18,7 @@ func pathDuoConfig() *framework.Path {
},
"username_format": &framework.FieldSchema{
Type: framework.TypeString,
Description: "Format string given auth backend username as argument to create Duo username (default '%s')",
Description: "Format string given auth method username as argument to create Duo username (default '%s')",
},
"push_info": &framework.FieldSchema{
Type: framework.TypeString,
@ -103,10 +103,10 @@ type DuoConfig struct {
}
const pathDuoConfigHelpSyn = `
Configure Duo second factor behavior.
Configure Duo second factor behavior.
`
const pathDuoConfigHelpDesc = `
This endpoint allows you to configure how the original auth backend username maps to
This endpoint allows you to configure how the original auth method username maps to
the Duo username by providing a template format string.
`

2
helper/mfa/mfa.go
View File

@ -1,5 +1,5 @@
// Package mfa provides wrappers to add multi-factor authentication
// to any auth backend.
// to any auth method.
//
// To add MFA to a backend, replace its login path with the
// paths returned by MFAPaths and add the additional root

2
vault/auth.go
View File

@ -116,7 +116,7 @@ func (c *Core) enableCredential(entry *MountEntry) error {
// Check for the correct backend type
backendType := backend.Type()
if entry.Type == "plugin" && backendType != logical.TypeCredential {
return fmt.Errorf("cannot mount '%s' of type '%s' as an auth backend", entry.Config.PluginName, backendType)
return fmt.Errorf("cannot mount '%s' of type '%s' as an auth method", entry.Config.PluginName, backendType)
}
if err := backend.Initialize(); err != nil {

8
vault/logical_system.go
View File

@ -1583,7 +1583,7 @@ func (b *SystemBackend) handleMountTuneRead(
logical.ErrInvalidRequest
}
// This call will read both logical backend's configuration as well as auth backends'.
// This call will read both logical backend's configuration as well as auth methods'.
// Retaining this behavior for backward compatibility. If this behavior is not desired,
// an error can be returned if path has a prefix of "auth/".
return b.handleTuneReadCommon(path)
@ -1635,7 +1635,7 @@ func (b *SystemBackend) handleMountTuneWrite(
return logical.ErrorResponse("path must be specified as a string"),
logical.ErrInvalidRequest
}
// This call will write both logical backend's configuration as well as auth backends'.
// This call will write both logical backend's configuration as well as auth methods'.
// Retaining this behavior for backward compatibility. If this behavior is not desired,
// an error can be returned if path has a prefix of "auth/".
return b.handleTuneWriteCommon(path, data)
@ -3069,10 +3069,10 @@ This path responds to the following HTTP methods.
credential backend.
POST /<mount point>
Enable a new auth backend.
Enable a new auth method.
DELETE /<mount point>
Disable the auth backend at the given mount point.
Disable the auth method at the given mount point.
`,
},

2
vault/request_handling.go
View File

@ -433,7 +433,7 @@ func (c *Core) handleLoginRequest(req *logical.Request) (retResp *logical.Respon
}
if strutil.StrListSubset(auth.Policies, []string{"root"}) {
return logical.ErrorResponse("authentication backends cannot create root tokens"), nil, logical.ErrInvalidRequest
return logical.ErrorResponse("auth methods cannot create root tokens"), nil, logical.ErrInvalidRequest
}
// Determine the source of the login

21
website/source/api/auth/app-id/index.html.md
View File

@ -1,17 +1,20 @@
---
layout: "api"
page_title: "App ID Auth Backend - HTTP API"
page_title: "AppID - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-appid"
description: |-
This is the API documentation for the Vault App ID authentication backend.
This is the API documentation for the Vault App ID auth method.
---
# App ID Auth Backend HTTP API (DEPRECATED)
# AppID Auth Method (API)
This is the API documentation for the Vault App ID authentication backend. For
general information about the usage and operation of the App ID backend, please
see the [Vault App ID backend documentation](/docs/auth/app-id.html).
~> This API is deprecated and will be removed in a future version of Vault.
Please use AppRole instead.
This documentation assumes the App ID backend is mounted at the `/auth/app-id`
path in Vault. Since it is possible to mount auth backends at any location,
please update your API calls accordingly.
This is the API documentation for the Vault App ID auth method. For
general information about the usage and operation of the App ID method, please
see the [Vault App ID method documentation](/docs/auth/app-id.html).
This documentation assumes the App ID method is mounted at the `/auth/app-id`
path in Vault. Since it is possible to mount auth methods at any location,
please update your API calls accordingly.

58
website/source/api/auth/approle/index.html.md
View File

@ -1,29 +1,28 @@
---
layout: "api"
page_title: "AppRole Auth Backend - HTTP API"
page_title: "AppRole - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-approle"
description: |-
This is the API documentation for the Vault AppRole authentication backend.
This is the API documentation for the Vault AppRole auth method.
---
# AppRole Auth Backend HTTP API
# AppRole Auth Method (API)
This is the API documentation for the Vault AppRole authentication backend. For
general information about the usage and operation of the AppRole backend, please
see the [Vault AppRole backend documentation](/docs/auth/approle.html).
This is the API documentation for the Vault AppRole auth method. For
general information about the usage and operation of the AppRole method, please
see the [Vault AppRole method documentation](/docs/auth/approle.html).
This documentation assumes the AppRole backend is mounted at the `/auth/approle`
path in Vault. Since it is possible to mount auth backends at any location,
This documentation assumes the AppRole method is mounted at the `/auth/approle`
path in Vault. Since it is possible to mount auth methods at any location,
please update your API calls accordingly.
## List Roles
This endpoint returns a list the existing AppRoles in the backend.
This endpoint returns a list the existing AppRoles in the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/approle/role` | `200 application/json` |
| `GET` | `/auth/approle/role?list=true` | `200 application/json` |
| `LIST` | `/auth/approle/role` | `200 application/json` |
### Sample Request
@ -68,28 +67,28 @@ enabled while creating or updating a role.
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `bind_secret_id` `(bool: true)` - Require `secret_id` to be presented when
- `bind_secret_id` `(bool: true)` - Require `secret_id` to be presented when
logging in using this AppRole.
- `bound_cidr_list` `(array: [])` - Comma-separated list of CIDR blocks; if set,
specifies blocks of IP addresses which can perform the login operation.
- `policies` `(array: [])` - Comma-separated list of policies set on tokens
- `policies` `(array: [])` - Comma-separated list of policies set on tokens
issued via this AppRole.
- `secret_id_num_uses` `(integer: 0)` - Number of times any particular SecretID
can be used to fetch a token from this AppRole, after which the SecretID will
can be used to fetch a token from this AppRole, after which the SecretID will
expire. A value of zero will allow unlimited uses.
- `secret_id_ttl` `(string: "")` - Duration in either an integer number of
- `secret_id_ttl` `(string: "")` - Duration in either an integer number of
seconds (`3600`) or an integer time unit (`60m`) after which any SecretID
expires.
- `token_num_uses` `(integer: 0)` - Number of times issued tokens can be used.
A value of 0 means unlimited uses.
- `token_ttl` `(string: "")` - Duration in either an integer number of seconds
(`3600`) or an integer time unit (`60m`) to set as the TTL for issued tokens
- `token_ttl` `(string: "")` - Duration in either an integer number of seconds
(`3600`) or an integer time unit (`60m`) to set as the TTL for issued tokens
and at renewal time.
- `token_max_ttl` `(string: "")` - Duration in either an integer number of
- `token_max_ttl` `(string: "")` - Duration in either an integer number of
seconds (`3600`) or an integer time unit (`60m`) after which the issued token
can no longer be renewed.
- `period` `(string: "")` - Duration in either an integer number of seconds
(`3600`) or an integer time unit (`60m`). If set, the token generated using
- `period` `(string: "")` - Duration in either an integer number of seconds
(`3600`) or an integer time unit (`60m`). If set, the token generated using
this AppRole is a _periodic_ token; so long as it is renewed it never expires,
but the TTL set on the token at each renewal is fixed to the value specified
here. If this value is modified, the token will pick up the new value at its
@ -166,7 +165,7 @@ $ curl \
## Delete AppRole
Deletes an existing AppRole from the backend.
Deletes an existing AppRole from the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -283,12 +282,12 @@ itself, and also to delete the SecretID from the AppRole.
- `role_name` `(string: <required>)` - Name of the AppRole.
- `metadata` `(map: {})` - Metadata to be tied to the SecretID. This should be
a JSON-formatted string containing the metadata in key-value pairs. This
metadata will be set on tokens issued with this SecretID, and is logged in
a JSON-formatted string containing the metadata in key-value pairs. This
metadata will be set on tokens issued with this SecretID, and is logged in
audit logs _in plaintext_.
- `cidr_list` `(string: "")` - Comma separated list of CIDR blocks enforcing
secret IDs to be used from specific set of IP addresses. If 'bound_cidr_list'
is set on the role, then the list of CIDR blocks listed here should be a
secret IDs to be used from specific set of IP addresses. If 'bound_cidr_list'
is set on the role, then the list of CIDR blocks listed here should be a
subset of the CIDR blocks listed on the role.
### Sample Payload
@ -336,7 +335,6 @@ This includes the accessors for "custom" SecretIDs as well.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/approle/role/:role_name/secret-id` | `200 application/json` |
| `GET` | `/auth/approle/role/:role_name/secret-id?list=true` | `200 application/json` |
### Parameters
@ -511,12 +509,12 @@ Assigns a "custom" SecretID against an existing AppRole. This is used in the
- `role_name` `(string: <required>)` - Name of the AppRole.
- `secret_id` `(string: <required>)` - SecretID to be attached to the Role.
- `metadata` `(map: {})` - Metadata to be tied to the SecretID. This should be
a JSON-formatted string containing the metadata in key-value pairs. This
metadata will be set on tokens issued with this SecretID, and is logged in
a JSON-formatted string containing the metadata in key-value pairs. This
metadata will be set on tokens issued with this SecretID, and is logged in
audit logs _in plaintext_.
- `cidr_list` `(string: "")` - Comma separated list of CIDR blocks enforcing
secret IDs to be used from ppecific set of IP addresses. If 'bound_cidr_list'
is set on the role, then the list of CIDR blocks listed here should be a
secret IDs to be used from ppecific set of IP addresses. If 'bound_cidr_list'
is set on the role, then the list of CIDR blocks listed here should be a
subset of the CIDR blocks listed on the role.
### Sample Payload

39
website/source/api/auth/aws/index.html.md
View File

@ -1,19 +1,19 @@
---
layout: "api"
page_title: "AWS Auth Backend - HTTP API"
page_title: "AWS - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-aws"
description: |-
This is the API documentation for the Vault AWS authentication backend.
This is the API documentation for the Vault AWS auth method.
---
# AWS Auth Backend HTTP API
# AWS Auth Method (API)
This is the API documentation for the Vault AWS authentication backend. For
general information about the usage and operation of the AWS backend, please
see the [Vault AWS backend documentation](/docs/auth/aws.html).
This is the API documentation for the Vault AWS auth method. For
general information about the usage and operation of the AWS method, please
see the [Vault AWS method documentation](/docs/auth/aws.html).
This documentation assumes the AWS backend is mounted at the `/auth/aws`
path in Vault. Since it is possible to mount auth backends at any location,
This documentation assumes the AWS method is mounted at the `/auth/aws`
path in Vault. Since it is possible to mount auth methods at any location,
please update your API calls accordingly.
## Configure Client
@ -26,7 +26,7 @@ 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
backend is configured on an EC2 instance with metadata querying
method is configured on an EC2 instance with metadata querying
capabilities, the credentials are fetched automatically.
| Method | Path | Produces |
@ -220,12 +220,11 @@ $ curl \
## List Certificate Configurations
Lists all the AWS public certificates that are registered with the backend.
Lists all the AWS public certificates that are registered with the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/aws/config/certificates` | `200 application/json` |
| `GET` | `/auth/aws/config/certificates?list=true` | `200 application/json` |
### Sample Request
@ -325,7 +324,6 @@ Lists all the AWS Account IDs for which an STS role is registered.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/aws/config/sts` | `200 application/json` |
| `GET` | `/auth/aws/config/sts?list=true` | `200 application/json` |
### Sample Request
@ -377,7 +375,7 @@ Configures the periodic tidying operation of the whitelisted identity entries.
### Parameters
- `safety_buffer` `(string: "72h")` - The amount of extra time that must have
passed beyond the `roletag` expiration, before it is removed from the backend
passed beyond the `roletag` expiration, before it is removed from the method
storage. Defaults to 72h.
- `disable_periodic_tidy` `(bool: false)` - If set to 'true', disables the
periodic tidying of the `identity-whitelist/<instance_id>` entries.
@ -455,7 +453,7 @@ Configures the periodic tidying operation of the blacklisted role tag entries.
### Parameters
- `safety_buffer` `(string: "72h")` - The amount of extra time that must have
passed beyond the `roletag` expiration, before it is removed from the backend
passed beyond the `roletag` expiration, before it is removed from the method
storage. Defaults to 72h.
- `disable_periodic_tidy` `(bool: false)` - If set to 'true', disables the
periodic tidying of the `roletag-blacklist/<instance_id>` entries.
@ -524,7 +522,7 @@ $ curl \
## Create Role
Registers a role in the backend. Only those instances or principals which
Registers a role in the method. Only those instances or principals which
are using the role registered using this endpoint, will be able to perform
the login operation. Contraints can be specified on the role, that are
applied on the instances or principals attempting to login. At least one
@ -726,12 +724,11 @@ $ curl \
## List Roles
Lists all the roles that are registered with the backend.
Lists all the roles that are registered with the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/aws/roles` | `200 application/json` |
| `GET` | `/auth/aws/roles?list=true` | `200 application/json` |
### Sample Request
@ -879,7 +876,7 @@ along with its RSA digest can be supplied to this endpoint.
and `signature` need to be set when using the ec2 auth method.
- `nonce` `(string: "")` - The nonce to be used for subsequent login requests.
If this parameter is not specified at all and if reauthentication is allowed,
then the backend will generate a random nonce, attaches it to the instance's
then the method will generate a random nonce, attaches it to the instance's
identity-whitelist entry and returns the nonce back as part of auth metadata.
This value should be used with further login requests, to establish client
authenticity. Clients can choose to set a custom nonce if preferred, in which
@ -1019,7 +1016,6 @@ Lists all the role tags that are blacklisted.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/aws/roletag-blacklist` | `200 application/json` |
| `GET` | `/auth/aws/roletag-blacklist?list=true` | `200 application/json` |
### Sample Request
@ -1078,7 +1074,7 @@ Cleans up the entries in the blacklist based on expiration time on the entry and
### Parameters
- `safety_buffer` `(string: "72h")` - The amount of extra time that must have
passed beyond the `roletag` expiration, before it is removed from the backend
passed beyond the `roletag` expiration, before it is removed from the method
storage. Defaults to 72h.
### Sample Request
@ -1135,7 +1131,6 @@ $ curl \
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/aws/identity-whitelist` | `200 application/json` |
| `GET` | `/auth/aws/identity-whitelist?list=true` | `200 application/json` |
### Sample Request
@ -1193,7 +1188,7 @@ Cleans up the entries in the whitelist based on expiration time and
### Parameters
- `safety_buffer` `(string: "72h")` - The amount of extra time that must have
passed beyond the `roletag` expiration, before it is removed from the backend
passed beyond the `roletag` expiration, before it is removed from the method
storage. Defaults to 72h.
### Sample Request

55
website/source/api/auth/cert/index.html.md
View File

@ -1,20 +1,20 @@
---
layout: "api"
page_title: "TLS Certificate Auth Backend - HTTP API"
page_title: "TLS Certificate - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-cert"
description: |-
This is the API documentation for the Vault TLS Certificate authentication
backend.
method.
---
# TLS Certificate Auth Backend HTTP API
# TLS Certificate Auth Method (API)
This is the API documentation for the Vault TLS Certificate authentication
backend. For general information about the usage and operation of the TLS
Certificate backend, please see the [Vault TLS Certificate backend documentation](/docs/auth/cert.html).
This is the API documentation for the Vault TLS Certificate authentication
method. For general information about the usage and operation of the TLS
Certificate method, please see the [Vault TLS Certificate method documentation](/docs/auth/cert.html).
This documentation assumes the TLS Certificate backend is mounted at the
`/auth/cert` path in Vault. Since it is possible to mount auth backends at any
This documentation assumes the TLS Certificate method is mounted at the
`/auth/cert` path in Vault. Since it is possible to mount auth methods at any
location, please update your API calls accordingly.
## Create CA Certificate Role
@ -29,17 +29,17 @@ Sets a CA cert and associated parameters in a role name.
- `name` `(string: <required>)` - The name of the certificate role.
- `certificate` `(string: <required>)` - The PEM-format CA certificate.
- `allowed_names` `(string: "")` - Constrain the Common and Alternative Names in
- `allowed_names` `(string: "")` - Constrain the Common and Alternative Names in
the client certificate with a [globbed pattern]
(https://github.com/ryanuber/go-glob/blob/master/README.md#example). Value is
(https://github.com/ryanuber/go-glob/blob/master/README.md#example). 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.
- `policies` `(string: "")` - A comma-separated list of policies to set on tokens
- `policies` `(string: "")` - A comma-separated list of policies to set on tokens
issued when authenticating against this CA certificate.
- `display_name` `(string: "")` - The `display_name` to set on tokens issued
when authenticating against this CA certificate. If not set, defaults to the
- `display_name` `(string: "")` - The `display_name` to set on tokens issued
when authenticating against this CA certificate. If not set, defaults to the
name of the role.
- `ttl` `(string: "")` - The TTL period of the token, provided as a number of
seconds. If not provided, the token is valid for the the mount or system
- `ttl` `(string: "")` - The TTL period of the token, provided as a number of
seconds. If not provided, the token is valid for the the mount or system
default TTL time, in that order.
### Sample Payload
@ -107,7 +107,6 @@ Lists configured certificate names.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/cert/certs` | `200 application/json` |
| `GET` | `/auth/cert/certs?list=true` | `200 application/json` |
### Sample Request
@ -126,7 +125,7 @@ $ curl \
"wrap_info": null,
"data": {
"keys": [
"cert1",
"cert1",
"cert2"
]
},
@ -138,7 +137,7 @@ $ curl \
## Delete Certificate Role
Deletes the named role and CA cert from the backend mount.
Deletes the named role and CA cert from the method mount.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -166,7 +165,7 @@ Sets a named CRL.
| `POST` | `/auth/cert/crls/:name` | `204 (empty body)` |
### Parameters
### Parameters
- `name` `(string: <required>)` - The name of the CRL.
- `crl` `(string: <required>)` - The PEM format CRL.
@ -230,7 +229,7 @@ $ curl \
## Delete CRL
Deletes the named CRL from the backend mount.
Deletes the named CRL from the auth method mount.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -249,9 +248,9 @@ $ curl \
https://vault.rocks/v1/auth/cert/crls/cert1
```
## Configure TLS Certificate Backend
## Configure TLS Certificate Method
Configuration options for the backend.
Configuration options for the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -261,7 +260,7 @@ Configuration options for the backend.
- `disable_binding` `(boolean: false)` - If set, during renewal, skips the
matching of presented client identity with the client identity used during
login.
login.
### Sample Payload
@ -281,10 +280,10 @@ $ curl \
https://vault.rocks/v1/auth/cert/certs/cert1
```
## Login with TLS Certiicate Backend
## Login with TLS Certiicate Method
Log in and fetch a token. If there is a valid chain to a CA configured in the
backend and all role constraints are matched, a token will be issued.
method and all role constraints are matched, a token will be issued.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -292,7 +291,7 @@ backend and all role constraints are matched, a token will be issued.
### Parameters
- `name` `(string: "")` - Authenticate against only the named certificate role,
- `name` `(string: "")` - 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.
@ -320,11 +319,11 @@ $ curl \
"auth": {
"client_token": "cf95f87d-f95b-47ff-b1f5-ba7bff850425",
"policies": [
"web",
"web",
"stage"
],
"lease_duration": 3600,
"renewable": true,
}
}
```
```

19
website/source/api/auth/gcp/index.html.md
View File

@ -1,20 +1,20 @@
---
layout: "api"
page_title: "Google Cloud Platform Auth Plugin Backend - HTTP API"
page_title: "Google Cloud Platform - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-gcp"
description: |-
This is the API documentation for the Vault GCP authentication
backend plugin.
method plugin.
---
# GCP Auth Plugin HTTP API
# GCP Auth Method (API)
This is the API documentation for the Vault GCP authentication backend
This is the API documentation for the Vault GCP auth method
plugin. To learn more about the usage and operation, see the
[Vault GCP backend documentation](/docs/auth/gcp.html).
[Vault GCP method documentation](/docs/auth/gcp.html).
This documentation assumes the plugin backend is mounted at the
`/auth/gcp` path in Vault. Since it is possible to mount auth backends
This documentation assumes the plugin method is mounted at the
`/auth/gcp` path in Vault. Since it is possible to mount auth methods
at any location, please update your API calls accordingly.
## Configure
@ -115,7 +115,7 @@ $ curl \
## Create Role
Registers a role in the backend. Role types have specific entities
Registers 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.
@ -228,7 +228,7 @@ $ curl \
## Edit Service Accounts For IAM Role
Edit service accounts for an existing IAM role in the backend.
Edit service accounts for an existing IAM role in the method.
This allows you to add or remove service accounts from the list of
service accounts on the role.
@ -362,7 +362,6 @@ Lists all the roles that are registered with the plugin.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/gcp/roles` | `200 application/json` |
| `GET` | `/auth/gcp/roles?list=true` | `200 application/json` |
### Sample Request

24
website/source/api/auth/github/index.html.md
View File

@ -1,24 +1,24 @@
---
layout: "api"
page_title: "Github Auth Backend - HTTP API"
page_title: "GitHub - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-github"
description: |-
This is the API documentation for the Vault Github authentication backend.
This is the API documentation for the Vault Github auth method.
---
# Github Auth Backend HTTP API
# Github Auth Method (API)
This is the API documentation for the Vault Github authentication backend. For
general information about the usage and operation of the Github backend, please
see the [Vault Github backend documentation](/docs/auth/github.html).
This is the API documentation for the Vault Github auth method. For
general information about the usage and operation of the Github method, please
see the [Vault Github method documentation](/docs/auth/github.html).
This documentation assumes the Github backend is mounted at the `/auth/github`
path in Vault. Since it is possible to mount auth backends at any location,
This documentation assumes the Github method is mounted at the `/auth/github`
path in Vault. Since it is possible to mount auth methods at any location,
please update your API calls accordingly.
## Configure Backend
## Configure Method
Configures the connection parameters for Github. This path honors the
Configures the connection parameters for GitHub. This path honors the
distinction between the `create` and `update` capabilities inside ACL policies.
| Method | Path | Produces |
@ -27,12 +27,12 @@ distinction between the `create` and `update` capabilities inside ACL policies.
### Parameters
- `organization` `(string: <required>)` - The organization users must be part
- `organization` `(string: <required>)` - The organization users must be part
of.
- `base_url` `(string: "")` - The API endpoint to use. Useful if you are running
GitHub Enterprise or an API-compatible authentication server.
- `ttl` `(string: "")` - Duration after which authentication will be expired.
- `max_ttl` `(string: "")` - Maximum duration after which authentication will
- `max_ttl` `(string: "")` - Maximum duration after which authentication will
be expired.
### Sample Payload

19
website/source/api/auth/index.html.md
View File

@ -1,19 +1,18 @@
---
layout: "api"
page_title: "HTTP API"
page_title: "Auth Methods - HTTP API"
sidebar_current: "docs-http-auth"
description: |-
Each authentication backend publishes its own set of API paths and methods.
Each auth method publishes its own set of API paths and methods.
These endpoints are documented in this section.
---
# Authentication Backends
# Auth Methods
Each authentication backend publishes its own set of API paths and methods.
These endpoints are documented in this section. Authentication backends are
mount at a path, but the documentation will assume the default mount points for
simplicity. If you are mounting at a different path, you should adjust your API
calls accordingly.
Each auth method publishes its own set of API paths and methods. These endpoints
are documented in this section. Auth methods are mount at a path, but the
documentation will assume the default mount points for simplicity. If you are
mounting at a different path, you should adjust your API calls accordingly.
For the API documentation for a specific authentication backend, please choose a
authentication backend from the navigation.
For the API documentation for a specific auth method, please choose a auth
method from the navigation.

55
website/source/api/auth/ldap/index.html.md
View File

@ -1,24 +1,24 @@
---
layout: "api"
page_title: "LDAP Auth Backend - HTTP API"
page_title: "LDAP - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-ldap"
description: |-
This is the API documentation for the Vault LDAP authentication backend.
This is the API documentation for the Vault LDAP auth method.
---
# LDAP Auth Backend HTTP API
# LDAP Auth Method (API)
This is the API documentation for the Vault LDAP authentication backend. For
general information about the usage and operation of the LDAP backend, please
see the [Vault LDAP backend documentation](/docs/auth/ldap.html).
This is the API documentation for the Vault LDAP auth method. For
general information about the usage and operation of the LDAP method, please
see the [Vault LDAP method documentation](/docs/auth/ldap.html).
This documentation assumes the LDAP backend is mounted at the `/auth/ldap`
path in Vault. Since it is possible to mount auth backends at any location,
This documentation assumes the LDAP method is mounted at the `/auth/ldap`
path in Vault. Since it is possible to mount auth methods at any location,
please update your API calls accordingly.
## Configure LDAP Backend
## Configure LDAP
This endpoint configures the LDAP authentication backend.
This endpoint configures the LDAP auth method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -26,17 +26,17 @@ This endpoint configures the LDAP authentication backend.
### Parameters
- `url` `(string: <required>)` – The LDAP server to connect to. Examples:
- `url` `(string: <required>)` – The LDAP server to connect to. Examples:
`ldap://ldap.myorg.com`, `ldaps://ldap.myorg.com:636`
- `starttls` `(bool: false)` – If true, issues a `StartTLS` command after
- `starttls` `(bool: false)` – If true, issues a `StartTLS` command after
establishing an unencrypted connection.
- `tls_min_version` `(string: tls12)` – Minimum TLS version to use. Accepted
- `tls_min_version` `(string: tls12)` – Minimum TLS version to use. Accepted
values are `tls10`, `tls11` or `tls12`.
- `tls_max_version` `(string: tls12)` – Maximum TLS version to use. Accepted
- `tls_max_version` `(string: tls12)` – Maximum TLS version to use. Accepted
values are `tls10`, `tls11` or `tls12`.
- `insecure_tls` `(bool: false)` – If true, skips LDAP server SSL certificate
- `insecure_tls` `(bool: false)` – If true, skips LDAP server SSL certificate
verification - insecure, use with caution!
- `certificate` `(string: "")` – CA certificate to use when verifying LDAP server
- `certificate` `(string: "")` – CA certificate to use when verifying LDAP server
certificate, must be x509 PEM encoded.
- `binddn` `(string: "")` – Distinguished name of object to bind when performing
user search. Example: `cn=vault,ou=Users,dc=example,dc=com`
@ -44,17 +44,17 @@ This endpoint configures the LDAP authentication backend.
user search.
- `userdn` `(string: "")` – Base DN under which to perform user search. Example:
`ou=Users,dc=example,dc=com`
- `userattr` `(string: "")` – Attribute on user attribute object matching the
- `userattr` `(string: "")` – Attribute on user attribute object matching the
username passed when authenticating. Examples: `sAMAccountName`, `cn`, `uid`
- `discoverdn` `(bool: false)` – Use anonymous bind to discover the bind DN of a
user.
- `deny_null_bind` `(bool: true)` – This option prevents users from bypassing
- `deny_null_bind` `(bool: true)` – This option prevents users from bypassing
authentication when providing an empty password.
- `upndomain` `(string: "")` – 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`.
- `groupfilter` `(string: "")` – Go template used when constructing the group
- `groupfilter` `(string: "")` – 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}}))`,
@ -62,11 +62,11 @@ This endpoint configures the LDAP authentication backend.
nested group resolution for Active Directory, instead use the following
query: `(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))`.
- `groupdn` `(string: "")` – LDAP search base to use for group membership
search. This can be the root containing either groups or users. Example:
search. This can be the root containing either groups or users. Example:
`ou=Groups,dc=example,dc=com`
- `groupattr` `(string: "")` – LDAP attribute to follow on objects returned by
- `groupattr` `(string: "")` – 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
groupfilter queries returning _group_ objects, use: `cn`. For queries
returning _user_ objects, use: `memberOf`. The default is `cn`.
### Sample Request
@ -101,7 +101,7 @@ $ curl \
## Read LDAP Configuration
This endpoint retrieves the LDAP configuration for the authentication backend.
This endpoint retrieves the LDAP configuration for the auth method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -148,12 +148,11 @@ $ curl \
## List LDAP Groups
This endpoint returns a list of existing groups in the backend.
This endpoint returns a list of existing groups in the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/ldap/groups` | `200 application/json` |
| `GET` | `/auth/ldap/groups?list=true` | `200 application/json` |
### Sample Request
@ -275,12 +274,11 @@ $ curl \
## List LDAP Users
This endpoint returns a list of existing users in the backend.
This endpoint returns a list of existing users in the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/ldap/users` | `200 application/json` |
| `GET` | `/auth/ldap/users?list=true` | `200 application/json` |
| `LIST` | `/auth/ldap/users` | `200 application/json` |
### Sample Request
@ -455,4 +453,3 @@ $ curl \
}
}
```

44
website/source/api/auth/okta/index.html.md
View File

@ -1,24 +1,24 @@
---
layout: "api"
page_title: "Okta Auth Backend - HTTP API"
page_title: "Okta - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-okta"
description: |-
This is the API documentation for the Vault Okta authentication backend.
This is the API documentation for the Vault Okta auth method.
---
# Okta Auth Backend HTTP API
# Okta Auth Method (API)
This is the API documentation for the Vault Okta authentication backend. For
general information about the usage and operation of the Okta backend, please
see the [Vault Okta backend documentation](/docs/auth/okta.html).
This is the API documentation for the Vault Okta auth method. For
general information about the usage and operation of the Okta method, please
see the [Vault Okta method documentation](/docs/auth/okta.html).
This documentation assumes the Okta backend is mounted at the `/auth/okta`
path in Vault. Since it is possible to mount auth backends at any location,
This documentation assumes the Okta method is mounted at the `/auth/okta`
path in Vault. Since it is possible to mount auth methods at any location,
please update your API calls accordingly.
## Create Configuration
Configures the connection parameters for Okta. This path honors the
Configures the connection parameters for Okta. This path honors the
distinction between the `create` and `update` capabilities inside ACL policies.
| Method | Path | Produces |
@ -29,13 +29,13 @@ distinction between the `create` and `update` capabilities inside ACL policies.
- `org_name` `(string: <required>)` - Name of the organization to be used in the
Okta API.
- `api_token` `(string: "")` - 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.
- `api_token` `(string: "")` - 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` `(string: "")` - If set, will be used as the base domain
for API requests. Examples are okta.com, oktapreview.com, and okta-emea.com.
- `ttl` `(string: "")` - Duration after which authentication will be expired.
- `max_ttl` `(string: "")` - Maximum duration after which authentication will
- `max_ttl` `(string: "")` - Maximum duration after which authentication will
be expired.
### Sample Payload
@ -94,12 +94,11 @@ $ curl \
## List Users
List the users configurated in the Okta backend.
List the users configurated in the Okta method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/okta/users` | `200 application/json` |
| `GET` | `/auth/okta/users?list=true` | `200 application/json` |
### Sample Request
@ -140,9 +139,9 @@ Registers a new user and maps a set of policies to it.
### Parameters
- `username` `(string: <required>)` - Name of the user.
- `groups` `(string: "")` - Comma-separated list of groups associated with the
- `groups` `(string: "")` - Comma-separated list of groups associated with the
user.
- `policies` `(string: "")` - Comma-separated list of policies associated with
- `policies` `(string: "")` - Comma-separated list of policies associated with
the user.
```json
@ -199,7 +198,7 @@ $ curl \
## Delete User
Deletes an existing username from the backend.
Deletes an existing username from the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -220,12 +219,11 @@ $ curl \
## List Groups
List the groups configurated in the Okta backend.
List the groups configurated in the Okta method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/okta/groups` | `200 application/json` |
| `GET` | `/auth/okta/groups?list=true` | `200 application/json` |
### Sample Request
@ -266,7 +264,7 @@ Registers a new group and maps a set of policies to it.
### Parameters
- `name` `(string: <required>)` - The name of the group.
- `policies` `(string: "")` - Comma-separated list of policies associated with
- `policies` `(string: "")` - Comma-separated list of policies associated with
the group.
```json
@ -322,7 +320,7 @@ $ curl \
## Delete Group
Deletes an existing group from the backend.
Deletes an existing group from the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -392,4 +390,4 @@ $ curl \
"lease_duration": 7200,
"renewable": true
}
```
```

35
website/source/api/auth/radius/index.html.md
View File

@ -1,24 +1,24 @@
---
layout: "api"
page_title: "RADIUS Auth Backend - HTTP API"
page_title: "RADIUS - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-radius"
description: |-
This is the API documentation for the Vault RADIUS authentication backend.
This is the API documentation for the Vault RADIUS auth method.
---
# RADIUS Auth Backend HTTP API
# RADIUS Auth Method (API)
This is the API documentation for the Vault RADIUS authentication backend. For
general information about the usage and operation of the RADIUS backend, please
see the [Vault RADIUS backend documentation](/docs/auth/radius.html).
This is the API documentation for the Vault RADIUS auth method. For
general information about the usage and operation of the RADIUS method, please
see the [Vault RADIUS method documentation](/docs/auth/radius.html).
This documentation assumes the RADIUS backend is mounted at the `/auth/radius`
path in Vault. Since it is possible to mount auth backends at any location,
This documentation assumes the RADIUS method is mounted at the `/auth/radius`
path in Vault. Since it is possible to mount auth methods at any location,
please update your API calls accordingly.
## Configure RADIUS
Configures the connection parameters and shared secret used to communicate with
Configures the connection parameters and shared secret used to communicate with
RADIUS.
| Method | Path | Produces |
@ -27,16 +27,16 @@ RADIUS.
### Parameters
- `host` `(string: <required>)` - The RADIUS server to connect to. Examples:
- `host` `(string: <required>)` - The RADIUS server to connect to. Examples:
`radius.myorg.com`, `127.0.0.1`
- `port` `(integer: 1812)` - The UDP port where the RADIUS server is listening
on. Defaults is 1812.
- `secret` `(string: <required>)` - The RADIUS shared secret.
- `unregistered_user_policies` `(string: "")` - A comma-separated list of
- `unregistered_user_policies` `(string: "")` - A comma-separated list of
policies to be granted to unregistered users.
- `dial_timeout` `(integer: 10)` - Number of second to wait for a backend
- `dial_timeout` `(integer: 10)` - Number of second to wait for a backend
connection before timing out. Default is 10.
- `nas_port` `(integer: 10)` - The NAS-Port attribute of the RADIUS request.
- `nas_port` `(integer: 10)` - The NAS-Port attribute of the RADIUS request.
Defaults is 10.
### Sample Payload
@ -61,7 +61,7 @@ $ curl \
## Register User
Registers a new user and maps a set of policies to it. This path honors the
Registers a new user and maps a set of policies to it. This path honors the
distinction between the `create` and `update` capabilities inside ACL policies.
| Method | Path | Produces |
@ -71,7 +71,7 @@ distinction between the `create` and `update` capabilities inside ACL policies.
### Parameters
- `username` `(string: <required>)` - Username for this user.
- `policies` `(string: "")` - Comma-separated list of policies. If set to
- `policies` `(string: "")` - Comma-separated list of policies. If set to
empty string, only the `default` policy will be applicable to the user.
```json
@ -127,7 +127,7 @@ $ curl \
## Delete User
Deletes an existing username from the backend.
Deletes an existing username from the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -148,12 +148,11 @@ $ curl \
## List Users
List the users registered with the backend.
List the users registered with the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/radius/users` | `200 application/json` |
| `GET` | `/auth/radius/users?list=true` | `200 application/json` |
### Sample Request

136
website/source/api/auth/token/index.html.md
View File

@ -1,27 +1,26 @@
---
layout: "api"
page_title: "Token Auth Backend - HTTP API"
page_title: "Token - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-token"
description: |-
This is the API documentation for the Vault token authentication backend.
This is the API documentation for the Vault token auth method.
---
# Token Auth Backend HTTP API
# Token Auth Method (API)
This is the API documentation for the Vault token authentication backend. For
general information about the usage and operation of the token backend, please
see the [Vault Token backend documentation](/docs/auth/token.html).
This is the API documentation for the Vault token auth method. For
general information about the usage and operation of the token method, please
see the [Vault Token method documentation](/docs/auth/token.html).
## List Accessors
This endpoint lists token accessor. This requires `sudo` capability, and access
This endpoint lists token accessor. This requires `sudo` capability, and access
to it should be tightly controlled as the accessors can be used to revoke very
large numbers of tokens and their associated leases at once.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/token/accessors` | `200 application/json` |
| `GET` | `/auth/token/accessors?list=true` | `200 application/json` |
### Sample Request
@ -68,37 +67,37 @@ during this call.
### Parameters
- `id` `(string: "")` – The ID of the client token. Can only be specified by a
- `id` `(string: "")` – The ID of the client token. Can only be specified by a
root token. Otherwise, the token ID is a randomly generated UUID.
- `role_name` `(string: "")` – The name of the token role.
- `policies` `(array: "")` – A list of policies for the token. This must be a
- `policies` `(array: "")` – 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.
- `meta` `(map: {})` – A map of string to string valued metadata. This is
passed through to the audit backends.
- `no_parent` `(bool: false)` - If true and set by a root caller, the token will
- `meta` `(map: {})` – A map of string to string valued metadata. This is
passed through to the audit devices.
- `no_parent` `(bool: false)` - 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.
- `no_default_policy` `(bool: false)` - If true the `default` policy will not be
- `no_default_policy` `(bool: false)` - If true the `default` policy will not be
contained in this token's policy set.
- `renewable` `(bool: true)` - Set to `false` to disable the ability of the token
to be renewed past its initial TTL. Setting the value to `true` will allow
the token to be renewable up to the system/mount maximum TTL.
- `lease` `(string: "")` - DEPRECATED; use `ttl` instead
- `ttl` `(string: "")` -The TTL period of the token, provided as "1h", where
- `ttl` `(string: "")` -The TTL period of the token, provided as "1h", where
hour is the largest suffix. If not provided, the token is valid for the
[default lease TTL](/docs/configuration/index.html), or indefinitely if the
[default lease TTL](/docs/configuration/index.html), or indefinitely if the
root policy is used.
- `explicit_max_ttl` `(string: "")` - If set, the token will have an explicit
max TTL set upon it. This maximum token TTL *cannot* be changed later, and
unlike with normal tokens, updates to the system/mount max TTL value will
have no effect at renewal time -- the token will never be able to be renewed
or used past the value set at issue time.
- `explicit_max_ttl` `(string: "")` - If set, the token will have an explicit
max TTL set upon it. This maximum token TTL *cannot* be changed later, and
unlike with normal tokens, updates to the system/mount max TTL value will
have no effect at renewal time -- the token will never be able to be renewed
or used past the value set at issue time.
- `display_name` `(string: "token")` - The display name of the token.
- `num_uses` `(integer: 0)` - The maximum uses for the given token. This can be
used to create a one-time-token or limited use token. The value of 0 has no
- `num_uses` `(integer: 0)` - The maximum uses for the given token. This can be
used to create a one-time-token or limited use token. The value of 0 has no
limit to the number of uses.
- `period` `(string: "")` - If specified, the token will be periodic; it will have
no maximum TTL (unless an "explicit-max-ttl" is also set) but every renewal
- `period` `(string: "")` - If specified, the token will be periodic; it will have
no maximum TTL (unless an "explicit-max-ttl" is also set) but every renewal
will use the given period. Requires a root/sudo token to use.
### Sample Payload
@ -134,7 +133,7 @@ $ curl \
"auth": {
"client_token": "ABCD",
"policies": [
"web",
"web",
"stage"
],
"metadata": {
@ -184,12 +183,12 @@ $ curl \
"data": {
"id": "ClientToken",
"policies": [
"web",
"web",
"stage"
],
"path": "auth/github/login",
"meta": {
"user": "armon",
"user": "armon",
"organization": "hashicorp"
},
"display_name": "github-armon",
@ -221,12 +220,12 @@ $ curl \
"data": {
"id": "ClientToken",
"policies": [
"web",
"web",
"stage"
],
"path": "auth/github/login",
"meta": {
"user": "armon",
"user": "armon",
"organization": "hashicorp"
},
"display_name": "github-armon",
@ -282,7 +281,7 @@ $ curl \
"orphan": false,
"path": "auth/token/create",
"policies": [
"default",
"default",
"web"
],
"ttl": 2591976
@ -294,8 +293,8 @@ $ curl \
## Renew a Token
Renews a lease associated with a token. This is used to prevent the expiration
of a token, and the automatic revocation of it. Token renewal is possible only
Renews a lease associated with a token. This is used to prevent the expiration
of a token, and the automatic revocation of it. Token renewal is possible only
if there is a lease associated with it.
| Method | Path | Produces |
@ -305,9 +304,9 @@ if there is a lease associated with it.
### Parameters
- `token` `(string: <required>)` - Token to renew. This can be part of the URL
- `token` `(string: <required>)` - Token to renew. This can be part of the URL
or the body.
- `increment` `(string: "")` - An optional requested lease increment can be
- `increment` `(string: "")` - An optional requested lease increment can be
provided. This increment may be ignored.
### Sample Payload
@ -335,7 +334,7 @@ $ curl \
"auth": {
"client_token": "ABCD",
"policies": [
"web",
"web",
"stage"
],
"metadata": {
@ -349,8 +348,8 @@ $ curl \
## Renew a Token (Self)
Renews a lease associated with the calling token. This is used to prevent the
expiration of a token, and the automatic revocation of it. Token renewal is
Renews a lease associated with the calling token. This is used to prevent the
expiration of a token, and the automatic revocation of it. Token renewal is
possible only if there is a lease associated with it.
| Method | Path | Produces |
@ -359,7 +358,7 @@ possible only if there is a lease associated with it.
### Parameters
- `increment` `(string: "")` - An optional requested lease increment can be
- `increment` `(string: "")` - An optional requested lease increment can be
provided. This increment may be ignored.
### Sample Payload
@ -387,7 +386,7 @@ $ curl \
"auth": {
"client_token": "ABCD",
"policies": [
"web",
"web",
"stage"
],
"metadata": {
@ -401,7 +400,7 @@ $ curl \
## Revoke a Token
Revokes a token and all child tokens. When the token is revoked, all secrets
Revokes a token and all child tokens. When the token is revoked, all secrets
generated with it are also revoked.
| Method | Path | Produces |
@ -432,7 +431,7 @@ $ curl \
## Revoke a Token (Self)
Revokes the token used to call it and all child tokens. When the token is
Revokes the token used to call it and all child tokens. When the token is
revoked, all dynamic secrets generated with it are also revoked.
| Method | Path | Produces |
@ -451,7 +450,7 @@ $ curl \
## Revoke a Token Accessor
Revoke the token associated with the accessor and all the child tokens. This is
meant for purposes where there is no access to token ID but there is need to
meant for purposes where there is no access to token ID but there is need to
revoke a token and its children.
| Method | Path | Produces |
@ -494,7 +493,7 @@ endpoint.
### Parameters
- `token` `(string: <required>)` - Token to revoke. This can be part of the URL
- `token` `(string: <required>)` - Token to revoke. This can be part of the URL
or the body.
### Sample Payload
@ -566,7 +565,6 @@ List available token roles.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/token/roles` | `200 application/json` |
| `GET` | `/auth/token/roles?list=true` | `200 application/json` |
### Sample Request
@ -592,7 +590,7 @@ $ curl \
## Create/Update Token Role
Creates (or replaces) the named role. Roles enforce specific behavior when
Creates (or replaces) the named role. Roles enforce specific behavior when
creating tokens that allow token functionality that is otherwise not
available or would require `sudo`/root privileges to access. Role
parameters, when set, override any provided options to the `create`
@ -607,38 +605,38 @@ endpoint.
### Parameters
- `role_name` `(string: <required>)` – The name of the token role.
- `allowed_policies` `(list: [])` – If set, tokens can be created with any
subset of the policies in this list, rather than the normal semantics of
tokens being a subset of the calling token's policies. The parameter is a
comma-delimited string of policy names. If at creation time
`no_default_policy` is not set and `"default"` is not contained in
`disallowed_policies`, the `"default"` policy will be added to the created
- `allowed_policies` `(list: [])` – If set, tokens can be created with any
subset of the policies in this list, rather than the normal semantics of
tokens being a subset of the calling token's policies. The parameter is a
comma-delimited string of policy names. If at creation time
`no_default_policy` is not set and `"default"` is not contained in
`disallowed_policies`, the `"default"` policy will be added to the created
token automatically.
- `disallowed_policies` `(list: [])` – If set, successful token creation via
this role will require that no policies in the given list are requested. The
parameter is a comma-delimited string of policy names. Adding `"default"` to
- `disallowed_policies` `(list: [])` – If set, successful token creation via
this role will require that no policies in the given list are requested. The
parameter is a comma-delimited string of policy names. Adding `"default"` to
this list will prevent `"default"` from being added automatically to created
tokens.
- `orphan` `(bool: true)` - If `true`, tokens created against this policy will
be orphan tokens (they will have no parent). As such, they will not be
- `orphan` `(bool: true)` - If `true`, tokens created against this policy will
be orphan tokens (they will have no parent). As such, they will not be
automatically revoked by the revocation of any other token.
- `period` `(string: "")` - If specified, the token will be periodic; it will have
no maximum TTL (unless an "explicit-max-ttl" is also set) but every renewal
- `period` `(string: "")` - If specified, the token will be periodic; it will have
no maximum TTL (unless an "explicit-max-ttl" is also set) but every renewal
will use the given period. Requires a root/sudo token to use.
- `renewable` `(bool: true)` - Set to `false` to disable the ability of the token
to be renewed past its initial TTL. Setting the value to `true` will allow
the token to be renewable up to the system/mount maximum TTL.
- `explicit_max_ttl` `(string: "")` - If set, the token will have an explicit
max TTL set upon it. This maximum token TTL *cannot* be changed later, and
unlike with normal tokens, updates to the system/mount max TTL value will
have no effect at renewal time -- the token will never be able to be renewed
- `explicit_max_ttl` `(string: "")` - If set, the token will have an explicit
max TTL set upon it. This maximum token TTL *cannot* be changed later, and
unlike with normal tokens, updates to the system/mount max TTL value will
have no effect at renewal time -- the token will never be able to be renewed
or used past the value set at issue time.
- `path_suffix` `(string: "")` - If set, tokens created against this role will
- `path_suffix` `(string: "")` - If set, tokens created against this role will
have the given suffix as part of their path in addition to the role name. This
can be useful in certain scenarios, such as keeping the same role name in the
future but revoking all tokens created against it before some point in time.
can be useful in certain scenarios, such as keeping the same role name in the
future but revoking all tokens created against it before some point in time.
The suffix can be changed, allowing new callers to have the new suffix as part
of their path, and then tokens with the old suffix can be revoked via
of their path, and then tokens with the old suffix can be revoked via
`sys/revoke-prefix`.
### Sample Payload
@ -688,7 +686,7 @@ $ curl \
Performs some maintenance tasks to clean up invalid entries that may remain
in the token store. Generally, running this is not needed unless upgrade
notes or support personnel suggest it. This may perform a lot of I/O to the
storage backend so should be used sparingly.
storage method so should be used sparingly.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -701,4 +699,4 @@ $ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://vault.rocks/v1/auth/token/tidy
```
```

23
website/source/api/auth/userpass/index.html.md
View File

@ -1,20 +1,20 @@
---
layout: "api"
page_title: "Userpass Auth Backend - HTTP API"
page_title: "Userpass - Auth Methods - HTTP API"
sidebar_current: "docs-http-auth-userpass"
description: |-
This is the API documentation for the Vault username and password
authentication backend.
auth method.
---
# Username & Password Auth Backend HTTP API
# Userpass Auth Method (HTTP API)
This is the API documentation for the Vault Username & Password authentication backend. For
general information about the usage and operation of the Username and Password backend, please
see the [Vault Userpass backend documentation](/docs/auth/userpass.html).
This is the API documentation for the Vault Username & Password auth method. For
general information about the usage and operation of the Username and Password method, please
see the [Vault Userpass method documentation](/docs/auth/userpass.html).
This documentation assumes the Username & Password backend is mounted at the `/auth/userpass`
path in Vault. Since it is possible to mount auth backends at any location,
This documentation assumes the Username & Password method is mounted at the `/auth/userpass`
path in Vault. Since it is possible to mount auth methods at any location,
please update your API calls accordingly.
## Create/Update User
@ -28,7 +28,7 @@ Create a new user or update an existing user. This path honors the distinction b
### Parameters
- `username` `(string: <required>)` – The username for the user.
- `password` `(string: <required>)` - The password for the user. Only required
- `password` `(string: <required>)` - The password for the user. Only required
when creating the user.
- `policies` `(string: "")` – Comma-separated list of policies. If set to empty
string, only the `default` policy will be applicable to the user.
@ -89,7 +89,7 @@ $ curl \
## Delete User
This endpoint deletes the user from the backend.
This endpoint deletes the user from the method.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -177,7 +177,6 @@ List available userpass users.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/auth/userpass/users` | `200 application/json` |
| `GET` | `/auth/userpass/users?list=true` | `200 application/json` |
### Sample Request
@ -251,4 +250,4 @@ $ curl \
"renewable": true
}
}
```
```

8
website/source/api/index.html.md
View File

@ -40,12 +40,12 @@ user may have a client token sent to her. The client token must be sent as the
Otherwise, a client token can be retrieved via [authentication
backends](/docs/auth/index.html).
Each authentication backend will have one or more unauthenticated login
Each auth method will have one or more unauthenticated login
endpoints. These endpoints can be reached without any authentication, and are
used for authentication itself. These endpoints are specific to each
authentication backend.
auth method.
Login endpoints for authentication backends that generate an identity will be
Login endpoints for auth methods that generate an identity will be
sent down via JSON. The resulting token should be saved on the client or passed
via the `X-Vault-Token` header for future requests.
@ -122,7 +122,7 @@ For more examples, please look at the Vault API client.
## Help
To retrieve the help for any API within Vault, including mounted
backends, credential providers, etc. then append `?help=1` to any
backends, auth methods, etc. then append `?help=1` to any
URL. If you have valid permission to access the path, then the help text
will be returned with the following structure:

13
website/source/api/secret/databases/index.html.md
View File

@ -41,7 +41,7 @@ list of additional parameters.
- `allowed_roles` `(slice: [])` - Array or comma separated string of the roles
allowed to use this connection. Defaults to empty (no roles), if contains a
"*" any role can use this connection.
"*" any role can use this connection.
### Sample Payload
@ -160,7 +160,7 @@ This endpoint creates or updates a role definition.
is specified as part of the URL.
- `db_name` `(string: <required>)` - The name of the database connection to use
for this role.
for this role.
- `default_ttl` `(string/int: 0)` - Specifies the TTL for the leases
associated with this role. Accepts time suffixed strings ("1h") or an integer
@ -172,21 +172,21 @@ This endpoint creates or updates a role definition.
- `creation_statements` `(string: <required>)` – Specifies the database
statements executed to create and configure a user. See the plugin's API page
for more information on support and formatting for this parameter.
for more information on support and formatting for this parameter.
- `revocation_statements` `(string: "")` – Specifies the database statements to
be executed to revoke a user. See the plugin's API page for more information
on support and formatting for this parameter.
on support and formatting for this parameter.
- `rollback_statements` `(string: "")` – Specifies the database statements to be
executed rollback a create operation in the event of an error. Not every
plugin type will support this functionality. See the plugin's API page for
more information on support and formatting for this parameter.
more information on support and formatting for this parameter.
- `renew_statements` `(string: "")` – Specifies the database statements to be
executed to renew a user. Not every plugin type will support this
functionality. See the plugin's API page for more information on support and
formatting for this parameter.
formatting for this parameter.
@ -256,7 +256,6 @@ returned, not any values.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
| `LIST` | `/database/roles` | `200 application/json` |
| `GET` | `/database/roles?list=true` | `200 application/json` |
### Sample Request

34
website/source/api/system/auth.html.md
View File

@ -3,18 +3,18 @@ layout: "api"
page_title: "/sys/auth - HTTP API"
sidebar_current: "docs-http-system-auth"
description: |-
The `/sys/auth` endpoint is used to manage auth backends in Vault.
The `/sys/auth` endpoint is used to manage auth methods in Vault.
---
# `/sys/auth`
The `/sys/auth` endpoint is used to list, create, update, and delete auth
backends. Auth backends convert user or machine-supplied information into a
methods. Auth methods convert user or machine-supplied information into a
token which can be used for all future requests.
## List Auth Backends
## List Auth Methods
This endpoint lists all enabled auth backends.
This endpoint lists all enabled auth methods.
| Method | Path | Produces |
| :------- | :--------------------------- | :--------------------- |
@ -47,13 +47,13 @@ $ curl \
}
```
## Mount Auth Backend
## Mount Auth Method
This endpoint enables a new auth backend. After mounting, the auth backend can
This endpoint enables a new auth method. After mounting, the auth method can
be accessed and configured via the auth path specified as part of the URL. This
auth path will be nested under the `auth` prefix.
For example, mounting the "foo" auth backend will make it accessible at
For example, mounting the "foo" auth method will make it accessible at
`/auth/foo`.
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
@ -66,30 +66,30 @@ For example, mounting the "foo" auth backend will make it accessible at
### Parameters
- `path` `(string: <required>)` – Specifies the path in which to mount the auth
backend. This is part of the request URL.
method. This is part of the request URL.
- `description` `(string: "")` – Specifies a human-friendly description of the
auth backend.
auth method.
- `type` `(string: <required>)` – Specifies the name of the authentication
backend type, such as "github" or "token".
method type, such as "github" or "token".
- `config` `(map<string|string>: nil)` – Specifies configuration options for
this mount. These are the possible values:
- `plugin_name`
The plugin_name can be provided in the config map or as a top-level option,
The plugin_name can be provided in the config map or as a top-level option,
with the former taking precedence.
- `plugin_name` `(string: "")` – Specifies the name of the auth plugin to
use based from the name in the plugin catalog. Applies only to plugin
backends.
methods.
Additionally, the following options are allowed in Vault open-source, but
relevant functionality is only supported in Vault Enterprise:
- `local` `(bool: false)` – Specifies if the auth backend is a local mount
- `local` `(bool: false)` – Specifies if the auth method is a local mount
only. Local mounts are not replicated nor (if a secondary) removed by
replication.
@ -112,9 +112,9 @@ $ curl \
https://vault.rocks/v1/sys/auth/my-auth
```
## Unmount Auth Backend
## Unmount Auth Method
This endpoint un-mounts the auth backend at the given auth path.
This endpoint un-mounts the auth method at the given auth path.
- **`sudo` required** – This endpoint requires `sudo` capability in addition to
any path-specific capabilities.
@ -137,7 +137,7 @@ $ curl \
https://vault.rocks/v1/sys/auth/my-auth
```
## Read Auth Backend Tuning
## Read Auth Method Tuning
This endpoint reads the given auth path's configuration. _This endpoint requires
`sudo` capability on the final path, but the same functionality can be achieved
@ -171,7 +171,7 @@ $ curl \
}
```
## Tune Auth Backend
## Tune Auth Method
Tune configuration parameters for a given auth path. _This endpoint
requires `sudo` capability on the final path, but the same functionality

154
website/source/docs/auth/app-id.html.md
View File

@ -1,31 +1,24 @@
---
layout: "docs"
page_title: "Auth Backend: App ID"
page_title: "AppID - Auth Methods"
sidebar_current: "docs-auth-appid"
description: |-
The App ID auth backend is a mechanism for machines to authenticate with Vault.
The AppID auth method is a mechanism for machines to authenticate with Vault.
---
# Auth Backend: App ID
# AppID Auth Method
Name: `app-id`
~> **DEPRECATED!** As of Vault 0.6.1, AppID is deprecated in favor of
[AppRole](/docs/auth/approle.html). AppRole can accommodate the same workflow as
AppID while enabling much more secure and flexible management and other types
of authentication workflows. No new features or enhancements are planned for App
ID, and new users should use AppRole instead of AppID.
## Deprecation Notice
As of Vault 0.6.1, App ID is deprecated in favor of
[AppRole](/docs/auth/approle.html). AppRole can
accommodate the same workflow as App ID while enabling much more secure and
flexible management and other types of authentication workflows. No new
features or enhancements are planned for App ID, and new users should use
AppRole instead of App ID.
## Introduction
The App ID auth backend is a mechanism for machines to authenticate with Vault.
The AppID auth method is a mechanism for machines to authenticate with Vault.
It works by requiring two hard-to-guess unique pieces of information: a unique
app ID, and a unique user ID.
The goal of this credential provider is to allow elastic users (dynamic
The goal of this auth method is to allow elastic users (dynamic
machines, containers, etc.) to authenticate with Vault without having to store
passwords outside of Vault. It is a single method of solving the
chicken-and-egg problem of setting up Vault access on a machine. With this
@ -37,92 +30,99 @@ salt).
An example, real world process for using this provider:
1. Create unique app IDs (UUIDs work well) and map them to policies. (Path:
map/app-id/<app-id>)
1. Create unique app IDs (UUIDs work well) and map them to policies. (Path:
map/app-id/<app-id>)
2. Store the app IDs within configuration management systems.
2. Store the app IDs within configuration management systems.
3. An out-of-band process run by security operators map unique user IDs to
these app IDs. Example: when an instance is launched, a cloud-init system
tells security operators a unique ID for this machine. This process can be
scripted, but the key is that it is out-of-band and out of reach of
configuration management. (Path: map/user-id/<user-id>)
3. An out-of-band process run by security operators map unique user IDs to
these app IDs. Example: when an instance is launched, a cloud-init system
tells security operators a unique ID for this machine. This process can be
scripted, but the key is that it is out-of-band and out of reach of
configuration management. (Path: map/user-id/<user-id>)
4. A new server is provisioned. Configuration management configures the app
ID, the server itself detects its user ID. With both of these pieces of
information, Vault can be accessed according to the policy set by the app
ID.
4. A new server is provisioned. Configuration management configures the app
ID, the server itself detects its user ID. With both of these pieces of
information, Vault can be accessed according to the policy set by the app
ID.
More details on this process follow:
The app ID is a unique ID that maps to a set of policies. This ID is generated
by an operator and configured into the backend. The ID itself is usually a
UUID, but any hard-to-guess unique value can be used.
- The app ID is a unique ID that maps to a set of policies. This ID is generated
by an operator and configured into the method. The ID itself is usually a
UUID, but any hard-to-guess unique value can be used.
After creating app IDs, an operator authorizes a fixed set of user IDs with
each app ID. When a valid {app ID, user ID} tuple is given to the "login" path,
then the user is authenticated with the configured app ID policies.
- After creating app IDs, an operator authorizes a fixed set of user IDs with
each app ID. When a valid {app ID, user ID} tuple is given to the "login"
path, then the user is authenticated with the configured app ID policies.
The user ID can be any value (just like the app ID), however it is generally a
value unique to a machine, such as a MAC address or instance ID, or a value
hashed from these unique values.
- The user ID can be any value (just like the app ID), however it is generally a
value unique to a machine, such as a MAC address or instance ID, or a value
hashed from these unique values.
## Authentication
#### Via the CLI
Via the CLI:
Use `vault write`, for example: `vault write auth/app-id/login/[app-id] user_id=[user-id]`
```text
$ vault write auth/app-id/login/:app-id user_id=:user_id
```
#### Via the API
Via the API:
The endpoint for the App ID login is `auth/app-id/login/[app_id]`. The client is expected
to provide the `user_id` parameter as part of the request.
```text
$ curl \
--header "X-Vault-Token: ..." \
--method POST \
--data '{"user_id": ":user_id"}' \
https://vault.rocks/v1/auth/app-id/login/:app_id
```
## Configuration
First you must enable the App ID auth backend:
Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.
```
$ vault auth-enable app-id
Successfully enabled 'app-id' at 'app-id'!
```
1. Enable the AppID auth method:
Now when you run `vault auth -methods`, the App ID backend is available:
```text
$ vault auth enable app-id
```
```
Path Type Description
app-id/ app-id
token/ token token based credentials
```
1. Configure it with the set of AppIDs, user IDs, and the mapping between them:
To use the App ID auth backend, an operator must configure it with
the set of App IDs, user IDs, and the mapping between them. An
example is shown below, use `vault path-help` for more details.
```text
$ vault write auth/app-id/map/app-id/foo value=admins display_name=foo
# ...
```
$ vault write auth/app-id/map/app-id/foo value=admins display_name=foo
...
$ vault write auth/app-id/map/user-id/bar value=foo cidr_block=10.0.0.0/16
# ...
```
$ vault write auth/app-id/map/user-id/bar value=foo cidr_block=10.0.0.0/16
...
```
This will create an AppID "foo" that associates with the policy "admins".
The `display_name` sets the display name for audit logs and secrets. Next,
we configure the user ID "bar" and say that the user ID bar can be paired
with "foo" but only if the client is in the "10.0.0.0/16" CIDR block. The
`cidr_block` configuration is optional.
The above creates an App ID "foo" that associates with the policy "admins".
The `display_name` sets the display name for audit logs and secrets.
Next, we configure the user ID "bar" and say that the user ID bar
can be paired with "foo" but only if the client is in the "10.0.0.0/16" CIDR block.
The `cidr_block` configuration is optional.
This means that if a client authenticates and provide both "foo" and "bar",
then the app ID will authenticate that client with the policy "admins".
This means that if a client authenticates and provide both "foo" and "bar",
then the app ID will authenticate that client with the policy "admins".
In practice, both the user and app ID are likely hard-to-guess UUID-like
values.
In practice, both the user and app ID are likely hard-to-guess UUID-like values.
Note that it is possible to authorize multiple app IDs with each user ID by
writing them as comma-separated values to the user ID mapping:
Note that it is possible to authorize multiple app IDs with each
user ID by writing them as comma-separated values to the user ID mapping:
```text
$ vault write auth/app-id/map/user-id/bar value=foo,baz cidr_block=10.0.0.0/16
# ...
```
```
$ vault write auth/app-id/map/user-id/bar value=foo,baz cidr_block=10.0.0.0/16
...
```
## API
The AppID auth method has a full HTTP API. Please see the
[AppID auth method API](/api/auth/app-id/index.html) for more
details.

331
website/source/docs/auth/approle.html.md
View File

@ -1,34 +1,188 @@
---
layout: "docs"
page_title: "Auth Backend: AppRole"
page_title: "AppRole - Auth Methods"
sidebar_current: "docs-auth-approle"
description: |-
The AppRole backend allows machines and services to authenticate with Vault.
The AppRole auth method allows machines and services to authenticate with
Vault.
---
# Auth Backend: AppRole
# AppRole Auth Method
This backend allows machines and services (_apps_) to authenticate with Vault
via a series of administratively defined _roles_: AppRoles. The open design of
`AppRole` enables a varied set of workflows and configurations to handle large
numbers of apps and their needs. This backend is oriented to automated
workflows, and is the successor to the `App-ID` backend.
The `approle` auth method allows machines or _apps_ to authenticate with Vault
Vault-defined _roles_. The open design of `AppRole` enables a varied set of
workflows and configurations to handle large numbers of apps. This auth method
is oriented to automated workflows (machines and services), and is less useful
for human operators.
## AppRoles
An AppRole represents a set of Vault policies and login constraints that must
An "AppRole" represents a set of Vault policies and login constraints that must
be met to receive a token with those policies. The scope can be as narrow or
broad as desired -- an AppRole can be created for a particular machine, or even
broad as desired. An AppRole can be created for a particular machine, or even
a particular user on that machine, or a service spread across machines. The
credentials required for successful login depend upon the constraints set on
the AppRole associated with the credentials.
## Authentication
### Via the CLI
The default path is `/approle`. If this auth method was enabled at a different
path, specify `auth/my-path/login` instead.
```text
$ vault write auth/approle/login \
role_id=db02de05-fa39-4855-059b-67221c5c2f63 \
secret_id=6a174c20-f6de-a53c-74d2-6018fcceff64
Key Value
--- -----
token 65b74ffd-842c-fd43-1386-f7d7006e520a
token_accessor 3c29bc22-5c72-11a6-f778-2bc8f48cea0e
token_duration 20m0s
token_renewable true
token_policies [default]
```
### Via the API
The default endpoint is `auth/approle/login`. If this auth method was enabled
at a different path, use that value instead of `approle`.
```sh
$ curl \
--request POST \
--data '{"role_id":"988a9df-...","secret_id":"37b74931..."}' \
https://vault.rocks/v1/auth/approle/login
```
The response will contain the token at `auth.client_token`:
```json
{
"auth": {
"renewable": true,
"lease_duration": 2764800,
"metadata": {},
"policies": [
"default",
"dev-policy",
"test-policy"
],
"accessor": "5d7fb475-07cb-4060-c2de-1ca3fcbf0c56",
"client_token": "98a4c7ab-b1fe-361b-ba0b-e307aacfd587"
}
}
```
## Configuration
Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.
### Via the CLI
1. Enable the AppRole auth method:
```text
$ vault auth enable approle
```
1. Create a named role:
```text
$ vault write auth/approle/role/my-role \
secret_id_ttl=10m \
token_num_uses=10 \
token_ttl=20m \
token_max_ttl=30m \
secret_id_num_uses=40
```
For the complete list of configuration options, please see the API
documentation.
1. Fetch the RoleID of the AppRole:
```text
$ vault read auth/approle/role/my-role/role-id
role_id db02de05-fa39-4855-059b-67221c5c2f63
```
1. Get a SecretID issued against the AppRole:
```text
$ vault write -f auth/approle/role/my-role/secret-id
secret_id 6a174c20-f6de-a53c-74d2-6018fcceff64
secret_id_accessor c454f7e5-996e-7230-6074-6ef26b7bcf86
```
### Via the API
1. Enable the AppRole auth method:
```sh
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"type": "approle"}' \
https://vault.rocks/v1/sys/auth/approle
```
1. Create an AppRole with desired set of policies:
```sh
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"policies": "dev-policy,test-policy"}' \
https://vault.rocks/v1/auth/approle/role/my-role
```
1. Fetch the identifier of the role:
```sh
$ curl \
--header "X-Vault-Token: ..." \
https://vault.rocks/v1/auth/approle/role/my-role/role-id
```
The response will look like:
```json
{
"data": {
"role_id": "988a9dfd-ea69-4a53-6cb6-9d6b86474bba"
}
}
```
1. Create a new secret identifier under the role:
```sh
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
https://vault.rocks/v1/auth/approle/role/my-role/secret-id
```
The response will look like:
```json
{
"data": {
"secret_id_accessor": "45946873-1d96-a9d4-678c-9229f74386a5",
"secret_id": "37b74931-c4cd-d49a-9246-ccc62d682a25"
}
}
```
## Credentials/Constraints
### RoleID
RoleID is an identifier that selects the AppRole against which the other
credentials are evaluated. When authenticating against this backend's login
credentials are evaluated. When authenticating against this auth method's login
endpoint, the RoleID is a required argument (via `role_id`) at all times. By
default, RoleIDs are unique UUIDs, which allow them to serve as secondary
secrets to the other credential information. However, they can be set to
@ -51,7 +205,7 @@ tokens, SecretIDs have properties like usage-limit, TTLs and expirations.
If the SecretID used for login is fetched from an AppRole, this is operating in
Pull mode. If a "custom" SecretID is set against an AppRole by the client, it
is referred to as a Push mode. Push mode mimics the behavior of the deprecated
App-ID backend; however, in most cases Pull mode is the better approach. The
App-ID auth method; however, in most cases Pull mode is the better approach. The
reason is that Push mode requires some other system to have knowledge of the
full set of client credentials (RoleID and SecretID) in order to create the
entry, even if these are then distributed via different paths. However, in Pull
@ -69,157 +223,14 @@ should be preferred.
`role_id` is a required credential at the login endpoint. AppRole pointed to by
the `role_id` will have constraints set on it. This dictates other `required`
credentials for login. The `bind_secret_id` constraint requires `secret_id` to
be presented at the login endpoint. Going forward, this backend can support
be presented at the login endpoint. Going forward, this auth method can support
more constraint parameters to support varied set of Apps. Some constraints will
not require a credential, but still enforce constraints for login. For
example, `bound_cidr_list` will only allow requests coming from IP addresses
belonging to configured CIDR blocks on the AppRole.
## Comparison to Tokens
## Authentication
### Via the CLI
#### Enable AppRole authentication
```shell
$ vault auth-enable approle
```
#### Create a role
```shell
$ vault write auth/approle/role/testrole secret_id_ttl=10m token_num_uses=10 token_ttl=20m token_max_ttl=30m secret_id_num_uses=40
```
#### Fetch the RoleID of the AppRole
```shell
$ vault read auth/approle/role/testrole/role-id
```
```shell
role_id db02de05-fa39-4855-059b-67221c5c2f63
```
#### Get a SecretID issued against the AppRole
```shell
$ vault write -f auth/approle/role/testrole/secret-id
```
```shell
secret_id 6a174c20-f6de-a53c-74d2-6018fcceff64
secret_id_accessor c454f7e5-996e-7230-6074-6ef26b7bcf86
```
#### Login to get a Vault Token
```shell
$ vault write auth/approle/login role_id=db02de05-fa39-4855-059b-67221c5c2f63 secret_id=6a174c20-f6de-a53c-74d2-6018fcceff64
```
```shell
token 65b74ffd-842c-fd43-1386-f7d7006e520a
token_accessor 3c29bc22-5c72-11a6-f778-2bc8f48cea0e
token_duration 20m0s
token_renewable true
token_policies [default]
```
### Via the API
#### Enable the AppRole authentication.
```javascript
$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" -d '{"type":"approle"}' http://127.0.0.1:8200/v1/sys/auth/approle
```
#### Create an AppRole with desired set of policies.
```javascript
$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" -d '{"policies":"dev-policy,test-policy"}' http://127.0.0.1:8200/v1/auth/approle/role/testrole
```
#### Fetch the identifier of the role.
```javascript
$ curl -X GET -H "X-Vault-Token:$VAULT_TOKEN" http://127.0.0.1:8200/v1/auth/approle/role/testrole/role-id | jq .
```
```javascript
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"role_id": "988a9dfd-ea69-4a53-6cb6-9d6b86474bba"
},
"lease_duration": 0,
"renewable": false,
"lease_id": "",
"request_id": "ef5c9b3f-e15e-0527-5457-79b4ecfe7b60"
}
```
#### Create a new secret identifier under the role.
```javascript
$ curl -X POST -H "X-Vault-Token:$VAULT_TOKEN" http://127.0.0.1:8200/v1/auth/approle/role/testrole/secret-id | jq .
```
```javascript
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"secret_id_accessor": "45946873-1d96-a9d4-678c-9229f74386a5",
"secret_id": "37b74931-c4cd-d49a-9246-ccc62d682a25"
},
"lease_duration": 0,
"renewable": false,
"lease_id": "",
"request_id": "c98fa1c2-7565-fd45-d9de-0b43c307f2aa"
}
```
#### Perform the login operation to fetch a new Vault token.
```javascript
$ curl -X POST \
-d '{"role_id":"988a9dfd-ea69-4a53-6cb6-9d6b86474bba","secret_id":"37b74931-c4cd-d49a-9246-ccc62d682a25"}' \
http://127.0.0.1:8200/v1/auth/approle/login | jq .
```
```javascript
{
"auth": {
"renewable": true,
"lease_duration": 2764800,
"metadata": {},
"policies": [
"default",
"dev-policy",
"test-policy"
],
"accessor": "5d7fb475-07cb-4060-c2de-1ca3fcbf0c56",
"client_token": "98a4c7ab-b1fe-361b-ba0b-e307aacfd587"
},
"warnings": null,
"wrap_info": null,
"data": null,
"lease_duration": 0,
"renewable": false,
"lease_id": "",
"request_id": "988fb8db-ce3b-0167-0ac7-1a568b902d75"
}
```
## API
The AppRole authentication backend has a full HTTP API. Please see the
The AppRole auth method has a full HTTP API. Please see the
[AppRole API](/api/auth/approle/index.html) for more
details.
details.

122
website/source/docs/auth/aws.html.md
View File

@ -1,16 +1,16 @@
---
layout: "docs"
page_title: "Auth Backend: AWS"
page_title: "AWS - Auth Methods"
sidebar_current: "docs-auth-aws"
description: |-
The aws backend allows automated authentication of AWS entities.
The aws auth method allows automated authentication of AWS entities.
---
# Auth Backend: aws
# AWS Auth Method
The aws auth backend provides an automated mechanism to retrieve
a Vault token for AWS EC2 instances and IAM principals. Unlike most Vault
authentication backends, this backend does not require manual first-deploying, or
The `aws` auth method provides an automated mechanism to retrieve
a Vault token for AWS EC2 instances and IAM principals. Unlike most Vault
auth methods, this method does not require manual first-deploying, or
provisioning security-sensitive credentials (tokens, username/password, client
certificates, etc), by operators under many circumstances. It treats
AWS as a Trusted Third Party and uses either
@ -24,17 +24,17 @@ clients.
## Authentication Workflow
There are two authentication types present in the aws backend: `ec2` and `iam`.
There are two authentication types present in the aws auth method: `ec2` and `iam`.
Based on how you attempt to authenticate, Vault will determine if you are
attempting to use the `ec2` or `iam` type. Each has a different authentication
workflow, and each can solve different use cases. See the section on comparing
attempting to use the `ec2` or `iam` type. Each has a different authentication
workflow, and each can solve different use cases. See the section on comparing
the two auth methods below to help determine which method is more appropriate
for your use cases.
### EC2 Authentication Method
### EC2 auth method
Amazon EC2 instances have access to metadata which describes the instance. The
Vault EC2 authentication method leverages this components of this metadata to
Vault EC2 auth method leverages this components of this metadata to
authenticate and distribute an initial Vault token to an EC2 instance. The data
flow (which is also represented in the graphic below) is as follows:
@ -63,7 +63,7 @@ instance metadata.
There are various modifications to this workflow that provide more or less
security, as detailed later in this documentation.
### IAM Authentication Method
### IAM auth method
The AWS STS API includes a method,
[`sts:GetCallerIdentity`](http://docs.aws.amazon.com/STS/latest/APIReference/API_GetCallerIdentity.html),
@ -95,7 +95,7 @@ requires that this header be one of the headers included in the AWS signature
and relies upon AWS to authenticate that signature.
While AWS API endpoints support both signed GET and POST requests, for
simplicity, the aws backend supports only POST requests. It also does not
simplicity, the aws auth method supports only POST requests. It also does not
support `presigned` requests, i.e., requests with `X-Amz-Credential`,
`X-Amz-Signature`, and `X-Amz-SignedHeaders` GET query parameters containing the
authenticating information.
@ -105,13 +105,13 @@ of authorization around calls to `GetCallerIdentity`. For example, if you have
an IAM policy on your credential that requires all access to be MFA authenticated,
non-MFA authenticated credentials (i.e., raw credentials, not those retrieved
by calling `GetSessionToken` and supplying an MFA code) will still be able to
authenticate to Vault using this backend. It does not appear possible to enforce
authenticate to Vault using this method. It does not appear possible to enforce
an IAM principal to be MFA authenticated while authenticating to Vault.
## Authorization Workflow
The basic mechanism of operation is per-role. Roles are registered in the
backend and associated with a specific authentication type that cannot be
method and associated with a specific authentication type that cannot be
changed once the role has been created. Roles can also be associated with
various optional restrictions, such as the set of allowed policies and max TTLs
on the generated tokens. Each role can be specified with the constraints that
@ -119,7 +119,7 @@ are to be met during the login. For example, one such constraint that is
supported is to bind against AMI ID. A role which is bound to a specific AMI,
can only be used for login by EC2 instances that are deployed on the same AMI.
The iam authentication method allows you to specify a bound IAM principal ARN.
The iam auth method allows you to specify a bound IAM principal ARN.
Clients authenticating to Vault must have an ARN that matches the ARN bound to
the role they are attempting to login to. The bound ARN allows specifying a
wildcard at the end of the bound ARN. For example, if the bound ARN were
@ -139,9 +139,9 @@ only apply specifically to EC2 instances.
In many cases, an organization will use a "seed AMI" that is specialized after
bootup by configuration management or similar processes. For this reason, a
role entry in the backend can also be associated with a "role tag" when using
role entry in the method can also be associated with a "role tag" when using
the ec2 auth type. These tags
are generated by the backend and are placed as the value of a tag with the
are generated by the method and are placed as the value of a tag with the
given key on the EC2 instance. The role tag can be used to further restrict the
parameters set on the role, but cannot be used to grant additional privileges.
If a role with an AMI bind constraint has "role tag" enabled on the role, and
@ -149,8 +149,8 @@ the EC2 instance performing login does not have an expected tag on it, or if the
tag on the instance is deleted for some reason, authentication fails.
The role tags can be generated at will by an operator with appropriate API
access. They are HMAC-signed by a per-role key stored within the backend, allowing
the backend to verify the authenticity of a found role tag and ensure that it has
access. They are HMAC-signed by a per-role key stored within the method, allowing
the method to verify the authenticity of a found role tag and ensure that it has
not been tampered with. There is also a mechanism to blacklist role tags if one
has been found to be distributed outside of its intended set of machines.
@ -181,11 +181,11 @@ trusted to call AssumeRole. When this is configured, EC2 calls AssumeRole on
behalf of your instance, with a RoleSessionName corresponding to the
instance's instance ID. Thus, it is possible for Vault to extract the instance
ID out of the value it sees when an EC2 instance in an instance profile
authenticates to Vault with the iam authentication method. This is known as
authenticates to Vault with the iam auth method. This is known as
"inferencing." Vault can be configured, on a role-by-role basis, to infer that a
caller is an EC2 instance and, if so, apply further bindings that apply
specifically to EC2 instances -- most of the bindings available to the ec2
authentication backend.
auth method.
However, it is very important to note that if any entity other than an AWS
service is permitted to call AssumeRole on your role, then that entity can
@ -198,7 +198,7 @@ would like to take advantage of inferencing, then you should tightly restrict
who is able to call AssumeRole on the role, tightly restrict who is able to call
UpdateAssumeRolePolicy on the role, and monitor CloudTrail logs for calls to
AssumeRole and UpdateAssumeRolePolicy. All of these caveats apply equally to
using the iam authentication method without inferencing; the point is merely
using the iam auth method without inferencing; the point is merely
that Vault cannot offer an iron-clad guarantee about the inference and it is up
to operators to determine, based on their own AWS controls and use cases,
whether or not it's appropriate to configure inferencing.
@ -221,10 +221,10 @@ role. Some examples of how this works in practice:
## Comparison of the EC2 and IAM Methods
The iam and ec2 authentication methods serve similar and somewhat overlapping
The iam and ec2 auth methods serve similar and somewhat overlapping
functionality, in that both authenticate some type of AWS entity to Vault. To
help you determine which method is more appropriate for your use case, here is a
comparison of the two authentication methods.
comparison of the two auth methods.
* What type of entity is authenticated:
* The ec2 auth method authenticates only AWS EC2 instances and is specialized
@ -235,7 +235,7 @@ comparison of the two authentication methods.
include IAM users, IAM roles assumed from other accounts, AWS Lambdas that
are launched in an IAM role, or even EC2 instances that are launched in an
IAM instance profile. However, because it authenticates more generalized IAM
principals, this backend doesn't offer more granular controls beyond binding
principals, this method doesn't offer more granular controls beyond binding
to a given IAM principal without the use of inferencing.
* How the entities are authenticated
* The ec2 auth method authenticates instances by making use of the EC2
@ -246,7 +246,7 @@ comparison of the two authentication methods.
Because the instance identity document is signed by AWS, you have a strong
guarantee that it came from an EC2 instance.
* The iam auth method authenticates by having clients provide a specially
signed AWS API request which the backend then passes on to AWS to validate
signed AWS API request which the method then passes on to AWS to validate
the signature and tell Vault who created it. The actual secret (i.e.,
the AWS secret access key) is never transmitted over the wire, and the
AWS signature algorithm automatically expires requests after 15 minutes,
@ -276,11 +276,11 @@ comparison of the two authentication methods.
## Recommended Vault IAM Policy
This specifies the recommended IAM policy needed by the AWS auth backend. Note
that if you are using the same credentials for the AWS auth and secret backends
This specifies the recommended IAM policy needed by the AWS auth method. Note
that if you are using the same credentials for the AWS auth and secret methods
(e.g., if you're running Vault on an EC2 instance in an IAM instance profile),
then you will need to add additional permissions as required by the AWS secret
backend.
method.
```json
{
@ -330,31 +330,31 @@ are needed.
## Client Nonce
Note: this only applies to the ec2 authentication method.
Note: this only applies to the ec2 auth method.
If an unintended party gains access to the PKCS#7 signature of the identity
document (which by default is available to every process and user that gains
access to an EC2 instance), it can impersonate that instance and fetch a Vault
token. The backend addresses this problem by using a Trust On First Use (TOFU)
token. The method addresses this problem by using a Trust On First Use (TOFU)
mechanism that allows the first client to present the PKCS#7 signature of the
document to be authenticated and denying the rest. An important property of
this design is detection of unauthorized access: if an unintended party authenticates,
the intended client will be unable to authenticate and can raise an alert for
investigation.
During the first login, the backend stores the instance ID that authenticated
in a `whitelist`. One method of operation of the backend is to disallow any
During the first login, the method stores the instance ID that authenticated
in a `whitelist`. One method of operation of the method is to disallow any
authentication attempt for an instance ID contained in the whitelist, using the
`disallow_reauthentication` option on the role, meaning that an instance is
allowed to login only once. However, this has consequences for token rotation,
as it means that once a token has expired, subsequent authentication attempts
would fail. By default, reauthentication is enabled in this backend, and can be
would fail. By default, reauthentication is enabled in this method, and can be
turned off using `disallow_reauthentication` parameter on the registered role.
In the default method of operation, the backend will return a unique nonce
In the default method of operation, the method will return a unique nonce
during the first authentication attempt, as part of auth `metadata`. Clients
should present this `nonce` for subsequent login attempts and it should match
the `nonce` cached at the identity-whitelist entry at the backend. Since only
the `nonce` cached at the identity-whitelist entry at the method. Since only
the original client knows the `nonce`, only the original client is allowed to
reauthenticate. (This is the reason that this is a whitelist rather than a
blacklist; by default, it's keeping track of clients allowed to reauthenticate,
@ -369,7 +369,7 @@ access to other users or applications on the instance. It is also up to the
operator to ensure that client nonces are in fact unique; sharing nonces allows
a compromise of the nonce value to enable an attacker that gains access to any
EC2 instance to imitate the legitimate client on that instance. This is why
nonces can be disabled on the backend side in favor of only a single
nonces can be disabled on the method side in favor of only a single
authentication per instance; in some cases, such as when using ASGs, instances
are immutable and single-boot anyways, and in conjunction with a high max TTL,
reauthentication may not be needed (and if it is, the instance can simply be
@ -394,7 +394,7 @@ inferencing is used.
If the instance is required to have customized set of policies based on the
role it plays, the `role_tag` option can be used to provide a tag to set on
instances, for a given role. When this option is set, during login, along with
verification of PKCS#7 signature and instance health, the backend will query
verification of PKCS#7 signature and instance health, the method will query
for the value of a specific tag with the configured key that is attached to the
instance. The tag holds information that represents a *subset* of privileges that
are set on the role and are used to further restrict the set of the role's
@ -402,7 +402,7 @@ privileges for that particular instance.
A `role_tag` can be created using `auth/aws/role/<role>/tag` endpoint
and is immutable. The information present in the tag is SHA256 hashed and HMAC
protected. The per-role key to HMAC is only maintained in the backend. This prevents
protected. The per-role key to HMAC is only maintained in the method. This prevents
an adversarial operator from modifying the tag when setting it on the EC2 instance
in order to escalate privileges.
@ -426,9 +426,9 @@ Note: This only applies to the ec2 auth method.
If an EC2 instance loses its client nonce (due to a reboot, a stop/start of the
client, etc.), subsequent login attempts will not succeed. If the client nonce
is lost, normally the only option is to delete the entry corresponding to the
instance ID from the identity `whitelist` in the backend. This can be done via
instance ID from the identity `whitelist` in the method. This can be done via
the `auth/aws/identity-whitelist/<instance_id>` endpoint. This allows a new
client nonce to be accepted by the backend during the next login request.
client nonce to be accepted by the method during the next login request.
Under certain circumstances there is another useful setting. When the instance
is placed onto a host upon creation, it is given a `pendingTime` value in the
@ -436,11 +436,11 @@ instance identity document (documentation from AWS does not cover this option,
unfortunately). If an instance is stopped and started, the `pendingTime` value
is updated (this does not apply to reboots, however).
The backend can take advantage of this via the `allow_instance_migration`
The method can take advantage of this via the `allow_instance_migration`
option, which is set per-role. When this option is enabled, if the client nonce
does not match the saved nonce, the `pendingTime` value in the instance
identity document will be checked; if it is newer than the stored `pendingTime`
value, the backend assumes that the client was stopped/started and allows the
value, the method assumes that the client was stopped/started and allows the
client to log in successfully, storing the new nonce as the valid nonce for
that client. This essentially re-starts the TOFU mechanism any time the
instance is stopped and started, so should be used with caution. Just like with
@ -449,7 +449,7 @@ alert should trigger based on its logs) if it is denied authentication.
Unfortunately, the `allow_instance_migration` only helps during stop/start
actions; the current metadata does not provide for a way to allow this
automatic behavior during reboots. The backend will be updated if this needed
automatic behavior during reboots. The method will be updated if this needed
metadata becomes available.
The `allow_instance_migration` option is set per-role, and can also be
@ -460,12 +460,12 @@ role tag has no effect.
### Disabling Reauthentication
Note: this only applies to the ec2 authentication method.
Note: this only applies to the ec2 auth method.
If in a given organization's architecture, a client fetches a long-lived Vault
token and has no need to rotate the token, all future logins for that instance
ID can be disabled. If the option `disallow_reauthentication` is set, only one
login will be allowed per instance. If the intended client successfully
login will be allowed per instance. If the intended client successfully
retrieves a token during login, it can be sure that its token will not be
hijacked by another entity.
@ -483,10 +483,10 @@ role tag has no effect.
### Blacklisting Role Tags
Note: this only applies to the ec2 authentication method or the iam auth method
Note: this only applies to the ec2 auth method or the iam auth method
when inferencing is used.
Role tags are tied to a specific role, but the backend has no control over, which
Role tags are tied to a specific role, but the method has no control over, which
instances using that role, should have any particular role tag; that is purely up
to the operator. Although role tags are only restrictive (a tag cannot escalate
privileges above what is set on its role), if a role tag is found to have been
@ -499,9 +499,9 @@ those instances that have the blacklisted tag attached to them.
### Expiration Times and Tidying of `blacklist` and `whitelist` Entries
The expired entries in both identity `whitelist` and role tag `blacklist` are
deleted automatically. The entries in both of these lists contain an expiration
deleted automatically. The entries in both of these lists contain an expiration
time which is dynamically determined by three factors: `max_ttl` set on the role,
`max_ttl` set on the role tag, and `max_ttl` value of the backend mount. The
`max_ttl` set on the role tag, and `max_ttl` value of the method mount. The
least of these three dictates the maximum TTL of the issued token, and
correspondingly will be set as the expiration times of these entries.
@ -512,7 +512,7 @@ past expiration by the amount of time dictated by the safety buffer in order
to actually remove the entry.
Automatic deletion of expired entries is performed by the periodic function
of the backend. This function does the tidying of both blacklist role tags
of the method. This function does the tidying of both blacklist role tags
and whitelist identities. Periodic tidying is activated by default and will
have a safety buffer of 72 hours, meaning only those entries are deleted which
were expired before 72 hours from when the tidy operation is being performed.
@ -521,7 +521,7 @@ endpoints.
### Varying Public Certificates
Note: this only applies to the ec2 authentication method.
Note: this only applies to the ec2 auth method.
The AWS public certificate, which contains the public key used to verify the
PKCS#7 signature, varies for different AWS regions. The primary AWS public
@ -534,8 +534,8 @@ via the `auth/aws/config/certificate/<cert_name>` endpoint.
### Dangling Tokens
An EC2 instance, after authenticating itself with the backend, gets a Vault token.
After that, if the instance terminates or goes down for any reason, the backend
An EC2 instance, after authenticating itself with the method, gets a Vault token.
After that, if the instance terminates or goes down for any reason, the method
will not be aware of such events. The token issued will still be valid, until
it expires. The token will likely be expired sooner than its lifetime when the
instance fails to renew the token on time.
@ -545,7 +545,7 @@ instance fails to renew the token on time.
To allow Vault to authenticate EC2 instances running in other accounts, AWS STS
(Security Token Service) can be used to retrieve temporary credentials by
assuming an IAM Role in those accounts. All these accounts should be configured
at the backend using the `auth/aws-ec2/config/sts/<account_id>` endpoint.
at the method using the `auth/aws-ec2/config/sts/<account_id>` endpoint.
The account in which Vault is running (i.e. the master account) must be listed as
a trusted entity in the IAM Role being assumed on the remote account. The Role itself
@ -562,7 +562,7 @@ for the IAM Role to be assumed.
#### Enable AWS EC2 authentication in Vault.
```
$ vault auth-enable aws
$ vault auth enable aws
```
#### Configure the credentials required to make AWS API calls
@ -572,7 +572,7 @@ If not specified, Vault will attempt to use standard environment variables
credentials if available.
The IAM account or role to which the credentials map must allow the
`ec2:DescribeInstances` action. In addition, if IAM Role binding is used (see
`ec2:DescribeInstances` action. In addition, if IAM Role binding is used (see
`bound_iam_role_arn` below), `iam:GetInstanceProfile` must also be allowed.
```
@ -606,7 +606,7 @@ For the iam auth method, generating the signed request is a non-standard
operation. The Vault cli supports generating this for you:
```
$ vault auth -method=aws header_value=vault.example.com role=dev-role-iam
$ vault login -method=aws header_value=vault.example.com role=dev-role-iam
```
This assumes you have AWS credentials configured in the standard locations AWS
@ -617,7 +617,7 @@ in on the command line (though this is not recommended), omitting
`aws_security_token` if not applicable.
```
$ vault auth -method=aws header_value=vault.example.com role=dev-role-iam \
$ vault login -method=aws header_value=vault.example.com role=dev-role-iam \
aws_access_key_id=<access_key> \
aws_secret_access_key=<secret_key> \
aws_security_token=<security_token>
@ -702,6 +702,6 @@ The response will be in JSON. For example:
## API
The AWS authentication backend has a full HTTP API. Please see the
The AWS auth method has a full HTTP API. Please see the
[AWS Auth API](/api/auth/aws/index.html) for more
details.

112
website/source/docs/auth/cert.html.md
View File

@ -1,20 +1,18 @@
---
layout: "docs"
page_title: "Auth Backend: TLS Certificates"
page_title: "TLS Certificates - Auth Methods"
sidebar_current: "docs-auth-cert"
description: |-
The "cert" auth backend allows users to authenticate with Vault using TLS client certificates.
The "cert" auth method allows users to authenticate with Vault using TLS client certificates.
---
# Auth Backend: TLS Certificates
# TLS Certificates Auth Method
Name: `cert`
The "cert" auth backend allows authentication using SSL/TLS client certificates
The `cert` auth method allows authentication using SSL/TLS client certificates
which are either signed by a CA or self-signed.
The trusted certificates and CAs are configured directly to the auth backend
using the `certs/` path. This backend cannot read trusted certificates from an
The trusted certificates and CAs are configured directly to the auth method
using the `certs/` path. This method cannot read trusted certificates from an
external source.
CA certs are associated with a role; role names and CRL names are normalized to
@ -22,7 +20,7 @@ lower-case.
## Revocation Checking
Since Vault 0.4, the backend supports revocation checking.
Since Vault 0.4, the method supports revocation checking.
An authorised user can submit PEM-formatted CRLs identified by a given name;
these can be updated or deleted at will. (Note: Vault **does not** fetch CRLs;
@ -34,6 +32,7 @@ When there are CRLs present, at the time of client authentication:
* If the client presents any chain where no certificate in the chain matches a
revoked serial number, authentication is allowed
* If there is no chain presented by the client without a revoked serial number,
authentication is denied
@ -45,84 +44,81 @@ the initial intermediate CA is revoked, the chain containing the replacement
will still allow the client to successfully authenticate.
**N.B.**: Matching is performed by *serial number only*. For most CAs,
including Vault's `pki` backend, multiple CRLs can successfully be used as
including Vault's `pki` method, multiple CRLs can successfully be used as
serial numbers are globally unique. However, since RFCs only specify that
serial numbers must be unique per-CA, some CAs issue serial numbers in-order,
which may cause clashes if attempting to use CRLs from two such CAs in the same
mount of the backend. The workaround here is to mount multiple copies of the
`cert` backend, configure each with one CA/CRL, and have clients connect to the
mount of the method. The workaround here is to mount multiple copies of the
`cert` method, configure each with one CA/CRL, and have clients connect to the
appropriate mount.
In addition, since the backend does not fetch the CRLs itself, the CRL's
In addition, since the method does not fetch the CRLs itself, the CRL's
designated time to next update is not considered. If a CRL is no longer in use,
it is up to the administrator to remove it from the backend.
it is up to the administrator to remove it from the method.
## Authentication
### Via the CLI
The below requires Vault to present a certificate signed by `ca.pem` and
presents `cert.pem` (using `key.pem`) to authenticate against the `web` cert
role. If a certificate role name is not specified, the auth backend will try to
role. If a certificate role name is not specified, the auth method will try to
authenticate against all trusted certificates.
```
$ vault auth -method=cert \
-ca-cert=ca.pem -client-cert=cert.pem -client-key=key.pem \
$ vault login \
-method=cert \
-ca-cert=ca.pem \
-client-cert=cert.pem \
-client-key=key.pem \
name=web
```
### Via the API
The endpoint for the login is `/login`. The client simply connects with their TLS
certificate and when the login endpoint is hit, the auth backend will determine
if there is a matching trusted certificate to authenticate the client. Optionally,
you may specify a single certificate role to authenticate against.
```
$ curl --cacert ca.pem --cert cert.pem --key key.pem -d name=web \
$VAULT_ADDR/v1/auth/cert/login -XPOST
The endpoint for the login is `/login`. The client simply connects with their
TLS certificate and when the login endpoint is hit, the auth method will
determine if there is a matching trusted certificate to authenticate the client.
Optionally, you may specify a single certificate role to authenticate against.
```sh
$ curl \
--request POST \
--cacert ca.pem \
--cert cert.pem \
--key key.pem \
--data '{"name": "web"}' \
https://vault.rocks/v1/auth/cert/login
```
## Configuration
First, you must enable the certificate auth backend:
Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.
```
$ vault auth-enable cert
Successfully enabled 'cert' at 'cert'!
```
1. Enable the certificate auth method:
Now when you run `vault auth -methods`, the certificate backend is available:
```text
$ vault auth enable cert
```
```
Path Type Description
cert/ cert
token/ token token based credentials
```
1. Configure it with trusted certificates that are allowed to authenticate:
To use the "cert" auth backend, an operator must configure it with
trusted certificates that are allowed to authenticate. An example is shown below.
Use `vault path-help` for more details.
```text
$ vault write auth/cert/certs/web \
display_name=web \
policies=web,prod \
certificate=@web-cert.pem \
ttl=3600
```
```
$ vault write auth/cert/certs/web \
display_name=web \
policies=web,prod \
certificate=@web-cert.pem \
ttl=3600
...
```
The above creates a new trusted certificate "web" with same display name
and the "web" and "prod" policies. The certificate (public key) used to verify
clients is given by the "web-cert.pem" file. Lastly, an optional `ttl` value
can be provided in seconds to limit the lease duration.
#### Via the API
The token is set directly as a header for the HTTP API. The name
of the header should be "X-Vault-Token" and the value should be the token.
This creates a new trusted certificate "web" with same display name and the
"web" and "prod" policies. The certificate (public key) used to verify
clients is given by the "web-cert.pem" file. Lastly, an optional `ttl` value
can be provided in seconds to limit the lease duration.
## API
The TLS Certificate authentication backend has a full HTTP API. Please see the
[TLS Certificate API](/api/auth/cert/index.html) for more details.
The TLS Certificate auth method has a full HTTP API. Please see the
[TLS Certificate API](/api/auth/cert/index.html) for more details.

211
website/source/docs/auth/gcp.html.md
View File

@ -1,14 +1,14 @@
---
layout: "docs"
page_title: "Auth Plugin Backend: GCP"
page_title: "GCP - Auth Methods"
sidebar_current: "docs-auth-gcp"
description: |-
The gcp backend plugin allows automated authentication of AWS entities.
The gcp auth method plugin allows automated authentication of AWS entities.
---
# Auth Plugin Backend: gcp
# GCP Auth Method
The `gcp` plugin backend allows authentication against Vault using
The `gcp` auth method allows authentication against Vault using
Google credentials. It treats GCP as a Trusted Third Party and expects a
[JSON Web Token (JWT)](https://tools.ietf.org/html/rfc7519) signed by Google
credentials from the authenticating entity. This token can be generated through
@ -21,7 +21,7 @@ Currently supports authentication for:
## Precursors:
The following documentation assumes that the backend has been
The following documentation assumes that the method has been
[mounted](/docs/plugin/index.html) at `auth/gcp`.
You must also [enable the following GCP APIs](https://support.google.com/cloud/answer/6158841?hl=en)
@ -29,14 +29,173 @@ for your GCP project:
* IAM API for both `iam` service accounts and `gce` instances
* GCE API for just `gce` instances
The next sections review how the authN/Z workflows work. If you
The next sections review how the authN/Z workflows work. If you
have already reviewed these sections, here are some quick links to:
* [Usage](#usage)
* [API documentation](/api/auth/gcp/index.html) docs.
* [API documentation](/api/auth/gcp/index.html) docs.
## Authentication
### Via the CLI
The default path is `/gcp`. If this auth method was enabled at a different
path, specify `auth/my-path/login` instead.
```text
$ vault write auth/gcp/login \
role="dev-role" \
jwt="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```
The `role` and `jwt` parameters are required. These map to the name of the role
to login against, and the signed JWT token for authenticating a role
respectively. The format of the provided JWT differs depending on the
authenticating entity.
### Via the API
The default endpoint is `auth/gcp/login`. If this auth method was enabled
at a different path, use that value instead of `gcp`.
```sh
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"role": "dev-role", "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."}' \
https://vault.rocks/v1/auth/gcp/login
```
The response will contain the token at `auth.client_token`:
```json
{
"auth": {
"client_token": "f33f8c72-924e-11f8-cb43-ac59d697597c",
"accessor": "0e9e354a-520f-df04-6867-ee81cae3d42d",
"policies": [
"default",
"dev",
"prod"
],
"metadata": {
"role": "dev-role",
"service_account_email": "dev1@project-123456.iam.gserviceaccount.com",
"service_account_id": "111111111111111111111"
},
"lease_duration": 2764800,
"renewable": true
}
}
```
## Configuration
Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.
### Via the CLI
1. Enable GCP authentication in Vault:
```text
$ vault auth enable gcp
```
1. Configure the GCP auth method:
```text
$ vault write auth/gcp/config credentials=@/path/to/creds.json
```
Configuration includes GCP credentials Vault will use these to make calls to
GCP APIs. If credentials are not configured or if the user explicitly sets
the config with no credentials, the Vault server will attempt to use
[Application Default
Credentials](https://developers.google.com/identity/protocols/application-default-credentials)
as set on the Vault server.
For the complete list of configuration options, please see the API
documentation.
1. Create a role:
```text
$ vault write auth/gcp/role/dev-role \
type="iam" \
project="project-123456" \
policies="prod,dev" \
service_accounts="serviceaccount1@project1234.iam.gserviceaccount.com,uuid123,..."
```
Roles are associated with an authentication type/entity and a set of Vault
policies. Roles are configured with constraints specific to the
authentication type, as well as overall constraints and configuration for
the generated auth tokens.
For the complete list of role options, please see the API documentation.
### Via the API
1. Enable GCP authentication in Vault:
```sh
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"type": "gcp"}' \
https://vault.rocks/v1/sys/auth/gcp
```
1. Configure the GCP auth method:
```sh
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"credentials": "{...}"}' \
https://vault.rocks/v1/auth/gcp/config
```
1. Create a role:
```sh
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"type": "iam", "project": "project-123456", ...}' \
https://vault.rocks/v1/auth/gcp/role/dev-role
```
### Plugin Setup
~> The following section is only relevant if you decide to enable the gcp auth
method as an external plugin. The gcp plugin method is integrated into Vault as
a builtin method by default.
Assuming you have saved the binary `vault-plugin-auth-gcp` to some folder and
configured the [plugin directory](/docs/internals/plugins.html#plugin-directory)
for your server at `path/to/plugins`:
1. Enable the plugin in the catalog:
```text
$ vault write sys/plugins/catalog/gcp-auth \
command="vault-plugin-auth-gcp" \
sha_256="..."
```
1. Enable the gcp auth method as a plugin:
```text
$ vault auth enable -path=gcp -plugin-name=gcp-auth plugin
```
## Authentication Workflow
### IAM
@ -62,9 +221,11 @@ The expected format of the JWT payload is as follows:
}
```
* `[SERVICE ACCOUNT ID OR EMAIL]`: Either the email or the unique ID of a service account.
* `[ROLE NAME]`: Name of the role that this token will be used to login against. The full expected `aud` string should end in "vault/$roleName".
* `[EXPIRATION]` : A [NumericDate](https://tools.ietf.org/html/rfc7519#section-2) value (seconds from Epoch). This value must be before the max JWT expiration allowed for a role (see `max_jwt_exp` parameter for creating a role). This defaults to 15 minutes and cannot be more than a hour.
- `[SERVICE ACCOUNT ID OR EMAIL]`: Either the email or the unique ID of a service account.
- `[ROLE NAME]`: Name of the role that this token will be used to login against. The full expected `aud` string should be "vault/$roleName".
- `[EXPIRATION]` : A [NumericDate](https://tools.ietf.org/html/rfc7519#section-2) value (seconds from Epoch). This value must be before the max JWT expiration allowed for a role (see `max_jwt_exp` parameter for creating a role). This defaults to 15 minutes and cannot be more than a hour.
**Note:** By default, we enforce a shorter `exp` period than the default length
for a given token (1 hour) in order to make reuse of tokens difficult. You can
@ -87,15 +248,15 @@ The Vault authentication workflow for GCE instances is as follows:
#### The `gce` Authentication Token
The token can be obtained from the `service-accounts/default/identity` endpoint for a instance's
[metadata server](https://cloud.google.com/compute/docs/storing-retrieving-metadata). You can use the
[example of how to obtain an instance metadata token](#generating-gce-token) to get started.
The token can be obtained from the `service-accounts/default/identity` endpoint for a instance's
[metadata server](https://cloud.google.com/compute/docs/storing-retrieving-metadata). You can use the
[example of how to obtain an instance metadata token](#generating-gce-token) to get started.
Learn more about the JWT format from the
[documentation](https://cloud.google.com/compute/docs/instances/verifying-instance-identity#token_format)
Learn more about the JWT format from the
[documentation](https://cloud.google.com/compute/docs/instances/verifying-instance-identity#token_format)
for the identity metadata token. The params the user provides are:
* `[AUD]`: The full expected `aud` string should end in "vault/$roleName". Note that Google requires the `aud`
* `[AUD]`: The full expected `aud` string should end in "vault/$roleName". Note that Google requires the `aud`
claim to contain a scheme or authority but Vault will only check for a suffix.
* `[FORMAT]`: MUST BE `full` for Vault. Format of the metadata token generated (`standard` or `full`).
@ -105,7 +266,7 @@ for the identity metadata token. The params the user provides are:
**HTTP Request Example**
This uses [Google API HTTP annotation](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto).
This uses [Google API HTTP annotation](https://github.com/googleapis/googleapis/blob/master/google/api/http.proto).
Note the `$PAYLOAD` must be a marshaled JSON string with escaped double quotes.
```sh
@ -121,7 +282,7 @@ OAUTH_TOKEN=$(oauth2l header cloud-platform)
PAYLOAD=$(echo "{ \"aud\": \"vault/$ROLE\", \"sub\": \"$SERVICE_ACCOUNT\"}" | sed -e 's/"/\\&/g')
curl -H "$OAUTH_TOKEN" \
-H "Content-Type: application/json" \
-X POST -d "{\"payload\":\"$PAYLOAD\"}" https://iam.googleapis.com/v1/projects/$PROJECT/serviceAccounts/$SERVICE_ACCOUNT:signJwt```
-X POST -d "{\"payload\":\"$PAYLOAD\"}" https://iam.googleapis.com/v1/projects/$PROJECT/serviceAccounts/$SERVICE_ACCOUNT:signJwt
```
**Golang Example**
@ -225,7 +386,7 @@ SERVICE_ACCOUNT="default" # replace with an instance's service account if needed
# [END PARAMS]
curl -H "Metadata-Flavor: Google"\
-G
-G
--data-urlencode "audience=$VAULT_ADDR/vault/$ROLE"\
--data-urlencode "format=full" \
"http://metadata/computeMetadata/v1/instance/service-accounts/$SERVICE_ACCOUNT/identity"
@ -283,7 +444,7 @@ $ vault write auth/gcp/role/dev-role \
policies="prod,dev" \
bound_service_accounts="serviceaccount1@project1234.iam.gserviceaccount.com,uuid123,..."
...
```
```
**Roles**: Roles are associated with an authentication type/entity and a set of
Vault [policies](/docs/concepts/policies.html). Roles are configured with constraints
@ -299,14 +460,14 @@ We also expose a helper path for updating the service accounts attached to an ex
```
and for updating the labels attached to an existing `gce` role:
```sh
vault write auth/gcp/role/gce-role/labels \
add='label1:value1,foo:bar,...' \
remove='key1,key2,...' \
```
See [API docs](/api/auth/gcp/index.html#create-role) to view
parameters for role creation and updates.
@ -384,7 +545,7 @@ The response will be in JSON. For example:
}
```
## Contributing
### Contributing
This plugin is developed in a separate Github repository: [`hashicorp/vault-plugin-auth-gcp`](https://github.com/hashicorp/vault-plugin-auth-gcp). Please file all feature requests, bugs, and pull requests specific to the GCP plugin under that repository.

171
website/source/docs/auth/github.html.md
View File

@ -1,62 +1,61 @@
---
layout: "docs"
page_title: "Auth Backend: GitHub"
page_title: "GitHub - Auth Methods"
sidebar_current: "docs-auth-github"
description: |-
The GitHub auth backend allows authentication with Vault using GitHub.
The GitHub auth method allows authentication with Vault using GitHub.
---
# Auth Backend: GitHub
# GitHub Auth Method
Name: `github`
The GitHub auth backend can be used to authenticate with Vault using a GitHub
The `github` auth method can be used to authenticate with Vault using a GitHub
personal access token. This method of authentication is most useful for humans:
operators or developers using Vault directly via the CLI.
**N.B.**: Vault does not support an OAuth workflow to generate GitHub tokens,
so does not act as a GitHub application. As a result, this backend uses
personal access tokens. An important consequence is that any valid GitHub
access token with the `read:org` scope can be used for authentication. If such
a token is stolen from a third party service, and the attacker is able to make
~> **IMPORTANT NOTE:** Vault does not support an OAuth workflow to generate
GitHub tokens, so does not act as a GitHub application. As a result, this method
uses personal access tokens. An important consequence is that any valid GitHub
access token with the `read:org` scope can be used for authentication. If such a
token is stolen from a third party service, and the attacker is able to make
network calls to Vault, they will be able to log in as the user that generated
the access token. When using this backend it is a good idea to ensure that
access to Vault is restricted at a network level rather than public. If these
risks are unacceptable to you, you should use a different backend.
the access token. When using this method it is a good idea to ensure that access
to Vault is restricted at a network level rather than public. If these risks are
unacceptable to you, you should use a different method.
## Authentication
#### Via the CLI
### Via the CLI
```
$ vault auth -method=github token=<api token>
...
The default path is `/github`. If this auth method was enabled at a different
path, specify `-path=/my-path` in the CLI.
```text
$ vault login -method=github token="MY_TOKEN"
```
#### Via the API
### Via the API
The endpoint for the GitHub login is `auth/github/login`.
The `github` mountpoint value in the url is the default mountpoint value.
If you have mounted the `github` backend with a different mountpoint, use that value.
The `token` should be sent in the POST body encoded as JSON.
The default endpoint is `auth/github/login`. If this auth method was enabled
at a different path, use that value instead of `github`.
```shell
$ curl $VAULT_ADDR/v1/auth/github/login \
-d '{ "token": "your_github_personal_access_token" }'
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"token": "MY_TOKEN"}' \
https://vault.rocks/v1/auth/github/login
```
The response will be in JSON. For example:
The response will contain a token at `auth.client_token`:
```javascript
```json
{
"auth": {
"renewable": true,
"lease_duration": 2764800,
"metadata": {
"username": "vishalnayak",
"org": "hashicorp"
"username": "my-user",
"org": "my-org"
},
"policies": [
"default",
@ -64,103 +63,57 @@ The response will be in JSON. For example:
],
"accessor": "f93c4b2d-18b6-2b50-7a32-0fecf88237b8",
"client_token": "1977fceb-3bfa-6c71-4d1f-b64af98ac018"
},
"warnings": null,
"wrap_info": null,
"data": null,
"lease_duration": 0,
"renewable": false,
"lease_id": "",
"request_id": "3c346f3b-e089-39ab-a953-a349f2284e3c"
}
}
```
## Configuration
First, you must enable the GitHub auth backend:
Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.
```
$ vault auth-enable github
Successfully enabled 'github' at 'github'!
```
1. Enable the GitHub auth method:
Now when you run `vault auth -methods`, the GitHub backend is available:
```text
$ vault auth enable github
```
```
Path Type Description
github/ github
token/ token token based credentials
```
1. Use the `/config` endpoint to configure Vault to talk to GitHub. For the list
of available configuration options, please see the API documentation.
Prior to using the GitHub auth backend, it must be configured. To
configure it, use the `/config` endpoint with the following arguments:
```text
$ vault write auth/github/config organization=hashicorp
```
* `organization` (string, required) - The organization name a user must
be a part of to authenticate.
* `base_url` (string, optional) - For GitHub Enterprise or other API-compatible
servers, the base URL to access the server.
* `max_ttl` (string, optional) - Maximum duration after which authentication will be expired.
This must be a string in a format parsable by Go's [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration)
* `ttl` (string, optional) - Duration after which authentication will be expired.
This must be a string in a format parsable by Go's [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration)
For the complete list of configuration options, please see the API
documentation.
###Generate a GitHub Personal Access Token
Access your Personal Access Tokens in GitHub at [https://github.com/settings/tokens](https://github.com/settings/tokens).
Generate a new Token that has the scope `read:org`. Save the generated token. This is what you will provide to vault.
1. Map the users/teams of that GitHub organization to policies in Vault. Team
names must be "slugified":
For example:
```text
$ vault write auth/github/map/teams/dev value=dev-policy
```
```
$ vault write auth/github/config organization=hashicorp
Success! Data written to: auth/github/config
```
In this example, when members of the team "dev" in the organization
"hashicorp" authenticate to Vault using a GitHub personal access token, they
will be given a token with the "dev-policy" policy attached.
After configuring that, you must map the teams of that organization to
policies within Vault. Use the `map/teams/<team>` endpoints to do that.
Team names must be slugified, so if your team name is: `Some Amazing Team`,
you will need to include it as: `some-amazing-team`.
Example:
---
```
$ vault write auth/github/map/teams/dev value=dev-policy
Success! Data written to: auth/github/map/teams/dev
```
You can also create mappings for a specific user `map/users/<user>`
endpoint:
The above would make anyone in the `dev` team receive tokens with the policy
`dev-policy`.
```text
$ vault write auth/github/map/users/sethvargo value=sethvargo-policy
```
You can then auth with a user that is a member of the `dev` team using a
Personal Access Token with the `read:org` scope.
You can also create mappings for specific users in a similar fashion with the
`map/users/<user>` endpoint.
Example:
```
$ vault write auth/github/map/users/user1 value=user1-policy
Success! Data written to: auth/github/map/teams/user1
```
Now a user with GitHub username `user1` will be assigned the `user1-policy` on authentication,
in addition to any team policies.
GitHub token can also be supplied from the env variable `VAULT_AUTH_GITHUB_TOKEN`.
```
$ vault auth -method=github token=000000905b381e723b3d6a7d52f148a5d43c4b45
Successfully authenticated! You are now logged in.
The token below is already saved in the session. You do not
need to "vault auth" again with the token.
token: 0d9ab511-bc25-4fb6-a58b-94ce12b8da9c
token_duration: 2764800
token_policies: [default dev-policy]
```
Clients can use this token to perform an allowed set of operations on all the
paths contained by the policy set.
In this example, a user with the GitHub username `sethvargo` will be
assigned the `sethvargo-policy` policy **in addition to** any team policies.
## API
The GitHub authentication backend has a full HTTP API. Please see the
The GitHub auth method has a full HTTP API. Please see the
[GitHub Auth API](/api/auth/github/index.html) for more
details.

48
website/source/docs/auth/index.html.md
View File

@ -1,40 +1,46 @@
---
layout: "docs"
page_title: "Auth Backends"
page_title: "Auth Methods"
sidebar_current: "docs-auth"
description: |-
Auth backends are mountable backends that perform authentication for Vault.
Auth methods are mountable methods that perform authentication for Vault.
---
# Auth Backends
# Auth Methods
Auth backends are the components in Vault that perform authentication
and are responsible for assigning identity and a set of policies to a
user.
Auth methods 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.
Having multiple auth methods enables you to use an auth method that makes the
sense for your use case of Vault and your organization.
For example, on developer machines, the [GitHub auth backend](/docs/auth/github.html)
For example, on developer machines, the [GitHub auth method](/docs/auth/github.html)
is easiest to use. But for servers the [AppRole](/docs/auth/approle.html)
backend is the recommended choice.
method is the recommended choice.
To learn more about authentication, see the
[authentication concepts page](/docs/concepts/auth.html).
## Enabling/Disabling Auth Backends
## Enabling/Disabling Auth Methods
Auth backends can be enabled/disabled using the CLI or the API.
Auth methods can be enabled/disabled using the CLI or the API.
When enabled, auth backends are similar to [secret backends](/docs/secrets/index.html):
```text
$ vault auth enable userpass
```
When enabled, auth methods are similar to [secrets engines](/docs/secrets/index.html):
they are mounted within the Vault mount table and can be accessed
and configured using the standard read/write API. The only difference
is that all auth backends are mounted underneath the `auth/` prefix.
and configured using the standard read/write API. All auth methods are mounted underneath the `auth/` prefix.
By default, auth backends are mounted to `auth/<type>`. For example,
if you enable "github", then you can interact with it at `auth/github`.
However, this path is customizable, allowing users with advanced use
cases to mount a single auth backend multiple times.
By default, auth methods are mounted to `auth/<type>`. For example, if you
enable "github", then you can interact with it at `auth/github`. However, this
path is customizable, allowing users with advanced use cases to mount a single
auth method multiple times.
When an auth backend is disabled, all users authenticated via that
backend are automatically logged out.
```text
$ vault auth enable -path=my-login userpass
```
When an auth method is disabled, all users authenticated via that method are
automatically logged out.

68
website/source/docs/auth/ldap.html.md
View File

@ -1,16 +1,15 @@
---
layout: "docs"
page_title: "Auth Backend: LDAP"
page_title: "LDAP - Auth Methods"
sidebar_current: "docs-auth-ldap"
description: |-
The "ldap" auth backend allows users to authenticate with Vault using LDAP credentials.
The "ldap" auth method allows users to authenticate with Vault using LDAP
credentials.
---
# Auth Backend: LDAP
# LDAP Auth Method
Name: `ldap`
The "ldap" auth backend allows authentication using an existing LDAP
The `ldap` auth method allows authentication using an existing LDAP
server and user/password credentials. This allows Vault to be integrated
into environments using LDAP without duplicating the user/pass configuration
in multiple places.
@ -23,7 +22,7 @@ the `users/` and `groups/` paths.
**It is up to the administrator** to provide properly escaped DNs. This
includes the user DN, bind DN for search, and so on.
The only DN escaping performed by this backend is on usernames given at login
The only DN escaping performed by this method is on usernames given at login
time when they are inserted into the final bind DN, and uses escaping rules
defined in RFC 4514.
@ -41,10 +40,10 @@ Directory](http://social.technet.microsoft.com/wiki/contents/articles/5312.activ
## Authentication
#### Via the CLI
### Via the CLI
```
$ vault auth -method=ldap username=mitchellh
```text
$ vault login -method=ldap username=mitchellh
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:
@ -52,15 +51,14 @@ with this token are listed below:
admins
```
#### Via the API
The endpoint for the login is `auth/ldap/login/<username>`.
The password should be sent in the POST body encoded as JSON.
### Via the API
```shell
$ curl $VAULT_ADDR/v1/auth/ldap/login/mitchellh \
-d '{ "password": "foo" }'
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"password": "foo"}' \
https://vault.rocks/v1/auth/ldap/login/mitchellh=
```
The response will be in JSON. For example:
@ -87,27 +85,19 @@ The response will be in JSON. For example:
## Configuration
First, you must enable the ldap auth backend:
Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.
```
$ vault auth-enable ldap
Successfully enabled 'ldap' at 'ldap'!
```
1. Enable the ldap auth method:
Now when you run `vault auth -methods`, the ldap backend is available:
```text
$ vault auth enable ldap
```
```
Path Type Description
ldap/ ldap
token/ token token based credentials
```
To use the ldap auth backend, it must first be configured with connection
details for your LDAP server, information on how to authenticate users, and
instructions on how to query for group membership.
The configuration options are categorized and detailed below.
Configuration is written to `auth/ldap/config`.
1. Configure connection details for your LDAP server, information on how to
authenticate users, and instructions on how to query for group membership. The
configuration options are categorized and detailed below.
### Connection parameters
@ -140,7 +130,7 @@ There are two alternate methods of resolving the user object used to authenticat
### Group Membership Resolution
Once a user has been authenticated, the LDAP auth backend must know how to resolve which groups the user is a member of. The configuration for this can vary depending on your LDAP server and your directory schema. There are two main strategies when resolving group membership - the first is searching for the authenticated user object and following an attribute to groups it is a member of. The second is to search for group objects of which the authenticated user is a member of. Both methods are supported.
Once a user has been authenticated, the LDAP auth method must know how to resolve which groups the user is a member of. The configuration for this can vary depending on your LDAP server and your directory schema. There are two main strategies when resolving group membership - the first is searching for the authenticated user object and following an attribute to groups it is a member of. The second is to search for group objects of which the authenticated user is a member of. Both methods are supported.
* `groupfilter` (string, optional) - 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}}))`.
* `groupdn` (string, required) - 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`
@ -250,7 +240,7 @@ policy.
Finally, we can test this by authenticating:
```
$ vault auth -method=ldap username=tesla
$ vault login -method=ldap username=tesla
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:
@ -264,6 +254,6 @@ It should be noted that user -> policy mapping happens at token creation time. A
## API
The LDAP authentication backend has a full HTTP API. Please see the
[LDAP auth backend API](/api/auth/ldap/index.html) for more
The LDAP auth method has a full HTTP API. Please see the
[LDAP auth method API](/api/auth/ldap/index.html) for more
details.

74
website/source/docs/auth/mfa.html.md
View File

@ -1,63 +1,68 @@
---
layout: "docs"
page_title: "Multi-Factor Authentication"
page_title: "Multi-Factor Authentication (MFA) - Auth Methods"
sidebar_current: "docs-auth-mfa"
description: |-
Multi-factor authentication is supported for several authentication backends.
Multi-factor authentication (MFA) is supported for several authentication
methods.
---
# Multi-Factor Authentication
Several authentication backends support multi-factor authentication (MFA). Once enabled for
a backend, users are required to provide additional verification, like a one-time passcode,
before being authenticated.
Several auth methods support multi-factor authentication (MFA). Once
enabled for a method, users are required to provide additional verification,
like a one-time passcode, before being authenticated.
Currently, the "ldap", "radius" and "userpass" backends support MFA.
Currently, the "ldap", "radius" and "userpass" methods support MFA.
## Authentication
When authenticating, users still provide the same information as before, in addition to
MFA verification. Usually this is a passcode, but in other cases, like a Duo Push
notification, no additional information is needed.
When authenticating, users still provide the same information as before, in
addition to MFA verification. Usually this is a passcode, but in other cases,
like a Duo Push notification, no additional information is needed.
### Via the CLI
```shell
$ vault auth -method=userpass \
username=user \
```tedt
$ vault login -method=userpass \
username=my-username \
password=test \
passcode=111111
```
```shell
$ vault auth -method=userpass \
username=user \
```text
$ vault login -method=userpass \
username=my-username \
password=test \
method=push
```
### Via the API
The endpoint for the login is the same as for the original backend. Additional
The endpoint for the login is the same as for the original method. Additional
MFA information should be sent in the POST body encoded as JSON.
```shell
$ curl $VAULT_ADDR/v1/auth/userpass/login/user \
-d '{ "password": "test", "passcode": "111111" }'
$ curl \
--request POST \
--data '{"password": "test", "passcode": "111111"}' \
https://vault.rocks/v1/auth/userpass/login/my-username
```
The response is the same as for the original backend.
The response is the same as for the original method.
## Configuration
To enable MFA for a supported backend, the MFA type must be set in `mfa_config`. For example:
To enable MFA for a supported method, the MFA type must be set in `mfa_config`.
For example:
```shell
```text
$ vault write auth/userpass/mfa_config type=duo
```
This enables the Duo MFA type, which is currently the only MFA type supported. The username
used for MFA is the same as the login username, unless the backend or MFA type provide
options to behave differently (see Duo configuration below).
This enables the Duo MFA type, which is currently the only MFA type supported.
The username used for MFA is the same as the login username, unless the method
or MFA type provide options to behave differently (see Duo configuration below).
### Duo
@ -65,7 +70,7 @@ The Duo MFA type is configured through two paths: `duo/config` and `duo/access`.
`duo/access` contains connection information for the Duo Auth API. To configure:
```shell
```text
$ vault write auth/[mount]/duo/access \
host=[host] \
ikey=[integration key] \
@ -75,21 +80,22 @@ $ vault write auth/[mount]/duo/access \
`duo/config` is an optional path that contains general configuration information
for Duo authentication. To configure:
```shell
```text
$ vault write auth/[mount]/duo/config \
user_agent="" \
username_format="%s"
```
`user_agent` is the user agent to use when connecting to Duo.
- `user_agent` is the user agent to use when connecting to Duo.
`username_format` controls how the username used to login is
transformed before authenticating with Duo. This field is a format string
that is passed the original username as its first argument and outputs
the new username. For example "%s@example.com" would append "@example.com"
to the provided username before connecting to Duo.
- `username_format` controls how the username used to login is transformed
before authenticating with Duo. This field is a format string that is passed
the original username as its first argument and outputs the new username. For
example "%s@example.com" would append "@example.com" to the provided username
before connecting to Duo.
`push_info` is a string of URL-encoded key/value pairs that provides additional
context about the authentication attempt in the Duo Mobile application.
- `push_info` is a string of URL-encoded key/value pairs that provides
additional context about the authentication attempt in the Duo Mobile
application.
More information can be found through the CLI `path-help` command.

178
website/source/docs/auth/okta.html.md
View File

@ -1,54 +1,48 @@
---
layout: "docs"
page_title: "Auth Backend: Okta"
page_title: "Okta - Auth Methods"
sidebar_current: "docs-auth-okta"
description: |-
The Okta auth backend allows users to authenticate with Vault using Okta credentials.
The Okta auth method allows users to authenticate with Vault using Okta
credentials.
---
# Auth Backend: Okta
# Okta Auth Method
Name: `okta`
The Okta auth backend allows authentication using Okta
and user/password credentials. This allows Vault to be integrated
into environments using Okta.
The `okta` auth method allows authentication using Okta and user/password
credentials. This allows Vault to be integrated into environments using Okta.
The mapping of groups in Okta to Vault policies is managed by using the
`users/` and `groups/` paths.
## Authentication
#### Via the CLI
### Via the CLI
```
$ vault auth -method=okta username=mitchellh
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:
The default path is `/okta`. If this auth method was enabled at a different
path, specify `-path=/my-path` in the CLI.
admins
```text
$ vault login -method=okta username=my-username
```
#### Via the API
### Via the API
The endpoint for the login is `auth/okta/login/<username>`.
The password should be sent in the POST body encoded as JSON.
The default endpoint is `auth/okta/login`. If this auth method was enabled
at a different path, use that value instead of `okta`.
```shell
$ curl $VAULT_ADDR/v1/auth/okta/login/mitchellh \
-d '{ "password": "foo" }'
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"password": "MY_PASSWORD"}' \
https://vault.rocks/v1/auth/okta/login/my-username
```
The response will be in JSON. For example:
The response will contain a token at `auth.client_token`:
```javascript
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"auth": {
"client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
"policies": [
@ -56,114 +50,70 @@ The response will be in JSON. For example:
],
"metadata": {
"username": "mitchellh"
},
"lease_duration": 0,
"renewable": false
}
}
}
```
## Configuration
First, you must enable the Okta auth backend:
Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.
```
$ vault auth-enable okta
Successfully enabled 'okta' at 'okta'!
```
### Via the CLI
Now when you run `vault auth -methods`, the Okta backend is available:
1. Enable the Okta auth method:
```
Path Type Description
okta/ okta
token/ token token based credentials
```
```text
$ vault auth enable okta
```
To use the Okta auth backend, it must first be configured for your Okta account.
The configuration options are categorized and detailed below.
1. Configure Vault to communicate with your Okta account:
Configuration is written to `auth/okta/config`.
```text
$ vault write auth/okta/config \
base_url="okta.com" \
organization="dev-123456" \
token="00KzlTNCqDf0enpQKYSAYUt88KHqXax6dT11xEZz_g"
```
### Connection parameters
**If no token is supplied, Vault will function, but only locally configured
group membership will be available. Without a token, groups will not be
queried.**
* `org_name` (string, required) - The Okta organization. This will be the first part of the url `https://XXX.okta.com` url.
* `api_token` (string, optional) - The 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. This can be generated from http://developer.okta.com/docs/api/getting_started/getting_a_token.html
* `base_url` (string, optional) - The Okta url. Examples: `oktapreview.com`, The default is `okta.com`
* `max_ttl` (string, optional) - Maximum duration after which authentication will be expired.
Either number of seconds or in a format parsable by Go's [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration)
* `ttl` (string, optional) - Duration after which authentication will be expired.
Either number of seconds or in a format parsable by Go's [time.ParseDuration](https://golang.org/pkg/time/#ParseDuration)
For the complete list of configuration options, please see the API
documentation.
Use `vault path-help` for more details.
1. Map an Okta group to a Vault policy:
## Examples:
```text
$ vault write auth/okta/groups/scientists policies=nuclear-reactor
```
### Scenario 1
In this example, anyone who successfully authenticates via Okta who is a
member of the "scientists" group will receive a Vault token with the
"nuclear-reactor" policy attached.
* Okta organization `XXXTest`.
* With no token supplied only locally configured group membership will be available. Groups will not be queried from Okta.
---
```
$ vault write auth/okta/config \
org_name="XXXTest"
...
```
It is also possible to add users directly:
### Scenario 2
```text
$ vault write auth/okta/groups/engineers policies=autopilot
$ vault write auth/okta/users/tesla groups=engineers
```
* Okta organization `dev-123456`.
* Okta base_url for developer account `oktapreview.com`
* API token `00KzlTNCqDf0enpQKYSAYUt88KHqXax6dT11xEZz_g`. This will allow group membership to be queried.
This adds the Okta user "tesla" to the "engineers" group, which maps to
the "autopilot" Vault policy.
```
$ vault write auth/okta/config base_url="oktapreview.com" \
org_name="dev-123456" \
api_token="00KzlTNCqDf0enpQKYSAYUt88KHqXax6dT11xEZz_g"
...
```
## Okta Group -> Policy Mapping
Next we want to create a mapping from an Okta group to a Vault policy:
```
$ vault write auth/okta/groups/scientists policies=foo,bar
```
This maps the Okta group "scientists" to the "foo" and "bar" Vault policies.
We can also add specific Okta users to additional (potentially non-Okta) groups:
```
$ vault write auth/okta/groups/engineers policies=foobar
$ vault write auth/okta/users/tesla groups=engineers
```
This adds the Okta user "tesla" to the "engineers" group, which maps to
the "foobar" Vault policy.
Finally, we can test this by authenticating:
```
$ vault auth -method=okta username=tesla
Password (will be hidden):
Successfully authenticated! The policies that are associated
with this token are listed below:
bar, foo, foobar
```
## Note on Okta Group's
Groups can only be pulled from Okta if an API token is configured via `token`
## Note on policy mapping
It should be noted that user -> policy mapping (via group membership) happens at token creation time. And changes in group membership in Okta will not affect tokens that have already been provisioned. To see these changes, old tokens should be revoked and the user should be asked to reauthenticate.
**The user-policy mapping via group membership happens at token _creation
time_. Any changes in group membership in Okta will not affect existing
tokens that have already been provisioned. To see these changes, users
will need to re-authenticate. You can force this by revoking the
existing tokens.**
## API
The Okta authentication backend has a full HTTP API. Please see the
[Okta Auth API](/api/auth/okta/index.html) for more
details.
The Okta auth method has a full HTTP API. Please see the
[Okta Auth API](/api/auth/okta/index.html) for more details.

110
website/source/docs/auth/radius.html.md
View File

@ -1,56 +1,45 @@
---
layout: "docs"
page_title: "Auth Backend: RADIUS"
page_title: "RADIUS - Auth Methods"
sidebar_current: "docs-auth-radius"
description: |-
The "radius" auth backend allows users to authenticate with Vault using an existing RADIUS server.
The "radius" auth method allows users to authenticate with Vault using an
existing RADIUS server.
---
# Auth Backend: RADIUS
# RADIUS Auth Method
Name: `radius`
The "radius" auth backend allows users to authenticate with Vault using
an existing RADIUS server that accepts the PAP authentication scheme.
The mapping of users to Vault policies is managed by using the
`users/` path.
Optionally, a configurable set of policies can be granted to all users that
can successfully authenticate but are not registered in the `users/` path.
The `radius` auth method allows users to authenticate with Vault using an
existing RADIUS server that accepts the PAP authentication scheme.
## Authentication
#### Via the CLI
The default path is `/radius`. If this auth method was enabled at a different
path, specify `-path=/my-path` in the CLI.
```
$ vault auth -method=userpass -path=radius \
username=foo \
password=bar
### Via the CLI
```text
$ vault login -path=radius username=sethvargo
```
#### Via the API
### Via the API
The endpoint for the login is `auth/radius/login/<username>`.
The password should be sent in the POST body encoded as JSON.
The default endpoint is `auth/radius/login`. If this auth method was enabled
at a different path, use that value instead of `radius`.
```shell
$ curl $VAULT_ADDR/v1/auth/radius/login/mitchellh \
-d '{ "password": "foo" }'
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data '{"password": "..."}' \
https://vault.rocks/v1/auth/radius/login/sethvargo
```
Alternatively a POST request can be made to `auth/radius/login/`
with both `username` and `password` sent in the POST body encoded as JSON.
The response will contain a token at `auth.client_token`:
The response will be in JSON. For example:
```javascript
```json
{
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"auth": {
"client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
"policies": [
@ -58,57 +47,40 @@ The response will be in JSON. For example:
],
"metadata": {
"username": "mitchellh"
},
"lease_duration": 0,
"renewable": false
}
}
}
```
## Configuration
First, you must enable the RADIUS auth backend:
### Via the CLI
```
$ vault auth-enable radius
Successfully enabled 'radius' at 'radius'!
```
1. Enable the radius auth method:
Now when you run `vault auth -methods`, the RADIUS backend is
available:
```text
$ vault auth enable radius
```
```
Path Type Description
token/ token token based credentials
radius/ radius
```
1. Configure connection details for your RADIUS server.
To use the radius auth backend, it must first be configured with connection
details for your RADIUS server.
The configuration options are detailed below in the API docs.
Configuration is written to `auth/radius/config`.
```text
$ vault write auth/radius/users/mitchellh policies=admins
```
To use the "radius" auth backend, an operator must configure a
mapping between users and policies. An example is shown below.
Use `vault path-help` for more details.
For the complete list of configuration options, please see the API
documentation.
```
$ vault write auth/radius/users/mitchellh \
policies=admins
...
```
The above creates a new mapping for user "mitchellh" that will be associated
with the "admins" policy.
The above creates a new mapping for user "mitchellh" that
will be associated with the "admins" policy.
Alternatively, Vault can assign a configurable set of policies to
any user that successfully authenticates with the RADIUS server but
has no explicit mapping in the `users/` path.
This is done through the `unregistered_user_policies` configuration parameter.
Alternatively, Vault can assign a configurable set of policies to any user
that successfully authenticates with the RADIUS server but has no explicit
mapping in the `users/` path. This is done through the
`unregistered_user_policies` configuration parameter.
## API
The RADIUS authentication backend has a full HTTP API. Please see the
The RADIUS auth method has a full HTTP API. Please see the
[RADIUS Auth API](/api/auth/radius/index.html) for more
details.

27
website/source/docs/auth/token.html.md
View File

@ -1,23 +1,21 @@
---
layout: "docs"
page_title: "Auth Backend: Token"
page_title: "Token - Auth Methods"
sidebar_current: "docs-auth-token"
description: |-
The token store auth backend is used to authenticate using tokens.
The token store auth method is used to authenticate using tokens.
---
# Auth Backend: Token
# Token Auth Method
The token backend is the only auth backend that is built-in and
automatically available at `/auth/token` as well as with first-class
built-in CLI methods such as `vault token-create`. It allows users to
authenticate using a token, as well to create new tokens, revoke
The `token` method is built-in and automatically available at `/auth/token`. It
allows users to authenticate using a token, as well to create new tokens, revoke
secrets by token, and more.
When any other auth backend returns an identity, Vault core invokes the
token backend to create a new unique token for that identity.
When any other auth method returns an identity, Vault core invokes the
token method to create a new unique token for that identity.
The token store can also be used to bypass any other auth backend:
The token store can also be used to bypass any other auth method:
you can create tokens directly, as well as perform a variety of other
operations on tokens such as renewal and revocation.
@ -28,9 +26,8 @@ to tokens.
### Via the CLI
```
$ vault auth <token>
...
```text
$ vault login token=<token>
```
### Via the API
@ -40,6 +37,6 @@ of the header should be "X-Vault-Token" and the value should be the token.
## API
The Token authentication backend has a full HTTP API. Please see the
[Token auth backend API](/api/auth/token/index.html) for more
The Token auth method has a full HTTP API. Please see the
[Token auth method API](/api/auth/token/index.html) for more
details.

82
website/source/docs/auth/userpass.html.md
View File

@ -1,49 +1,45 @@
---
layout: "docs"
page_title: "Auth Backend: Username & Password"
page_title: "Userpass - Auth Methods"
sidebar_current: "docs-auth-userpass"
description: |-
The "userpass" auth backend allows users to authenticate with Vault using a username and password.
The "userpass" auth method allows users to authenticate with Vault using a username and password.
---
# Auth Backend: Username & Password
# Userpass Auth Method
Name: `userpass`
The "userpass" auth backend allows users to authenticate with Vault using
The `userpass` auth method allows users to authenticate with Vault using
a username and password combination.
The username/password combinations are configured directly to the auth
backend using the `users/` path. This backend cannot read usernames and
method using the `users/` path. This method cannot read usernames and
passwords from an external source.
The backend lowercases all submitted usernames, e.g. `Mary` and `mary` are the
The method lowercases all submitted usernames, e.g. `Mary` and `mary` are the
same entry.
## Authentication
#### Via the CLI
### Via the CLI
```
$ vault auth -method=userpass \
```text
$ vault login -method=userpass \
username=foo \
password=bar
```
#### Via the API
The endpoint for the login is `auth/userpass/login/<username>`.
The password should be sent in the POST body encoded as JSON.
### Via the API
```shell
$ curl $VAULT_ADDR/v1/auth/userpass/login/mitchellh \
-d '{ "password": "foo" }'
$ curl \
--request POST \
--data '{"password": "foo"}' \
https://vault.rocks/v1/auth/userpass/login/mitchellh
```
The response will be in JSON. For example:
The response will contain the token at `auth.client_token`:
```javascript
```json
{
"lease_id": "",
"renewable": false,
@ -65,40 +61,30 @@ The response will be in JSON. For example:
## Configuration
First, you must enable the username/password auth backend:
Auth methods must be configured in advance before users or machines can
authenticate. These steps are usually completed by an operator or configuration
management tool.
```
$ vault auth-enable userpass
Successfully enabled 'userpass' at 'userpass'!
```
1. Enable the userpass auth method:
Now when you run `vault auth -methods`, the username/password backend is
available:
```text
$ vault auth enable userpass
```
```
Path Type Description
token/ token token based credentials
userpass/ userpass
```
1. Configure it with users that are allowed to authenticate:
To use the "userpass" auth backend, an operator must configure it with
users that are allowed to authenticate. An example is shown below.
Use `vault path-help` for more details.
```text
$ vault write auth/userpass/users/mitchellh \
password=foo \
policies=admins
```
```
$ vault write auth/userpass/users/mitchellh \
password=foo \
policies=admins
...
```
The above creates a new user "mitchellh" with the password "foo" that
will be associated with the "admins" policy. This is the only configuration
necessary.
This creates a new user "mitchellh" with the password "foo" that will be
associated with the "admins" policy. This is the only configuration
necessary.
## API
The Username & Password authentication backend has a full HTTP API. Please see the
[Userpass auth backend API](/api/auth/userpass/index.html) for more
The Userpass auth method has a full HTTP API. Please see the
[Userpass auth method API](/api/auth/userpass/index.html) for more
details.

2
website/source/docs/commands/auth/help.html.md
View File

@ -26,7 +26,7 @@ Get usage instructions for the userpass auth method:
$ vault auth help userpass
Usage: vault login -method=userpass [CONFIG K=V...]
The userpass authentication method allows users to authenticate using Vault's
The userpass auth method allows users to authenticate using Vault's
internal user database.
# ...

12
website/source/docs/commands/login.html.md
View File

@ -15,13 +15,13 @@ arguments. A successful authentication results in a Vault token - conceptually
similar to a session token on a website. By default, this token is cached on the
local machine for future requests.
The `-method` flag allows using other authentication methods, such as userpass,
The `-method` flag allows using other auth methods, such as userpass,
github, or cert. For these, additional "K=V" pairs may be required. For more
information about the list of configuration parameters available for a given
authentication method, use the "vault auth help TYPE". You can also use "vault
auth list" to see the list of enabled authentication methods.
auth method, use the "vault auth help TYPE". You can also use "vault
auth list" to see the list of enabled auth methods.
If an authentication method is enabled at a non-standard path, the `-method`
If an auth method is enabled at a non-standard path, the `-method`
flag still refers to the canonical type, but the `-path` flag refers to the
enabled path.
@ -66,7 +66,7 @@ renewable: true
policies: [default]
```
If a github authentication method was enabled at the path "github-ent":
If a github auth method was enabled at the path "github-ent":
```text
$ vault login -method=github -path=github-prod
@ -105,7 +105,7 @@ flags](/docs/commands/index.html) included on all commands.
(usually the local filesystem) after authentication for use in future
requests. The token will only be displayed in the command output.
- `-path` `(string: "")` - Remote path in Vault where the authentication method
- `-path` `(string: "")` - Remote path in Vault where the auth method
is enabled. This defaults to the TYPE of method (e.g. userpass -> userpass/).
- `-token-only` `(bool: false)` - Output only the token with no verification.

2
website/source/docs/commands/ssh.html.md
View File

@ -45,7 +45,7 @@ $ vault ssh \
```
For step-by-step guides and instructions for each of the available SSH
authentication methods, please see the corresponding [SSH secrets
auth methods, please see the corresponding [SSH secrets
engine](/docs/secrets/ssh/index.html).
## Usage

2
website/source/docs/commands/unwrap.html.md
View File

@ -26,7 +26,7 @@ $ vault unwrap 3de9ece1-b347-e143-29b0-dc2dc31caafd
Unwrap the data in the active token:
```text
$ vault auth 848f9ccf-7176-098c-5e2b-75a0689d41cd
$ vault login 848f9ccf-7176-098c-5e2b-75a0689d41cd
$ vault unwrap # unwraps 848f9ccf...
```

30
website/source/docs/concepts/auth.html.md
View File

@ -10,26 +10,26 @@ description: |-
Authentication in Vault is the process by which user or machine supplied
information is verified against an internal or external system. Vault supports
multiple [authentication backends](/docs/auth/index.html) including GitHub,
LDAP, AppRole, and more. Each authentication backend has a specific use case.
multiple [auth methods](/docs/auth/index.html) including GitHub,
LDAP, AppRole, and more. Each auth method has a specific use case.
Before a client can interact with Vault, it must _authenticate_ against an
authentication backend. Upon authentication, a token is generated. This token is
auth method. Upon authentication, a token is generated. This token is
conceptually similar to a session ID on a website. The token may have attached
policy, which is mapped at authentication time. This process is described in
detail in the [policies concepts](/docs/concepts/policies.html) documentation.
## Authentication Backends
## auth methods
Vault supports a number of authentication backends. Some backends are targeted
Vault supports a number of auth methods. Some backends are targeted
toward users while others are targeted toward machines. Most authentication
backends must be enabled before use. To enable an authentication backend:
backends must be enabled before use. To enable an auth method:
```sh
$ vault write sys/auth/my-auth type=userpass
```
This mounts the "userpass" authentication backend at the path "my-auth". This
This mounts the "userpass" auth method at the path "my-auth". This
authentication will be accessible at the path "my-auth". Often you will see
authentications at the same path as their name, but this is not a requirement.
@ -40,10 +40,10 @@ $ vault path-help auth/my-auth
# ...
```
Vault supports multiple authentication backends simultaneously, and you can even
mount the same type of authentication backend at different paths. Only one
Vault supports multiple auth methods simultaneously, and you can even
mount the same type of auth method at different paths. Only one
authentication is required to gain access to Vault, and it is not currently
possible to force a user through multiple authentication backends to gain
possible to force a user through multiple auth methods to gain
access, although some backends do support MFA.
## Tokens
@ -67,10 +67,10 @@ revoking tokens, and renewing tokens. This is all covered on the
### Via the CLI
To authenticate with the CLI, `vault auth` is used. This supports many
of the built-in authentication methods. For example, with GitHub:
of the built-in auth methods. For example, with GitHub:
```
$ vault auth -method=github token=<token>
$ vault login -method=github token=<token>
...
```
@ -79,7 +79,7 @@ output your raw token. This token is used for revocation and renewal.
As the user logging in, the primary use case of the token is renewal,
covered below in the "Auth Leases" section.
To determine what variables are needed for an authentication method,
To determine what variables are needed for an auth method,
supply the `-method` flag without any additional arguments and help
will be shown.
@ -89,7 +89,7 @@ must be used.
### Via the API
API authentication is generally used for machine authentication. Each
auth backend implements its own login endpoint. Use the `vault path-help`
auth method implements its own login endpoint. Use the `vault path-help`
mechanism to find the proper endpoint.
For example, the GitHub login endpoint is located at `auth/github/login`.
@ -104,7 +104,7 @@ you must reauthenticate after the given lease period to continue accessing
Vault.
To set the lease associated with an identity, reference the help for
the specific authentication backend in use. It is specific to each backend
the specific auth method in use. It is specific to each backend
how leasing is implemented.
And just like secrets, identities can be renewed without having to

2
website/source/docs/concepts/dev-server.html.md
View File

@ -44,7 +44,7 @@ The properties of the dev server:
## Use Case
The dev server should be used for experimentation with Vault features, such
as different authentication backends, secret backends, audit backends, etc.
as different auth methods, secret backends, audit backends, etc.
If you're new to Vault, you may want to pick up with [Your First
Secret](/intro/getting-started/first-secret.html) in
our getting started guide.

16
website/source/docs/concepts/policies.html.md
View File

@ -18,22 +18,22 @@ system.
## Policy-Authorization Workflow
Before a human or machine can gain access, an administrator must configure Vault
with an [authentication backend](/docs/concepts/auth.html). Authentication is
with an [auth method](/docs/concepts/auth.html). Authentication is
the process by which human or machine-supplied information is verified against
an internal or external system.
Consider the following diagram, which illustrates the steps a security team
would take to configure Vault to authenticate using a corporate LDAP or
ActiveDirectory installation. Even though this example uses LDAP, the concept
applies to all authentication backends.
applies to all auth methods.
[![Vault Auth Workflow](/assets/images/vault-policy-workflow.svg)](/assets/images/vault-policy-workflow.svg)
1. The security team configures Vault to connect to an authentication backend.
This configuration varies by authentication backend. In the case of LDAP, Vault
1. The security team configures Vault to connect to an auth method.
This configuration varies by auth method. In the case of LDAP, Vault
needs to know the address of the LDAP server and whether to connect using TLS.
It is important to note that Vault does not store a copy of the LDAP database -
Vault will delegate the authentication to the authentication backend.
Vault will delegate the authentication to the auth method.
1. The security team authors a policy (or uses an existing policy) which grants
access to paths in Vault. Policies are written in HCL in your editor of
@ -53,7 +53,7 @@ policy. For example, the security team might create mappings like:
Now Vault has an internal mapping between a backend authentication system and
internal policy. When a user authenticates to Vault, the actual authentication
is delegated to the authentication backend. As a user, the flow looks like:
is delegated to the auth method. As a user, the flow looks like:
[![Vault Auth Workflow](/assets/images/vault-auth-workflow.svg)](/assets/images/vault-auth-workflow.svg)
@ -527,7 +527,7 @@ policy that does not exist.
Vault can automatically associate a set of policies to a token based on an
authorization. This configuration varies significantly between authentication
backends. For simplicity, this example will use Vault's built-in userpass
authentication backend.
auth method.
A Vault administrator or someone from the security team would create the user in
Vault with a list of associated policies:
@ -545,7 +545,7 @@ of policies attached.
The user wishing to authenticate would run
```sh
$ vault auth -method="userpass" username="sethvargo"
$ vault login -method="userpass" username="sethvargo"
Password (will be hidden): ...
```

18
website/source/docs/concepts/tokens.html.md
View File

@ -3,19 +3,19 @@ layout: "docs"
page_title: "Tokens"
sidebar_current: "docs-concepts-tokens"
description: |-
Tokens are a core authentication method in Vault. Concepts and important features.
Tokens are a core auth method in Vault. Concepts and important features.
---
# Tokens
Tokens are the core method for _authentication_ within Vault. Tokens
can be used directly or [authentication backends](/docs/concepts/auth.html)
can be used directly or [auth methods](/docs/concepts/auth.html)
can be used to dynamically generate tokens based on external identities.
If you've gone through the getting started guide, you probably noticed that
`vault server -dev` (or `vault init` for a non-dev server) outputs an
initial "root token." This is the first method of authentication for Vault.
It is also the only authentication backend that cannot be disabled.
It is also the only auth method that cannot be disabled.
As stated in the [authentication concepts](/docs/concepts/auth.html),
all external authentication mechanisms, such as GitHub, map down to dynamically
@ -39,7 +39,7 @@ Often in documentation or in help channels, the "token store" is referenced.
This is the same as the [`token` authentication
backend](/docs/auth/token.html). This is a special
backend in that it is responsible for creating and storing tokens, and cannot
be disabled. It is also the only authentication backend that has no login
be disabled. It is also the only auth method that has no login
capability -- all actions require existing authenticated tokens.
### Root Tokens
@ -59,7 +59,7 @@ of version 0.6.1, there are only three ways to create root tokens:
Root tokens are useful in development but should be extremely carefully guarded
in production. In fact, the Vault team recommends that root tokens are only
used for just enough initial setup (usually, setting up authentication backends
used for just enough initial setup (usually, setting up auth methods
and policies necessary to allow administrators to acquire more limited tokens)
or in emergencies, and are revoked immediately after they are no longer needed.
If a new root token is needed, the `generate-root` command and associated [API
@ -87,7 +87,7 @@ token tree. These orphan tokens can be created:
2. By having `sudo` capability or `root` policy when accessing
`auth/token/create` and setting the `orphan` parameter to `true`
3. Via token store roles
4. By logging in with any other (non-`token`) authentication backend
4. By logging in with any other (non-`token`) auth method
Users with appropriate permissions can also use the `auth/token/revoke-orphan`
endpoint, which revokes the given token but rather than revoke the rest of the
@ -135,7 +135,7 @@ If the token is renewable, Vault can be asked to extend the token validity
period using `vault token-renew` or the appropriate renewal endpoint. At this
time, various factors come into play. What happens depends upon whether the
token is a periodic token (available for creation by `root`/`sudo` users, token
store roles, or some authentication backends), has an explicit maximum TTL
store roles, or some auth methods), has an explicit maximum TTL
attached, or neither.
#### The General Case
@ -152,7 +152,7 @@ token's information is looked up. It is based on a combination of factors:
tuning](/api/system/mounts.html). This value
is allowed to override the system max TTL -- it can be longer or shorter,
and if set this value will be respected.
3. A value suggested by the authentication backend that issued the token. This
3. A value suggested by the auth method that issued the token. This
might be configured on a per-role, per-group, or per-user basis. This value
is allowed to be less than the mount max TTL (or, if not set, the system max
TTL), but it is not allowed to be longer.
@ -184,7 +184,7 @@ can be created in a few ways:
1. By having `sudo` capability or a `root` token with the `auth/token/create`
endpoint
2. By using token store roles
3. By using an authentication backend that supports issuing these, such as
3. By using an auth method that supports issuing these, such as
AppRole
At issue time, the TTL of a periodic token will be equal to the configured

2
website/source/docs/enterprise/hsm/behavior.html.md
View File

@ -1,6 +1,6 @@
---
layout: "docs"
page_title: "Vault Enterprise HSM Behavioral Changes"
page_title: "Behavioral Changes - HSM Integration - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-hsm-behavior"
description: |-
Vault Enterprise HSM support changes the way Vault works with regard to unseal and recovery keys as well as rekey and recovery operations.

8
website/source/docs/enterprise/hsm/configuration.html.md
View File

@ -1,6 +1,6 @@
---
layout: "docs"
page_title: "Vault Enterprise HSM Configuration"
page_title: "Configuration - HSM Integration - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-hsm-configuration"
description: |-
Vault Enterprise HSM configuration details.
@ -50,11 +50,11 @@ strings.
### Required Directives
* `lib`: The path to the PKCS#11 library shared object file. May also be
specified by the `VAULT_HSM_LIB` environment variable. **Note:** Depending
specified by the `VAULT_HSM_LIB` environment variable. **Note:** Depending
on your HSM, this may be either a binary or a dynamic library, and its use
may require other libraries depending on which system the Vault binary is
may require other libraries depending on which system the Vault binary is
currently running on (e.g.: a Linux system may require other libraries to
interpret Windows .dll files).
interpret Windows .dll files).
* `slot`: The slot number to use, specified as a string (e.g. `"0"`). May also
be specified by the `VAULT_HSM_SLOT` environment variable.
* `pin`: The PIN for login. May also be specified by the `VAULT_HSM_PIN`

2
website/source/docs/enterprise/hsm/index.html.md
View File

@ -1,6 +1,6 @@
---
layout: "docs"
page_title: "Vault Enterprise HSM Support"
page_title: "HSM Integration - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-hsm"
description: |-
Vault Enterprise has HSM support, allowing for external master key storage and automatic unsealing.

2
website/source/docs/enterprise/hsm/security.html.md
View File

@ -1,6 +1,6 @@
---
layout: "docs"
page_title: "Vault Enterprise HSM Security Details"
page_title: "Security Details - HSM Integration - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-hsm-security"
description: |-
Recommendations to ensure the security of a Vault Enterprise HSM deployment.

18
website/source/docs/enterprise/identity/index.html.md
View File

@ -1,6 +1,6 @@
---
layout: "docs"
page_title: "Vault Enterprise Identity"
page_title: "Identity - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-identity"
description: |-
Vault Enterprise has the foundations of the identity management system.
@ -52,12 +52,12 @@ identifier, the policies on the token should be taken into account.
### Mount Bound Personas
Vault supports multiple authentication backends and also allows enabling same
authentication backend on different mounts. The persona name of the user with
Vault supports multiple auth methods and also allows enabling same
auth method on different mounts. The persona name of the user with
each identity provider will be unique within the provider. But Vault also needs
to uniquely distinguish between conflicting persona names across different
mounts of these identity providers. Hence the persona name, in combination with
the authentication backend mount's accessor serve as the unique identifier of a
the auth method mount's accessor serve as the unique identifier of a
persona.
### Implicit Entities
@ -65,19 +65,19 @@ persona.
Operators can create entities for all the users of an auth mount
beforehand and assign policies to them, so that when users login, the desired
capabilities to the tokens via entities are already assigned. But if that's not
done, upon a successful user login from any of the authentication backends,
done, upon a successful user login from any of the auth methods,
Vault will create a new entity and assign a persona against the login that was
successful.
Note that, tokens created using the token authentication backend will not have
Note that, tokens created using the token auth method will not have
an associated identity information. Logging in using the authentication
backends is the only way to create tokens that have a valid entity identifiers.
### Identity Auditing
If the token used to make API calls have an associated entity identifier, it will
be audit logged as well. This leaves a trail of actions performed by specific
users.
If the token used to make API calls have an associated entity identifier, it
will be audit logged as well. This leaves a trail of actions performed by
specific users.
### API

8
website/source/docs/enterprise/mfa/index.html.md
View File

@ -1,6 +1,6 @@
---
layout: "docs"
page_title: "Vault Enterprise MFA Support"
page_title: "MFA Support - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-mfa"
description: |-
Vault Enterprise has support for Multi-factor Authentication (MFA), using different authentication types.
@ -50,10 +50,10 @@ parameters.
### Sample Policy
```
```hcl
path "secret/foo" {
capabilities = ["read"]
mfa_methods = ["dev_team_duo", "sales_team_totp"]
capabilities = ["read"]
mfa_methods = ["dev_team_duo", "sales_team_totp"]
}
```

213
website/source/docs/enterprise/mfa/mfa-duo.html.md
View File

@ -1,6 +1,6 @@
---
layout: "docs"
page_title: "Vault Enterprise Duo MFA"
page_title: "Duo MFA - MFA Support - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-mfa-duo"
description: |-
Vault Enterprise supports Duo MFA type.
@ -10,132 +10,123 @@ description: |-
This page demonstrates the Duo MFA on ACL'd paths of Vault.
## Steps
## Configuration
### Enable Auth Backend
1. Enable the appropriate auth method:
```
vault auth-enable userpass
```
```text
$ vault auth enable userpass
```
### Fetch Mount Accessor
1. Fetch the mount accessor for the enabled auth method:
```
vault auth -methods
```
```text
$ vault auth list -detailed
```
```
Path Type Accessor Default TTL Max TTL Replication Behavior Description
...
userpass/ userpass auth_userpass_54b8e339 system system replicated
```
The response will look like:
```text
Path Type Accessor Plugin Default TTL Max TTL Replication Description
---- ---- -------- ------ ----------- ------- ----------- -----------
token/ token auth_token_289703e9 n/a system system replicated token based credentials
userpass/ userpass auth_userpass_54b8e339 n/a system system replicated n/a
```
1. Configure Duo MFA:
```text
$ vault write sys/mfa/method/duo/my_duo \
mount_accessor=auth_userpass_54b8e339 \
integration_key=BIACEUEAXI20BNWTEYXT \
secret_key=HIGTHtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz \
api_hostname=api-2b5c39f5.duosecurity.com
```
1. Create a policy that gives access to secret through the MFA method created
above:
```text
$ vault policy-write duo-policy -<<EOF
path "secret/foo" {
capabilities = ["read"]
mfa_methods = ["my_duo"]
}
EOF
```
1. Create a user. MFA works only for tokens that have identity information on
them. Tokens created by logging in using auth methods will have the associated
identity information. Create a user in the `userpass` auth method and
authenticate against it:
### Configure Duo MFA method
```text
$ vault write auth/userpass/users/testuser \
password=testpassword \
policies=duo-policy
```
```
vault write sys/mfa/method/duo/my_duo mount_accessor=auth_userpass_54b8e339 integration_key=BIACEUEAXI20BNWTEYXT secret_key=HIGTHtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz api_hostname=api-2b5c39f5.duosecurity.com
```
1. Create a login token:
### Create Policy
```text
$ vault write auth/userpass/login/testuser \
password=testpassword
Create a policy that gives access to secret through the MFA method created
above.
Key Value
--- -----
token 70f97438-e174-c03c-40fe-6bcdc1028d6c
token_accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
token_duration 768h
token_renewable true
token_policies [default duo-policy]
token_meta_username "testuser"
```
#### Sample Payload
Note that the CLI is not authenticated with the newly created token yet, we
did not call `vault login`, instead we used the login API to simply return a
token.
```hcl
path "secret/foo" {
capabilities = ["read"]
mfa_methods = ["my_duo"]
}
```
1. Fetch the entity ID from the token. The caller identity is represented by the
`entity_id` property of the token:
```
vault policy-write duo-policy payload.hcl
```
```text
$ vault token-lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
### Create User
Key Value
--- -----
accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
creation_time 1502245243
creation_ttl 2764800
display_name userpass-testuser
entity_id 307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
expire_time 2017-09-09T22:20:43.448543132-04:00
explicit_max_ttl 0
id 70f97438-e174-c03c-40fe-6bcdc1028d6c
issue_time 2017-08-08T22:20:43.448543003-04:00
meta map[username:testuser]
num_uses 0
orphan true
path auth/userpass/login/testuser
policies [default duo-policy]
renewable true
ttl 2764623
```
MFA works only for tokens that have identity information on them. Tokens
created by logging in using authentication backends will have the associated
identity information. Let's create a user in the `userpass` backend and
authenticate against it.
1. Login as the user:
```text
$ vault login 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
```
vault write auth/userpass/users/testuser password=testpassword policies=duo-policy
```
1. Read a secret to trigger a Duo push. This will be a blocking call until
the push notification is either approved or declined:
### Create Login Token
```text
$ vault read secret/foo
```
vault write auth/userpass/login/testuser password=testpassword
```
```
Key Value
--- -----
token 70f97438-e174-c03c-40fe-6bcdc1028d6c
token_accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
token_duration 768h0m0s
token_renewable true
token_policies [default duo-policy]
token_meta_username "testuser"
```
Note that the CLI is not authenticated with the newly created token yet, we did
not call `vault auth`, instead we used the login API to simply return a token.
### Fetch Entity ID From Token
Caller identity is represented by the `entity_id` property of the token.
```
vault token-lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
```
Key Value
--- -----
accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
creation_time 1502245243
creation_ttl 2764800
display_name userpass-testuser
entity_id 307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
expire_time 2017-09-09T22:20:43.448543132-04:00
explicit_max_ttl 0
id 70f97438-e174-c03c-40fe-6bcdc1028d6c
issue_time 2017-08-08T22:20:43.448543003-04:00
meta map[username:testuser]
num_uses 0
orphan true
path auth/userpass/login/testuser
policies [default duo-policy]
renewable true
ttl 2764623
```
### Login
Authenticate the CLI to use the newly created token.
```
vault auth 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
### Read Secret
Reading the secret will trigger a Duo push. This will be a blocking call until
the push notification is either approved or declined.
```
vault read secret/foo
```
```
Key Value
--- -----
refresh_interval 768h0m0s
data which can only be read after MFA validation
```
Key Value
--- -----
refresh_interval 768h
data which can only be read after MFA validation
```

211
website/source/docs/enterprise/mfa/mfa-okta.html.md
View File

@ -1,6 +1,6 @@
---
layout: "docs"
page_title: "Vault Enterprise Okta MFA"
page_title: "Okta MFA - MFA Support - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-mfa-okta"
description: |-
Vault Enterprise supports Okta MFA type.
@ -10,132 +10,121 @@ description: |-
This page demonstrates the Okta MFA on ACL'd paths of Vault.
## Steps
## Configuration
### Enable Auth Backend
1. Enable the appropriate auth method:
```
vault auth-enable userpass
```
```text
$ vault auth enable userpass
```
### Fetch Mount Accessor
1. Fetch the mount accessor for the enabled auth method:
```
vault auth -methods
```
```text
$ vault auth list -detailed
```
```
Path Type Accessor Default TTL Max TTL Replication Behavior Description
...
userpass/ userpass auth_userpass_54b8e339 system system replicated
```
The response will look like:
```text
Path Type Accessor Plugin Default TTL Max TTL Replication Description
---- ---- -------- ------ ----------- ------- ----------- -----------
token/ token auth_token_289703e9 n/a system system replicated token based credentials
userpass/ userpass auth_userpass_54b8e339 n/a system system replicated n/a
```
1. Configure Okta MFA:
```text
$ vault write sys/mfa/method/okta/my_okta \
mount_accessor=auth_userpass_54b8e339 \
org_name="dev-262775" \
api_token="0071u8PrReNkzmATGJAP2oDyIXwwveqx9vIOEyCZDC"
```
1. Create a policy that gives access to secret through the MFA method created
above:
```text
$ vault policy-write okta-policy -<<EOF
path "secret/foo" {
capabilities = ["read"]
mfa_methods = ["my_okta"]
}
EOF
```
1. Create a user. MFA works only for tokens that have identity information on
them. Tokens created by logging in using auth methods will have the associated
identity information. Create a user in the `userpass` auth method and
authenticate against it:
### Configure Okta MFA method
```text
$ vault write auth/userpass/users/testuser \
password=testpassword \
policies=okta-policy
```
```
vault write sys/mfa/method/okta/my_okta mount_accessor=auth_userpass_54b8e339 org_name="dev-262775" api_token="0071u8PrReNkzmATGJAP2oDyIXwwveqx9vIOEyCZDC"
```
1. Create a login token:
### Create Policy
```text
$ vault write auth/userpass/login/testuser password=testpassword
Create a policy that gives access to secret through the MFA method created
above.
Key Value
--- -----
token 70f97438-e174-c03c-40fe-6bcdc1028d6c
token_accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
token_duration 768h0m0s
token_renewable true
token_policies [default okta-policy]
token_meta_username "testuser"
```
#### Sample Payload
Note that the CLI is not authenticated with the newly created token yet, we
did not call `vault login`, instead we used the login API to simply return a
token.
```hcl
path "secret/foo" {
capabilities = ["read"]
mfa_methods = ["my_okta"]
}
```
1. Fetch the entity ID from the token. The caller identity is represented by the
`entity_id` property of the token:
```
vault policy-write okta-policy payload.hcl
```
```text
$ vault token-lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
### Create User
Key Value
--- -----
accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
creation_time 1502245243
creation_ttl 2764800
display_name userpass-testuser
entity_id 307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
expire_time 2017-09-09T22:20:43.448543132-04:00
explicit_max_ttl 0
id 70f97438-e174-c03c-40fe-6bcdc1028d6c
issue_time 2017-08-08T22:20:43.448543003-04:00
meta map[username:testuser]
num_uses 0
orphan true
path auth/userpass/login/testuser
policies [default okta-policy]
renewable true
ttl 2764623
```
MFA works only for tokens that have identity information on them. Tokens
created by logging in using authentication backends will have the associated
identity information. Let's create a user in the `userpass` backend and
authenticate against it.
1. Login as the user:
```text
$ vault login 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
```
vault write auth/userpass/users/testuser password=testpassword policies=okta-policy
```
1. Read a secret to trigger an Okta push. This will be a blocking call until
the push notification is either approved or declined:
### Create Login Token
```text
$ vault read secret/foo
```
vault write auth/userpass/login/testuser password=testpassword
```
```
Key Value
--- -----
token 70f97438-e174-c03c-40fe-6bcdc1028d6c
token_accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
token_duration 768h0m0s
token_renewable true
token_policies [default okta-policy]
token_meta_username "testuser"
```
Note that the CLI is not authenticated with the newly created token yet, we did
not call `vault auth`, instead we used the login API to simply return a token.
### Fetch Entity ID From Token
Caller identity is represented by the `entity_id` property of the token.
```
vault token-lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
```
Key Value
--- -----
accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
creation_time 1502245243
creation_ttl 2764800
display_name userpass-testuser
entity_id 307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
expire_time 2017-09-09T22:20:43.448543132-04:00
explicit_max_ttl 0
id 70f97438-e174-c03c-40fe-6bcdc1028d6c
issue_time 2017-08-08T22:20:43.448543003-04:00
meta map[username:testuser]
num_uses 0
orphan true
path auth/userpass/login/testuser
policies [default okta-policy]
renewable true
ttl 2764623
```
### Login
Authenticate the CLI to use the newly created token.
```
vault auth 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
### Read Secret
Reading the secret will trigger an Okta push. This will be a blocking call until
the push notification is either approved or declined.
```
vault read secret/foo
```
```
Key Value
--- -----
refresh_interval 768h0m0s
data which can only be read after MFA validation
```
Key Value
--- -----
refresh_interval 768h0m0s
data which can only be read after MFA validation
```

199
website/source/docs/enterprise/mfa/mfa-pingid.html.md
View File

@ -1,6 +1,6 @@
---
layout: "docs"
page_title: "Vault Enterprise PingID MFA"
page_title: "PingID MFA - MFA Support - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-mfa-pingid"
description: |-
Vault Enterprise supports PingID MFA type.
@ -10,132 +10,121 @@ description: |-
This page demonstrates PingID MFA on ACL'd paths of Vault.
## Steps
## Configuration
### Enable Auth Backend
1. Enable the appropriate auth method:
```
vault auth-enable userpass
```
```text
$ vault auth enable userpass
```
### Fetch Mount Accessor
1. Fetch the mount accessor for the enabled auth method:
```
vault auth -methods
```
```text
$ vault auth list -detailed
```
```
Path Type Accessor Default TTL Max TTL Replication Behavior Description
...
userpass/ userpass auth_userpass_54b8e339 system system replicated
```
The response will look like:
```text
Path Type Accessor Plugin Default TTL Max TTL Replication Description
---- ---- -------- ------ ----------- ------- ----------- -----------
token/ token auth_token_289703e9 n/a system system replicated token based credentials
userpass/ userpass auth_userpass_54b8e339 n/a system system replicated n/a
```
### Configure PingID MFA method
1. Configure PingID MFA:
```
vault write sys/mfa/method/pingid/ping mount_accessor=auth_userpass_54b8e339 settings_file_base64="AABDwWaR..."
```
```text
$ vault write sys/mfa/method/pingid/ping \
mount_accessor=auth_userpass_54b8e339 \
settings_file_base64="AABDwWaR..."
```
### Create Policy
1. Create a policy that gives access to secret through the MFA method created
above:
Create a policy that gives access to secret through the MFA method created
above.
```
$ vault policy-write ping-policy -<<EOF
path "secret/foo" {
capabilities = ["read"]
mfa_methods = ["ping"]
}
EOF
```
#### Sample Payload
```hcl
path "secret/foo" {
capabilities = ["read"]
mfa_methods = ["ping"]
}
```
```
vault policy-write ping-policy payload.hcl
```
### Create User
MFA works only for tokens that have identity information on them. Tokens
created by logging in using authentication backends will have the associated
identity information. Let's create a user in the `userpass` backend and
authenticate against it.
1. Create a user. MFA works only for tokens that have identity information on
them. Tokens created by logging in using auth methods will have the associated
identity information. Create a user in the `userpass` auth method and
authenticate against it:
```
vault write auth/userpass/users/testuser password=testpassword policies=ping-policy
```
```text
$ vault write auth/userpass/users/testuser \
password=testpassword \
policies=ping-policy
```
### Create Login Token
1. Create a login token:
```
vault write auth/userpass/login/testuser password=testpassword
```
```text
$ vault write auth/userpass/login/testuser password=testpassword
```
Key Value
--- -----
token 70f97438-e174-c03c-40fe-6bcdc1028d6c
token_accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
token_duration 768h0m0s
token_renewable true
token_policies [default ping-policy]
token_meta_username "testuser"
```
Key Value
--- -----
token 70f97438-e174-c03c-40fe-6bcdc1028d6c
token_accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
token_duration 768h0m0s
token_renewable true
token_policies [default ping-policy]
token_meta_username "testuser"
```
Note that the CLI is not authenticated with the newly created token yet, we did
not call `vault auth`, instead we used the login API to simply return a token.
Note that the CLI is not authenticated with the newly created token yet, we
did not call `vault login`, instead we used the login API to simply return a
token.
### Fetch Entity ID From Token
1. Fetch the entity ID from the token. The caller identity is represented by the
`entity_id` property of the token:
Caller identity is represented by the `entity_id` property of the token.
```text
$ vault token-lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
vault token-lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
Key Value
--- -----
accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
creation_time 1502245243
creation_ttl 2764800
display_name userpass-testuser
entity_id 307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
expire_time 2017-09-09T22:20:43.448543132-04:00
explicit_max_ttl 0
id 70f97438-e174-c03c-40fe-6bcdc1028d6c
issue_time 2017-08-08T22:20:43.448543003-04:00
meta map[username:testuser]
num_uses 0
orphan true
path auth/userpass/login/testuser
policies [default ping-policy]
renewable true
ttl 2764623
```
```
Key Value
--- -----
accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
creation_time 1502245243
creation_ttl 2764800
display_name userpass-testuser
entity_id 307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
expire_time 2017-09-09T22:20:43.448543132-04:00
explicit_max_ttl 0
id 70f97438-e174-c03c-40fe-6bcdc1028d6c
issue_time 2017-08-08T22:20:43.448543003-04:00
meta map[username:testuser]
num_uses 0
orphan true
path auth/userpass/login/testuser
policies [default ping-policy]
renewable true
ttl 2764623
```
1. Login as the user:
### Login
```text
$ vault login 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
Authenticate the CLI to use the newly created token.
1. Read a secret to trigger a PingID push. This will be a blocking call until
the push notification is either approved or declined:
```
vault auth 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
```text
$ vault read secret/foo
### Read Secret
Reading the secret will trigger a PingID push. This will be a blocking call until
the push notification is either approved or declined.
```
vault read secret/foo
```
```
Key Value
--- -----
refresh_interval 768h0m0s
data which can only be read after MFA validation
```
Key Value
--- -----
refresh_interval 768h
data which can only be read after MFA validation
```

223
website/source/docs/enterprise/mfa/mfa-totp.html.md
View File

@ -1,6 +1,6 @@
---
layout: "docs"
page_title: "Vault Enterprise TOTP MFA"
page_title: "TOTP MFA - MFA Support - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-mfa-totp"
description: |-
Vault Enterprise supports TOTP MFA type.
@ -10,145 +10,140 @@ description: |-
This page demonstrates the TOTP MFA on ACL'd paths of Vault.
## Steps
## Configuration
### Configure TOTP MFA method
1. Enable the appropriate auth method:
```
vault write sys/mfa/method/totp/my_totp issuer=Vault period=30 key_size=30 algorithm=SHA256 digits=6
```
```text
$ vault auth enable userpass
```
### Create Secret
1. Fetch the mount accessor for the enabled auth method:
Create a secret to be accessed after validating MFA.
```text
$ vault auth list -detailed
```
```
vault write secret/foo data="which can only be read after MFA validation"
```
The response will look like:
### Create Policy
```text
Path Type Accessor Plugin Default TTL Max TTL Replication Description
---- ---- -------- ------ ----------- ------- ----------- -----------
token/ token auth_token_289703e9 n/a system system replicated token based credentials
userpass/ userpass auth_userpass_54b8e339 n/a system system replicated n/a
```
Create a policy that gives access to secret through the MFA method created
above.
1. Configure TOTP MFA:
#### Sample Payload
```text
$ vault write sys/mfa/method/totp/my_totp \
issuer=Vault \
period=30 \
key_size=30 \
algorithm=SHA256 \
digits=6
```
```hcl
path "secret/foo" {
capabilities = ["read"]
mfa_methods = ["my_totp"]
}
```
1. Create a policy that gives access to secret through the MFA method created
above:
```
vault policy-write totp-policy payload.hcl
```
```text
$ vault policy-write totp-policy -<<EOF
path "secret/foo" {
capabilities = ["read"]
mfa_methods = ["my_totp"]
}
EOF
```
### Enable Auth Backend
1. Create a user. MFA works only for tokens that have identity information on
them. Tokens created by logging in using auth methods will have the associated
identity information. Create a user in the `userpass` auth method and
authenticate against it:
MFA works only for tokens that have identity information on them. Tokens
created by logging in using authentication backends will have the associated
identity information. Let's create a user in the `userpass` backend and
authenticate against it.
```
vault auth-enable userpass
```
```text
$ vault write auth/userpass/users/testuser \
password=testpassword \
policies=duo-policy
```
### Create User
1. Create a login token:
```
vault write auth/userpass/users/testuser password=testpassword policies=totp-policy
```
```text
$ vault write auth/userpass/login/testuser \
password=testpassword
### Create Login Token
Key Value
--- -----
token 70f97438-e174-c03c-40fe-6bcdc1028d6c
token_accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
token_duration 768h
token_renewable true
token_policies [default duo-policy]
token_meta_username "testuser"
```
```
vault write auth/userpass/login/testuser password=testpassword
```
Note that the CLI is not authenticated with the newly created token yet, we
did not call `vault login`, instead we used the login API to simply return a
token.
```
Key Value
--- -----
token 70f97438-e174-c03c-40fe-6bcdc1028d6c
token_accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
token_duration 768h0m0s
token_renewable true
token_policies [default totp-policy]
token_meta_username "testuser"
```
1. Fetch the entity ID from the token. The caller identity is represented by the
`entity_id` property of the token:
Note that the CLI is not authenticated with the newly created token yet, we did
not call `vault auth`, instead we used the login API to simply return a token.
```text
$ vault token-lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
### Fetch Entity ID From Token
Key Value
--- -----
accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
creation_time 1502245243
creation_ttl 2764800
display_name userpass-testuser
entity_id 307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
expire_time 2017-09-09T22:20:43.448543132-04:00
explicit_max_ttl 0
id 70f97438-e174-c03c-40fe-6bcdc1028d6c
issue_time 2017-08-08T22:20:43.448543003-04:00
meta map[username:testuser]
num_uses 0
orphan true
path auth/userpass/login/testuser
policies [default duo-policy]
renewable true
ttl 2764623
```
Caller identity is represented by the `entity_id` property of the token.
1. Generate TOTP method attached to the entity. This should be distributed to
the intended user to be able to generate TOTP passcode:
```
vault token-lookup 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
```text
$ vault write sys/mfa/method/totp/my_totp/admin-generate \
entity_id=307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
```
Key Value
--- -----
accessor a91d97f4-1c7d-6af3-e4bf-971f74f9fab9
creation_time 1502245243
creation_ttl 2764800
display_name userpass-testuser
entity_id 307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
expire_time 2017-09-09T22:20:43.448543132-04:00
explicit_max_ttl 0
id 70f97438-e174-c03c-40fe-6bcdc1028d6c
issue_time 2017-08-08T22:20:43.448543003-04:00
meta map[username:testuser]
num_uses 0
orphan true
path auth/userpass/login/testuser
policies [default totp-policy]
renewable true
ttl 2764623
```
Key Value
--- -----
barcode iVBORw0KGgoAAAANSUhEUgAAAM...
url otpauth://totp/Vault:307d6c16-6f5c-4ae7-46a9-2d153ffcbc63?algo...
```
### Generate TOTP Method Secret on Entity
Either the base64 encoded png barcode or the url should be given to the end
user. This barcode/url can be loaded into Google Authenticator or a similar
TOTP tool to generate codes.
Let's generate a TOTP key using the `my_totp` configuration and store it in the
entity of the user. A barcode and a URL for the secret key will be returned by
the API. This should be distributed to the intended user to be able to generate
TOTP passcode.
1. Login as the user:
```
vault write sys/mfa/method/totp/my_totp/admin-generate entity_id=307d6c16-6f5c-4ae7-46a9-2d153ffcbc63
```
```text
$ vault login 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
```
Key Value
--- -----
barcode iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAG50lEQVR4nOydwW4sOwhEX57y/7+cu3AWvkKgA/To1ozqrKJut9tJCYRxZeb75+c/I8T//3oB5m8siBgWRAwLIoYFEcOCiGFBxLAgYlgQMSyIGBZEDAsihgURw4KIYUHEsCBiWBAxLIgYFkSMbzrw64uOzE7pzwzn7j3bPT6+5R6f/RxHkvXEN8aR/G4Ndy44QsSwIGLglHXg4R+vxIRTj7nv3uPjz2dMHEnmzxJd9tvF+bt/kxpHiBgWRIxmyjqQSiarT2KyimnnHpmlwTrVZPNkCTNLO3UFmL0xPstxhIhhQcQYpSxOlsrqWiWmLz7/fb1OU/UM2cg6xe1xhIhhQcR4ccriySGOv5/qbuW6Xal6ntmzMxwhYlgQMUYpqxu2WX1CGuZ1uuCdKzJnPbLmqVTmCBHDgojRTFndZjI576t/zuaJq6qvb+asjwO6f5MaR4gYFkQMnLL2VUSdQDbv6iarewyfJ455xSbRESKGBRHji4YdOac71GeCpN39lG1gNg8/T+z20wiOEDEsiBiLKqubmriJlCST2lYa5yEJpLtm0pzvnjA6QsSwIGLgKut3eNN5fsP7Rd1OV7fHVf922Zp5F2uzYXSEiGFBxGimrN+HQNIgW6pu+JPElT3Lx8SR3Q0m/ztEHCFiWBAxFieG9UYsu3Lg1Qv3w8eZs/l5qqxNrfVG0r2sj8CCiPFQlTWbIVK7p2aeK1Iv8Tb7xqpBcISIYUHEWPeyajtofZ374bm5ND5bj9xs67rbYYIjRAwLIsajJodZbyrerVPBrGdVj490Dxrsfv9QLIgYD/3Dzt3zOXf5pmxmP7ivkxqvTmu8K5VdeSqJOULEsCBirN3vs39gqf8FpttCv6/wjR45i8yu1PB0HXGEiGFBxBh9KunMTllvr2YeJ94Gr9dWnyeS3l135RmOEDEsiBjrE8OujZOnpu4pXn2XN9K5wbWeh/wWEUeIGBZEjPUnOZCqI0sv3TNH4q3KKkBSKc3OMWe2igxHiBgWRIzFZ79vNoPdvlCc+b7LDQzkLeS0kZ8husp6cyyIGCNf1qF7Bkca45FuH4nXSGQGYiIla+Y4QsSwIGI89A07+x5ONwl00+M9snu+Sda832weHCFiWBAxFp/9noVnfYVXX+Sckb8ljuym0/qNsxPPiCNEDAsixqj9nnmi4sj7bubFImeF0apan0gSm2iE15C8rnOV9eZYEDFGG8NZeHKHVbcy4YmUNM+5PaNOZfZlfQQWRIxHv66i63rKnuUpqL5O1lmn33p8XR+6/f4RWBAxFr2srOOUQaqUbkeI+8FqsiRDElp211XWR2BBxHjI5FCfGG7MD9n82dq4a31miyWzbQyljhAxLIgYzQ+fOczO4zYGhpmJoruNJW/hqW+GI0QMCyLGo5/kwM8N46Yya1zXdgKSuGbngN2uVNdYm+EIEcOCiNH8JAe+NTtkqak+lSO2UrJaMid5C084+4rLESKGBRFj1H7P6ocsLZANXV071U1+sp0kllRSKc16WRxHiBgWRIxFL4t0nLJ5eODXz97w2owkE76dnP0dMhwhYlgQMZq9rCw89xs6cuaYVXR1pVePzNZA7Kb1G7Pfq8YRIoYFEePRr149kCqI2wn2bNIpr6BIBUhwhIhhQcQYfZByvE6c6rwimq2EW1K7Jopun6q7Cb1xhIhhQcRYbAwjmzM+bjrNrtdbs2wG7mOfOdN8YvjmWBAxHvq6ivtnshHb1DmROrl1O1Fxzu74WfV4cISIYUHEWPSybrJkNXOJZ/Pw7V69qnqGunlet9NnaerGESKGBRFjZHK4Icf6z9oh9p4ovgmNT83GuMp6WyyIGItvi44dpJkfqdug5r4sbjHla4hbzmzM/UaOI0QMCyLGo19XEcfcdE/f+LYxe6p7tsjrKO7L6uIIEcOCiLH+UrBZt6qe+YZYI8j4OCa+nRhW47NPmUgPjhAxLIgYo/Y7mvgFziiSEMgWjxhB+TrJetzLelssiBhrK2kkWgtm1koe5qSyiuPju/j17L38boYjRAwLIsZD32N4yLxPmUuKnx5uzBL3mKyCmjXkiR+siyNEDAsixvrDZw5ZeNYbt5n/ql5JPb5eZ92VyhJyNg9PyDeOEDEsiBiLr6sg1AFbVzsZ5Aigm1R5lcWNpl3zxsERIoYFEePFKYtUX1niyu7e12eWA1LpRXina5asDo4QMSyIGAsr6WzM7FmyYdxvV8kxAW/1u/3+EVgQMR796tV6JN8uzSyg3A5Rr4HP0DVCEBwhYlgQMV7myzIzHCFiWBAxLIgYFkQMCyKGBRHDgohhQcSwIGJYEDEsiBgWRAwLIoYFEcOCiGFBxLAgYlgQMSyIGBZEjD8BAAD//xDzM7XcohEsAAAAAElFTkSuQmCC
url otpauth://totp/Vault:307d6c16-6f5c-4ae7-46a9-2d153ffcbc63?algorithm=SHA256&digits=6&issuer=Vault&period=30&secret=AQESPQUPHWYIXV7FGOMBYT3A2N4LQKEIRNKTSRCWTKVEW66L
```
1. Read the secret, specifying the mfa flag:
Note that Vault's [TOTP secret backend](/docs/secrets/totp/index.html) can be leveraged to create TOTP passcodes.
```text
$ vault read -mfa my_totp:146378 secret/foo
### Login
Authenticate the CLI to use the newly created token.
```
vault auth 70f97438-e174-c03c-40fe-6bcdc1028d6c
```
### Read Secret
Read the secret by supplying the TOTP passcode.
```
vault read -mfa my_totp:146378 secret/foo
```
```
Key Value
--- -----
refresh_interval 768h0m0s
data which can only be read after MFA validation
```
Key Value
--- -----
refresh_interval 768h
data which can only be read after MFA validation
```

40
website/source/docs/enterprise/replication/index.html.md
View File

@ -1,13 +1,13 @@
---
layout: "docs"
page_title: "Vault Enterprise Replication"
page_title: "Replication - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-replication"
description: |-
Vault Enterprise has support for Replication, allowing critical data to be replicated across clusters to support horizontally scaling and disaster recovery workloads.
---
# Vault Replication
# Vault Enterprise Replication
## Overview
@ -17,19 +17,19 @@ policy management. This functionality is expected to be highly available and
to scale as the number of clients and their functional needs increase; at the
same time, operators would like to ensure that a common set of policies are
enforced globally, and a consistent set of secrets and keys are exposed to
applications that need to interoperate.
applications that need to interoperate.
Vault replication addresses both of these needs in providing consistency,
scalability, and highly-available disaster recovery.
Vault replication addresses both of these needs in providing consistency,
scalability, and highly-available disaster recovery.
## Architecture
The core unit of Vault replication is a **cluster**, which is comprised of a
collection of Vault nodes (an active and its corresponding HA nodes). Multiple Vault
The core unit of Vault replication is a **cluster**, which is comprised of a
collection of Vault nodes (an active and its corresponding HA nodes). Multiple Vault
clusters communicate in a one-to-many near real-time flow.
Replication operates on a leader/follower model, wherein a leader cluster (known as a
**primary**) is linked to a series of follower **secondary** clusters. The primary
Replication operates on a leader/follower model, wherein a leader cluster (known as a
**primary**) is linked to a series of follower **secondary** clusters. The primary
cluster acts as the system of record and asynchronously replicates most Vault data.
All communication between primaries and secondaries is end-to-end encrypted
@ -43,16 +43,16 @@ relationships.
## Performance Replication and Disaster Recovery (DR) Replication
*Performance Replication*:
In performance replication, secondaries keep track of their own tokens and leases
*Performance Replication*:
In performance replication, secondaries keep track of their own tokens and leases
but share the underlying configuration, policies, and supporting secrets (K/V values,
encryption keys for `transit`, etc).
encryption keys for `transit`, etc).
If a user action would modify underlying shared state, the secondary forwards the request
to the primary to be handled; this is transparent to the client. In practice, most
high-volume workloads (reads in the `kv` backend, encryption/decryption operations
If a user action would modify underlying shared state, the secondary forwards the request
to the primary to be handled; this is transparent to the client. In practice, most
high-volume workloads (reads in the `generic` backend, encryption/decryption operations
in `transit`, etc.) can be satisfied by the local secondary, allowing Vault to scale
relatively horizontally with the number of secondaries rather than vertically as
relatively horizontally with the number of secondaries rather than vertically as
in the past.
*Disaster Recovery (DR) Replication*:
@ -60,15 +60,15 @@ In disaster recovery (or DR) replication, secondaries share the same underlying
policy, and supporting secrets (K/V values, encryption keys for `transit`, etc) infrastructure
as the primary. They also share the same token and lease infrastructure as the primary, as
they are designed to allow for continuous operations with applications connecting to the
original primary on the election of the DR secondary.
original primary on the election of the DR secondary.
DR is designed to be a mechanism to protect against catastrophic failure of entire clusters.
They do not forward service read or write requests until they are elected and become a new primary.
DR is designed to be a mechanism to protect against catastrophic failure of entire clusters.
They do not forward service read or write requests until they are elected and become a new primary.
| Capability | Disaster Recovery | Performance |
|-------------------------------------------------------------------------------------------------------------------------- |------------------- |-------------------------------------------------------------------------- |
| Mirrors the secrets infrastructure of a primary cluster | Yes | Yes |
| Mirrors the configuration of a primary cluster’s backends (i.e.: auth backends, storage backends, secret backends, etc.) | Yes | Yes |
| Mirrors the configuration of a primary cluster’s backends (i.e.: auth methods, storage backends, secret backends, etc.) | Yes | Yes |
| Contains a local replica of secrets on the secondary and allows the secondary to forward writes | No | Yes |
| Mirrors the token auth infrastructure for applications or users interacting with the primary cluster | Yes | No. Upon promotion, applications must re-auth tokens with a new primary. |

4
website/source/docs/enterprise/ui/index.html.md
View File

@ -1,6 +1,6 @@
---
layout: "docs"
page_title: "Vault Enterprise UI"
page_title: "UI - Vault Enterprise"
sidebar_current: "docs-vault-enterprise-ui"
description: |-
Vault Enterprise features a user interface for interacting with Vault. Easily
@ -8,7 +8,7 @@ description: |-
the Vault Enterprise UI.
---
# Vault UI
# Vault Enterprise UI
Vault Enterprise features a user interface for interacting with Vault. Easily
create, read, update, and delete secrets, authenticate, unseal, and more with

12
website/source/docs/internals/architecture.html.md
View File

@ -45,7 +45,7 @@ clarify what is being discussed:
and response from Vault goes through the configured audit backends. This provides a simple
way to integrate Vault with multiple audit logging destinations of different types.
* **Auth Backend** - An auth backend is used to authenticate users or applications which
* **auth method** - An auth method is used to authenticate users or applications which
are connecting to Vault. Once authenticated, the backend returns the list of applicable policies
which should be applied. Vault takes an authenticated user and returns a client token that can
be used for future requests. As an example, the `userpass` backend uses a username and password
@ -101,7 +101,7 @@ The number of shares and the minimum threshold required can both be specified. S
technique can be disabled, and the master key used directly for unsealing. Once Vault
retrieves the encryption key, it is able to decrypt the data in the storage backend,
and enters the _unsealed_ state. Once unsealed, Vault loads all of the configured
audit, credential and secret backends.
audit devices, auth methods, and secrets engines.
The configuration of those backends must be stored in Vault since they are security
sensitive. Only users with the correct permissions should be able to modify them,
@ -113,10 +113,10 @@ The core is used to manage the flow of requests through the system, enforce ACLs
and ensure audit logging is done.
When a client first connects to Vault, it needs to authenticate. Vault provides
configurable credential backends providing flexibility in the authentication mechanism
configurable auth methods providing flexibility in the authentication mechanism
used. Human friendly mechanisms such as username/password or GitHub might be
used for operators, while applications may use public/private keys or tokens to authenticate.
An authentication request flows through core and into a credential backend, which determines
An authentication request flows through core and into an auth method, which determines
if the request is valid and returns a list of associated policies.
Policies are just a named ACL rule. For example, the "root" policy is built-in and
@ -127,11 +127,11 @@ Since a user may have multiple policies associated, an action is allowed if any
permits it. Policies are stored and managed by an internal policy store. This internal store
is manipulated through the system backend, which is always mounted at `sys/`.
Once authentication takes place and a credential backend provides a set of applicable
Once authentication takes place and an auth method provides a set of applicable
policies, a new client token is generated and managed by the token store. This client token
is sent back to the client, and is used to make future requests. This is similar to
a cookie sent by a website after a user logs in. The client token may have a lease associated
with it depending on the credential backend configuration. This means the client token
with it depending on the auth method configuration. This means the client token
may need to be periodically renewed to avoid invalidation.
Once authenticated, requests are made providing the client token. The token is used

2
website/source/docs/internals/security.html.md
View File

@ -95,7 +95,7 @@ to gain access to secret material they are not authorized to. This is an interna
threat if the attacker is already permitted some level of access to Vault and is
able to authenticate.
When a client first authenticates with Vault, a credential backend is used to
When a client first authenticates with Vault, an auth method is used to
verify the identity of the client and to return a list of associated ACL policies.
This association is configured by operators of Vault ahead of time. For example,
GitHub users in the "engineering" team may be mapped to the "engineering" and "ops"

16
website/source/docs/internals/telemetry.html.md
View File

@ -82,7 +82,7 @@ These metrics represent operational aspects of the running Vault instance.
|`vault.core.seal-internal`| This measures the number of internal seal operations | Number of operations | Gauge |
|`vault.core.step_down`| This measures the number of cluster leadership step downs | Number of stepdowns | Summary |
|`vault.core.unseal`| This measures the number of unseal operations | Number of operations | Summary |
|`vault.runtime.alloc_bytes` | This measures the number of bytes allocated by the Vault process. This may burst from time to time but should return to a steady state value.| Number of bytes | Gauge |
|`vault.runtime.alloc_bytes` | This measures the number of bytes allocated by the Vault process. This may burst from time to time but should return to a steady state value.| Number of bytes | Gauge |
|`vault.runtime.free_count`| This measures the number of `free` operations | Number of operations | Gauge |
|`vault.runtime.heap_objects`| This measures the number of objects on the heap and is a good general memory pressure indicator | Number of heap objects | Gauge |
|`vault.runtime.malloc_count`| This measures the number of `malloc` operations | Number of operations | Gauge |
@ -119,21 +119,21 @@ These metrics relate to policies and tokens.
`vault.token.revoke-tree`| This measures the number of revoke tree operations | Number of operations | Gauge |
`vault.token.store`| This measures the number of operations to store an updated token entry without writing to the secondary index | Number of operations | Gauge |
### Authentication Backend Metrics
### Auth Method Metrics
These metrics relate to supported authentication backends.
These metrics relate to supported auth methods.
| Metric | Description | Unit | Type |
| ---------------- | ----------------------------------| ---- | ---- |
| `vault.rollback.attempt.auth-token-` | This measures the number of rollback operations attempted for authentication tokens backend | Number of operations | Summary |
| `vault.rollback.attempt.auth-ldap-` | This measures the number of rollback operations attempted for the LDAP authentication backend | Number of operations | Summary |
| `vault.rollback.attempt.cubbyhole-` | This measures the number of rollback operations attempted for the cubbyhole authentication backend | Number of operations | Summary |
| `vault.rollback.attempt.auth-ldap-` | This measures the number of rollback operations attempted for the LDAP auth method | Number of operations | Summary |
| `vault.rollback.attempt.cubbyhole-` | This measures the number of rollback operations attempted for the cubbyhole auth method | Number of operations | Summary |
| `vault.rollback.attempt.secret-` | This measures the number of rollback operations attempted for the kv secret backend | Number of operations | Summary |
| `vault.rollback.attempt.sys-` | This measures the number of rollback operations attempted for the sys backend | Number of operations | Summary |
| `vault.route.rollback.auth-ldap-` | This measures the number of rollback operations for the LDAP authentication backend | Number of operations | Summary |
| `vault.route.rollback.auth-ldap-` | This measures the number of rollback operations for the LDAP auth method | Number of operations | Summary |
| `vault.route.rollback.auth-token-` | This measures the number of rollback operations for the authentication tokens backend | Number of operations | Summary |
| `vault.route.rollback.cubbyhole-` | This measures the number of rollback operations for the cubbyhole authentication backend | Number of operations | Summary |
| `vault.route.rollback.secret-` | This measures the number of rollback operations for the kv secret backend | Number of operations | Summary |
| `vault.route.rollback.cubbyhole-` | This measures the number of rollback operations for the cubbyhole auth method | Number of operations | Summary |
| `vault.route.rollback.secret-` | This measures the number of rollback operations for the kv secret backend | Number of operations | Summary |
| `vault.route.rollback.sys-` | This measures the number of rollback operations for the sys backend | Number of operations | Summary |
### Storage Backend Metrics

6
website/source/docs/internals/token.html.md
View File

@ -8,8 +8,8 @@ description: |-
# Token Authentication
The `token` authentication backend is built-in and is at the core of
client authentication. Other authentication backends may be used to
The `token` auth method is built-in and is at the core of
client authentication. Other auth methods may be used to
authenticate a client, but they eventually result in the generation of a client
token managed by the `token` backend.
@ -36,7 +36,7 @@ prefix will revoke all client tokens generated at that path, as well as all
dynamic secrets generated by those tokens. This provides a powerful "break glass"
procedure during a potential compromise.
If a token is created by another authentication backend, they do not have
If a token is created by another auth method, they do not have
a parent token. However, any tokens created by the `auth/token/create` API
have a parent token, namely the token used to make that request. By maintaining
this parent-child relationship, Vault models token trees. Child tokens can

11
website/source/docs/secrets/identity/index.html.md
View File

@ -15,12 +15,11 @@ internally maintains the clients who are recognized by Vault. Each client is
internally termed as an `Entity`. An entity can have multiple `Personas`. For
example, a single user who has accounts in both Github and LDAP, can be mapped
to a single entity in Vault that has 2 personas, one of type Github and one of
type LDAP. When a client authenticates via any of the credential backend
(except the Token backend), Vault creates a new entity and attaches a new
persona to it, if an entity doesn't already exist. The entity identifier will
be tied to the authenticated token. When such tokens are put to use, their
entity identifiers are audit logged, marking a trail of actions performed by
specific users.
type LDAP. When a client authenticates via any of the auth methods (except
"token"), Vault creates a new entity and attaches a new persona to it, if an
entity doesn't already exist. The entity identifier will be tied to the
authenticated token. When such tokens are put to use, their entity identifiers
are audit logged, marking a trail of actions performed by specific users.
Identity store allows operators to **manage** the entities in Vault. Entities
can be created and personas can be tied to entities, via the ACL'd API. There

12
website/source/guides/plugin-backends.html.md
View File

@ -8,14 +8,14 @@ description: |-
# Introduction
Plugin backends utilize the [plugin system][plugin-system] to enable
third-party secret and auth backends to be mounted.
Plugin backends utilize the [plugin system][plugin-system] to enable
third-party secret and auth methods to be mounted.
It is worth noting that even though [database backends][database-backend]
operate under the same underlying plugin mechanism, they are slightly different
in design than plugin backends demonstrated in this guide. The database backend
in design than plugin backends demonstrated in this guide. The database backend
manages multiple plugins under the same backend mount point, whereas plugin
backends are generic backends that function as either secret or auth backends.
backends are generic backends that function as either secret or auth methods.
This guide provides steps to build, register, and mount non-database external
plugin backends.
@ -35,7 +35,7 @@ plugin_directory="/etc/vault/vault_plugins"
## Build the Plugin Backend
Build the custom backend binary, and move it to the `plugin_directory` path.
In this guide, we will use `mock-plugin` that comes from Vault's
In this guide, we will use `mock-plugin` that comes from Vault's
`logical/plugin/mock` package.
```
@ -100,4 +100,4 @@ sys/ system system_e3a4cccd n/a n/a n/a false
```
[plugin-system]: /docs/internals/plugins.html
[database-backend]: /docs/secrets/databases/index.html
[database-backend]: /docs/secrets/databases/index.html

2
website/source/guides/production.html.md
View File

@ -76,7 +76,7 @@ and practical.
* **Avoid Root Tokens**. Vault provides a root token when it is first
initialized. This token should be used to setup the system initially,
particularly setting up authentication backends so that users may
particularly setting up auth methods so that users may
authenticate. We recommend treating Vault [configuration as
code](https://www.hashicorp.com/blog/codifying-vault-policies-and-configuration/),
and using version control to manage policies. Once setup, the root token

4
website/source/guides/replication.html.md
View File

@ -85,8 +85,8 @@ consistent `~/.vault-token` file or `VAULT_TOKEN` environment variable when
working with both clusters.
On a production system, after a secondary is activated, the enabled
authentication backends should be used to get tokens with appropriate policies,
as policies and auth backend configuration are replicated.
auth methods should be used to get tokens with appropriate policies,
as policies and auth method configuration are replicated.
The generate-root command can also be used to generate a root token local to
the secondary cluster.

2
website/source/guides/upgrading/upgrade-to-0.5.0.html.md
View File

@ -35,7 +35,7 @@ manually re-type it.
## `TTL` Field in Token Lookup
Previously, the `ttl` field returned when calling `lookup` or `lookup-self` on
the token authentication backend displayed the TTL set at token creation. It
the token auth method displayed the TTL set at token creation. It
now displays the time remaining (in seconds) for the token's validity period.
The original behavior has been moved to a field named `creation_ttl`.

2
website/source/guides/upgrading/upgrade-to-0.5.1.html.md
View File

@ -36,7 +36,7 @@ certificate storage, or both. In addition, you can specify a safety buffer
(defaulting to 72 hours) to ensure that any time discrepancies between your
hosts is accounted for.
## Cert Authentication Backend Performs Client Checking During Renewals
## Cert auth method Performs Client Checking During Renewals
The `cert` backend now performs a variant of channel binding at renewal time
for increased security. In order to not overly burden clients, a notion of

4
website/source/guides/upgrading/upgrade-to-0.6.1.html.md
View File

@ -65,7 +65,7 @@ it is *very important* that you set this option **before** upgrading your Vault
instances. Without doing so, each Vault instance will believe that it is
standalone and there could be consistency issues.
## LDAP Auth Backend Forgets Bind Password and Insecure TLS Settings
## LDAP Auth Method Forgets Bind Password and Insecure TLS Settings
Due to a bug, these two settings are forgotten if they have been configured in
the LDAP backend prior to 0.6.1. If you are using these settings with LDAP,
@ -73,7 +73,7 @@ please be sure to re-submit your LDAP configuration to Vault after the upgrade,
so ensure that you have a valid token to do so before upgrading if you are
relying on LDAP authentication for permissions to modify the backend itself.
## LDAP Auth Backend Does Not Search `memberOf`
## LDAP Auth Method Does Not Search `memberOf`
The LDAP backend went from a model where all permutations of storing and
filtering groups were tried in all cases to one where specific filters are

2
website/source/guides/upgrading/upgrade-to-0.6.2.html.md
View File

@ -68,7 +68,7 @@ not the URL.
## Behavior Change for `bound_iam_role_arn` in AWS-EC2 Backend
In prior versions a bug caused the `bound_iam_role_arn` value in the `aws-ec2`
authentication backend to actually use the instance profile ARN. This has been
auth method to actually use the instance profile ARN. This has been
corrected, but as a result there is a behavior change. To match using the
instance profile ARN, a new parameter `bound_iam_instance_profile_arn` has been
added. Existing roles will automatically transfer the value over to the correct

2
website/source/guides/upgrading/upgrade-to-0.6.3.html.md
View File

@ -14,7 +14,7 @@ for Vault 0.6.3. Please read it carefully.
## LDAP Null Binds Disabled By Default
When using the LDAP Auth Backend, `deny_null_bind` has a default value of
When using the LDAP auth method, `deny_null_bind` has a default value of
`true`, preventing a successful user authentication when an empty password
is provided. If you utilize passwordless LDAP binds, `deny_null_bind` must
be set to `false`. Upgrades will keep previous behavior until the LDAP

2
website/source/intro/getting-started/apis.html.md
View File

@ -115,7 +115,7 @@ output. This will return a JSON response:
}
```
Now any of the available authentication backends can be enabled and configured.
Now any of the available auth methods can be enabled and configured.
For the purposes of this guide lets enable [AppRole](/docs/auth/approle.html)
authentication.

43
website/source/intro/getting-started/authentication.html.md
View File

@ -10,8 +10,9 @@ description: |-
Now that we know how to use the basics of Vault, it is important to understand
how to authenticate to Vault itself. Up to this point, we haven't had to
authenticate because starting the Vault server in dev mode automatically logs
us in as the root user. In practice, you'll almost always have to manually authenticate.
authenticate because starting the Vault server in dev mode automatically logs us
in as the root user. In practice, you'll almost always have to manually
authenticate.
On this page, we'll talk specifically about _authentication_. On the
next page, we talk about
@ -20,14 +21,14 @@ mechanism of assigning an identity to a Vault user. The access control
and permissions associated with an identity are authorization, and will
not be covered on this page.
Vault has pluggable authentication backends, making it easy to authenticate
Vault has pluggable auth methods, making it easy to authenticate
with Vault using whatever form works best for your organization. On this page
we'll use the token backend as well as the GitHub backend.
## Tokens
We'll first explain token authentication before going over any other
authentication backends. Token authentication is enabled by default in
auth methods. Token authentication is enabled by default in
Vault and cannot be disabled. It is also what we've been using up to this
point.
@ -69,7 +70,7 @@ is only used for revoking _secrets_. For revoking _tokens_, the
To authenticate with a token, use the `vault auth` command:
```
$ vault auth d08e2bd5-ffb0-440d-6486-b8f650ec8c0c
$ vault login d08e2bd5-ffb0-440d-6486-b8f650ec8c0c
Successfully authenticated! The policies that are associated
with this token are listed below:
@ -80,25 +81,25 @@ This authenticates with Vault. It will verify your token and let you know
what access policies the token is associated with. If you want to test
`vault auth`, make sure you create a new token first.
## Auth Backends
## Auth Methods
In addition to tokens, other authentication, or _auth_, backends can be enabled.
Auth backends enable alternate methods of identifying with
Auth methods enable alternate methods of identifying with
Vault. These identities are tied back to a set of access policies, just
like tokens. For example, for desktop environments, private key or
GitHub based authentication are available. For server environments, some
shared secret may be best. Auth backends give you flexibility
shared secret may be best. Auth methods give you flexibility
to choose what authentication you want to use.
As an example, let's authenticate using GitHub. First, enable the
GitHub authentication backend:
GitHub auth method:
```
$ vault auth-enable github
Successfully enabled 'github' at 'github'!
```text
$ vault auth enable github
Success! Enabled github auth method at: github/
```
Auth backends are mounted, just like secret backends, except auth
Auth methods are mounted, just like secret backends, except auth
backends are always prefixed with `auth/`. So the GitHub backend we just
mounted can be accessed at `auth/github`. You can use `vault path-help` to
learn more about it.
@ -106,7 +107,7 @@ learn more about it.
With the GitHub backend enabled, we first have to configure it. For GitHub,
we tell it what organization users must be a part of, and map a team to a policy:
```
```text
$ vault write auth/github/config organization=hashicorp
Success! Data written to: auth/github/config
@ -121,8 +122,8 @@ the only policy (other than `root`) we have right now until the next section.
With GitHub enabled, we can now authenticate using `vault auth`:
```
$ vault auth -method=github token=e6919b17dd654f2b64e67b6369d61cddc0bcc7d5
```text
$ vault login -method=github token=e6919b17dd654f2b64e67b6369d61cddc0bcc7d5
Successfully authenticated! The policies that are associated
with this token are listed below:
@ -137,7 +138,7 @@ token](https://help.github.com/articles/creating-an-access-token-for-command-lin
At this point, if you're following along, re-authenticate with the root token
from earlier (using `vault auth <token>`) to run the next commands.
You can revoke authentication from any authentication backend using
You can revoke authentication from any auth method using
`vault token-revoke` as well, which can revoke any path prefix. For
example, to revoke all GitHub tokens, you could run the following.
@ -145,12 +146,12 @@ example, to revoke all GitHub tokens, you could run the following.
$ vault token-revoke -mode=path auth/github
```
When you're done, you can disable authentication backends with
`vault auth-disable`. This will immediately invalidate all authenticated
When you're done, you can disable auth methods with
`vault auth disable`. This will immediately invalidate all authenticated
users from this backend.
```
$ vault auth-disable github
$ vault auth disable github
Disabled auth provider at path 'github'!
```
@ -161,7 +162,7 @@ about the built-in token system as well as enabling other authentication
backends. At this point you know how Vault assigns an _identity_ to
a user.
The multiple authentication backends Vault provides let you choose the
The multiple auth methods Vault provides let you choose the
most appropriate authentication mechanism for your organization.
In this next section, we'll learn about

89
website/source/intro/getting-started/dev-server.html.md
View File

@ -10,72 +10,65 @@ description: |-
With Vault installed, the next step is to start a Vault server.
Vault operates as a client/server application. The Vault server is the
only piece of the Vault architecture that interacts with the data
storage and backends. All operations done via the Vault CLI interact
with the server over a TLS connection.
Vault operates as a client/server application. The Vault server is the only
piece of the Vault architecture that interacts with the data storage and
backends. All operations done via the Vault CLI interact with the server over a
TLS connection.
In this page, we'll start and interact with the Vault server to understand
how the server is started.
In this page, we'll start and interact with the Vault server to understand how
the server is started.
## Starting the Dev Server
First, we're going to start a Vault _dev server_. The dev server
is a built-in, pre-configured server that is not very
secure but useful for playing with Vault locally. Later in this guide
we'll configure and start a real server.
First, we're going to start a Vault _dev server_. The dev server is a built-in,
pre-configured server that is not very secure but useful for playing with Vault
locally. Later in this guide we'll configure and start a real server.
To start the Vault dev server, run:
```
$ vault server -dev
WARNING: Dev mode is enabled!
In this mode, Vault is completely in-memory and unsealed.
Vault is configured to only have a single unseal key. The root
token has already been authenticated with the CLI, so you can
immediately begin using the Vault CLI.
The only step you need to take is to set the following
environment variable since Vault will be talking without TLS:
export VAULT_ADDR='http://127.0.0.1:8200'
The unseal key and root token are reproduced below in case you
want to seal/unseal the Vault or play with authentication.
Unseal Key: 2252546b1a8551e8411502501719c4b3
Root Token: 79bd8011-af5a-f147-557e-c58be4fedf6c
==> Vault server configuration:
Log Level: info
Backend: inmem
Listener 1: tcp (addr: "127.0.0.1:8200", tls: "disabled")
Cgo: enabled
Cluster Address: https://127.0.0.1:8201
Listener 1: tcp (addr: "127.0.0.1:8200", cluster address: "127.0.0.1:8201", tls: "disabled")
Log Level: info
Mlock: supported: false, enabled: false
Redirect Address: http://127.0.0.1:8200
Storage: inmem
Version: Vault x.y.z
...
WARNING! dev mode is enabled! In this mode, Vault runs entirely in-memory
and starts unsealed with a single unseal key. The root token is already
authenticated to the CLI, so you can immediately begin using Vault.
You may need to set the following environment variable:
$ export VAULT_ADDR='http://127.0.0.1:8200'
The unseal key and initial root token are displayed below in case you want to
seal/unseal the Vault or re-authenticate.
Unseal Key: PUxYl07Io6Kt63tqcMddImB2s1RPYaK+L0UVZNhD+Yo=
Root Token: 2b9a7a8f-ed9b-669e-3827-36c05504cec2
Development mode should NOT be used in production installations!
==> Vault server started! Log data will stream in below:
# ...
```
You should see output similar to that above. Vault does not fork, so it will
continue to run in the foreground; to connect to it with later commands, open
another shell.
continue to run in the foreground. Open another shell or terminal tab to run the
remaining commands.
As you can see, when you start a dev server, Vault warns you loudly. The dev
server stores all its data in-memory (but still encrypted), listens on
The dev server stores all its data in-memory (but still encrypted), listens on
`localhost` without TLS, and automatically unseals and shows you the unseal key
and root access key. We'll go over what all this means shortly.
and root access key. **Do not run a dev server in production!**
The important thing about the dev server is that it is meant for
development only.
-> **Note:** Do not run the dev server in production.
Even if the dev server was run in production, it wouldn't be very useful
since it stores data in-memory and every restart would clear all your
secrets.
With the dev server running, do the following three things before anything
else:
With the dev server running, do the following three things before anything else:
1. Launch a new terminal session.

2
website/source/intro/getting-started/first-secret.html.md
View File

@ -49,7 +49,7 @@ Success! Data written to: secret/hello
`vault write` is a very powerful command. In addition to writing data
directly from the command-line, it can read values and key pairs from
`STDIN` as well as files. For more information, see the
[vault write documentation](/docs/commands/read-write.html).
[command documentation](/docs/commands/index.html).
~> **Warning:** The documentation uses the `key=value` based entry
throughout, but it is more secure to use files if possible. Sending

66
website/source/intro/getting-started/install.html.md
View File

@ -38,55 +38,33 @@ terminal session and checking that the `vault` binary is available. By executing
```
$ vault
usage: vault [-version] [-help] <command> [args]
Usage: vault <command> [args]
Common commands:
delete Delete operation on secrets in Vault
path-help Look up the help for a path
read Read data or secrets from Vault
renew Renew the lease of a secret
revoke Revoke a secret.
server Start a Vault server
status Outputs status of whether Vault is sealed and if HA mode is enabled
unwrap Unwrap a wrapped secret
write Write secrets or configuration into Vault
read Read data and retrieves secrets
write Write data, configuration, and secrets
delete Delete secrets and configuration
list List data or secrets
login Authenticate locally
server Start a Vault server
status Print seal and HA status
unwrap Unwrap a wrapped secret
All other commands:
audit-disable Disable an audit backend
audit-enable Enable an audit backend
audit-list Lists enabled audit backends in Vault
auth Prints information about how to authenticate with Vault
auth-disable Disable an auth provider
auth-enable Enable a new auth provider
capabilities Fetch the capabilities of a token on a given path
generate-root Generates a new root token
init Initialize a new Vault server
key-status Provides information about the active encryption key
list List data or secrets in Vault
mount Mount a logical backend
mount-tune Tune mount configuration parameters
mounts Lists mounted backends in Vault
policies List the policies on the server
policy-delete Delete a policy from the server
policy-write Write a policy to the server
rekey Rekeys Vault to generate new unseal keys
remount Remount a secret backend to a new path
rotate Rotates the backend encryption key used to persist data
seal Seals the vault server
ssh Initiate a SSH session
step-down Force the Vault node to give up active duty
token-create Create a new auth token
token-lookup Display information about the specified token
token-renew Renew an auth token if there is an associated lease
token-revoke Revoke one or more auth tokens
unmount Unmount a secret backend
unseal Unseals the vault server
version Prints the Vault version
Other commands:
audit Interact with audit devices
auth Interact with auth methods
lease Interact with leases
operator Perform operator-specific tasks
path-help Retrieve API help for paths
policy Interact with policies
secrets Interact with secrets engines
ssh Initiate an SSH session
token Interact with tokens
```
If you get an error that the binary could not be found, then your `PATH` environment
variable was not setup properly. Please go back and ensure that your `PATH`
variable contains the directory where Vault was installed.
If you get an error that the binary could not be found, then your `PATH`
environment variable was not setup properly. Please go back and ensure that your
`PATH` variable contains the directory where Vault was installed.
Otherwise, Vault is installed and ready to go!

34
website/source/intro/getting-started/policies.html.md
View File

@ -12,10 +12,10 @@ Policies in Vault control what a user can access. In
the last section, we learned about _authentication_. This section is
about _authorization_.
For authentication Vault has multiple options or backends that
can be enabled and used. For authorization and policies Vault always
uses the same format. All authentication backends must map identities back to
the core policies that are configured with Vault.
For authentication Vault has multiple options or methods that can be enabled and
used. For authorization and policies Vault always uses the same format. All auth
methods must map identities back to the core policies that are configured with
Vault.
When initializing Vault, there is always one special policy created
that can't be removed: the `root` policy. This policy is a special policy
@ -43,11 +43,11 @@ path "auth/token/lookup-self" {
}
```
The policy format uses a prefix matching system on the API path
to determine access control. The most specific defined policy is used,
either an exact match or the longest-prefix glob match. Since everything
in Vault must be accessed via the API, this gives strict control over every
aspect of Vault, including mounting backends, authenticating, as well as secret access.
The policy format uses a prefix matching system on the API path to determine
access control. The most specific defined policy is used, either an exact match
or the longest-prefix glob match. Since everything in Vault must be accessed via
the API, this gives strict control over every aspect of Vault, including
mounting backends, authenticating, as well as secret access.
In the policy above, a user could write any secret to `secret/`, except
to `secret/foo`, where only read access is allowed. Policies default to
@ -84,7 +84,7 @@ token_duration 2764800
token_renewable true
token_policies [default secret]
$ vault auth d97ef000-48cf-45d9-1907-3ea6ce298a29
$ vault login d97ef000-48cf-45d9-1907-3ea6ce298a29
Successfully authenticated!
token: d97ef000-48cf-45d9-1907-3ea6ce298a29
token_duration: 2591938
@ -110,13 +110,13 @@ Code: 403. Errors:
You also don't have access to `sys` according to the policy, so commands
such as `vault mounts` will not work either.
## Mapping Policies to Auth Backends
## Mapping Policies to Auth Methods
Vault is the single policy authority, unlike auth where you can mount
multiple backends. Any mounted auth backend must map identities to these
core policies.
Vault is the single policy authority, unlike auth where you can enable multiple
auth methods. Any enabled auth method must map identities to these core
policies.
We use the `vault path-help` system with your auth backend to determine how the
We use the `vault path-help` system with your auth method to determine how the
mapping is done, since it is specific to each backend. For example,
with GitHub, it is done by team using the `map/teams/<team>` path:
@ -128,7 +128,7 @@ Success! Data written to: auth/github/map/teams/default
For GitHub, the `default` team is the default policy set that everyone
is assigned to no matter what team they're on.
Other auth backends use alternate, but likely similar mechanisms for
Other auth methods use alternate, but likely similar mechanisms for
mapping policies to identity.
## Next
@ -138,7 +138,7 @@ is easiest to get up and running, you'll want to restrict access to
Vault very quickly, and the policy system is the way to do this.
The syntax and function of policies is easy to understand and work
with, and because auth backends all must map to the central policy system,
with, and because auth methods all must map to the central policy system,
you only have to learn this policy system.
Next, we'll cover how to [deploy Vault](/intro/getting-started/deploy.html).

33
website/source/intro/index.html.markdown
View File

@ -8,29 +8,28 @@ description: |-
# Introduction to Vault
Welcome to the intro guide to Vault! This guide is the best
place to start with Vault. We cover what Vault is, what
problems it can solve, how it compares to existing software,
and contains a quick start for using Vault.
Welcome to the introduction guide to HashiCorp Vault! This guide is the best
place to get started with Vault. This guide covers what Vault is, what problems
it can solve, how it compares to existing software, and contains a quick start
for using Vault.
If you are already familiar with the basics of Vault, the
[documentation](/docs/index.html) provides a better reference
guide for all available features as well as internals.
[documentation](/docs/index.html) provides a better reference guide for all
available features as well as internals.
## What is Vault?
Vault is a tool for securely accessing _secrets_. A secret is anything
that you want to tightly control access to, such as API keys, passwords,
certificates, and more. Vault provides a unified interface to any
secret, while providing tight access control and recording a detailed
audit log.
Vault is a tool for securely accessing _secrets_. A secret is anything that you
want to tightly control access to, such as API keys, passwords, or certificates.
Vault provides a unified interface to any secret, while providing tight access
control and recording a detailed audit log.
A modern system requires access to a multitude of secrets: database
credentials, API keys for external services, credentials for
service-oriented architecture communication, etc. Understanding who is
accessing what secrets is already very difficult and platform-specific.
Adding on key rolling, secure storage, and detailed audit logs is almost
impossible without a custom solution. This is where Vault steps in.
A modern system requires access to a multitude of secrets: database credentials,
API keys for external services, credentials for service-oriented architecture
communication, etc. Understanding who is accessing what secrets is already very
difficult and platform-specific. Adding on key rolling, secure storage, and
detailed audit logs is almost impossible without a custom solution. This is
where Vault steps in.
Examples work best to showcase Vault. Please see the
[use cases](/intro/use-cases.html).

2
website/source/layouts/_sidebar.erb
View File

@ -7,8 +7,8 @@
<ul class="nav sidebar-nav">
<li><a href="/intro/index.html">Intro</a></li>
<li><a href="/docs/index.html">Docs</a></li>
<li><a href="/guides/index.html">Guides</a></li>
<li><a href="/docs/index.html">Docs</a></li>
<li><a href="/api/index.html">API</a></li>
<li><a href="/community.html">Community</a></li>
<li><a href="/security.html">Security</a></li>

4
website/source/layouts/api.erb
View File

@ -93,7 +93,7 @@
</li>
<li<%= sidebar_current("docs-http-auth") %>>
<a href="/api/auth/index.html">Auth Backends</a>
<a href="/api/auth/index.html">Auth Methods</a>
<ul class="nav">
<li<%= sidebar_current("docs-http-auth-approle") %>>
<a href="/api/auth/approle/index.html">AppRole</a>
@ -230,7 +230,7 @@
<a href="/api/system/replication-dr.html"><tt>/sys/replication/dr</tt></a>
</li>
</ul>
</li>
</li>
<li<%= sidebar_current("docs-http-system-rotate") %>>
<a href="/api/system/rotate.html"><tt>/sys/rotate</tt></a>
</li>

2
website/source/layouts/docs.erb
View File

@ -431,7 +431,7 @@
</li>
<li<%= sidebar_current("docs-auth") %>>
<a href="/docs/auth/index.html">Auth Backends</a>
<a href="/docs/auth/index.html">Auth Methods</a>
<ul class="nav">
<li<%= sidebar_current("docs-auth-approle") %>>
<a href="/docs/auth/approle.html">AppRole</a>

2
website/source/layouts/layout.erb
View File

@ -73,8 +73,8 @@
<nav class="navigation-links" role="navigation">
<ul class="main-links nav navbar-nav navbar-right">
<li><a href="/intro/index.html">Intro</a></li>
<li><a href="/docs/index.html">Docs</a></li>
<li><a href="/guides/index.html">Guides</a></li>
<li><a href="/docs/index.html">Docs</a></li>
<li><a href="/api/index.html">API</a></li>
<li><a href="https://www.hashicorp.com/vault.html?utm_source=oss&utm_medium=header-nav&utm_campaign=vault">Enterprise</a></li>
<li>