open-vault/website/source/docs/auth/approle.html.md

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

# Auth Backend: AppRole

This backend allows machines and services (logically referred as `app`s) 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

```javascript
$ vault auth-enable approle
```

#### Create a role

```javascript
$ 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

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

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

#### Get a SecretID issued against the AppRole

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

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


#### Login to get a Vault Token

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

```javascript
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

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

#### Create a role

```javascript
$ 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

```javascript
$ 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

```javascript
$ 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

```javascript
$ 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
<dl class="api">
  <dt>Description</dt>
  <dd>
  Lists the existing AppRoles in the backend
  </dd>

  <dt>Method</dt>
  <dd>`/auth/approle/role` (LIST) or `/auth/approle/role?list=true` (GET)</dd>

  <dt>URL</dt>
  <dd>`LIST/GET`</dd>

  <dt>Parameters</dt>
  <dd>
  None
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "keys": [
      "dev",
      "prod",
      "test"
    ]
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>


### /auth/approle/role/[role_name]
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
  Create a new AppRole or update an existing AppRole. This endpoint
  supports both `create` and `update` capabilities.
  </dd>

  <dt>Method</dt>
  <dd>`POST`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/role/[role_name]`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">role_name</span>
        <span class="param-flags">required</span>
        Name of the Role.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">bind_secret_id</span>
        <span class="param-flags">optional</span>
        Impose secret_id to be presented when logging in using this Role.
        Defaults to 'true'.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">bound_cidr_list</span>
        <span class="param-flags">optional</span>
        Comma separated list of CIDR blocks, if set, specifies blocks of IP
        addresses which can perform the login operation
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">policies</span>
        <span class="param-flags">optional</span>
        Comma separated list of policies on the Role.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">secret_id_num_uses</span>
        <span class="param-flags">optional</span>
        Number of times a SecretID can access the Role, after which the SecretID will expire.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">secret_id_ttl</span>
        <span class="param-flags">optional</span>
        Duration in seconds after which the issued SecretID should expire.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">token_ttl</span>
        <span class="param-flags">optional</span>
        Duration in seconds after which the issued token should expire.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">token_max_ttl</span>
        <span class="param-flags">optional</span>
        Duration in seconds after which the issued token should not be allowed to be renewed.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">period</span>
        <span class="param-flags">optional</span>
        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.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>

#### GET
<dl class="api">
  <dt>Description</dt>
  <dd>
  Reads the properties of an existing AppRole.
  </dd>

  <dt>Method</dt>
  <dd>`GET`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/role/[role_name]`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "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": ""
}
```

  </dd>
</dl>

#### DELETE
<dl class="api">
  <dt>Description</dt>
  <dd>
  Deletes an existing AppRole from the backend.
  </dd>

  <dt>Method</dt>
  <dd>`DELETE`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/role/[role_name]`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>`204` response code.
  </dd>
</dl>


### /auth/approle/role/[role_name]/role-id
#### GET
<dl class="api">
  <dt>Description</dt>
  <dd>
  Reads the RoleID of an existing AppRole.
  </dd>

  <dt>Method</dt>
  <dd>`GET`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/role/[role_name]/role-id`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "auth": null,
  "warnings": null,
  "wrap_info": null,
  "data": {
    "role_id": "e5a7b66e-5d08-da9c-7075-71984634b882"
  },
  "lease_duration": 0,
  "renewable": false,
  "lease_id": ""
}
```

  </dd>
</dl>

#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
  Updates the RoleID of an existing AppRole.
  </dd>

  <dt>Method</dt>
  <dd>`POST`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/role/[role_name]/role-id`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">role_id</span>
        <span class="param-flags">required</span>
        Value to be set as RoleID.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>
  `204` response code.
  </dd>
</dl>



### /auth/approle/role/[role_name]/secret-id
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
  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.
  </dd>

  <dt>Method</dt>
  <dd>`POST`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/role/[role_name]/secret-id`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">metadata</span>
        <span class="param-flags">optional</span>
        Metadata to be tied to the SecretID. This should be a JSON
        formatted string containing the metadata in key value pairs.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "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": ""
}
```

  </dd>
</dl>

#### List
<dl class="api">
  <dt>Description</dt>
  <dd>
  Lists the accessors of all the SecretIDs issued against the AppRole.
  This includes the accessors for the "custom" SecretIDs as well.
  </dd>

  <dt>Method</dt>
  <dd>`LIST/GET`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/role/[role_name]/secret-id` (LIST) or `/auth/approle/role/[role_name]/secret-id?list=true` (GET)</dd>

  <dt>Parameters</dt>
  <dd>
  None
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "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": ""
}
```

  </dd>
</dl>

### /auth/approle/role/[role_name]/secret-id/<secret_id_accessor>
#### GET
<dl class="api">
  <dt>Description</dt>
  <dd>
  Reads out the properties of the SecretID to which the supplied `secret_id_accessor` is an index of.
  </dd>

  <dt>Method</dt>
  <dd>`GET`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/role/[role_name]/secret-id/<secret_id_accessor>`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "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": ""
}
```

  </dd>
</dl>

#### DELETE
<dl class="api">
  <dt>Description</dt>
  <dd>
  Deletes the SecretID to which the supplied `secret_id_accessor` is an index of.
  </dd>

  <dt>Method</dt>
  <dd>`DELETE`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/role/[role_name]/secret-id/<secret_id_accessor>`</dd>

  <dt>Parameters</dt>
  <dd>
    None.
  </dd>

  <dt>Returns</dt>
  <dd>
  `204` response code.
  </dd>
</dl>


### /auth/approle/role/[role_name]/custom-secret-id
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
  Assigns a "custom" SecretID against an existing AppRole.
  </dd>

  <dt>Method</dt>
  <dd>`POST`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/role/[role_name]/custom-secret-id`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">secret_id</span>
        <span class="param-flags">required</span>
        SecretID to be attached to the Role.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">metadata</span>
        <span class="param-flags">optional</span>
        Metadata to be tied to the SecretID. This should be a JSON
        formatted string containing the metadata in key value pairs.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "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": ""
}
```

  </dd>
</dl>


### /auth/approle/login
#### POST
<dl class="api">
  <dt>Description</dt>
  <dd>
  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.
  </dd>

  <dt>Method</dt>
  <dd>`POST`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/login`</dd>

  <dt>Parameters</dt>
  <dd>
    <ul>
      <li>
        <span class="param">role_id</span>
        <span class="param-flags">required</span>
        RoleID of the AppRole.
      </li>
    </ul>
    <ul>
      <li>
        <span class="param">secret_id</span>
        <span class="param-flags">required when `bind_secret_id` is enabled</span>
        SecretID belonging to AppRole.
      </li>
    </ul>
  </dd>

  <dt>Returns</dt>
  <dd>

```javascript
{
  "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": ""
}
```

  </dd>
</dl>

### /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
<dl class="api">
  <dt>Description</dt>
  <dd>
  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.
  </dd>

  <dt>Method</dt>
  <dd>`POST/GET/DELETE`</dd>

  <dt>URL</dt>
  <dd>`/auth/approle/role/[role_name]/[field_name]`</dd>

  <dt>Parameters</dt>
  <dd>
  Refer to `/auth/approle/role/[role_name]` endpoint.
  </dd>

  <dt>Returns</dt>
  <dd>
  Refer to `/auth/approle/role/[role_name]` endpoint.
  </dd>
</dl>