luxolus/open-vault
2
0
Fork 0
Code Issues 1 Pull requests Releases Activity
open-vault/website/content/api-docs/auth/approle.mdx
Remco Buddelmeijer b93d6e44e0
Add fields 'ttl' and 'num_uses' to SecretID generation. (#14474) 
* Add fields 'ttl' and 'num_uses' to SecretID generation.

Add fields 'ttl' and 'num_uses' when generating/obtaining a SecretID.
Rather than just being able to use the Role's SecretID ttl and num uses. #14390

* Add secret_id_num_uses response field to generating SecretID

Add the response field secret_id_num_uses to the endpoints for generating
SecretIDs. Used in testing but also to supply the vendor with this variable.

* Add tests for new ttl and num_uses SecretID generation fields

Add tests to assert the new TTL and NumUses option in the SecretID entry.
Separate test for testing with just parameters vs a -force example.

* Patch up test for ttl and num_uses fields

* Add changelog entry for auth/approle 'ttl' and 'num_uses' fields

* Add fields to API Docs and AppRole Auth Docs example

* Correct error message for failing test on missing field.
Change the error message produced when a test fails due to a missing field.
Previous values did not map to correct fields.

* Remove unnecessary int cast to int "secret_id_num_uses" field.
Unnecessary cast to int where type already is int.

* Move numUses field check to after assignment.

* Remove metadata entry in sample payload to limit change to changes made.
Remove metadata entry in sample payload for custom-secret-id. The metadata was not
changed in the features pull request.

* Bind fields 'ttl' and 'num_uses' to role's configuration.

Rather than implicitly overriding, error when the ttl is lower than and the num
uses higher than the role's configuration. #14390

* Update changelog 14474 with a more detailed description.

More elaborate description for the changelog. Specifying the per-request based fields.

* Elaborate more on the bounds of the 'ttl' and 'num_uses' field.

Specify in both the api-docs and the CLI the limits of the fields.
Specify that the role's configuration is still the leading factor.

* Upper bound ttl with role secret id ttl

Upper bound ttl with role secret id ttl when creating a secret id
Adding test cases for infinite ttl and num uses
Adding test cases for negative ttl and num uses
Validation on infinite ttl and num uses

* Formatting issues. Removed unnecessary newline

* Update documentation for AppRole Secret ID and Role

Changed that TTL is not allowed to be shorter to longer

* Cleanup approle secret ID test and impl

* Define ttl and num_uses in every test

Define ttl and num_uses in every test despite them not being tested.
This is to ensure that no unexpected behaviour comes to mind.

* Rename test RoleSecretID -> RoleSecretIDWithoutFields

* Test secret id generation defaults to Role's config

Test secret id generation defaults to Role's configuration entries.

* Change finit -> finite

Co-authored-by: Josh Black <raskchanky@users.noreply.github.com>

* Rephrase comments to the correct validation check

* Rephrase role-secret-id option description

* Remove "default" incorrect statement about ttl

* Remove "default" incorrect statement about ttl for custom secret id

* Touch up approle.mdx to align more with path_role documentation

Co-authored-by: Remco Buddelmeijer <r.buddelmeijer@fullstaq.com>
Co-authored-by: Josh Black <raskchanky@users.noreply.github.com>
2022-09-02 09:29:59 -07:00

677 lines
18 KiB
Plaintext
Raw Blame History

---
layout: api
page_title: AppRole - Auth Methods - HTTP API
description: This is the API documentation for the Vault AppRole auth method.
---
# AppRole Auth Method (API)
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).
This documentation assumes the AppRole method is mounted at the `/auth/approle`
path in Vault. Since it is possible to enable auth methods at any location,
please update your API calls accordingly.
## List Roles
This endpoint returns a list the existing AppRoles in the method.
| Method | Path |
| :----- | :------------------- |
| `LIST` | `/auth/approle/role` |
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/approle/role
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"keys": ["dev", "prod", "test"]
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Create/Update AppRole
Creates a new AppRole or updates an existing AppRole. This endpoint
supports both `create` and `update` capabilities. There can be one or more
constraints enabled on the role. It is required to have at least one of them
enabled while creating or updating a role.
| Method | Path |
| :----- | :------------------------------ |
| `POST` | `/auth/approle/role/:role_name` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `bind_secret_id` `(bool: true)` - Require `secret_id` to be presented when
logging in using this AppRole.
- `secret_id_bound_cidrs` `(array: [])` - Comma-separated string or list of CIDR
blocks; if set, specifies blocks of IP addresses which can perform the login
operation.
- `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 by default
will expire. A value of zero will allow unlimited uses.
However, this option may be overridden by the request's 'num_uses' field when generating a SecretID.
- `secret_id_ttl` `(string: "")` - Duration in either an integer number of
seconds (`3600`) or an integer time unit (`60m`) after which by default any SecretID
expires. A value of zero will allow the SecretID to not expire.
However, this option may be overridden by the request's 'ttl' field when generating a SecretID.
- `local_secret_ids` `(bool: false)` - If set, the secret IDs generated
using this role will be cluster local. This can only be set during role
creation and once set, it can't be reset later.
@include 'tokenfields.mdx'
### Sample Payload
```json
{
"token_ttl": "10m",
"token_max_ttl": "15m",
"token_policies": ["default"],
"period": 0,
"bind_secret_id": true
}
```
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1
```
## Read AppRole
Reads the properties of an existing AppRole.
| Method | Path |
| :----- | :------------------------------ |
| `GET` | `/auth/approle/role/:role_name` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/approle/role/application1
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"token_ttl": 1200,
"token_max_ttl": 1800,
"secret_id_ttl": 600,
"secret_id_num_uses": 40,
"token_policies": ["default"],
"period": 0,
"bind_secret_id": true,
"secret_id_bound_cidrs": []
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Delete AppRole
Deletes an existing AppRole from the method.
| Method | Path |
| :------- | :------------------------------ |
| `DELETE` | `/auth/approle/role/:role_name` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request DELETE \
http://127.0.0.1:8200/v1/auth/approle/role/application1
```
## Read AppRole Role ID
Reads the RoleID of an existing AppRole.
| Method | Path |
| :----- | :-------------------------------------- |
| `GET` | `/auth/approle/role/:role_name/role-id` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
http://127.0.0.1:8200/v1/auth/approle/role/application1/role-id
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"role_id": "e5a7b66e-5d08-da9c-7075-71984634b882"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Update AppRole Role ID
Updates the RoleID of an existing AppRole to a custom value.
| Method | Path |
| :----- | :-------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/role-id` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `role_id` `(string: <required>)` - Value to be set as RoleID.
### Sample Payload
```json
{
"role_id": "custom-role-id"
}
```
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/role-id
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"role_id": "e5a7b66e-5d08-da9c-7075-71984634b882"
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Generate New Secret ID
Generates and issues a new SecretID on an existing AppRole. Similar to
tokens, the response will also contain a `secret_id_accessor` value which can
be used to read the properties of the SecretID without divulging the SecretID
itself, and also to delete the SecretID from the AppRole.
| Method | Path |
| :----- | :---------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `metadata` `(string: "")` - 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
audit logs _in plaintext_.
- `cidr_list` `(array: [])` - Comma separated string or list of CIDR blocks
enforcing secret IDs to be used from specific set of IP addresses. If
`secret_id_bound_cidrs` 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.
- `token_bound_cidrs` `(array: [])` - Comma-separated string or list of CIDR
blocks; if set, specifies blocks of IP addresses which can use the auth tokens
generated by this SecretID. Overrides any role-set value but must be a subset.
- `num_uses` `(integer: 0)` - Number of times this SecretID can be used, after which
the SecretID expires. A value of zero will allow unlimited uses.
Overrides secret_id_num_uses role option when supplied.
May not be higher than role's secret_id_num_uses.
- `ttl` `(string: "")` - Duration in seconds (`3600`) or an integer time unit (`60m`)
after which this SecretID expires. A value of zero will allow the SecretID to not expire.
Overrides secret_id_ttl role option when supplied.
May not be longer than role's secret_id_ttl.
### Sample Payload
```json
{
"metadata": "{ \"tag1\": \"production\" }",
"ttl": 600,
"num_uses": 50
}
```
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780",
"secret_id": "841771dc-11c9-bbc7-bcac-6a3945a69cd9",
"secret_id_ttl": 600,
"secret_id_num_uses": 50
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## List Secret ID Accessors
Lists the accessors of all the SecretIDs issued against the AppRole.
This includes the accessors for "custom" SecretIDs as well.
| Method | Path |
| :----- | :---------------------------------------- |
| `LIST` | `/auth/approle/role/:role_name/secret-id` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request LIST \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id
```
### Sample Response
```json
{
"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": ""
}
```
## Read AppRole Secret ID
Reads out the properties of a SecretID.
| Method | Path |
| :----- | :----------------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id/lookup` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `secret_id` `(string: <required>)` - Secret ID attached to the role.
### Sample Payload
```json
{
"secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id/lookup
```
## Destroy AppRole Secret ID
Destroy an AppRole secret ID.
| Method | Path |
| :----- | :------------------------------------------------ |
| `POST` | `/auth/approle/role/:role_name/secret-id/destroy` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `secret_id` `(string: <required>)` - Secret ID attached to the role.
### Sample Payload
```json
{
"secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id/destroy
```
## Read AppRole Secret ID Accessor
Reads out the properties of a SecretID.
| Method | Path |
| :----- | :-------------------------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id-accessor/lookup` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `secret_id_accessor` `(string: <required>)` - Secret ID accessor attached to the role.
### Sample Payload
```json
{
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id-accessor/lookup
```
## Destroy AppRole Secret ID Accessor
Destroy an AppRole secret ID by its accessor.
| Method | Path |
| :----- | :--------------------------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/secret-id-accessor/destroy` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `secret_id_accessor` `(string: <required>)` - Secret ID accessor attached to the role.
### Sample Payload
```json
{
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id-accessor/destroy
```
## Create Custom AppRole Secret ID
Assigns a "custom" SecretID against an existing AppRole. This is used in the
"Push" model of operation.
| Method | Path |
| :----- | :----------------------------------------------- |
| `POST` | `/auth/approle/role/:role_name/custom-secret-id` |
### Parameters
- `role_name` `(string: <required>)` - Name of the AppRole.
- `secret_id` `(string: <required>)` - SecretID to be attached to the Role.
- `metadata` `(string: "")` - 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
audit logs _in plaintext_.
- `cidr_list` `(array: [])` - Comma separated string or list of CIDR blocks
enforcing secret IDs to be used from specific set of IP addresses. If
`secret_id_bound_cidrs` 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.
- `token_bound_cidrs` `(array: [])` - Comma-separated string or list of CIDR
blocks; if set, specifies blocks of IP addresses which can use the auth tokens
generated by this SecretID. Overrides any role-set value but must be a subset.
- `num_uses` `(integer: 0)` - Number of times this SecretID can be used, after which
the SecretID expires. A value of zero will allow unlimited uses.
Overrides secret_id_num_uses role option when supplied.
May not be higher than role's secret_id_num_uses.
- `ttl` `(string: "")` - Duration in seconds (`3600`) or an integer time unit (`60m`)
after which this SecretID expires. A value of zero will allow the SecretID to not expire.
Overrides secret_id_ttl role option when supplied.
May not be longer than role's secret_id_ttl.
### Sample Payload
```json
{
"secret_id": "testsecretid",
"ttl": 600,
"num_uses": 50
}
```
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/role/application1/custom-secret-id
```
### Sample Response
```json
{
"auth": null,
"warnings": null,
"wrap_info": null,
"data": {
"secret_id": "testsecretid",
"secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780",
"secret_id_ttl": 600,
"secret_id_num_uses": 50
},
"lease_duration": 0,
"renewable": false,
"lease_id": ""
}
```
## Login With AppRole
Issues a Vault token based on the presented credentials. `role_id` is always
required; if `bind_secret_id` is enabled (the default) on the AppRole,
`secret_id` is required too. Any other bound authentication values on the
AppRole (such as client IP CIDR) are also evaluated.
| Method | Path |
| :----- | :-------------------- |
| `POST` | `/auth/approle/login` |
### Parameters
- `role_id` `(string: <required>)` - RoleID of the AppRole.
- `secret_id` `(string: <required>)` - SecretID belonging to AppRole.
### Sample Payload
```json
{
"role_id": "59d6d1ca-47bb-4e7e-a40b-8be3bc5a0ba8",
"secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}
```
### Sample Request
```shell-session
$ curl \
--request POST \
--data @payload.json \
http://127.0.0.1:8200/v1/auth/approle/login
```
### Sample Response
```json
{
"auth": {
"renewable": true,
"lease_duration": 1200,
"metadata": null,
"token_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": ""
}
```
## Read, Update, or Delete AppRole Properties
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 | Path |
| :---------------- | :---------------------------------------------------- | --------- |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/policies` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/secret-id-num-uses` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/secret-id-ttl` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/token-ttl` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/token-max-ttl` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/bind-secret-id` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/secret-id-bound-cidrs` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/token-bound-cidrs` | `200/204` |
| `GET/POST/DELETE` | `/auth/approle/role/:role_name/period` | `200/204` |
Refer to `/auth/approle/role/:role_name` endpoint.
## Tidy Tokens
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 method so should be used sparingly.
| Method | Path |
| :----- | :----------------------------- |
| `POST` | `/auth/approle/tidy/secret-id` |
### Sample Request
```shell-session
$ curl \
--header "X-Vault-Token: ..." \
--request POST \
http://127.0.0.1:8200/v1/auth/approle/tidy/secret-id
```
### Sample Response
```json
{
"request_id": "b20b56e3-4699-5b19-cc6b-e74f7b787bbf",
"lease_id": "",
"renewable": false,
"lease_duration": 0,
"data": null,
"wrap_info": null,
"warnings": [
"Tidy operation successfully started. Any information from the operation will be printed to Vault's server logs."
],
"auth": null
}
```
Reference in a new issue View git blame Copy permalink