Skip to main content

AppRole auth method (API)

This is the API documentation for the OpenBao AppRole auth method. For general information about the usage and operation of the AppRole method, please see the OpenBao AppRole method documentation.

This documentation assumes the AppRole method is mounted at the /auth/approle path in OpenBao. 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.

MethodPath
LIST/auth/approle/role

Parameters​

  • after (string: "") - Optional entry to begin listing after for pagination; not required to exist.

  • limit (int: 0) - Optional number of entries to return; defaults to all entries.

Sample request​

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/auth/approle/role

Sample response​

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

MethodPath
POST/auth/approle/role/:role_name

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes, accepted characters include a-Z, 0-9, space, hyphen, underscore and periods.
  • 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.
  • token_ttl (integer: 0 or string: "") - The incremental lifetime for generated tokens. This current value of this will be referenced at renewal time.
  • token_max_ttl (integer: 0 or string: "") - The maximum lifetime for generated tokens. This current value of this will be referenced at renewal time.
  • token_policies (array: [] or comma-delimited string: "") - List of token policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.
  • policies (array: [] or comma-delimited string: "") - DEPRECATED: Please use the token_policies parameter instead. List of token policies to encode onto generated tokens. Depending on the auth method, this list may be supplemented by user/group/other values.
  • token_bound_cidrs (array: [] or comma-delimited string: "") - List of CIDR blocks; if set, specifies blocks of IP addresses which can authenticate successfully, and ties the resulting token to these blocks as well.
  • token_strictly_bind_ip (bool: false) - If set, the token will be restricted to the source IP address making the initial login request. This conflicts with token_bound_cidrs.
  • token_explicit_max_ttl (integer: 0 or string: "") - If set, will encode an explicit max TTL onto the token. This is a hard cap even if token_ttl and token_max_ttl would otherwise allow a renewal.
  • token_no_default_policy (bool: false) - If set, the default policy will not be set on generated tokens; otherwise it will be added to the policies set in token_policies.
  • token_num_uses (integer: 0) - The maximum number of times a generated token may be used (within its lifetime); 0 means unlimited. If you require the token to have the ability to create child tokens, you will need to set this value to 0.
  • token_period (integer: 0 or string: "") - The maximum allowed period value when a periodic token is requested from this role.
  • token_type (string: "") - The type of token that should be generated. Can be service, batch, or default to use the mount's tuned default (which unless changed will be service tokens). For token store roles, there are two additional possibilities: default-service and default-batch which specify the type to return unless the client requests a different type at generation time.

Sample payload​

{
  "token_ttl": "10m",
  "token_max_ttl": "15m",
  "token_policies": ["default"],
  "period": 0,
  "bind_secret_id": true
}

Sample request​

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

MethodPath
GET/auth/approle/role/:role_name

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes.

Sample request​

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/approle/role/application1

Sample response​

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

MethodPath
DELETE/auth/approle/role/:role_name

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes.

Sample request​

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

MethodPath
GET/auth/approle/role/:role_name/role-id

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes.

Sample request​

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/auth/approle/role/application1/role-id

Sample response​

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

MethodPath
POST/auth/approle/role/:role_name/role-id

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes.
  • role_id (string: <required>) - Value to be set as RoleID.

Sample payload​

{
  "role_id": "custom-role-id"
}

Sample request​

$ 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​

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

MethodPath
POST/auth/approle/role/:role_name/secret-id

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes.
  • 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​

{
  "metadata": "{ \"tag1\": \"production\" }",
  "ttl": 600,
  "num_uses": 50
}

Sample request​

$ 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​

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

MethodPath
LIST/auth/approle/role/:role_name/secret-id

Parameters​

  • after (string: "") - Optional entry to begin listing after for pagination; not required to exist.

  • limit (int: 0) - Optional number of entries to return; defaults to all entries.

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes.

Sample request​

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id

Sample response​

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

MethodPath
POST/auth/approle/role/:role_name/secret-id/lookup

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes.
  • secret_id (string: <required>) - Secret ID attached to the role.

Sample payload​

{
  "secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}

Sample request​

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id/lookup

Sample Response​

{
  "request_id": "74752925-f309-6859-3d2d-0fcded95150e",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "cidr_list": [],
    "creation_time": "2023-02-10T18:17:27.089757383Z",
    "expiration_time": "0001-01-01T00:00:00Z",
    "last_updated_time": "2023-02-10T18:17:27.089757383Z",
    "metadata": {
      "tag1": "production"
    },
    "secret_id_accessor": "2be760a4-86bb-2fa9-1637-1b7fa9ba2896",
    "secret_id_num_uses": 0,
    "secret_id_ttl": 0,
    "token_bound_cidrs": []
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Destroy AppRole Secret ID​

Destroy an AppRole secret ID.

MethodPath
POST/auth/approle/role/:role_name/secret-id/destroy

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes.
  • secret_id (string: <required>) - Secret ID attached to the role.

Sample payload​

{
  "secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}

Sample request​

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

MethodPath
POST/auth/approle/role/:role_name/secret-id-accessor/lookup

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes.
  • secret_id_accessor (string: <required>) - Secret ID accessor attached to the role.

Sample payload​

{
  "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}

Sample request​

$ 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

Sample Response​

{
  "request_id": "72836cd1-139c-fe66-1402-8bb5ca4044b8",
  "lease_id": "",
  "renewable": false,
  "lease_duration": 0,
  "data": {
    "cidr_list": [],
    "creation_time": "2023-02-10T18:17:27.089757383Z",
    "expiration_time": "0001-01-01T00:00:00Z",
    "last_updated_time": "2023-02-10T18:17:27.089757383Z",
    "metadata": {
      "tag1": "production"
    },
    "secret_id_accessor": "2be760a4-86bb-2fa9-1637-1b7fa9ba2896",
    "secret_id_num_uses": 0,
    "secret_id_ttl": 0,
    "token_bound_cidrs": []
  },
  "wrap_info": null,
  "warnings": null,
  "auth": null
}

Destroy AppRole Secret ID Accessor​

Destroy an AppRole secret ID by its accessor.

MethodPath
POST/auth/approle/role/:role_name/secret-id-accessor/destroy

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes.
  • secret_id_accessor (string: <required>) - Secret ID accessor attached to the role.

Sample payload​

{
  "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}

Sample request​

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

MethodPath
POST/auth/approle/role/:role_name/custom-secret-id

Parameters​

  • role_name (string: <required>) - Name of the AppRole. Must be less than 4096 bytes.
  • 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​

{
  "secret_id": "testsecretid",
  "ttl": 600,
  "num_uses": 50
}

Sample request​

$ 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​

{
  "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 an OpenBao 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.

MethodPath
POST/auth/approle/login

Parameters​

  • role_id (string: <required>) - RoleID of the AppRole.
  • secret_id (string: <required>) - SecretID belonging to AppRole.

Sample payload​

{
  "role_id": "59d6d1ca-47bb-4e7e-a40b-8be3bc5a0ba8",
  "secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780"
}

Sample request​

$ curl \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/auth/approle/login

Sample response​

{
  "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 OpenBao'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.

MethodPath
POST/auth/approle/tidy/secret-id

Sample request​

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/auth/approle/tidy/secret-id

Sample response​

{
  "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 OpenBao's server logs."
  ],
  "auth": null
}