luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity
open-vault/website/source/docs/auth/approle.html.md
Matt Hurne 56252fb637 AppRole documentation tweaks (#1735) 
* Fix spelling error in AppRole docs

* Add force flag to sample command to generate a secret ID in AppRole docs

* Update sample output for AppRole login in docs
2016-08-15 16:12:08 -04:00

17 KiB
Raw Blame History

layout page_title sidebar_current description
docs Auth Backend: AppRole docs-auth-approle The AppRole backend allows machines and services to authenticate with Vault.

Auth Backend: AppRole

This backend allows machines and services (logically referred as apps) to authenticate with Vault, by registering them as AppRoles. The open design of AppRoles, enables a varied set of Apps to authenticate themselves. Since an AppRole can represent a service, or a machine or anything that can be IDed, this backend is the successor for the App-ID backend.

AppRole

An AppRole represents a set of Vault policies, under a name. In essence, if a machine needs to authenticate with Vault for a set of policies, an AppRole can be registered under the machine's name with the desired set of policies. If a service requires a set of Vault policies, an AppRole can be registered under the service's name with the desired policies. The credentials presented at the login endpoint depends on the constraints set on AppRoles.

RoleID

RoleID is a credential to be used at the login endpoint. The credentials used to fetch a Vault token depends on the configured contraints on the AppRole. The credential role_id is a required argument for the login endpoint at all times. RoleIDs by default are unique UUIDs that map to the human read-able AppRole names. This credential lets the backend know which AppRole to refer to, in verifying the set constraints. RoleID for an AppRole can be fetched via role/<role_name>/role-id endpoint.

SecretID

SecretID is a credential to be used at the login endpoint. By default, this backend enables a login constraint on the AppRole, called bind_secret_id. When this constraint is enabled, the login endpoint expects another credential, secret_id to be presented, along with role_id. The backend supports both creation of SecretID by the backend and setting custom SecretID by the client. It is recommended that SecretIDs be generated by the backend. The ones generated by the backend will be cryptographically strong random UUIDs. SecretIDs have properties like usage-limit, TTLs and expirations; similar to tokens. SecretID for an AppRole can be fetched via role/<role_name>/secret-id endpoint.

Pull And Push SecretID Modes

If the SecretID generated by the backend is fetched and used for login, it is referred as Pull mode. If a "custom" SecretID is set against an AppRole by the client, it is referred as a Push mode.

While the user_id of the App-ID backend worked in a Push mode, this backend recommends the Pull mode. The Push mode is supported in AppRole backend, only to be able to make this backend to do all that App-ID did.

AppRole Constraints

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 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.

Authentication

Via the CLI

Enable AppRole authentication

$ vault auth-enable approle

Create a role

$ vault write auth/approle/role/testrole secret_id_ttl=10m token_ttl=20m token_max_ttl=30m secret_id_num_uses=40

Fetch the RoleID of the AppRole

$ vault read auth/approle/role/testrole/role-id

role_id     db02de05-fa39-4855-059b-67221c5c2f63

Get a SecretID issued against the AppRole

$ vault write -f auth/approle/role/testrole/secret-id

secret_id               6a174c20-f6de-a53c-74d2-6018fcceff64
secret_id_accessor      c454f7e5-996e-7230-6074-6ef26b7bcf86

Login to get a Vault Token

$ vault write auth/approle/login role_id=db02de05-fa39-4855-059b-67221c5c2f63 secret_id=6a174c20-f6de-a53c-74d2-6018fcceff64

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 AppRole authentication

$ curl -XPOST -H "X-Vault-Token:xxx" "http://127.0.0.1:8200/v1/sys/auth/approle" -d '{"type":"approle"}'

Create a role

$ curl -XPOST -H "X-Vault-Token:xxx" "http://127.0.0.1:8200/v1/auth/approle/role/testrole" -d '{"secret_id_ttl":"10m", "token_ttl":"20m", "token_max_ttl":"30m", "secret_id_num_uses":40}'

Fetch the RoleID of the AppRole

$ curl -XGET -H "X-Vault-Token:xxx" "http://127.0.0.1:8200/v1/auth/approle/role/testrole/role-id"

Get a SecretID issued against the AppRole

$ curl -XPOST -H "X-Vault-Token:xxx" "http://127.0.0.1:8200/v1/auth/approle/role/testrole/secret-id"

Login to get a Vault Token

$ curl -XPOST -H "X-Vault-Token:xxx" "http://127.0.0.1:8200/v1/auth/approle/login" -d '{"role_id":"50bec295-3535-0ddc-b729-e4d0773717b3","secret_id":"0c36edb2-8b34-c077-9e3a-9bdcbb4ab0df"}'

API

/auth/approle/role

List

Description
Lists the existing AppRoles in the backend
Method
`/auth/approle/role` (LIST) or `/auth/approle/role?list=true` (GET)
URL
`LIST/GET`
Parameters
None
Returns
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": [
      "dev",
      "prod",
      "test"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

/auth/approle/role/[role_name]

POST

Description
Create a new AppRole or update an existing AppRole. This endpoint supports both `create` and `update` capabilities.
Method
`POST`
URL
`/auth/approle/role/[role_name]`
Parameters
  • role_name required Name of the Role.
  • bind_secret_id optional Impose secret_id to be presented when logging in using this Role. Defaults to 'true'.
  • bound_cidr_list optional Comma separated list of CIDR blocks, if set, specifies blocks of IP addresses which can perform the login operation
  • policies optional Comma separated list of policies on the Role.
  • secret_id_num_uses optional Number of times a SecretID can access the Role, after which the SecretID will expire.
  • secret_id_ttl optional Duration in seconds after which the issued SecretID should expire.
  • token_ttl optional Duration in seconds after which the issued token should expire.
  • token_max_ttl optional Duration in seconds after which the issued token should not be allowed to be renewed.
  • period optional If set, indicates that the token generated using this Role should never expire. The token should be renewed within the duration specified by this value. The renewal duration will be fixed, if this value is not modified. If the Period in the Role is modified, the token will pick up the new value during its next renewal.
Returns
`204` response code.

GET

Description
Reads the properties of an existing AppRole.
Method
`GET`
URL
`/auth/approle/role/[role_name]`
Parameters
None.
Returns
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "token_ttl": 1200,
    "token_max_ttl": 1800,
    "secret_id_ttl": 600,
    "secret_id_num_uses": 40,
    "policies": [
      "default"
    ],
    "period": 0,
    "bind_secret_id": true,
    "bound_cidr_list": ""
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

DELETE

Description
Deletes an existing AppRole from the backend.
Method
`DELETE`
URL
`/auth/approle/role/[role_name]`
Parameters
None.
Returns
`204` response code.

/auth/approle/role/[role_name]/role-id

GET

Description
Reads the RoleID of an existing AppRole.
Method
`GET`
URL
`/auth/approle/role/[role_name]/role-id`
Parameters
None.
Returns
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "role_id": "e5a7b66e-5d08-da9c-7075-71984634b882"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

POST

Description
Updates the RoleID of an existing AppRole.
Method
`POST`
URL
`/auth/approle/role/[role_name]/role-id`
Parameters
  • role_id required Value to be set as RoleID.
Returns
`204` response code.

/auth/approle/role/[role_name]/secret-id

POST

Description
Generates and issues a new SecretID on an existing AppRole. The response will also contain the `secret_id_accessor` which can be used to read the properties of the SecretID and also to delete the SecretID from the backend.
Method
`POST`
URL
`/auth/approle/role/[role_name]/secret-id`
Parameters
  • metadata optional Metadata to be tied to the SecretID. This should be a JSON formatted string containing the metadata in key value pairs.
Returns
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780",
    "secret_id": "841771dc-11c9-bbc7-bcac-6a3945a69cd9"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

List

Description
Lists the accessors of all the SecretIDs issued against the AppRole. This includes the accessors for the "custom" SecretIDs as well.
Method
`LIST/GET`
URL
`/auth/approle/role/[role_name]/secret-id` (LIST) or `/auth/approle/role/[role_name]/secret-id?list=true` (GET)
Parameters
None
Returns
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": [
      "ce102d2a-8253-c437-bf9a-aceed4241491",
      "a1c8dee4-b869-e68d-3520-2040c1a0849a",
      "be83b7e2-044c-7244-07e1-47560ca1c787",
      "84896a0c-1347-aa90-a4f6-aca8b7558780",
      "239b1328-6523-15e7-403a-a48038cdc45a"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

/auth/approle/role/[role_name]/secret-id/<secret_id_accessor>

GET

Description
Reads out the properties of the SecretID to which the supplied `secret_id_accessor` is an index of.
Method
`GET`
URL
`/auth/approle/role/[role_name]/secret-id/`
Parameters
None.
Returns
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "secret_id_ttl": 600,
    "secret_id_num_uses": 40,
    "secret_id_accessor": "5e222f10-278d-a829-4e74-10d71977bb53",
    "metadata": {},
    "last_updated_time": "2016-06-29T05:31:09.407042587Z",
    "expiration_time": "2016-06-29T05:41:09.407042587Z",
    "creation_time": "2016-06-29T05:31:09.407042587Z"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

DELETE

Description
Deletes the SecretID to which the supplied `secret_id_accessor` is an index of.
Method
`DELETE`
URL
`/auth/approle/role/[role_name]/secret-id/`
Parameters
None.
Returns
`204` response code.

/auth/approle/role/[role_name]/custom-secret-id

POST

Description
Assigns a "custom" SecretID against an existing AppRole.
Method
`POST`
URL
`/auth/approle/role/[role_name]/custom-secret-id`
Parameters
  • secret_id required SecretID to be attached to the Role.
  • metadata optional Metadata to be tied to the SecretID. This should be a JSON formatted string containing the metadata in key value pairs.
Returns
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "secret_id_accessor": "a109dc4a-1fd3-6df6-feda-0ca28b2d4a81",
    "secret_id": "testsecretid"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

/auth/approle/login

POST

Description
Issues a Vault token based on the presented credentials. Credentials other than `role_id`, to be presented depends on the constraints set on the AppRole. If `bind_secret_id` is enabled, then parameter `secret_id` becomes a required credential.
Method
`POST`
URL
`/auth/approle/login`
Parameters
  • role_id required RoleID of the AppRole.
  • secret_id required when `bind_secret_id` is enabled SecretID belonging to AppRole.
Returns
{
  "auth": {
    "renewable": true,
    "lease_duration": 1200,
    "metadata": null,
    "policies": [
      "default"
    ],
    "accessor": "fd6c9a00-d2dc-3b11-0be5-af7ae0e1d374",
    "client_token": "5b1a0318-679c-9c45-e5c6-d1b9a9035d49"
  },
  "warnings": null,
  "wrap_info": null,
  "data": null,
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}

/auth/approle/role/[role_name]/policies

/auth/approle/role/[role_name]/secret-id-num-uses

/auth/approle/role/[role_name]/secret-id-ttl

/auth/approle/role/[role_name]/token-ttl

/auth/approle/role/[role_name]/token-max-ttl

/auth/approle/role/[role_name]/bind-secret-id

/auth/approle/role/[role_name]/bound-cidr-list

/auth/approle/role/[role_name]/period

POST/GET/DELETE

Description
Updates the respective property in the existing AppRole. All of these parameters of the AppRole can be updated using the `/auth/approle/role/[role_name]` endpoint directly. The endpoints for each field is provided separately to be able to delegate specific endpoints using Vault's ACL system.
Method
`POST/GET/DELETE`
URL
`/auth/approle/role/[role_name]/[field_name]`
Parameters
Refer to `/auth/approle/role/[role_name]` endpoint.
Returns
Refer to `/auth/approle/role/[role_name]` endpoint.