website: cleanup dead docs
This commit is contained in:
Armon Dadgar
parent
d0cc32db8b
commit
5cd47f54d7
|
|
@ -1,36 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Audit Backend: File"
|
||||
sidebar_current: "docs-audit-file"
|
||||
description: |-
|
||||
The "file" audit backend writes audit logs to a file.
|
||||
---
|
||||
|
||||
# Audit Backend: File
|
||||
|
||||
Name: `file`
|
||||
|
||||
The "file" audit backend writes audit logs to a file.
|
||||
|
||||
This is a very simple audit backend: it appends logs to a file. It does
|
||||
not currently assist with any log rotation.
|
||||
|
||||
## Options
|
||||
|
||||
When enabling this backend, the following options are accepted:
|
||||
|
||||
* `path` (required) - The path to where the file will be written. If
|
||||
this path exists, the audit backend will append to it.
|
||||
* `log_raw` (optional) Should security sensitive information be logged raw. Defaults to "false".
|
||||
|
||||
## Format
|
||||
|
||||
Each line in the audit log is a JSON object. The "type" field specifies
|
||||
what type of object it is. Currently, only two types exist: "request" and
|
||||
"response".
|
||||
|
||||
The line contains all of the information for any given request and response.
|
||||
|
||||
If `log_raw` if false, as is default, all sensitive information is first hashed
|
||||
before logging. If explicitly enabled, all values are logged raw without hashing.
|
||||
|
||||
|
|
@ -1,67 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Audit Backends"
|
||||
sidebar_current: "docs-audit"
|
||||
description: |-
|
||||
Audit backends are mountable backends that log requests and responses in Nomad.
|
||||
---
|
||||
|
||||
# Audit Backends
|
||||
|
||||
Audit backends are the components in Nomad that keep a detailed log
|
||||
of all requests and response to Nomad. Because _every_ operation with
|
||||
Nomad is an API request/response, the audit log contains _every_ interaction
|
||||
with Nomad, including errors.
|
||||
|
||||
Nomad ships with multiple audit backends, depending on the location you want
|
||||
the logs sent to. Multiple audit backends can be enabled and Nomad will send
|
||||
the audit logs to both. This allows you to not only have a redundant copy,
|
||||
but also a second copy in case the first is tampered with.
|
||||
|
||||
## Sensitive Information
|
||||
|
||||
The audit logs contain the full request and response objects for every
|
||||
interaction with Nomad. The data in the request and the data in the
|
||||
response (including secrets and authentication tokens) will be hashed
|
||||
without a salt using SHA1.
|
||||
|
||||
The purpose of the hash is so that secrets aren't in plaintext within
|
||||
your audit logs. However, you're still able to check the value of
|
||||
secrets by SHA-ing it yourself.
|
||||
|
||||
## Enabling/Disabling Audit Backends
|
||||
|
||||
When a Nomad server is first initialized, no auditing is enabled. Audit
|
||||
backends must be enabled by a root user using `vault audit-enable`.
|
||||
|
||||
When enabling an audit backend, options can be passed to it to configure it.
|
||||
For example, the command below enables the file audit backend:
|
||||
|
||||
```
|
||||
$ vault audit-enable file path=/var/log/vault_audit.log
|
||||
...
|
||||
```
|
||||
|
||||
In the command above, we passed the "path" parameter to specify the path
|
||||
where the audit log will be written to. Each audit backend has its own
|
||||
set of parameters. See the documentation to the left for more details.
|
||||
|
||||
When an audit backend is disabled, it will stop receiving logs immediately.
|
||||
The existing logs that it did store are untouched.
|
||||
|
||||
## Blocked Audit Backends
|
||||
|
||||
If there are any audit backends enabled, Nomad requires that at least
|
||||
one be able to persist the log before completing a Nomad request.
|
||||
|
||||
If you have only one audit backend enabled, and it is blocking (network
|
||||
block, etc.), then Nomad will be _unresponsive_. Nomad _will not_ complete
|
||||
any requests until the audit backend can write.
|
||||
|
||||
If you have more than one audit backend, then Nomad will complete the request
|
||||
as long as one audit backend persists the log.
|
||||
|
||||
Nomad will not respond to requests if audit backends are blocked because
|
||||
audit logs are critically important and ignoring blocked requests opens
|
||||
an avenue for attack. Be absolutely certain that your audit backends cannot
|
||||
block.
|
||||
|
|
@ -1,37 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Audit Backend: Syslog"
|
||||
sidebar_current: "docs-audit-syslog"
|
||||
description: |-
|
||||
The "syslog" audit backend writes audit logs to syslog.
|
||||
---
|
||||
|
||||
# Audit Backend: Syslog
|
||||
|
||||
Name: `syslog`
|
||||
|
||||
The "syslog" audit backend writes audit logs to syslog.
|
||||
|
||||
It currently does not support a configurable syslog destination, and
|
||||
always sends to the local agent. This backend is only supported on Unix systems,
|
||||
and should not be enabled if any standby Nomad instances do not support it.
|
||||
|
||||
## Options
|
||||
|
||||
When enabling this backend, the following options are accepted:
|
||||
|
||||
* `facility` (optional) - The syslog facility to use. Defaults to "AUTH".
|
||||
* `tag` (optional) - The syslog tag to use. Defaults to "vault".
|
||||
* `log_raw` (optional) Should security sensitive information be logged raw. Defaults to "false".
|
||||
|
||||
## Format
|
||||
|
||||
Each line in the audit log is a JSON object. The "type" field specifies
|
||||
what type of object it is. Currently, only two types exist: "request" and
|
||||
"response".
|
||||
|
||||
The line contains all of the information for any given request and response.
|
||||
|
||||
If `log_raw` if false, as is default, all sensitive information is first hashed
|
||||
before logging. If explicitly enabled, all values are logged raw without hashing.
|
||||
|
||||
|
|
@ -1,119 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Auth Backend: App ID"
|
||||
sidebar_current: "docs-auth-appid"
|
||||
description: |-
|
||||
The App ID auth backend is a mechanism for machines to authenticate with Nomad.
|
||||
---
|
||||
|
||||
# Auth Backend: App ID
|
||||
|
||||
Name: `app-id`
|
||||
|
||||
The App ID auth backend is a mechanism for machines to authenticate with
|
||||
Nomad. 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 machines, containers, etc.) to authenticate with Nomad without
|
||||
having to store passwords outside of Nomad. It is a single method of
|
||||
solving the chicken-and-egg problem of setting up Nomad access on a machine.
|
||||
With this provider, nobody except the machine itself has access to both
|
||||
pieces of information necessary to authenticate. For example:
|
||||
configuration management will have the app IDs, but the machine itself
|
||||
will detect its user ID based on some unique machine property such as a
|
||||
MAC address (or a hash of it with some 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>)
|
||||
|
||||
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>)
|
||||
|
||||
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, Nomad 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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
## Authentication
|
||||
|
||||
#### Via the CLI
|
||||
|
||||
App ID authentication is not allowed via the CLI.
|
||||
|
||||
#### Via the API
|
||||
|
||||
The endpoint for the App ID login is `/login`. The client is expected
|
||||
to provide the `app_id` and `user_id` parameters as part of the request.
|
||||
|
||||
## Configuration
|
||||
|
||||
First you must enable the App ID auth backend:
|
||||
|
||||
```
|
||||
$ vault auth-enable app-id
|
||||
Successfully enabled 'app-id' at 'app-id'!
|
||||
```
|
||||
|
||||
Now when you run `vault auth -methods`, the App ID backend is available:
|
||||
|
||||
```
|
||||
Path Type Description
|
||||
app-id/ app-id
|
||||
token/ token token based credentials
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
$ vault write auth/app-id/map/app-id/foo value=root display_name=foo
|
||||
...
|
||||
|
||||
$ vault write auth/app-id/map/user-id/bar value=foo cidr_block=10.0.0.0/16
|
||||
...
|
||||
```
|
||||
|
||||
The above creates an App ID "foo" that associates with the policy "root".
|
||||
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 "root".
|
||||
|
||||
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:
|
||||
|
||||
```
|
||||
$ vault write auth/app-id/map/user-id/bar value=foo,baz cidr_block=10.0.0.0/16
|
||||
...
|
||||
```
|
||||
|
|
@ -1,68 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Auth Backend: TLS Certificates"
|
||||
sidebar_current: "docs-auth-cert"
|
||||
description: |-
|
||||
The "cert" auth backend allows users to authenticate with Nomad using TLS client certificates.
|
||||
---
|
||||
|
||||
# Auth Backend: TLS Certificates
|
||||
|
||||
Name: `cert`
|
||||
|
||||
The "cert" auth backend 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 external source.
|
||||
|
||||
## Authentication
|
||||
|
||||
### Via the CLI
|
||||
```
|
||||
vault auth -method=cert \
|
||||
-ca-cert=ca.pem -client-cert=cert.pem -client-key=key.pem
|
||||
```
|
||||
|
||||
### 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.
|
||||
|
||||
```
|
||||
curl --cacert ca.pem --cert cert.pem --key key.pem \
|
||||
$VAULT_ADDR/v1/auth/cert/login -XPOST
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
First, you must enable the certificate auth backend:
|
||||
|
||||
```
|
||||
$ vault auth-enable cert
|
||||
Successfully enabled 'cert' at 'cert'!
|
||||
```
|
||||
|
||||
Now when you run `vault auth -methods`, the certificate backend is available:
|
||||
|
||||
```
|
||||
Path Type Description
|
||||
cert/ cert
|
||||
token/ token token based credentials
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
$ vault write auth/cert/certs/web display_name=web policies=web,prod certificate=@web-cert.pem lease=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 lease value
|
||||
can be provided in seconds to limit the lease period.
|
||||
|
||||
|
|
@ -1,86 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Auth Backend: GitHub"
|
||||
sidebar_current: "docs-auth-github"
|
||||
description: |-
|
||||
The GitHub auth backend allows authentication with Nomad using GitHub.
|
||||
---
|
||||
|
||||
# Auth Backend: GitHub
|
||||
|
||||
Name: `github`
|
||||
|
||||
The GitHub auth backend can be used to authenticate with Nomad using
|
||||
a GitHub personal access token.
|
||||
This method of authentication is most useful for humans: operators or
|
||||
developers using Nomad directly via the CLI.
|
||||
|
||||
## Authentication
|
||||
|
||||
#### Via the CLI
|
||||
|
||||
```
|
||||
$ vault auth -method=github token=<api token>
|
||||
...
|
||||
```
|
||||
|
||||
#### Via the API
|
||||
|
||||
The endpoint for the GitHub login is `/login`.
|
||||
|
||||
## Configuration
|
||||
|
||||
First, you must enable the GitHub auth backend:
|
||||
|
||||
```
|
||||
$ vault auth-enable github
|
||||
Successfully enabled 'github' at 'github'!
|
||||
```
|
||||
|
||||
Now when you run `vault auth -methods`, the GitHub backend is available:
|
||||
|
||||
```
|
||||
Path Type Description
|
||||
github/ github
|
||||
token/ token token based credentials
|
||||
```
|
||||
|
||||
Prior to using the GitHub auth backend, it must be configured. To
|
||||
configure it, use the `/config` endpoint with the following arguments:
|
||||
|
||||
* `organization` (string, required) - The organization name a user must
|
||||
be a part of to authenticate.
|
||||
|
||||
###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.
|
||||
|
||||
For example:
|
||||
|
||||
```
|
||||
$ vault write auth/github/config organization=hashicorp
|
||||
Success! Data written to: auth/github/config
|
||||
```
|
||||
|
||||
After configuring that, you must map the teams of that organization to
|
||||
policies within Nomad. Use the `map/teams/<team>` endpoints to do that.
|
||||
Example:
|
||||
|
||||
```
|
||||
$ vault write auth/github/map/teams/owners value=root
|
||||
Success! Data written to: auth/github/map/teams/owners
|
||||
```
|
||||
|
||||
The above would make anyone in the "owners" team a root user in Nomad
|
||||
(not recommended).
|
||||
|
||||
You can then auth with a user that is a member of the "owners" team using a Personal Access Token with the `read:org` scope.
|
||||
|
||||
```
|
||||
$ vault auth -method=github token=000000905b381e723b3d6a7d52f148a5d43c4b45
|
||||
Successfully authenticated! The policies that are associated
|
||||
with this token are listed below:
|
||||
|
||||
root
|
||||
```
|
||||
|
||||
|
|
@ -1,40 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Auth Backends"
|
||||
sidebar_current: "docs-auth"
|
||||
description: |-
|
||||
Auth backends are mountable backends that perform authentication for Nomad.
|
||||
---
|
||||
|
||||
# Auth Backends
|
||||
|
||||
Auth backends are the components in Nomad 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 Nomad and your organization.
|
||||
|
||||
For example, on developer machines, the [GitHub auth backend](/docs/auth/github.html)
|
||||
is easiest to use. But for servers the [App ID](/docs/auth/app-id.html)
|
||||
backend is the recommended choice.
|
||||
|
||||
To learn more about authentication, see the
|
||||
[authentication concepts page](/docs/concepts/auth.html).
|
||||
|
||||
## Enabling/Disabling Auth Backends
|
||||
|
||||
Auth backends can be enabled/disabled using the CLI or the API.
|
||||
|
||||
When enabled, auth backends are similar to [secret backends](/docs/secrets/index.html):
|
||||
they are mounted within the Nomad 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.
|
||||
|
||||
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.
|
||||
|
||||
When an auth backend is disabled, all users authenticated via that
|
||||
backend are automatically logged out.
|
||||
|
|
@ -1,131 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Auth Backend: LDAP"
|
||||
sidebar_current: "docs-auth-ldap"
|
||||
description: |-
|
||||
The "ldap" auth backend allows users to authenticate with Nomad using LDAP credentials.
|
||||
---
|
||||
|
||||
# Auth Backend: LDAP
|
||||
|
||||
Name: `ldap`
|
||||
|
||||
The "ldap" auth backend allows authentication using an existing LDAP
|
||||
server and user/password credentials. This allows Nomad to be integrated
|
||||
into environments using LDAP without duplicating the user/pass configuration
|
||||
in multiple places.
|
||||
|
||||
The mapping of groups in LDAP to Nomad policies is managed by using the
|
||||
`users/` and `groups/` paths.
|
||||
|
||||
## Authentication
|
||||
|
||||
#### Via the CLI
|
||||
|
||||
```
|
||||
$ vault auth -method=ldap username=mitchellh
|
||||
Password (will be hidden):
|
||||
Successfully authenticated! The policies that are associated
|
||||
with this token are listed below:
|
||||
|
||||
root
|
||||
```
|
||||
|
||||
#### 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.
|
||||
|
||||
```shell
|
||||
$ curl $VAULT_ADDR/v1/auth/ldap/login/mitchellh \
|
||||
-d '{ "password": "foo" }'
|
||||
```
|
||||
|
||||
The response will be in JSON. For example:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"lease_id":"",
|
||||
"renewable":false,
|
||||
"lease_duration":0,
|
||||
"data":null,
|
||||
"auth":{
|
||||
"client_token":"c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
|
||||
"policies":[
|
||||
"root"
|
||||
],
|
||||
"metadata":{
|
||||
"username":"mitchellh"
|
||||
},
|
||||
"lease_duration":0,
|
||||
"renewable":false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
First, you must enable the ldap auth backend:
|
||||
|
||||
```
|
||||
$ vault auth-enable ldap
|
||||
Successfully enabled 'ldap' at 'ldap'!
|
||||
```
|
||||
|
||||
Now when you run `vault auth -methods`, the ldap backend is available:
|
||||
|
||||
```
|
||||
Path Type Description
|
||||
ldap/ ldap
|
||||
token/ token token based credentials
|
||||
```
|
||||
|
||||
To use the "ldap" auth backend, an operator must configure it with
|
||||
the address of the LDAP server that is to be used. An example is shown below.
|
||||
Use `vault path-help` for more details.
|
||||
|
||||
```
|
||||
$ vault write auth/ldap/config url="ldap://ldap.forumsys.com" \
|
||||
userattr=uid \
|
||||
userdn="dc=example,dc=com" \
|
||||
groupdn="dc=example,dc=com" \
|
||||
upndomain="forumsys.com" \
|
||||
certificate=@ldap_ca_cert.pem \
|
||||
insecure_tls=false \
|
||||
starttls=true
|
||||
...
|
||||
```
|
||||
|
||||
The above configures the target LDAP server, along with the parameters
|
||||
specifying how users and groups should be queried from the LDAP server.
|
||||
|
||||
Next we want to create a mapping from an LDAP group to a Nomad policy:
|
||||
|
||||
```
|
||||
$ vault write auth/ldap/groups/scientists policies=foo,bar
|
||||
```
|
||||
|
||||
This maps the LDAP group "scientists" to the "foo" and "bar" Nomad policies.
|
||||
|
||||
We can also add specific LDAP users to additional (potentially non-LDAP) groups:
|
||||
|
||||
```
|
||||
$ vault write auth/ldap/groups/engineers policies=foobar
|
||||
$ vault write auth/ldap/users/tesla groups=engineers
|
||||
```
|
||||
|
||||
This adds the LDAP user "tesla" to the "engineers" group, which maps to
|
||||
the "foobar" Nomad policy.
|
||||
|
||||
Finally, we can test this by authenticating:
|
||||
|
||||
```
|
||||
$ vault auth -method=ldap username=tesla
|
||||
Password (will be hidden):
|
||||
Successfully authenticated! The policies that are associated
|
||||
with this token are listed below:
|
||||
|
||||
bar, foo, foobar
|
||||
```
|
||||
|
||||
|
|
@ -1,92 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Multi-Factor Authentication"
|
||||
sidebar_current: "docs-auth-mfa"
|
||||
description: |-
|
||||
Multi-factor authentication is supported for several authentication backends.
|
||||
---
|
||||
|
||||
# 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.
|
||||
|
||||
Currently, the "ldap" and "userpass" backends 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.
|
||||
|
||||
### Via the CLI
|
||||
|
||||
```shell
|
||||
$ vault auth -method=userpass \
|
||||
username=user \
|
||||
password=test \
|
||||
passcode=111111
|
||||
```
|
||||
```shell
|
||||
$ vault auth -method=userpass \
|
||||
username=user \
|
||||
password=test \
|
||||
method=push
|
||||
```
|
||||
|
||||
### Via the API
|
||||
|
||||
The endpoint for the login is the same as for the original backend. 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" }'
|
||||
```
|
||||
|
||||
The response is the same as for the original backend.
|
||||
|
||||
## Configuration
|
||||
|
||||
To enable MFA for a supported backend, the MFA type must be set in `mfa_config`. For example:
|
||||
|
||||
```shell
|
||||
$ 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).
|
||||
|
||||
### Duo
|
||||
|
||||
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
|
||||
$ vault write auth/[mount]/duo/access \
|
||||
host=[host] \
|
||||
ikey=[integration key] \
|
||||
skey=[secret key]
|
||||
```
|
||||
|
||||
`duo/config` is an optional path that contains general configuration information
|
||||
for Duo authentication. To configure:
|
||||
|
||||
```shell
|
||||
$ vault write auth/[mount]/duo/config \
|
||||
user_agent="" \
|
||||
username_format="%s"
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
More information can be found through the CLI `path-help` command.
|
||||
|
|
@ -1,326 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Auth Backend: Token"
|
||||
sidebar_current: "docs-auth-token"
|
||||
description: |-
|
||||
The token store auth backend is used to authenticate using tokens.
|
||||
---
|
||||
|
||||
# Auth Backend: Token
|
||||
|
||||
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
|
||||
secrets by token, and more.
|
||||
|
||||
When any other auth backend returns an identity, Nomad core invokes the
|
||||
token backend to create a new unique token for that identity.
|
||||
|
||||
The token store can also be used to bypass any other auth backend:
|
||||
you can create tokens directly, as well as perform a variety of other
|
||||
operations on tokens such as renewal and revocation.
|
||||
|
||||
Please see the [token concepts](/docs/concepts/tokens.html) page dedicated
|
||||
to tokens.
|
||||
|
||||
## Authentication
|
||||
|
||||
#### Via the CLI
|
||||
|
||||
```
|
||||
$ vault auth <token>
|
||||
...
|
||||
```
|
||||
|
||||
#### Via the API
|
||||
|
||||
The token is set directly as a cookie for the HTTP API. The name
|
||||
of the cookie should be "token" and the value should be the token.
|
||||
|
||||
## API
|
||||
|
||||
### /auth/token/create
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Creates a new token. Certain options are only available to
|
||||
when called by a root token.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/create`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">id</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The ID of the client token. Can only be specified by a root token.
|
||||
Otherwise, the token ID is a randomly generated UUID.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">policies</span>
|
||||
<span class="param-flags">optional</span>
|
||||
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.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">meta</span>
|
||||
<span class="param-flags">optional</span>
|
||||
A map of string to string valued metadata. This is passed through
|
||||
to the audit backends.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">no_parent</span>
|
||||
<span class="param-flags">optional</span>
|
||||
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.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">lease</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The lease period of the token, provided as "1h", where hour is
|
||||
the largest suffix. If not provided, the token is valid for the
|
||||
[default lease duration](/docs/config/index.html), or
|
||||
indefinitely if the root policy is used.
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">display_name</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The display name of the token. Defaults to "token".
|
||||
</li>
|
||||
<li>
|
||||
<span class="param">num_uses</span>
|
||||
<span class="param-flags">optional</span>
|
||||
The maximum uses for the given token. This can be used to create
|
||||
a one-time-token or limited use token. Defaults to 0, which has
|
||||
no limit to number of uses.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"auth": {
|
||||
"client_token": "ABCD",
|
||||
"policies": ["web", "stage"],
|
||||
"metadata": {"user": "armon"},
|
||||
"lease_duration": 3600,
|
||||
"renewable": true,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /auth/token/lookup-self
|
||||
#### GET
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Returns information about the current client token.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"data": {
|
||||
"id": "ClientToken",
|
||||
"policies": ["web", "stage"],
|
||||
"path": "auth/github/login",
|
||||
"meta": {"user": "armon", "organization": "hashicorp"},
|
||||
"display_name": "github-armon",
|
||||
"num_uses": 0,
|
||||
}
|
||||
}
|
||||
```
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /auth/token/lookup/
|
||||
#### GET
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Returns information about the current client token.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>GET</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/lookup/<token>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"data": {
|
||||
"id": "ClientToken",
|
||||
"policies": ["web", "stage"],
|
||||
"path": "auth/github/login",
|
||||
"meta": {"user": "armon", "organization": "hashicorp"},
|
||||
"display_name": "github-armon",
|
||||
"num_uses": 0,
|
||||
}
|
||||
}
|
||||
```
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
|
||||
### /auth/token/revoke/
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Revokes a token and all child tokens. When the token is revoked,
|
||||
all secrets generated with it are also revoked.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/revoke/<token>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /auth/token/revoke-orphan/
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Revokes a token but not its child tokens. When the token is revoked,
|
||||
all secrets generated with it are also revoked. All child tokens
|
||||
are orphaned, but can be revoked sub-sequently using `/auth/token/revoke/`.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/revoke-orphan/<token>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /auth/token/revoke-prefix/
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Revokes all tokens generated at a given prefix, along with child tokens,
|
||||
and all secrets generated using those tokens. Uses include revoking all
|
||||
tokens generated by a credential backend during a suspected compromise.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/revoke-prefix/<prefix>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
None
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>`204` response code.
|
||||
</dd>
|
||||
</dl>
|
||||
|
||||
### /auth/token/renew/
|
||||
#### POST
|
||||
|
||||
<dl class="api">
|
||||
<dt>Description</dt>
|
||||
<dd>
|
||||
Renews a lease associated with a token. This is used to prevent
|
||||
the expiration of a token, and the automatic revocation of it.
|
||||
</dd>
|
||||
|
||||
<dt>Method</dt>
|
||||
<dd>POST</dd>
|
||||
|
||||
<dt>URL</dt>
|
||||
<dd>`/auth/token/renew/<token>`</dd>
|
||||
|
||||
<dt>Parameters</dt>
|
||||
<dd>
|
||||
<ul>
|
||||
<li>
|
||||
<span class="param">increment</span>
|
||||
<span class="param-flags">optional</span>
|
||||
An optional requested lease increment can be provided. This
|
||||
increment may be ignored.
|
||||
</li>
|
||||
</ul>
|
||||
</dd>
|
||||
|
||||
<dt>Returns</dt>
|
||||
<dd>
|
||||
|
||||
```javascript
|
||||
{
|
||||
"auth": {
|
||||
"client_token": "ABCD",
|
||||
"policies": ["web", "stage"],
|
||||
"metadata": {"user": "armon"},
|
||||
"lease_duration": 3600,
|
||||
"renewable": true,
|
||||
}
|
||||
}
|
||||
```
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
|
|
@ -1,92 +0,0 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Auth Backend: Username & Password"
|
||||
sidebar_current: "docs-auth-userpass"
|
||||
description: |-
|
||||
The "userpass" auth backend allows users to authenticate with Nomad using a username and password.
|
||||
---
|
||||
|
||||
# Auth Backend: Username & Password
|
||||
|
||||
Name: `userpass`
|
||||
|
||||
The "userpass" auth backend allows users to authenticate with Nomad 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
|
||||
passwords from an external source.
|
||||
|
||||
## Authentication
|
||||
|
||||
#### Via the CLI
|
||||
|
||||
```
|
||||
$ vault auth -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.
|
||||
|
||||
```shell
|
||||
$ curl $VAULT_ADDR/v1/auth/userpass/login/mitchellh \
|
||||
-d '{ "password": "foo" }'
|
||||
```
|
||||
|
||||
The response will be in JSON. For example:
|
||||
|
||||
```javascript
|
||||
{
|
||||
"lease_id":"",
|
||||
"renewable":false,
|
||||
"lease_duration":0,
|
||||
"data":null,
|
||||
"auth":{
|
||||
"client_token":"c4f280f6-fdb2-18eb-89d3-589e2e834cdb",
|
||||
"policies":[
|
||||
"root"
|
||||
],
|
||||
"metadata":{
|
||||
"username":"mitchellh"
|
||||
},
|
||||
"lease_duration":0,
|
||||
"renewable":false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
First, you must enable the username/password auth backend:
|
||||
|
||||
```
|
||||
$ vault auth-enable userpass
|
||||
Successfully enabled 'userpass' at 'userpass'!
|
||||
```
|
||||
|
||||
Now when you run `vault auth -methods`, the username/password backend is
|
||||
available:
|
||||
|
||||
```
|
||||
Path Type Description
|
||||
token/ token token based credentials
|
||||
userpass/ userpass
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
```
|
||||
$ vault write auth/userpass/users/mitchellh password=foo policies=root
|
||||
...
|
||||
```
|
||||
|
||||
The above creates a new user "mitchellh" with the password "foo" that
|
||||
will be associated with the "root" policy. This is the only configuration
|
||||
necessary.
|
||||
|
|
@ -117,8 +117,8 @@
|
|||
|
||||
<hr>
|
||||
|
||||
<li<%= sidebar_current("docs-secrets") %>>
|
||||
<a href="/docs/secrets/index.html">Secret Backends</a>
|
||||
<li<%= sidebar_current("docs-drivers") %>>
|
||||
<a href="/docs/drivers/index.html">Drivers</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-secrets-aws") %>>
|
||||
<a href="/docs/secrets/aws/index.html">AWS</a>
|
||||
|
|
@ -162,51 +162,6 @@
|
|||
</ul>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-auth") %>>
|
||||
<a href="/docs/auth/index.html">Auth Backends</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-auth-token") %>>
|
||||
<a href="/docs/auth/token.html">Tokens</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-auth-github") %>>
|
||||
<a href="/docs/auth/github.html">GitHub</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-auth-appid") %>>
|
||||
<a href="/docs/auth/app-id.html">App ID</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-auth-userpass") %>>
|
||||
<a href="/docs/auth/userpass.html">Username & Password</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-auth-cert") %>>
|
||||
<a href="/docs/auth/cert.html">TLS Certificates</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-auth-ldap") %>>
|
||||
<a href="/docs/auth/ldap.html">LDAP</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-auth-mfa") %>>
|
||||
<a href="/docs/auth/mfa.html">MFA</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-audit") %>>
|
||||
<a href="/docs/audit/index.html">Audit Backends</a>
|
||||
<ul class="nav">
|
||||
<li<%= sidebar_current("docs-audit-file") %>>
|
||||
<a href="/docs/audit/file.html">File</a>
|
||||
</li>
|
||||
|
||||
<li<%= sidebar_current("docs-audit-syslog") %>>
|
||||
<a href="/docs/audit/syslog.html">Syslog</a>
|
||||
</li>
|
||||
</ul>
|
||||
</li>
|
||||
</ul>
|
||||
</div>
|
||||
<% end %>
|
||||
|
|
|
|||
Loading…
Reference in New Issue