96 lines
3.5 KiB
Markdown
96 lines
3.5 KiB
Markdown
---
|
|
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 Vault.
|
|
---
|
|
|
|
# Auth Backend: App ID
|
|
|
|
Name: `app-id`
|
|
|
|
The App ID auth backend 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 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 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, 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.
|
|
|
|
After creating app IDs, an operator authorizes a fixed set of user IDs
|
|
with each app ID. When the valid {app ID, user ID} set is 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`.
|
|
|
|
## Configuration
|
|
|
|
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 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 in 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.
|