From a798bdb82287d8d3b133178ab410bb57eed3d337 Mon Sep 17 00:00:00 2001 From: Jeff Mitchell Date: Mon, 14 Mar 2016 16:43:02 -0400 Subject: [PATCH] Update app-id docs to use new endpoint --- website/source/docs/auth/app-id.html.md | 72 ++++++++++++------------- 1 file changed, 35 insertions(+), 37 deletions(-) diff --git a/website/source/docs/auth/app-id.html.md b/website/source/docs/auth/app-id.html.md index e51cec4fa..249acd5e8 100644 --- a/website/source/docs/auth/app-id.html.md +++ b/website/source/docs/auth/app-id.html.md @@ -10,65 +10,63 @@ description: |- 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 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). +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/) + 1. Create unique app IDs (UUIDs work well) and map them to policies. (Path: + map/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/) + 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/) - 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 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. +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 -App ID authentication is not allowed via the CLI. +Use `vault write`, for example: `vault write auth/app-id/login/[app-id] user_id=[user-id]` #### Via the API -The endpoint for the App ID login is `auth/app-id/login`. The client is expected -to provide the `app_id` and `user_id` parameters as part of the request. +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. ## Configuration