diff --git a/website/source/api/auth/app-id/index.html.md b/website/source/api/auth/app-id/index.html.md new file mode 100644 index 000000000000..4d509f0dfc36 --- /dev/null +++ b/website/source/api/auth/app-id/index.html.md @@ -0,0 +1,17 @@ +--- +layout: "api" +page_title: "App ID Auth Backend - HTTP API" +sidebar_current: "docs-http-auth-appid" +description: |- + This is the API documentation for the Vault App ID authentication backend. +--- + +# App ID Auth Backend HTTP API (DEPRECATED) + +This is the API documentation for the Vault App ID authentication backend. For +general information about the usage and operation of the App ID backend, please +see the [Vault App ID backend documentation](/docs/auth/app-id.html). + +This documentation assumes the App ID backend is mounted at the `/auth/app-id` +path in Vault. Since it is possible to mount auth backends at any location, +please update your API calls accordingly. \ No newline at end of file diff --git a/website/source/api/auth/approle/index.html.md b/website/source/api/auth/approle/index.html.md new file mode 100644 index 000000000000..4da06160e2ad --- /dev/null +++ b/website/source/api/auth/approle/index.html.md @@ -0,0 +1,630 @@ +--- +layout: "api" +page_title: "AppRole Auth Backend - HTTP API" +sidebar_current: "docs-http-auth-approle" +description: |- + This is the API documentation for the Vault AppRole authentication backend. +--- + +# AppRole Auth Backend HTTP API + +This is the API documentation for the Vault AppRole authentication backend. For +general information about the usage and operation of the AppRole backend, please +see the [Vault AppRole backend documentation](/docs/auth/approle.html). + +This documentation assumes the AppRole backend is mounted at the `/auth/approle` +path in Vault. Since it is possible to mount auth backends at any location, +please update your API calls accordingly. + +## List Roles + +This endpoint returns a list the existing AppRoles in the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/approle/role` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/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 New 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 | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/approle/role/:role_name` | `204 (empty body)` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. +- `bind_secret_id` `(bool: true)` - Require `secret_id` to be presented when + logging in using this AppRole. +- `bind_cidr_list` `(array: [])` - Comma-separated list of CIDR blocks; if set, + specifies blocks of IP addresses which can perform the login operation. +- `policies` `(array: [])` - Comma-separated list of policies set on tokens + issued via this AppRole. +- `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 will + expire. A value of zero will allow unlimited uses. +- `secret_id_ttl` `(string: "")` - Duration in either an integer number of + seconds (`3600`) or an integer time unit (`60m`) after which any SecretID + expires. +- `token_num_uses` `(integer: 0)` - Number of times issued tokens can be used. + A value of 0 means unlimited uses. +- `token_ttl` `(string: "")` - Duration in either an integer number of seconds + (`3600`) or an integer time unit (`60m`) to set as the TTL for issued tokens + and at renewal time. +- `token_max_ttl` `(string: "")` - Duration in either an integer number of + seconds (`3600`) or an integer time unit (`60m`) after which the issued token + can no longer be renewed. +- `period` `(string: "")` - Duration in either an integer number of seconds + (`3600`) or an integer time unit (`60m`). If set, the token generated using + this AppRole is a _periodic_ token; so long as it is renewed it never expires, + but the TTL set on the token at each renewal is fixed to the value specified + here. If this value is modified, the token will pick up the new value at its + next renewal. + +### Sample Payload + +```json +{ + "token_ttl": "10m", + "token_max_ttl": "15m", + "policies": [ + "default" + ], + "period": 0, + "bind_secret_id": true +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/approle/role/application1 +``` + +## Read AppRole + +Reads the properties of an existing AppRole. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/approle/role/:role_name` | `200 application/json` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/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, + "policies": [ + "default" + ], + "period": 0, + "bind_secret_id": true, + "bound_cidr_list": "" + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Delete AppRole + +Deletes an existing AppRole from the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/approle/role/:role_name` | `204 (empty body)` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/approle/role/application1 +``` + +## Read AppRole Role ID + +Reads the RoleID of an existing AppRole. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/approle/role/:role_name/role-id` | `200 application/json` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/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 | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/approle/role/:role_name/role-id` | `204 (empty body)` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. +- `role_id` `(string: )` - Value to be set as RoleID. + +### Sample Payload + +```json +{ + "role_id": "custom-role-id" +} + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/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 | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/approle/role/:role_name/secret-id` | `200 application/json` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. +- `metadata` `(map: {})` - 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` `(string: "")` - Comma separated list of CIDR blocks enforcing + secret IDs to be used from ppecific set of IP addresses. If 'bound_cidr_list' + 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. + +### Sample Payload + +```json +{ + "metadata": { + "tag1": "production" + } +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/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" + }, + "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 | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/approle/role/:role_name/secret-id` | `200 application/json` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/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 | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/approle/role/:role_name/secret-id/lookup` | `200 application/json` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. +- `secret_id` `(string: )` - Secret ID attached to the role. + +### Sample Payload + +```json +{ + "secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --payload @payload.json \ + https://vault.rocks/v1/auth/approle/role/application1/secret-id/lookup +``` + +## Destroy AppRole Secret ID + +Destroy an AppRole secret ID. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/approle/role/:role_name/secret-id/destroy` | `204 (empty body)` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. +- `secret_id` `(string: )` - Secret ID attached to the role. + +### Sample Payload + +```json +{ + "secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --payload @payload.json \ + https://vault.rocks/v1/auth/approle/role/application1/secret-id/destroy +``` + +## Read AppRole Secret ID Accessor + +Reads out the properties of a SecretID. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/approle/role/:role_name/secret-id-accessor/lookup` | `200 application/json` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. +- `secret_id_accessor` `(string: )` - Secret ID accessor attached to the role. + +### Sample Payload + +```json +{ + "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --payload @payload.json \ + https://vault.rocks/v1/auth/approle/role/application1/secret-id-accessor/lookup +``` + +## Destroy AppRole Secret ID Accessor + +Destroy an AppRole secret ID by its accessor. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/approle/role/:role_name/secret-id-accessor/destroy` | `204 (empty body)` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. +- `secret_id_accessor` `(string: )` - Secret ID accessor attached to the role. + +### Sample Payload + +```json +{ + "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --payload @payload.json \ + https://vault.rocks/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 | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/approle/role/:role_name/custom-secret-id` | `200 application/json` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. +- `secret_id` `(string: )` - SecretID to be attached to the Role. +- `metadata` `(map: {})` - 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` `(string: "")` - Comma separated list of CIDR blocks enforcing + secret IDs to be used from ppecific set of IP addresses. If 'bound_cidr_list' + 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. + +### Sample Payload + +```json +{ + "secret-id": "testsecretid" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/approle/role/application1/custom-secret-id +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780", + "secret_id": "testsecretid" + }, + "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 | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/approle/login` | `200 application/json` | + +### Parameters + +- `role_id` `(string: )` - RoleID of the AppRole. +- `secret_id` `(string: )` - SecretID belonging to AppRole. + +### Sample Payload + +```json +{ + "role_id": "59d6d1ca-47bb-4e7e-a40b-8be3bc5a0ba8", + "secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/approle/login +``` + +### Sample Response + +```json +{ + "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": "" +} +``` + +## 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 | Produces | +| :------- | :--------------------------- | :--------------------- | +| `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/bound-cidr-list` | `200/204` | +| `GET/POST/DELETE` | `/auth/approle/role/:role_name/period` | `200/204` | + +Refer to `/auth/approle/role/:role_name` endpoint. \ No newline at end of file diff --git a/website/source/api/auth/aws/index.html.md b/website/source/api/auth/aws/index.html.md new file mode 100644 index 000000000000..f998d21f0740 --- /dev/null +++ b/website/source/api/auth/aws/index.html.md @@ -0,0 +1,1254 @@ +--- +layout: "api" +page_title: "AWS Auth Backend - HTTP API" +sidebar_current: "docs-http-auth-aws" +description: |- + This is the API documentation for the Vault AWS authentication backend. +--- + +# AWS Auth Backend HTTP API + +This is the API documentation for the Vault AWS authentication backend. For +general information about the usage and operation of the AWS backend, please +see the [Vault AWS backend documentation](/docs/auth/aws.html). + +This documentation assumes the AWS backend is mounted at the `/auth/aws` +path in Vault. Since it is possible to mount auth backends at any location, +please update your API calls accordingly. + +## Configure Client + +Configures the credentials required to perform API calls to AWS as well as +custom endpoints to talk to AWS APIs. The instance identity document +fetched from the PKCS#7 signature will provide the EC2 instance ID. The +credentials configured using this endpoint will be used to query the status +of the instances via DescribeInstances API. If static credentials are not +provided using this endpoint, then the credentials will be retrieved from +the environment variables `AWS_ACCESS_KEY`, `AWS_SECRET_KEY` and +`AWS_REGION` respectively. If the credentials are still not found and if the +backend is configured on an EC2 instance with metadata querying +capabilities, the credentials are fetched automatically. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/aws/config/client` | `204 (empty body)` | + +### Parameters + +- `access_key` `(string: "")` - AWS Access key with permissions to query AWS + APIs. The permissions required depend on the specific configurations. If using + the `iam` auth method without inferencing, then no credentials are necessary. + If using the `ec2` auth method or using the `iam` auth method with + inferencing, then these credentials need access to `ec2:DescribeInstances`. If + additionally a `bound_iam_role` is specified, then these credentials also need + access to `iam:GetInstanceProfile`. If, however, an alternate sts + configuration is set for the target account, then the credentials must be + permissioned to call `sts:AssumeRole` on the configured role, and that role + must have the permissions described here. +- `secret_key` `(string: "")` - AWS Secret key with permissions to query AWS + APIs. +- `endpoint` `(string: "")` - URL to override the default generated endpoint for + making AWS EC2 API calls. +- `iam_endpoint` `(string: "")` - URL to override the default generated endpoint + for making AWS IAM API calls. +- `sts_endpoint` `(string: "")` - URL to override the default generated endpoint + for making AWS STS API calls. +- `iam_server_id_header_value` `(string: "")` - The value to require in the + `X-Vault-AWS-IAM-Server-ID` header as part of GetCallerIdentity requests that + are used in the iam auth method. If not set, then no value is required or + validated. If set, clients must include an X-Vault-AWS-IAM-Server-ID header in + the headers of login requests, and further this header must be among the + signed headers validated by AWS. This is to protect against different types of + replay attacks, for example a signed request sent to a dev server being resent + to a production server. Consider setting this to the Vault server's DNS name. + +### Sample Payload + +```json +{ + "access_key": "VKIAJBRHKH6EVTTNXDHA", + "secret_key": "vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/aws/config/client +``` + +## Read Config + +Returns the previously configured AWS access credentials. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/aws/config/client` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/aws/config/client +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "secret_key": "vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj", + "access_key": "VKIAJBRHKH6EVTTNXDHA" + "endpoint" "", + "iam_endpoint" "", + "sts_endpoint" "", + "iam_server_id_header_value" "", + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Delete Config + +Deletes the previously configured AWS access credentials. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/aws/config/client` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/aws/config/client +``` + +## Create Certificate Configuration + +Registers an AWS public key to be used to verify the instance identity +documents. While the PKCS#7 signature of the identity documents have DSA +digest, the identity signature will have RSA digest, and hence the public +keys for each type varies respectively. Indicate the type of the public key +using the "type" parameter. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/aws/config/certificate/:cert_name` | `204 (empty body)` | + +### Parameters + +- `cert_name` `(string: )` - Name of the certificate. +- `aws_public_cert` `(string: )` - AWS Public key required to verify + PKCS7 signature of the EC2 instance metadata. +- `type` `(string: "pkcs7")` - Takes the value of either "pkcs7" or "identity", + indicating the type of document which can be verified using the given + certificate. The PKCS#7 document will have a DSA digest and the identity + signature will have an RSA signature, and accordingly the public certificates + to verify those also vary. Defaults to "pkcs7". + +### Sample Payload + +```json +{ + "aws_public_cert": "-----BEGIN CERTIFICATE-----\nMIIC7TCCAq0CCQCWukjZ5V4aZzAJBgcqhkjOOAQDMFwxCzAJBgNVBAYTAlVTMRkw\nFwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYD\nVQQKExdBbWF6b24gV2ViIFNlcnZpY2VzIExMQzAeFw0xMjAxMDUxMjU2MTJaFw0z\nODAxMDUxMjU2MTJaMFwxCzAJBgNVBAYTAlVTMRkwFwYDVQQIExBXYXNoaW5ndG9u\nIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6b24gV2ViIFNl\ncnZpY2VzIExMQzCCAbcwggEsBgcqhkjOOAQBMIIBHwKBgQCjkvcS2bb1VQ4yt/5e\nih5OO6kK/n1Lzllr7D8ZwtQP8fOEpp5E2ng+D6Ud1Z1gYipr58Kj3nssSNpI6bX3\nVyIQzK7wLclnd/YozqNNmgIyZecN7EglK9ITHJLP+x8FtUpt3QbyYXJdmVMegN6P\nhviYt5JH/nYl4hh3Pa1HJdskgQIVALVJ3ER11+Ko4tP6nwvHwh6+ERYRAoGBAI1j\nk+tkqMVHuAFcvAGKocTgsjJem6/5qomzJuKDmbJNu9Qxw3rAotXau8Qe+MBcJl/U\nhhy1KHVpCGl9fueQ2s6IL0CaO/buycU1CiYQk40KNHCcHfNiZbdlx1E9rpUp7bnF\nlRa2v1ntMX3caRVDdbtPEWmdxSCYsYFDk4mZrOLBA4GEAAKBgEbmeve5f8LIE/Gf\nMNmP9CM5eovQOGx5ho8WqD+aTebs+k2tn92BBPqeZqpWRa5P/+jrdKml1qx4llHW\nMXrs3IgIb6+hUIB+S8dz8/mmO0bpr76RoZVCXYab2CZedFut7qc3WUH9+EUAH5mw\nvSeDCOUMYQR7R9LINYwouHIziqQYMAkGByqGSM44BAMDLwAwLAIUWXBlk40xTwSw\n7HX32MxXYruse9ACFBNGmdX2ZBrVNGrN9N2f6ROk0k9K\n-----END CERTIFICATE-----\n" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/aws/config/certificate/test-cert +``` + +## Read Certificate Configuration + +Returns the previously configured AWS public key. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/aws/config/certificate/:cert_name` | `200 application/json` | + +### Parameters + +- `cert_name` `(string: )` - Name of the certificate. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/aws/config/certificate/test-cert +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "aws_public_cert": "-----BEGIN CERTIFICATE-----\nMIIC7TCCAq0CCQCWukjZ5V4aZzAJBgcqhkjOOAQDMFwxCzAJBgNVBAYTAlVTMRkw\nFwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYD\nVQQKExdBbWF6b24gV2ViIFNlcnZpY2VzIExMQzAeFw0xMjAxMDUxMjU2MTJaFw0z\nODAxMDUxMjU2MTJaMFwxCzAJBgNVBAYTAlVTMRkwFwYDVQQIExBXYXNoaW5ndG9u\nIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6b24gV2ViIFNl\ncnZpY2VzIExMQzCCAbcwggEsBgcqhkjOOAQBMIIBHwKBgQCjkvcS2bb1VQ4yt/5e\nih5OO6kK/n1Lzllr7D8ZwtQP8fOEpp5E2ng+D6Ud1Z1gYipr58Kj3nssSNpI6bX3\nVyIQzK7wLclnd/YozqNNmgIyZecN7EglK9ITHJLP+x8FtUpt3QbyYXJdmVMegN6P\nhviYt5JH/nYl4hh3Pa1HJdskgQIVALVJ3ER11+Ko4tP6nwvHwh6+ERYRAoGBAI1j\nk+tkqMVHuAFcvAGKocTgsjJem6/5qomzJuKDmbJNu9Qxw3rAotXau8Qe+MBcJl/U\nhhy1KHVpCGl9fueQ2s6IL0CaO/buycU1CiYQk40KNHCcHfNiZbdlx1E9rpUp7bnF\nlRa2v1ntMX3caRVDdbtPEWmdxSCYsYFDk4mZrOLBA4GEAAKBgEbmeve5f8LIE/Gf\nMNmP9CM5eovQOGx5ho8WqD+aTebs+k2tn92BBPqeZqpWRa5P/+jrdKml1qx4llHW\nMXrs3IgIb6+hUIB+S8dz8/mmO0bpr76RoZVCXYab2CZedFut7qc3WUH9+EUAH5mw\nvSeDCOUMYQR7R9LINYwouHIziqQYMAkGByqGSM44BAMDLwAwLAIUWXBlk40xTwSw\n7HX32MxXYruse9ACFBNGmdX2ZBrVNGrN9N2f6ROk0k9K\n-----END CERTIFICATE-----\n" + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## List Certificate Configurations + +Lists all the AWS public certificates that are registered with the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/aws/config/certificates` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/auth/aws/config/certificates +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": [ + "cert1" + ] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Create STS Role + +Allows the explicit association of STS roles to satellite AWS accounts +(i.e. those which are not the account in which the Vault server is +running.) Login attempts from EC2 instances running in these accounts will +be verified using credentials obtained by assumption of these STS roles. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/aws/config/sts/:account_id` | `204 (empty body)` | + +### Parameters + +- `account_id` `(string: )` - AWS account ID to be associated with + STS role. If set, Vault will use assumed credentials to verify any login + attempts from EC2 instances in this account. +- `sts_role` `(string: )` - AWS ARN for STS role to be assumed when + interacting with the account specified. The Vault server must have + permissions to assume this role. + +### Sample Payload + +```json +{ + "sts_role": "arn:aws:iam:111122223333:role/myRole" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/aws/config/sts/111122223333 +``` + +## Read STS Role + +Returns the previously configured STS role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/aws/config/sts/:account_id` | `200 application/json` | + +### Parameters + +- `account_id` `(string: )` - AWS account ID to be associated with + STS role. If set, Vault will use assumed credentials to verify any login + attempts from EC2 instances in this account. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/aws/config/sts/111122223333 +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "sts_role ": "arn:aws:iam:111122223333:role/myRole" + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## List STS Roles + +Lists all the AWS Account IDs for which an STS role is registered. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/aws/config/sts` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/auth/aws/config/sts +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "keys": [ + "111122223333", + "999988887777" + ] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Delete STS Role + +Deletes a previously configured AWS account/STS role association. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/aws/config/sts` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/aws/config/sts +``` + +## Configure Identity Whitelist Tidy Operation + +Configures the periodic tidying operation of the whitelisted identity entries. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/aws/config/tidy/identity-whitelist` | `204 (empty body)` | + +### Parameters + +- `safety_buffer` `(string: "72h")` - The amount of extra time that must have + passed beyond the `roletag` expiration, before it is removed from the backend + storage. Defaults to 72h. +- `disable_periodic_tidy` `(bool: false)` - If set to 'true', disables the + periodic tidying of the `identity-whitelist/` entries. + +### Sample Payload + +```json +{ + "safety_buffer": "48h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/aws/config/tidy/identity-whitelist +``` + +## Read Identity Whitelist Tidy Settings + +Returns the previously configured periodic whitelist tidying settings. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/aws/config/tidy/identity-whitelist` | `200 applicaiton/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/aws/config/tidy/identity-whitelist +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "safety_buffer": 600, + "disable_periodic_tidy": false + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Delete Identity Whitelist Tidy Settings + +Deletes the previously configured periodic whitelist tidying settings. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/aws/config/tidy/identity-whitelist` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/aws/config/tidy/identity-whitelist +``` + +## Configure Role Tag Blacklist Tidy Operation + +Configures the periodic tidying operation of the blacklisted role tag entries. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/aws/config/tidy/roletag-blacklist` | `204 (empty body)` | + +### Parameters + +- `safety_buffer` `(string: "72h")` - The amount of extra time that must have + passed beyond the `roletag` expiration, before it is removed from the backend + storage. Defaults to 72h. +- `disable_periodic_tidy` `(bool: false)` - If set to 'true', disables the + periodic tidying of the `roletag-blacklist/` entries. + +### Sample Payload + +```json +{ + "safety_buffer": "48h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/aws/config/tidy/roletag-blacklist +``` + +## Read Role Tag Blackist Tidy Settings + +Returns the previously configured periodic blacklist tidying settings. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/aws/config/tidy/roletag-blacklist` | `200 applicaiton/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/aws/config/tidy/roletag-blacklist +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "safety_buffer": 600, + "disable_periodic_tidy": false + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Delete Role Tag Blackist Tidy Settings + +Deletes the previously configured periodic blacklist tidying settings. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/aws/config/tidy/roletag-blacklist` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/aws/config/tidy/roletag-blacklist +``` + +## Create Role + +Registers a role in the backend. Only those instances or principals which +are using the role registered using this endpoint, will be able to perform +the login operation. Contraints can be specified on the role, that are +applied on the instances or principals attempting to login. At least one +constraint should be specified on the role. The available constraints you +can choose are dependent on the `auth_type` of the role and, if the +`auth_type` is `iam`, then whether inferencing is enabled. A role will not +let you configure a constraint if it is not checked by the `auth_type` and +inferencing configuration of that role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/aws/role/:role` | `204 (empty body)` | + +### Parameters + +- `role` `(string: )` - Name of the role. +- `auth_type` `(string: "iam")` - The auth type permitted for this role. Valid + choices are "ec2" or "iam". If no value is specified, then it will default to + "iam" (except for legacy `aws-ec2` auth types, for which it will default to + "ec2"). Only those bindings applicable to the auth type chosen will be allowed + to be configured on the role. +- `bound_ami_id` `(string: "")` - If set, defines a constraint on the EC2 + instances that they should be using the AMI ID specified by this parameter. + This constraint is checked during ec2 auth as well as the iam auth method only + when inferring an EC2 instance. +- `bound_account_id` `(string: "")` - If set, defines a constraint on the EC2 + instances that the account ID in its identity document to match the one + specified by this parameter. This constraint is checked during ec2 auth as + well as the iam auth method only when inferring an EC2 instance. +- `bound_region` `(string: "")` - If set, defines a constraint on the EC2 + instances that the region in its identity document must match the one + specified by this parameter. This constraint is only checked by the ec2 auth + method as well as the iam auth method only when inferring an ec2 instance. +- `bound_vpc_id` `(string: "")` - If set, defines a constraint on the EC2 + instance to be associated with the VPC ID that matches the value specified by + this parameter. This constraint is only checked by the ec2 auth method as well + as the iam auth method only when inferring an ec2 instance. +- `bound_subnet_id` `(string: "")` - If set, defines a constraint on the EC2 + instance to be associated with the subnet ID that matches the value specified + by this parameter. This constraint is only checked by the ec2 auth method as + well as the iam auth method only when inferring an ec2 instance. +- `bound_iam_role_arn` `(string: "")` - If set, defines a constraint on the + authenticating EC2 instance that it must match the IAM role ARN specified by + this parameter. The value is refix-matched (as though it were a glob ending + in `*`). The configured IAM user or EC2 instance role must be allowed to + execute the `iam:GetInstanceProfile` action if this is specified. This + constraint is checked by the ec2 auth method as well as the iam auth method + only when inferring an EC2 instance. +- `bound_iam_instance_profile_arn` `(string: "")` - If set, defines a constraint + on the EC2 instances to be associated with an IAM instance profile ARN which + has a prefix that matches the value specified by this parameter. The value is + prefix-matched (as though it were a glob ending in `*`). This constraint is + checked by the ec2 auth method as well as the iam auth method only when + inferring an ec2 instance. +- `role_tag` `(string: "")` - If set, enables the role tags for this role. The + value set for this field should be the 'key' of the tag on the EC2 instance. + The 'value' of the tag should be generated using `role//tag` endpoint. + Defaults to an empty string, meaning that role tags are disabled. This + constraint is valid only with the ec2 auth method and is not allowed when an + auth_type is iam. +- `bound_iam_principal_arn` `(string: "")` - Defines the IAM principal that must + be authenticated using the iam auth method. It should look like + "arn:aws:iam::123456789012:user/MyUserName" or + "arn:aws:iam::123456789012:role/MyRoleName". This constraint is only checked + by the iam auth method. +- `inferred_entity_type` `(string: "")` - When set, instructs Vault to turn on + inferencing. The only current valid value is "ec2_instance" instructing Vault + to infer that the role comes from an EC2 instance in an IAM instance profile. + This only applies to the iam auth method. If you set this on an existing role + where it had not previously been set, tokens that had been created prior will + not be renewable; clients will need to get a new token. +- `inferred_aws_region` `(string: "")` - When role inferencing is activated, the + region to search for the inferred entities (e.g., EC2 instances). Required if + role inferencing is activated. This only applies to the iam auth method. +- `resolve_aws_unique_ids` `(bool: false)` - When set, resolves the + `bound_iam_principal_arn` to the [AWS Unique ID](http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-unique-ids). + This requires Vault to be able to call `iam:GetUser` or `iam:GetRole` on the + `bound_iam_principal_arn` that is being bound. Resolving to internal AWS IDs + more closely mimics the behavior of AWS services in that if an IAM user or + role is deleted and a new one is recreated with the same name, those new users + or roles won't get access to roles in Vault that were permissioned to the + prior principals of the same name. The default value for new roles is true, + while the default value for roles that existed prior to this option existing + is false (you can check the value for a given role using the GET method on the + role). Any authentication tokens created prior to this being supported won't + verify the unique ID upon token renewal. When this is changed from false to + true on an existing role, Vault will attempt to resolve the role's bound IAM + ARN to the unique ID and, if unable to do so, will fail to enable this option. + Changing this from `true` to `false` is not supported; if absolutely + necessary, you would need to delete the role and recreate it explicitly + setting it to `false`. However; the instances in which you would want to do + this should be rare. If the role creation (or upgrading to use this) succeed, + then Vault has already been able to resolve internal IDs, and it doesn't need + any further IAM permissions to authenticate users. If a role has been deleted + and recreated, and Vault has cached the old unique ID, you should just call + this endpoint specifying the same `bound_iam_principal_arn` and, as long as + Vault still has the necessary IAM permissions to resolve the unique ID, Vault + will update the unique ID. (If it does not have the necessary permissions to + resolve the unique ID, then it will fail to update.) If this option is set to + false, then you MUST leave out the path component in bound_iam_principal_arn + for **roles** only, but not IAM users. That is, if your IAM role ARN is of the + form `arn:aws:iam::123456789012:role/some/path/to/MyRoleName`, you **must** + specify a bound_iam_principal_arn of + `arn:aws:iam::123456789012:role/MyRoleName` for authentication to work. +- `ttl` `(string: "")` - The TTL period of tokens issued using this role, + provided as "1h", where hour is the largest suffix. +- `max_ttl` `(string: "")` - The maximum allowed lifetime of tokens issued using + this role. +- `period` `(string: "")` - 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. At each renewal, the token's TTL will be set to the + value of this parameter. The maximum allowed lifetime of tokens issued using + this role. +- `policies` `(array: [])` - Policies to be set on tokens issued using this + role. +- `allow_instance_migration` `(bool: false)` - If set, allows migration of the + underlying instance where the client resides. This keys off of pendingTime in + the metadata document, so essentially, this disables the client nonce check + whenever the instance is migrated to a new host and pendingTime is newer than + the previously-remembered time. Use with caution. This only applies to + authentications via the ec2 auth method. +- `disallow_reauthentication` `(bool: false)` - If set, only allows a single + token to be granted per instance ID. In order to perform a fresh login, the + entry in whitelist for the instance ID needs to be cleared using + 'auth/aws/identity-whitelist/' endpoint. Defaults to 'false'. + This only applies to authentications via the ec2 auth method. + +### Sample Payload + +```json +{ + "bound_ami_id": "ami-fce36987", + "role_tag": "", + "policies": [ + "default", + "dev", + "prod" + ], + "max_ttl": 1800000, + "disallow_reauthentication": false, + "allow_instance_migration": false +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/aws/role/dev-role +``` + +## Read Role + +Returns the previously registered role configuration. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/aws/role/:role` | `200 application/json` | + +### Parameters + +- `role` `(string: )` - Name of the role. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/aws/role/dev-role +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "bound_ami_id": "ami-fce36987", + "role_tag": "", + "policies": [ + "default", + "dev", + "prod" + ], + "max_ttl": 1800000, + "disallow_reauthentication": false, + "allow_instance_migration": false + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## List Roles + +Lists all the roles that are registered with the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/aws/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/auth/aws/roles +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "keys": [ + "dev-role", + "prod-role" + ] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Delete Role + +Deletes the previously registered role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/aws/role/:role` | `204 (empty body)` | + +### Parameters + +- `role` `(string: )` - Name of the role. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/aws/role/dev-role +``` + +## Create Role Tags + +Creates a role tag on the role, which help in restricting the capabilities +that are set on the role. Role tags are not tied to any specific ec2 +instance unless specified explicitly using the `instance_id` parameter. By +default, role tags are designed to be used across all instances that +satisfies the constraints on the role. Regardless of which instances have +role tags on them, capabilities defined in a role tag must be a strict +subset of the given role's capabilities. Note that, since adding and +removing a tag is often a widely distributed privilege, care needs to be +taken to ensure that the instances are attached with correct tags to not +let them gain more privileges than what were intended. If a role tag is +changed, the capabilities inherited by the instance will be those defined +on the new role tag. Since those must be a subset of the role +capabilities, the role should never provide more capabilities than any +given instance can be allowed to gain in a worst-case scenario. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/aws/role/:role/tag` | `200 application/json` | + +### Parameters + +- `role` `(string: )` - Name of the role. +- `policies` `(array: [])` - Policies to be associated with the tag. If set, + must be a subset of the role's policies. If set, but set to an empty value, + only the 'default' policy will be given to issued tokens. +- `max_ttl` `(string: "")` - The maximum allowed lifetime of tokens issued using + this role. +- `instance_id` `(string: "")` - Instance ID for which this tag is intended for. + If set, the created tag can only be used by the instance with the given ID. +- `allow_instance_migration` `(bool: false)` - If set, allows migration of the + underlying instance where the client resides. This keys off of pendingTime in + the metadata document, so essentially, this disables the client nonce check + whenever the instance is migrated to a new host and pendingTime is newer than + the previously-remembered time. Use with caution. Defaults to 'false'. +- `disallow_reauthentication` `(bool: false)` - If set, only allows a single + token to be granted per instance ID. This can be cleared with the + auth/aws/identity-whitelist endpoint. Defaults to 'false'. + +### Sample Payload + +```json +{ + "policies": ["default", "prod"] +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/aws/role/dev-role/tag +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "tag_value": "v1:09Vp0qGuyB8=:r=dev-role:p=default,prod:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/pJIdVyOI=", + "tag_key": "VaultRole" + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Login + +Fetch a token. This endpoint verifies the pkcs7 signature of the instance +identity document or the signature of the signed GetCallerIdentity request. +With the ec2 auth method, or when inferring an EC2 instance, verifies that +the instance is actually in a running state. Cross checks the constraints +defined on the role with which the login is being performed. With the ec2 +auth method, as an alternative to pkcs7 signature, the identity document +along with its RSA digest can be supplied to this endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/aws/login` | `200 application/json` | + +### Sample Payload + +- `role` `(string: "")` - Name of the role against which the login is being + attempted. If `role` is not specified, then the login endpoint looks for a + role bearing the name of the AMI ID of the EC2 instance that is trying to + login if using the ec2 auth method, or the "friendly name" (i.e., role name or + username) of the IAM principal authenticated. If a matching role is not found, + login fails. +- `identity` `(string: )` - Base64 encoded EC2 instance identity + document. This needs to be supplied along with the `signature` parameter. If + using `curl` for fetching the identity document, consider using the option + `-w 0` while piping the output to `base64` binary. +- `signature` `(string: )` - Base64 encoded SHA256 RSA signature of + the instance identity document. This needs to be supplied along with + `identity` parameter when using the ec2 auth method. +- `pkcs7` `(string: )` - PKCS7 signature of the identity document with + all `\n` characters removed. Either this needs to be set *OR* both `identity` + and `signature` need to be set when using the ec2 auth method. +- `nonce` `(string: "")` - The nonce to be used for subsequent login requests. + If this parameter is not specified at all and if reauthentication is allowed, + then the backend will generate a random nonce, attaches it to the instance's + identity-whitelist entry and returns the nonce back as part of auth metadata. + This value should be used with further login requests, to establish client + authenticity. Clients can choose to set a custom nonce if preferred, in which + case, it is recommended that clients provide a strong nonce. If a nonce is + provided but with an empty value, it indicates intent to disable + reauthentication. Note that, when `disallow_reauthentication` option is + enabled on either the role or the role tag, the `nonce` holds no significance. + This is ignored unless using the ec2 auth method. +- `iam_http_request_method` `(string: )` - HTTP method used in the + signed request. Currently only POST is supported, but other methods may be + supported in the future. This is required when using the iam auth method. +- `iam_request_url` `(string: )` - Base64-encoded HTTP URL used in + the signed request. Most likely just `aHR0cHM6Ly9zdHMuYW1hem9uYXdzLmNvbS8=` + (base64-encoding of `https://sts.amazonaws.com/`) as most requests will + probably use POST with an empty URI. This is required when using the iam auth + method. +- `iam_request_body` `(string: )` - Base64-encoded body of the + signed request. Most likely + `QWN0aW9uPUdldENhbGxlcklkZW50aXR5JlZlcnNpb249MjAxMS0wNi0xNQ==` which is the + base64 encoding of `Action=GetCallerIdentity&Version=2011-06-15`. This is + required when using the iam auth method. +- `iam_request_headers` `(string: )` - Base64-encoded, + JSON-serialized representation of the sts:GetCallerIdentity HTTP request + headers. The JSON serialization assumes that each header key maps to either a + string value or an array of string values (though the length of that array + will probably only be one). If the `iam_server_id_header_value` is configured + in Vault for the aws auth mount, then the headers must include the + X-Vault-AWS-IAM-Server-ID header, its value must match the value configured, + and the header must be included in the signed headers. This is required when + using the iam auth method. + + +### Sample Payload + +```json +{} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/aws/login +``` + +### Sample Response + +```json +{ + "auth": { + "renewable": true, + "lease_duration": 1800000, + "metadata": { + "role_tag_max_ttl": "0", + "instance_id": "i-de0f1344" + "ami_id": "ami-fce36983" + "role": "dev-role", + "auth_type": "ec2" + }, + "policies": [ + "default", + "dev", + ], + "accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e", + "client_token": "c9368254-3f21-aded-8a6f-7c818e81b17a" + }, + "warnings": null, + "data": null, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Place Role Tags in Blacklist + +Places a valid role tag in a blacklist. This ensures that the role tag +cannot be used by any instance to perform a login operation again. Note +that if the role tag was previously used to perform a successful login, +placing the tag in the blacklist does not invalidate the already issued +token. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/aws/roletag-blacklist/:role_tag` | `204 (empty body)` | + +### Parameters + +- `role_tag` `(string: )` - Role tag to be blacklisted. The tag can be + supplied as-is. In order to avoid any encoding problems, it can be base64 + encoded. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/auth/aws/roletag-blacklist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo= +``` + +### Read Role Tag Blacklist Information + +Returns the blacklist entry of a previously blacklisted role tag. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/aws/roletag-blacklist/:role_tag` | `200 application/json` | + +### Parameters + +- `role_tag` `(string: )` - Role tag to be blacklisted. The tag can be + supplied as-is. In order to avoid any encoding problems, it can be base64 + encoded. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/aws/roletag-blacklist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo= +``` + + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "expiration_time": "2016-04-25T10:35:20.127058773-04:00", + "creation_time": "2016-04-12T22:35:01.178348124-04:00" + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## List Blacklist Tags + +Lists all the role tags that are blacklisted. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/aws/roletag-blacklist` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/auth/aws/roletag-blacklist +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "keys": [ + "v1:09Vp0qGuyB8=:a=ami-fce3c696:p=default,prod:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/" + ] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Delete Blacklist Tags + +Deletes a blacklisted role tag. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/aws/roletag-blacklist/:role_tag` | `204 (empty body)` | + +### Parameters + +- `role_tag` `(string: )` - Role tag to be blacklisted. The tag can be + supplied as-is. In order to avoid any encoding problems, it can be base64 + encoded. + + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/aws/roletag-blacklist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo= +``` + +## Tidy Blacklist Tags + +Cleans up the entries in the blacklist based on expiration time on the entry and +`safety_buffer`. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/aws/tidy/roletag-blacklist` | `204 (empty body)` | + +### Parameters + +- `safety_buffer` `(string: "72h")` - The amount of extra time that must have + passed beyond the `roletag` expiration, before it is removed from the backend + storage. Defaults to 72h. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/auth/aws/tidy/roletag-blacklist +``` + +### Read Identity Whitelist Information + +Returns an entry in the whitelist. An entry will be created/updated by every +successful login. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/aws/identity-whitelist/:instance_id` | `200 application/json` | + +### Parameters + +- `instance_id` `(string: )` - EC2 instance ID. A successful login + operation from an EC2 instance gets cached in this whitelist, keyed off of + instance ID. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/aws/identity-whitelist/i-aab47d37 +``` + + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "pending_time": "2016-04-14T01:01:41Z", + "expiration_time": "2016-05-05 10:09:16.67077232 +0000 UTC", + "creation_time": "2016-04-14 14:09:16.67077232 +0000 UTC", + "client_nonce": "5defbf9e-a8f9-3063-bdfc-54b7a42a1f95", + "role": "dev-role" + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## List Identity Whitelist Entries + + Lists all the instance IDs that are in the whitelist of successful logins. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/aws/identity-whitelist` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/auth/aws/roletag-blacklist +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "data": { + "keys": [ + "i-aab47d37" + ] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Delete Identity Whitelist Entries + +Deletes a cache of the successful login from an instance. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/aws/identity-whitelist/:instance_id` | `204 (empty body)` | + +### Parameters + +- `instance_id` `(string: )` - EC2 instance ID. A successful login + operation from an EC2 instance gets cached in this whitelist, keyed off of + instance ID. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/aws/identity-whitelist/i-aab47d37 +``` + +## Tidy Identity Whitelist Entries + +Cleans up the entries in the whitelist based on expiration time and +`safety_buffer`. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/aws/tidy/identity-whitelist` | `204 (empty body)` | + +### Parameters + +- `safety_buffer` `(string: "72h")` - The amount of extra time that must have + passed beyond the `roletag` expiration, before it is removed from the backend + storage. Defaults to 72h. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/auth/aws/tidy/identity-whitelist +``` \ No newline at end of file diff --git a/website/source/api/auth/cert/index.html.md b/website/source/api/auth/cert/index.html.md new file mode 100644 index 000000000000..9182b94bafa5 --- /dev/null +++ b/website/source/api/auth/cert/index.html.md @@ -0,0 +1,329 @@ +--- +layout: "api" +page_title: "TLS Certificate Auth Backend - HTTP API" +sidebar_current: "docs-http-auth-cert" +description: |- + This is the API documentation for the Vault TLS Certificate authentication + backend. +--- + +# TLS Certificate Auth Backend HTTP API + +This is the API documentation for the Vault TLS Certificate authentication +backend. For general information about the usage and operation of the TLS +Certificate backend, please see the [Vault TLS Certificate backend documentation](/docs/auth/cert.html). + +This documentation assumes the TLS Certificate backend is mounted at the +`/auth/cert` path in Vault. Since it is possible to mount auth backends at any +location, please update your API calls accordingly. + +## Create CA Certificate Role + +Sets a CA cert and associated parameters in a role name. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/cert/certs/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` - The name of the certificate role. +- `certificate` `(string: )` - The PEM-format CA certificate. +- `allowed_names` `(string: "")` - Constrain the Common and Alternative Names in + the client certificate with a [globbed pattern] + (https://github.com/ryanuber/go-glob/blob/master/README.md#example). Value is + a comma-separated list of patterns. Authentication requires at least one Name matching at least one pattern. If not set, defaults to allowing all names. +- `policies` `(string: "")` - A comma-separated list of policies to set on tokens + issued when authenticating against this CA certificate. +- `display_name` `(string: "")` - The `display_name` to set on tokens issued + when authenticating against this CA certificate. If not set, defaults to the + name of the role. +- `ttl` `(string: "")` - The TTL period of the token, provided as a number of + seconds. If not provided, the token is valid for the the mount or system + default TTL time, in that order. + +### Sample Payload + +```json +{ + "certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----", + "display_name": "test" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json + https://vault.rocks/v1/auth/cert/certs/test-ca +``` + +## Read CA Certificate Role + +Gets information associated with the named role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/cert/certs/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` - The name of the certificate role. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/cert/certs/test-ca +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----", + "display_name": "test", + "policies": "", + "allowed_names": "", + "ttl": 2764800 + }, + "warnings": null, + "auth": null +} +``` + +## List Certificate Roles + +Lists configured certificate names. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/cert/certs` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/auth/cert/certs + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": [ + "cert1", + "cert2" + ] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Delete Certificate Role + +Deletes the named role and CA cert from the backend mount. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/cert/certs/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` - The name of the certificate role. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/cert/certs/cert1 +``` + +## Create CRL + +Sets a named CRL. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/cert/crls/:name` | `204 (empty body)` | + + +### Parameters + +- `name` `(string: )` - The name of the CRL. +- `crl` `(string: )` - The PEM format CRL. + +### Sample Payload + +```json +{ + "crl": "-----BEGIN X509 CRL-----\n...\n-----END X509 CRL-----" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --date @payload.json \ + https://vault.rocks/v1/auth/cert/crls/custom-crl +``` + +## Read CRL + +Gets information associated with the named CRL (currently, the serial +numbers contained within). As the serials can be integers up to an +arbitrary size, these are returned as strings. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/cert/crls/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` - The name of the CRL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/cert/crls/custom-crl +``` + +### Sample Response + +```json +{ + "auth": null, + "data": { + "serials": { + "13": {} + } + }, + "lease_duration": 0, + "lease_id": "", + "renewable": false, + "warnings": null +} +``` + +## Delete Certificate Role + +Deletes the named role and CA cert from the backend mount. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/cert/crls/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` - The name of the CRL. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/cert/crls/cert1 +``` + +## Configure TLS Certificate Backend + +Configuration options for the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/cert/config` | `204 (empty body)` | + +### Parameters + +- `disable_binding` `(boolean: false)` - If set, during renewal, skips the + matching of presented client identity with the client identity used during + login. + +### Sample Payload + +```json +{ + "disable_binding": true +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --date @payload.json \ + https://vault.rocks/v1/auth/cert/certs/cert1 +``` + +## Login with TLS Certiicate Backend + +Log in and fetch a token. If there is a valid chain to a CA configured in the +backend and all role constraints are matched, a token will be issued. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/cert/login` | `200 application/json` | + +### Parameters + +- `name` `(string: "")` - Authenticate against only the named certificate role, + returning its policy list if successful. If not set, defaults to trying all + certificate roles and returning any one that matches. + +### Sample Payload + +```json +{ + "name": "cert1" +} +``` + +### Sample Request + +``` +$ curl \ + --request POST \ + --date @payload.json \ + https://vault.rocks/v1/auth/cert/login +``` + +### Sample Response + +```json +{ + "auth": { + "client_token": "cf95f87d-f95b-47ff-b1f5-ba7bff850425", + "policies": [ + "web", + "stage" + ], + "lease_duration": 3600, + "renewable": true, + } +} +``` \ No newline at end of file diff --git a/website/source/api/auth/github/index.html.md b/website/source/api/auth/github/index.html.md new file mode 100644 index 000000000000..6cc61878107c --- /dev/null +++ b/website/source/api/auth/github/index.html.md @@ -0,0 +1,17 @@ +--- +layout: "api" +page_title: "Github Auth Backend - HTTP API" +sidebar_current: "docs-http-auth-github" +description: |- + This is the API documentation for the Vault Github authentication backend. +--- + +# Github Auth Backend HTTP API + +This is the API documentation for the Vault Github authentication backend. For +general information about the usage and operation of the Github backend, please +see the [Vault Github backend documentation](/docs/auth/github.html). + +This documentation assumes the Github backend is mounted at the `/auth/github` +path in Vault. Since it is possible to mount auth backends at any location, +please update your API calls accordingly. \ No newline at end of file diff --git a/website/source/api/auth/index.html.md b/website/source/api/auth/index.html.md new file mode 100644 index 000000000000..b89d31c6aca7 --- /dev/null +++ b/website/source/api/auth/index.html.md @@ -0,0 +1,19 @@ +--- +layout: "api" +page_title: "HTTP API" +sidebar_current: "docs-http-auth" +description: |- + Each authentication backend publishes its own set of API paths and methods. + These endpoints are documented in this section. +--- + +# Authentication Backends + +Each authentication backend publishes its own set of API paths and methods. +These endpoints are documented in this section. Authentication backends are +mount at a path, but the documentation will assume the default mount points for +simplicity. If you are mounting at a different path, you should adjust your API +calls accordingly. + +For the API documentation for a specific authentication backend, please choose a +authentication backend from the navigation. diff --git a/website/source/api/auth/ldap/index.html.md b/website/source/api/auth/ldap/index.html.md new file mode 100644 index 000000000000..f263a5e815c2 --- /dev/null +++ b/website/source/api/auth/ldap/index.html.md @@ -0,0 +1,450 @@ +--- +layout: "api" +page_title: "LDAP Auth Backend - HTTP API" +sidebar_current: "docs-http-auth-ldap" +description: |- + This is the API documentation for the Vault LDAP authentication backend. +--- + +# LDAP Auth Backend HTTP API + +This is the API documentation for the Vault LDAP authentication backend. For +general information about the usage and operation of the LDAP backend, please +see the [Vault LDAP backend documentation](/docs/auth/ldap.html). + +This documentation assumes the LDAP backend is mounted at the `/auth/ldap` +path in Vault. Since it is possible to mount auth backends at any location, +please update your API calls accordingly. + +## Configure LDAP Backend + +This endpoint configures the LDAP authentication backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/ldap/config` | `204 (empty body)` | + +### Parameters + +- `url` `(string: )` – The LDAP server to connect to. Examples: + `ldap://ldap.myorg.com`, `ldaps://ldap.myorg.com:636` +- `starttls` `(bool: false)` – If true, issues a `StartTLS` command after + establishing an unencrypted connection. +- `tls_min_version` `(string: tls12)` – Minimum TLS version to use. Accepted + values are `tls10`, `tls11` or `tls12`. +- `tls_max_version` `(string: tls12)` – Maximum TLS version to use. Accepted + values are `tls10`, `tls11` or `tls12`. +- `insecure_tls` `(bool: false)` – If true, skips LDAP server SSL certificate + verification - insecure, use with caution! +- `certificate` `(string: "")` – CA certificate to use when verifying LDAP server + certificate, must be x509 PEM encoded. +- `binddn` `(string: "")` – Distinguished name of object to bind when performing + user search. Example: `cn=vault,ou=Users,dc=example,dc=com` +- `bindpass` `(string: "")` – Password to use along with `binddn` when performing + user search. +- `userdn` `(string: "")` – Base DN under which to perform user search. Example: + `ou=Users,dc=example,dc=com` +- `userattr` `(string: "")` – Attribute on user attribute object matching the + username passed when authenticating. Examples: `sAMAccountName`, `cn`, `uid` +- `discoverdn` `(bool: false)` – Use anonymous bind to discover the bind DN of a + user. +- `deny_null_bind` `(bool: true)` – This option prevents users from bypassing + authentication when providing an empty password. +- `upndomain` `(string: "")` – The userPrincipalDomain used to construct the UPN + string for the authenticating user. The constructed UPN will appear as + `[username]@UPNDomain`. Example: `example.com`, which will cause vault to bind + as `username@example.com`. +- `groupfilter` `(string: "")` – Go template used when constructing the group + membership query. The template can access the following context variables: + \[`UserDN`, `Username`\]. The default is + `(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))`, + which is compatible with several common directory schemas. To support + nested group resolution for Active Directory, instead use the following + query: `(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))`. +- `groupdn` `(string: "")` – LDAP search base to use for group membership + search. This can be the root containing either groups or users. Example: + `ou=Groups,dc=example,dc=com` +- `groupattr` `(string: "")` – LDAP attribute to follow on objects returned by + `groupfilter` in order to enumerate user group membership. Examples: for + groupfilter queries returning _group_ objects, use: `cn`. For queries + returning _user_ objects, use: `memberOf`. The default is `cn`. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/ldap/config +``` + +### Sample Payload + +```json +{ + "binddn": "cn=vault,ou=Users,dc=example,dc=com", + "deny_null_bind": true, + "discoverdn": false, + "groupattr": "cn", + "groupdn": "ou=Groups,dc=example,dc=com", + "groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))", + "insecure_tls": false, + "starttls": false, + "tls_max_version": "tls12", + "tls_min_version": "tls12", + "url": "ldaps://ldap.myorg.com:636", + "userattr": "samaccountname", + "userdn": "ou=Users,dc=example,dc=com" +} +``` + +## Read LDAP Configuration + +This endpoint retrieves the LDAP configuration for the authentication backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/ldap/config` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/ldap/config +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "binddn": "cn=vault,ou=Users,dc=example,dc=com", + "bindpass": "", + "certificate": "", + "deny_null_bind": true, + "discoverdn": false, + "groupattr": "cn", + "groupdn": "ou=Groups,dc=example,dc=com", + "groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))", + "insecure_tls": false, + "starttls": false, + "tls_max_version": "tls12", + "tls_min_version": "tls12", + "upndomain": "", + "url": "ldaps://ldap.myorg.com:636", + "userattr": "samaccountname", + "userdn": "ou=Users,dc=example,dc=com" + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## List LDAP Groups + +This endpoint returns a list of existing groups in the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/ldap/groups` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/auth/ldap/groups +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": [ + "scientists", + "engineers" + ] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Read LDAP Group + +This endpoint returns the policies associated with a LDAP group. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/ldap/groups/:name` | `200 application/json` | + +### Parameters + +- `name` `(string: )` – The name of the LDAP group + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/ldap/groups/admins +``` + +### Sample Response + +```json +{ + "data": { + "policies": "admin,default" + }, + "renewable": false, + "lease_id": "" + "lease_duration": 0, + "warnings": null +} +``` + +## Create/Update LDAP Group + +This endpoint creates or updates LDAP group policies. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/ldap/groups/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – The name of the LDAP group +- `policies` `(string: "")` – Comma-separated list of policies associated to the + group. + +### Sample Payload + +```json +{ + "policies": "admin,default" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/ldap/groups/admins +``` + +## Delete LDAP Group + +This endpoint deletes the LDAP group and policy association. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/ldap/groups/:name` | `204 (empty body)` | + +### Parameters + +- `name` `(string: )` – The name of the LDAP group + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/ldap/groups/admins +``` + +## List LDAP Users + +This endpoint returns a list of existing users in the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/ldap/users` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/auth/ldap/users +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": [ + "mitchellh", + "armon" + ] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Read LDAP User + +This endpoint returns the policies associated with a LDAP user. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/ldap/users/:username` | `200 application/json` | + +### Parameters + +- `username` `(string: )` – The username of the LDAP user + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/ldap/users/mitchellh +``` + +### Sample Response + +```json +{ + "data": { + "policies": "admin,default", + "groups": "" + }, + "renewable": false, + "lease_id": "" + "lease_duration": 0, + "warnings": null +} +``` + +## Create/Update LDAP User + +This endpoint creates or updates LDAP users policies and group associations. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/ldap/users/:username` | `204 (empty body)` | + +### Parameters + +- `username` `(string: )` – The username of the LDAP user +- `policies` `(string: "")` – Comma-separated list of policies associated to the + user. +- `groups` `(string: "")` – Comma-separated list of groups associated to the + user. + +### Sample Payload + +```json +{ + "policies": "admin,default" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/ldap/users/mitchellh +``` + +## Delete LDAP User + +This endpoint deletes the LDAP user and policy association. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/ldap/users/:username` | `204 (empty body)` | + +### Parameters + +- `username` `(string: )` – The username of the LDAP user + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/ldap/users/mitchellh +``` + +## Login with LDAP User + +This endpoint allows you to log in with LDAP credentials + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/ldap/login/:username` | `200 application/json` | + +### Parameters + +- `username` `(string: )` – The username of the LDAP user +- `password` `(string: )` – The password for the LDAP user + +### Sample Payload + +```json +{ + "password": "MyPassword1" +} +``` + +### Sample Request + +``` +$ curl \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/ldap/login/mitchellh +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": null, + "auth": { + "client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb", + "policies": [ + "admins", + "default" + ], + "metadata": { + "username": "mitchellh" + }, + "lease_duration": 0, + "renewable": false + } +} +``` + diff --git a/website/source/api/auth/mfa/index.html.md b/website/source/api/auth/mfa/index.html.md new file mode 100644 index 000000000000..01e2dc99cbd6 --- /dev/null +++ b/website/source/api/auth/mfa/index.html.md @@ -0,0 +1,17 @@ +--- +layout: "api" +page_title: "MFA Auth Backend - HTTP API" +sidebar_current: "docs-http-auth-mfa" +description: |- + This is the API documentation for the Vault MFA authentication backend. +--- + +# MFA Auth Backend HTTP API + +This is the API documentation for the Vault MFA authentication backend. For +general information about the usage and operation of the AppRole backend, please +see the [Vault MFA backend documentation](/docs/auth/mfa.html). + +This documentation assumes the MFA backend is mounted at the `/auth/mfa` +path in Vault. Since it is possible to mount auth backends at any location, +please update your API calls accordingly. \ No newline at end of file diff --git a/website/source/api/auth/okta/index.html.md b/website/source/api/auth/okta/index.html.md new file mode 100644 index 000000000000..484ef7cd0f2d --- /dev/null +++ b/website/source/api/auth/okta/index.html.md @@ -0,0 +1,17 @@ +--- +layout: "api" +page_title: "Okta Auth Backend - HTTP API" +sidebar_current: "docs-http-auth-okta" +description: |- + This is the API documentation for the Vault Okta authentication backend. +--- + +# Okta Auth Backend HTTP API + +This is the API documentation for the Vault Okta authentication backend. For +general information about the usage and operation of the Okta backend, please +see the [Vault Okta backend documentation](/docs/auth/okta.html). + +This documentation assumes the Okta backend is mounted at the `/auth/okta` +path in Vault. Since it is possible to mount auth backends at any location, +please update your API calls accordingly. \ No newline at end of file diff --git a/website/source/api/auth/radius/index.html.md b/website/source/api/auth/radius/index.html.md new file mode 100644 index 000000000000..222035000796 --- /dev/null +++ b/website/source/api/auth/radius/index.html.md @@ -0,0 +1,238 @@ +--- +layout: "api" +page_title: "RADIUS Auth Backend - HTTP API" +sidebar_current: "docs-http-auth-radius" +description: |- + This is the API documentation for the Vault RADIUS authentication backend. +--- + +# RADIUS Auth Backend HTTP API + +This is the API documentation for the Vault RADIUS authentication backend. For +general information about the usage and operation of the RADIUS backend, please +see the [Vault RADIUS backend documentation](/docs/auth/radius.html). + +This documentation assumes the RADIUS backend is mounted at the `/auth/radius` +path in Vault. Since it is possible to mount auth backends at any location, +please update your API calls accordingly. + +## Configure RADIUS + +Configures the connection parameters and shard secret used to communicate with +RADIUS. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/radius/config` | `204 (empty body)` | + +### Parameters + +- `host` `(string: )` - The RADIUS server to connect to. Examples: + `radius.myorg.com`, `127.0.0.1` +- `port` `(integer: 1812)` - The UDP port where the RADIUS server is listening + on. Defaults is 1812. +- `secret` `(string: )` - The RADIUS shared secret. +- `unregistered_user_policies` `(string: "")` - A comma-separated list of + policies to be granted to unregistered users. +- `dial_timeout` `(integer: 10)` - Number of second to wait for a backend + connection before timing out. Defaults is 10. +- `read_timeout` `(integer: 10)` - Number of second to wait for a backend + response before timing out. Defaults is 10. +- `nas_port` `(integer: 10)` - The NAS-Port attribute of the RADIUS request. + Defaults is 10. + +### Sample Payload + +```json +{ + "host": "radius.myorg.com", + "port": 1812, + "secret": "mySecret" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/radius/config +``` + +## Register User + +Registers a new user and maps a set of policies to it. This path honors the +distinction between the `create` and `update` capabilities inside ACL policies. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/radius/users/:username` | `204 (empty body)` | + +### Parameters + +- `username` `(string: )` - Username for this user. +- `policies` `(string: "")` - Comma-separated list of policies. If set to + empty string, only the `default` policy will be applicable to the user. + +```json +{ + "policies": "dev,prod", +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/radius/users/test-user +``` + +## Read User + +Reads the properties of an existing username. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/radius/users/:username` | `200 application/json` | + +### Parameters + +- `username` `(string: )` - Username for this user. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/radius/users/test-user +``` + +### Sample Response + +```javascript +{ + "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "policies": "default,dev" + }, + "warnings": null +} +``` + +## Delete User + +Deletes an existing username from the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/radius/users/:username` | `204 (empty body)` | + +### Parameters + +- `username` `(string: )` - Username for this user. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/radius/users/test-user +``` + +## List Users + +List the users registered with the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/radius/users` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/auth/radius/users +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": [ + "devuser", + "produser" + ] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Login + +Login with the username and password. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/radius/login` | `200 application/json` | +| `POST` | `/auth/radius/login/:username` | `200 application/json` | + +### Parameters + +- `username` `(string: )` - Username for this user. +- `password` `(string: )` - Password for the autheticating user. + +### Sample Payload + +```json +{ + "password": "Password!" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/auth/radius/login/test-user +``` + +### Sample Response + +```javascript +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": null, + "warnings": null, + "auth": { + "client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344", + "accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d", + "policies": ["default"], + "metadata": { + "username": "vishal" + }, + }, + "lease_duration": 7200, + "renewable": true +} + ``` \ No newline at end of file diff --git a/website/source/api/auth/token/index.html.md b/website/source/api/auth/token/index.html.md new file mode 100644 index 000000000000..8c5ae55c49c8 --- /dev/null +++ b/website/source/api/auth/token/index.html.md @@ -0,0 +1,702 @@ +--- +layout: "api" +page_title: "Token Auth Backend - HTTP API" +sidebar_current: "docs-http-auth-token" +description: |- + This is the API documentation for the Vault token authentication backend. +--- + +# Token Auth Backend HTTP API + +This is the API documentation for the Vault token authentication backend. For +general information about the usage and operation of the token backend, please +see the [Vault Token backend documentation](/docs/auth/token.html). + +## List Accessors + +This endpoint lists token accessor. This requires `sudo` capability, and access +to it should be tightly controlled as the accessors can be used to revoke very +large numbers of tokens and their associated leases at once. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/token/accessors` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://vault.rocks/v1/auth/token/accessors +``` + +### Sample Response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": [ + "476ea048-ded5-4d07-eeea-938c6b4e43ec", + "bb00c093-b7d3-b0e9-69cc-c4d85081165b" + ] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Create Token + +Creates a new token. Certain options are only available when called by a +root token. If used via the `/auth/token/create-orphan` endpoint, a root +token is not required to create an orphan token (otherwise set with the +`no_parent` option). If used with a role name in the path, the token will +be created against the specified role name; this may override options set +during this call. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/token/create` | `200 application/json` | +| `POST` | `/auth/token/create-orphan` | `200 application/json` | +| `POST` | `/auth/token/create/:role_name` | `200 application/json` | + +### Parameters + +- `id` `(string: "")` – The ID of the client token. Can only be specified by a + root token. Otherwise, the token ID is a randomly generated UUID. +- `role_name` `(string: "")` – The name of the token role. +- `policies` `(array: "")` – A list of policies for the token. This must be a + subset of the policies belonging to the token making the request, unless root. + If not specified, defaults to all the policies of the calling token. +- `meta` `(map: {})` – A map of string to string valued metadata. This is + passed through to the audit backends. +- `no_parent` `(bool: false)` - If true and set by a root caller, the token will + not have the parent token of the caller. This creates a token with no parent. +- `no_default_policy` `(bool: false)` - If true the `default` policy will not be + contained in this token's policy set. +- `renewable` `(bool: true)` - Set to `false` to disable the ability of the token + to be renewed past its initial TTL. Setting the value to `true` will allow + the token to be renewable up to the system/mount maximum TTL. +- `lease` `(string: "")` - DEPRECATED; use `ttl` instead +- `ttl` `(string: "")` -The TTL period of the token, provided as "1h", where + hour is the largest suffix. If not provided, the token is valid for the + [default lease TTL](/docs/configuration/index.html), or indefinitely if the + root policy is used. +- `explicit_max_ttl` `(string: "")` - If set, the token will have an explicit + max TTL set upon it. This maximum token TTL *cannot* be changed later, and + unlike with normal tokens, updates to the system/mount max TTL value will + have no effect at renewal time -- the token will never be able to be renewed + or used past the value set at issue time. +- `display_name` `(string: "token")` - The display name of the token. +- `num_uses` `(integer: 0)` - The maximum uses for the given token. This can be + used to create a one-time-token or limited use token. The value of 0 has no + limit to the number of uses. +- `period` `(string: "")` - If specified, the token will be periodic; it will have + no maximum TTL (unless an "explicit-max-ttl" is also set) but every renewal + will use the given period. Requires a root/sudo token to use. + +### Sample Payload + +```json +{ + "policies": [ + "web", + "stage" + ], + "metadata": { + "user": "armon" + }, + "ttl": "1h", + "renewable": true +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/token/create +``` + +### Sample Response + +```json +{ + "auth": { + "client_token": "ABCD", + "policies": [ + "web", + "stage" + ], + "metadata": { + "user": "armon" + }, + "lease_duration": 3600, + "renewable": true, + } +} +``` + +## Lookup a Token + +Returns information about the client token. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/token/lookup` | `200 application/json` | +| `GET` | `/auth/token/lookup/:token` | `200 application/json` | + +### Parameters + +- `token` `(string: )` - Token to lookup. + +### Sample Payload + +```json +{ + "token": "ClientToken" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/token/lookup +``` + +### Sample Response + +```json +{ + "data": { + "id": "ClientToken", + "policies": [ + "web", + "stage" + ], + "path": "auth/github/login", + "meta": { + "user": "armon", + "organization": "hashicorp" + }, + "display_name": "github-armon", + "num_uses": 0, + } +} +``` + +## Lookup a Token (Self) + +Returns information about the current client token. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/token/lookup-self` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/token/lookup-self +``` + +### Sample Response + +```json +{ + "data": { + "id": "ClientToken", + "policies": [ + "web", + "stage" + ], + "path": "auth/github/login", + "meta": { + "user": "armon", + "organization": "hashicorp" + }, + "display_name": "github-armon", + "num_uses": 0, + } +} +``` + +## Lookup a Token Accessor + +Returns information about the client token from the accessor. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/token/lookup-accessor` | `200 application/json` | +| `GET` | `/auth/token/lookup-accessor/:accessor` | `200 application/json` | + +### Parameters + +- `accessor` `(string: )` - Token accessor to lookup. + +### Sample Payload + +```json +{ + "accessor": "2c84f488-2133-4ced-87b0-570f93a76830" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/token/lookup-accessor +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "creation_time": 1457533232, + "creation_ttl": 2764800, + "display_name": "token", + "meta": null, + "num_uses": 0, + "orphan": false, + "path": "auth/token/create", + "policies": [ + "default", + "web" + ], + "ttl": 2591976 + }, + "warnings": null, + "auth": null +} +``` + +## Renew a Token + +Renews a lease associated with a token. This is used to prevent the expiration +of a token, and the automatic revocation of it. Token renewal is possible only +if there is a lease associated with it. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/token/renew` | `200 application/json` | +| `POST` | `/auth/token/renew/:token` | `200 application/json` | + +### Parameters + +- `token` `(string: )` - Token to renew. This can be part of the URL + or the body. +- `increment` `(string: "")` - An optional requested lease increment can be + provided. This increment may be ignored. + +### Sample Payload + +```json +{ + "token": "ClientToken" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/token/renew +``` + +### Sample Response + +```json +{ + "auth": { + "client_token": "ABCD", + "policies": [ + "web", + "stage" + ], + "metadata": { + "user": "armon" + }, + "lease_duration": 3600, + "renewable": true, + } +} +``` + +## Renew a Token (Self) + +Renews a lease associated with the calling token. This is used to prevent the +expiration of a token, and the automatic revocation of it. Token renewal is +possible only if there is a lease associated with it. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/token/renew-self` | `200 application/json` | + +### Parameters + +- `increment` `(string: "")` - An optional requested lease increment can be + provided. This increment may be ignored. + +### Sample Payload + +```json +{ + "increment": "1h" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/token/renew-self +``` + +### Sample Response + +```json +{ + "auth": { + "client_token": "ABCD", + "policies": [ + "web", + "stage" + ], + "metadata": { + "user": "armon" + }, + "lease_duration": 3600, + "renewable": true, + } +} +``` + +## Revoke a Token + +Revokes a token and all child tokens. When the token is revoked, all secrets +generated with it are also revoked. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/token/revoke` | `204 (empty body)` | + +### Parameters + +- `token` `(string: )` - Token to revoke. + +### Sample Payload + +```json +{ + "token": "ClientToken" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/token/revoke +``` + +## Revoke a Token (Self) + +Revokes the token used to call it and all child tokens. When the token is +revoked, all dynamic secrets generated with it are also revoked. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/token/revoke-self` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/auth/token/revoke-self +``` + +## Revoke a Token Accessor + +Revoke the token associated with the accessor and all the child tokens. This is +meant for purposes where there is no access to token ID but there is need to +revoke a token and its children. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/token/revoke-accessor` | `204 (empty body)` | + +### Parameters + +- `accessor` `(string: )` - Accessor of the token. + +### Sample Payload + +```json +{ + "accessor": "2c84f488-2133-4ced-87b0-570f93a76830" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/token/revoke-accessor +``` + +## Revoke Token and Orphan Children + +Revokes a token but not its child tokens. When the token is revoked, all secrets +generated with it are also revoked. All child tokens are orphaned, but can be +revoked sub-sequently using `/auth/token/revoke/`. This is a root-protected +endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/token/revoke-orphan` | `204 (empty body)` | +| `POST` | `/auth/token/revoke-orphan/:token` | `204 (empty body)` | + +### Parameters + +- `token` `(string: )` - Token to revoke. This can be part of the URL + or the body. + +### Sample Payload + +```json +{ + "token": "ClientToken" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/token/revoke-orphan +``` + +## Read Token Role + +Fetches the named role configuration. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/token/roles/:role_name`| `200 application/json` | + +### Parameters + +- `role_name` `(string: )` - The name of the token role. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/token/roles/nomad +``` + +### Sample Response + +```javascript +{ + "request_id": "075a19cd-4e56-a3ca-d956-7609819831ec", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "allowed_policies": [ + "dev" + ], + "disallowed_policies": [], + "explicit_max_ttl": 0, + "name": "nomad", + "orphan": false, + "path_suffix": "", + "period": 0, + "renewable": true + }, + "warnings": null +} +``` + +## List Token Roles + +List available token roles. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/token/roles` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST + https://vault.rocks/v1/auth/token/roles +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "role1", + "role2" + ] + } +} +``` + +## Create/Update Token Role + +Creates (or replaces) the named role. Roles enforce specific behavior when +creating tokens that allow token functionality that is otherwise not +available or would require `sudo`/root privileges to access. Role +parameters, when set, override any provided options to the `create` +endpoints. The role name is also included in the token path, allowing all +tokens created against a role to be revoked using the `sys/revoke-prefix` +endpoint. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/token/roles/:role_name` | `204 (empty body)` | + +### Parameters + +- `role_name` `(string: )` – The name of the token role. +- `allowed_policies` `(list: [])` – If set, tokens can be created with any + subset of the policies in this list, rather than the normal semantics of + tokens being a subset of the calling token's policies. The parameter is a + comma-delimited string of policy names. If at creation time + `no_default_policy` is not set and `"default"` is not contained in + `disallowed_policies`, the `"default"` policy will be added to the created + token automatically. +- `disallowed_policies` `(list: [])` – If set, successful token creation via + this role will require that no policies in the given list are requested. The + parameter is a comma-delimited string of policy names. Adding `"default"` to + this list will prevent `"default"` from being added automatically to created + tokens. +- `orphan` `(bool: true)` - If `true`, tokens created against this policy will + be orphan tokens (they will have no parent). As such, they will not be + automatically revoked by the revocation of any other token. +- `period` `(string: "")` - If specified, the token will be periodic; it will have + no maximum TTL (unless an "explicit-max-ttl" is also set) but every renewal + will use the given period. Requires a root/sudo token to use. +- `renewable` `(bool: true)` - Set to `false` to disable the ability of the token + to be renewed past its initial TTL. Setting the value to `true` will allow + the token to be renewable up to the system/mount maximum TTL. +- `explicit_max_ttl` `(string: "")` - If set, the token will have an explicit + max TTL set upon it. This maximum token TTL *cannot* be changed later, and + unlike with normal tokens, updates to the system/mount max TTL value will + have no effect at renewal time -- the token will never be able to be renewed + or used past the value set at issue time. +- `path_suffix` `(string: "")` - If set, tokens created against this role will + have the given suffix as part of their path in addition to the role name. This + can be useful in certain scenarios, such as keeping the same role name in the + future but revoking all tokens created against it before some point in time. + The suffix can be changed, allowing new callers to have the new suffix as part + of their path, and then tokens with the old suffix can be revoked via + `sys/revoke-prefix`. + +### Sample Payload + +```json + "allowed_policies": [ + "dev" + ], + "name": "nomad", + "orphan": false, + "renewable": true +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST + --data @payload.json + https://vault.rocks/v1/auth/token/roles/nomad +``` + +## Delete Token Role + +This endpoint deletes the named token role. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/token/roles/:role_name` | `204 (empty body)` | + +### Parameters + +- `role_name` `(string: )` - The name of the token role. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/token/roles/admins +``` + +## 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 backend so should be used sparingly. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/token/tidy` | `204 (empty body)` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://vault.rocks/v1/auth/token/tidy +``` \ No newline at end of file diff --git a/website/source/api/auth/userpass/index.html.md b/website/source/api/auth/userpass/index.html.md new file mode 100644 index 000000000000..e5b4e4eaf740 --- /dev/null +++ b/website/source/api/auth/userpass/index.html.md @@ -0,0 +1,254 @@ +--- +layout: "api" +page_title: "Userpass Auth Backend - HTTP API" +sidebar_current: "docs-http-auth-userpass" +description: |- + This is the API documentation for the Vault username and password + authentication backend. +--- + +# Username & Password Auth Backend HTTP API + +This is the API documentation for the Vault Username & Password authentication backend. For +general information about the usage and operation of the Username and Password backend, please +see the [Vault Userpass backend documentation](/docs/auth/userpass.html). + +This documentation assumes the Username & Password backend is mounted at the `/auth/userpass` +path in Vault. Since it is possible to mount auth backends at any location, +please update your API calls accordingly. + +## Create/Update User + +Create a new user or update an existing user. This path honors the distinction between the `create` and `update` capabilities inside ACL policies. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/userpass/users/:username` | `204 (empty body)` | + +### Parameters + +- `username` `(string: )` – The username for the user. +- `password` `(string: )` - The password for the user. Only required + when creating the user. +- `policies` `(string: "")` – Comma-separated list of policies. If set to empty + string, only the `default` policy will be applicable to the user. +- `ttl` `(string: "")` - The lease duration which decides login expiration. +- `max_ttl` `(string: "")` - Maximum duration after which login should expire. + +### Sample Payload + +```json +{ + "password": "superSecretPassword", + "policies": "admin,default" +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/userpass/users/mitchellh +``` + +## Read User + +Reads the properties of an existing username. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `GET` | `/auth/userpass/users/:username` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + https://vault.rocks/v1/auth/userpass/users/mitchellh +``` + +### Sample Response + +```json +{ + "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "max_ttl": 0, + "policies": "default,dev", + "ttl": 0 + }, + "warnings": null +} +``` + +## Delete User + +This endpoint deletes the user from the backend. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `DELETE` | `/auth/userpass/users/:username` | `204 (empty body)` | + +### Parameters + +- `username` `(string: )` - The username for the user. + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://vault.rocks/v1/auth/userpass/users/mitchellh +``` + +## Update Password on User + +Update password for an existing user. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/userpass/users/:username/password` | `204 (empty body)` | + +### Parameters + +- `username` `(string: )` – The username for the user. +- `password` `(string: )` - The password for the user. + +### Sample Payload + +```json +{ + "password": "superSecretPassword2", +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/userpass/users/mitchellh/password +``` + +## Update Policies on User + +Update policies for an existing user. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/userpass/users/:username/policies` | `204 (empty body)` | + +### Parameters + +- `username` `(string: )` – The username for the user. +- `policies` `(string: "")` – Comma-separated list of policies. If set to empty + +### Sample Payload + +```json +{ + "policies": "policy1,policy2", +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/userpass/users/mitchellh/policies +``` + +## List Users + +List available userpass users. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `LIST` | `/auth/userpass/users` | `200 application/json` | + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST + https://vault.rocks/v1/auth/userpass/users +``` + +### Sample Response + +```json +{ + "data": { + "keys": [ + "mitchellh", + "armon" + ] + } +} +``` + +## Login + +Login with the username and password. + +| Method | Path | Produces | +| :------- | :--------------------------- | :--------------------- | +| `POST` | `/auth/userpass/login/:username` | `200 application/json` | + +### Parameters + +- `username` `(string: )` – The username for the user. +- `password` `(string: )` - The password for the user. + +### Sample Payload + +```json +{ + "password": "superSecretPassword2", +} +``` + +### Sample Request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://vault.rocks/v1/auth/userpass/login/mitchellh +``` + +### Sample Response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": null, + "warnings": null, + "auth": { + "client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344", + "accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d", + "policies": ["default"], + "metadata": { + "username": "mitchellh" + }, + "lease_duration": 7200, + "renewable": true + } +} +``` \ No newline at end of file diff --git a/website/source/docs/auth/approle.html.md b/website/source/docs/auth/approle.html.md index 782af5f94155..92349212dbab 100644 --- a/website/source/docs/auth/approle.html.md +++ b/website/source/docs/auth/approle.html.md @@ -219,733 +219,7 @@ $ curl -X POST \ ``` ## API -### /auth/approle/role -#### LIST/GET -
-
Description
-
- Lists the existing AppRoles in the backend -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/approle/role` (LIST) or `/auth/approle/role?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "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
-
- 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
-
POST
- -
URL
-
`/auth/approle/role/[role_name]`
- -
Parameters
-
-
    -
  • - role_name - required - Name of the AppRole. -
    • -
-
    -
  • - bind_secret_id - optional - Require `secret_id` to be presented when logging in using this AppRole. - 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 set on tokens issued via this AppRole. -
    • -
-
    -
  • - secret_id_num_uses - optional - Number of times any particular SecretID can be used to fetch a token - from this AppRole, after which the SecretID will expire. -
    • -
-
    -
  • - secret_id_ttl - optional - Duration in either an integer number of seconds (`3600`) or an integer - time unit (`60m`) after which any SecretID expires. -
    • -
-
    -
  • - token_num_uses - optional - Number of times issued tokens can be used. -
    • -
-
    -
  • - token_ttl - optional - Duration in either an integer number of seconds (`3600`) or an integer - time unit (`60m`) to set as the TTL for issued tokens and at renewal - time. -
    • -
-
    -
  • - token_max_ttl - optional - Duration in either an integer number of seconds (`3600`) or an integer - time unit (`60m`) after which the issued token can no longer be - renewed. -
    • -
-
    -
  • - period - optional - Duration in either an integer number of seconds (`3600`) or an integer - time unit (`60m`). If set, the token generated using this AppRole is a - _periodic_ token; so long as it is renewed it never expires, but the - TTL set on the token at each renewal is fixed to the value specified - here. If this value is modified, the token will pick up the new value - at 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
-
- - ```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": "" - } - ``` - -
-
- -#### 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
-
- - ```javascript - { - "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 to a custom value. -
- -
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. 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
-
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. This metadata will - be set on tokens issued with this SecretID, and is logged in audit logs - _in plaintext_. -
    • -
-
    -
  • - cidr_list - optional -Comma separated list of CIDR blocks enforcing secret IDs to be used from -specific set of IP addresses. If 'bound_cidr_list' 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. -
    • -
-
- -
Returns
-
- - ```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": "" - } - ``` - -
-
- -#### LIST -
-
Description
-
- Lists the accessors of all the SecretIDs issued against the AppRole. - This includes the accessors for "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
-
- - ```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": "" - } - ``` - -
-
- -### /auth/approle/role/[role_name]/secret-id/lookup -#### POST -
-
Description
-
- Reads out the properties of a SecretID. -
- -
Method
-
POST
- -
URL
-
`/auth/approle/role/[role_name]/secret-id/lookup`
- -
Parameters
-
-
    -
  • - secret_id - required -Secret ID attached to the role -
    • -
-
- -
Returns
-
- - ```javascript - { - "request_id": "0d25d8ec-0d16-2842-1dda-c28c25aefd4b", - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": { - "cidr_list": null, - "creation_time": "2016-09-28T21:00:46.760570318-04:00", - "expiration_time": "0001-01-01T00:00:00Z", - "last_updated_time": "2016-09-28T21:00:46.760570318-04:00", - "metadata": {}, - "secret_id_accessor": "b4bea6b2-0214-9f7f-33cf-e732155feadb", - "secret_id_num_uses": 10, - "secret_id_ttl": 0 - } - } - ``` - -
-
- -### /auth/approle/role/[role_name]/secret-id/destroy -#### POST -
-
Description
-
- Deletes a SecretID. -
- -
Method
-
POST
- -
URL
-
`/auth/approle/role/[role_name]/secret-id/destroy`
- -
Parameters
-
-
    -
  • - secret_id - required -Secret ID attached to the role -
    • -
-
- -
Returns
-
- `204` response code. -
-
- -### /auth/approle/role/[role_name]/secret-id-accessor/lookup -#### POST -
-
Description
-
- Reads out the properties of the SecretID associated with the supplied - accessor. -
- -
Method
-
POST
- -
URL
-
`/auth/approle/role/[role_name]/secret-id-accessor/lookup`
- -
Parameters
-
-
    -
  • - secret_id_accessor - required -Accessor of the secret ID -
    • -
-
- -
Returns
-
- - ```javascript - { - "request_id": "2132237e-d1b6-d298-6117-b54a2d938d00", - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": { - "cidr_list": null, - "creation_time": "2016-09-28T22:09:02.834238344-04:00", - "expiration_time": "0001-01-01T00:00:00Z", - "last_updated_time": "2016-09-28T22:09:02.834238344-04:00", - "metadata": {}, - "secret_id_accessor": "54ba219d-b539-ac4f-e3cf-763c02f351fb", - "secret_id_num_uses": 10, - "secret_id_ttl": 0 - } - } - ``` - -
-
- -### /auth/approle/role/[role_name]/secret-id-accessor/destroy -#### POST -
-
Description
-
- Deletes the SecretID associated with the given accessor. -
- -
Method
-
POST
- -
URL
-
`/auth/approle/role/[role_name]/secret-id-accessor/destroy`
- -
Parameters
-
-
    -
  • - secret_id_accessor - required -Accessor of the secret ID -
    • -
-
- -
Returns
-
- `204` response code. -
-
- - -### /auth/approle/role/[role_name]/custom-secret-id -#### POST -
-
Description
-
- Assigns a "custom" SecretID against an existing AppRole. This is used in the - "Push" model of operation. -
- -
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. This metadata will - be set on tokens issued with this SecretID, and is logged in audit logs - _in plaintext_. -
    • -
-
    -
  • - cidr_list - optional -Comma separated list of CIDR blocks enforcing secret IDs to be used from -specific set of IP addresses. If 'bound_cidr_list' 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. -
    • -
-
- -
Returns
-
- - ```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": "" - } - ``` - -
-
- - -### /auth/approle/login -#### POST -
-
Description
-
- 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
-
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
-
- - ```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": "" - } - ``` - -
-
- -### /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. -
-
+ +The AppRole authentication backend has a full HTTP API. Please see the +[AppRole API](/api/auth/approle/index.html) for more +details. \ No newline at end of file diff --git a/website/source/docs/auth/aws.html.md b/website/source/docs/auth/aws.html.md index f729f71b8c55..b14da024a10c 100644 --- a/website/source/docs/auth/aws.html.md +++ b/website/source/docs/auth/aws.html.md @@ -636,1605 +636,7 @@ The response will be in JSON. For example: ``` ## API -### /auth/aws/config/client -#### POST -
-
Description
-
- Configures the credentials required to perform API calls to AWS as well as - custom endpoints to talk to AWS APIs. The instance identity document - fetched from the PKCS#7 signature will provide the EC2 instance ID. The - credentials configured using this endpoint will be used to query the status - of the instances via DescribeInstances API. If static credentials are not - provided using this endpoint, then the credentials will be retrieved from - the environment variables `AWS_ACCESS_KEY`, `AWS_SECRET_KEY` and - `AWS_REGION` respectively. If the credentials are still not found and if the - backend is configured on an EC2 instance with metadata querying - capabilities, the credentials are fetched automatically. -
- -
Method
-
POST
- -
URL
-
`/auth/aws/config/client`
- -
Parameters
-
-
    -
  • - access_key - optional - AWS Access key with permissions to query AWS APIs. The permissions - required depend on the specific configurations. If using the `iam` auth - method without inferencing, then no credentials are necessary. If using - the `ec2` auth method or using the `iam` auth method with inferencing, - then these credentials need access to `ec2:DescribeInstances`. If - additionally a `bound_iam_role` is specified, then these credentials - also need access to `iam:GetInstanceProfile`. If, however, an alternate - sts configuration is set for the target account, then the credentials - must be permissioned to call `sts:AssumeRole` on the configured role, - and that role must have the permissions described here. -
    • -
-
    -
  • - secret_key - optional - AWS Secret key with permissions to query AWS APIs. -
    • -
-
    -
  • - endpoint - optional - URL to override the default generated endpoint for making AWS EC2 API calls. -
    • -
-
    -
  • - iam_endpoint - optional - URL to override the default generated endpoint for making AWS IAM API calls. -
    • -
-
    -
  • - sts_endpoint - optional - URL to override the default generated endpoint for making AWS STS API calls. -
    • -
-
    -
  • - iam_server_id_header_value - optional - The value to require in the `X-Vault-AWS-IAM-Server-ID` header as part of - GetCallerIdentity requests that are used in the iam auth method. If not - set, then no value is required or validated. If set, clients must - include an X-Vault-AWS-IAM-Server-ID header in the headers of login - requests, and further this header must be among the signed headers - validated by AWS. This is to protect against different types of replay - attacks, for example a signed request sent to a dev server being resent - to a production server. Consider setting this to the Vault server's DNS - name. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -#### GET -
-
Description
- Returns the previously configured AWS access credentials. -
- -
- -
Method
-
GET
- -
URL
-
`/auth/aws/config/client`
- -
Parameters
-
- None. -
- -
Returns
-
-``` -{ - "auth": null, - "warnings": null, - "data": { - "secret_key": "vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj", - "access_key": "VKIAJBRHKH6EVTTNXDHA" - "endpoint" "", - "iam_endpoint" "", - "sts_endpoint" "", - "iam_server_id_header_value" "", - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- - -#### DELETE -
-
Description
-
- Deletes the previously configured AWS access credentials. -
- -
Method
-
DELETE
- -
URL
-
`/auth/aws/config/client`
- -
Parameters
-
- None. -
- -
Returns
-
`204` response code. -
-
- - -### /auth/aws/config/certificate/ -#### POST -
-
Description
-
- Registers an AWS public key to be used to verify the instance identity - documents. While the PKCS#7 signature of the identity documents have DSA - digest, the identity signature will have RSA digest, and hence the public - keys for each type varies respectively. Indicate the type of the public key - using the "type" parameter. -
- -
Method
-
POST
- -
URL
-
`/auth/aws/config/certificate/`
- -
Parameters
-
-
    -
  • - cert_name - required - Name of the certificate. -
    • -
-
    -
  • - aws_public_cert - required - AWS Public key required to verify PKCS7 signature of the EC2 instance metadata. -
    • -
-
    -
  • - type - optional - Takes the value of either "pkcs7" or "identity", indicating the type of - document which can be verified using the given certificate. The PKCS#7 - document will have a DSA digest and the identity signature will have an - RSA signature, and accordingly the public certificates to verify those - also vary. Defaults to "pkcs7". -
    • -
-
- -
Returns
-
`204` response code. -
-
- - -#### GET -
-
Description
-
- Returns the previously configured AWS public key. -
- -
Method
-
GET
- -
URL
-
`/auth/aws/config/certificate/`
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "aws_public_cert": "-----BEGIN CERTIFICATE-----\nMIIC7TCCAq0CCQCWukjZ5V4aZzAJBgcqhkjOOAQDMFwxCzAJBgNVBAYTAlVTMRkw\nFwYDVQQIExBXYXNoaW5ndG9uIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYD\nVQQKExdBbWF6b24gV2ViIFNlcnZpY2VzIExMQzAeFw0xMjAxMDUxMjU2MTJaFw0z\nODAxMDUxMjU2MTJaMFwxCzAJBgNVBAYTAlVTMRkwFwYDVQQIExBXYXNoaW5ndG9u\nIFN0YXRlMRAwDgYDVQQHEwdTZWF0dGxlMSAwHgYDVQQKExdBbWF6b24gV2ViIFNl\ncnZpY2VzIExMQzCCAbcwggEsBgcqhkjOOAQBMIIBHwKBgQCjkvcS2bb1VQ4yt/5e\nih5OO6kK/n1Lzllr7D8ZwtQP8fOEpp5E2ng+D6Ud1Z1gYipr58Kj3nssSNpI6bX3\nVyIQzK7wLclnd/YozqNNmgIyZecN7EglK9ITHJLP+x8FtUpt3QbyYXJdmVMegN6P\nhviYt5JH/nYl4hh3Pa1HJdskgQIVALVJ3ER11+Ko4tP6nwvHwh6+ERYRAoGBAI1j\nk+tkqMVHuAFcvAGKocTgsjJem6/5qomzJuKDmbJNu9Qxw3rAotXau8Qe+MBcJl/U\nhhy1KHVpCGl9fueQ2s6IL0CaO/buycU1CiYQk40KNHCcHfNiZbdlx1E9rpUp7bnF\nlRa2v1ntMX3caRVDdbtPEWmdxSCYsYFDk4mZrOLBA4GEAAKBgEbmeve5f8LIE/Gf\nMNmP9CM5eovQOGx5ho8WqD+aTebs+k2tn92BBPqeZqpWRa5P/+jrdKml1qx4llHW\nMXrs3IgIb6+hUIB+S8dz8/mmO0bpr76RoZVCXYab2CZedFut7qc3WUH9+EUAH5mw\nvSeDCOUMYQR7R9LINYwouHIziqQYMAkGByqGSM44BAMDLwAwLAIUWXBlk40xTwSw\n7HX32MxXYruse9ACFBNGmdX2ZBrVNGrN9N2f6ROk0k9K\n-----END CERTIFICATE-----\n" - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- -#### LIST -
-
Description
-
- Lists all the AWS public certificates that are registered with the backend. -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/aws/config/certificates` (LIST) or `/auth/aws/config/certificates?list=true` (GET)
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "keys": [ - "cert1" - ] - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- - -### /auth/aws/config/sts/ -#### POST -
-
Description
-
- Allows the explicit association of STS roles to satellite AWS accounts - (i.e. those which are not the account in which the Vault server is - running.) Login attempts from EC2 instances running in these accounts will - be verified using credentials obtained by assumption of these STS roles. -
- -
Method
-
POST
- -
URL
-
`/auth/aws/config/sts/`
- -
Parameters
-
-
    -
  • - account_id - required - AWS account ID to be associated with STS role. If set, Vault will use - assumed credentials to verify any login attempts from EC2 instances in - this account. -
    • -
-
    -
  • - sts_role - required - AWS ARN for STS role to be assumed when interacting with the account - specified. The Vault server must have permissions to assume this role. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -#### GET -
-
Description
-
- Returns the previously configured STS role. -
- -
Method
-
GET
- -
URL
-
`/auth/aws/config/sts/`
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "sts_role ": "arn:aws:iam::role/myRole" - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- -#### LIST -
-
Description
-
- Lists all the AWS Account IDs for which an STS role is registered -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/aws/config/sts` (LIST) or `/auth/aws/config/sts?list=true` (GET)
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "keys": [ - "", - "" - ] - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- -#### DELETE -
-
Description
-
- Deletes a previously configured AWS account/STS role association -
- -
Method
-
DELETE
- -
URL
-
`/auth/aws/config/sts/`
- -
Parameters
-
- None. -
- -
Returns
-
`204` response code. -
-
- -### /auth/aws/config/tidy/identity-whitelist -##### POST -
-
Description
-
- Configures the periodic tidying operation of the whitelisted identity entries. -
- -
Method
-
POST
- -
URL
-
`/auth/aws/config/tidy/identity-whitelist`
- -
Parameters
-
-
    -
  • - safety_buffer - optional - The amount of extra time that must have passed beyond the `roletag` - expiration, before it is removed from the backend storage. Defaults to - 72h. -
    • -
-
    -
  • - disable_periodic_tidy - optional - If set to 'true', disables the periodic tidying of the - 'identity-whitelist/' entries. -
    • -
-
- -
Returns
-
`204` response code. -
-
- - -#### GET -
-
Description
-
- Returns the previously configured periodic whitelist tidying settings. -
- -
Method
-
GET
- -
URL
-
`/auth/aws/config/tidy/identity-whitelist`
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "safety_buffer": 60, - "disable_periodic_tidy": false - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- -#### DELETE -
-
Description
-
- Deletes the previously configured periodic whitelist tidying settings. -
- -
Method
-
DELETE
- -
URL
-
`/auth/aws/config/tidy/identity-whitelist`
- -
Parameters
-
- None. -
- -
Returns
-
`204` response code. -
-
- - - -### /auth/aws/config/tidy/roletag-blacklist -##### POST -
-
Description
-
- Configures the periodic tidying operation of the blacklisted role tag entries. -
- -
Method
-
POST
- -
URL
-
`/auth/aws/config/tidy/roletag-blacklist`
- -
Parameters
-
-
    -
  • - safety_buffer - optional - The amount of extra time that must have passed beyond the `roletag` - expiration, before it is removed from the backend storage. Defaults to - 72h. -
    • -
-
    -
  • - disable_periodic_tidy - optional - If set to 'true', disables the periodic tidying of the - 'roletag-blacklist/' entries. -
    • -
-
- -
Returns
-
`204` response code. -
-
- - -#### GET -
-
Description
-
- Returns the previously configured periodic blacklist tidying settings. -
- -
Method
-
GET
- -
URL
-
`/auth/aws/config/tidy/roletag-blacklist`
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "safety_buffer": 60, - "disable_periodic_tidy": false - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- -#### DELETE -
-
Description
-
- Deletes the previously configured periodic blacklist tidying settings. -
- -
Method
-
DELETE
- -
URL
-
`/auth/aws/config/tidy/roletag-blacklist`
- -
Parameters
-
- None. -
- -
Returns
-
`204` response code. -
-
- - - -### /auth/aws/role/[role] -#### POST -
-
Description
-
- Registers a role in the backend. Only those instances or principals which - are using the role registered using this endpoint, will be able to perform - the login operation. Contraints can be specified on the role, that are - applied on the instances or principals attempting to login. At least one - constraint should be specified on the role. The available constraints you - can choose are dependent on the `auth_type` of the role and, if the - `auth_type` is `iam`, then whether inferencing is enabled. A role will not - let you configure a constraint if it is not checked by the `auth_type` and - inferencing configuration of that role. -
- -
Method
-
POST
- -
URL
-
`/auth/aws/role/`
- -
Parameters
-
-
    -
  • - role - required - Name of the role. -
    • -
-
    -
  • - auth_type - optional - The auth type permitted for this role. Valid choices are "ec2" or "iam". - If no value is specified, then it will default to "iam" (except for - legacy `aws-ec2` auth types, for which it will default to "ec2"). Only - those bindings applicable to the auth type chosen will be allowed to be - configured on the role. -
    • -
-
    -
  • - bound_ami_id - optional - If set, defines a constraint on the EC2 instances that they should be - using the AMI ID specified by this parameter. This constraint is checked - during ec2 auth as well as the iam auth method only when inferring an - EC2 instance. -
    • -
-
    -
  • - bound_account_id - optional - If set, defines a constraint on the EC2 instances that the account ID in - its identity document to match the one specified by this parameter. This - constraint is checked during ec2 auth as well as the iam auth method - only when inferring an EC2 instance. -
    • -
-
    -
  • - bound_region - optional - If set, defines a constraint on the EC2 instances that the region in - its identity document must match the one specified by this parameter. This - constraint is only checked by the ec2 auth method as well as the iam - auth method only when inferring an ec2 instance.. -
    • -
-
    -
  • - bound_vpc_id - optional - If set, defines a constraint on the EC2 instance to be associated with - the VPC ID that matches the value specified by this parameter. This - constraint is only checked by the ec2 auth method as well as the iam - auth method only when inferring an ec2 instance. -
    • -
-
    -
  • - bound_subnet_id - optional - If set, defines a constraint on the EC2 instance to be associated with - the subnet ID that matches the value specified by this parameter. This - constraint is only checked by the ec2 auth method as well as the iam - auth method only when inferring an ec2 instance. -
    • -
-
    -
  • - bound_iam_role_arn - optional - If set, defines a constraint on the authenticating EC2 instance that it must - match the IAM role ARN specified by this parameter. The value is - prefix-matched (as though it were a glob ending in `*`). The configured IAM - user or EC2 instance role must be allowed to execute the - `iam:GetInstanceProfile` action if this is specified. This constraint is - checked by the ec2 auth method as well as the iam auth method only when - inferring an EC2 instance. -
    • -
-
    -
  • - bound_iam_instance_profile_arn - optional - If set, defines a constraint on the EC2 instances to be associated with - an IAM instance profile ARN which has a prefix that matches the value - specified by this parameter. The value is prefix-matched (as though it - were a glob ending in `*`). This constraint is checked by the ec2 auth - method as well as the iam auth method only when inferring an ec2 - instance. -
    • -
-
    -
  • - role_tag - optional - If set, enables the role tags for this role. The value set for this - field should be the 'key' of the tag on the EC2 instance. The 'value' - of the tag should be generated using `role//tag` endpoint. - Defaults to an empty string, meaning that role tags are disabled. This - constraint is valid only with the ec2 auth method and is not allowed - when an auth_type is iam. -
    • -
-
    -
  • - bound_iam_principal_arn - optional - Defines the IAM principal that must be authenticated using the iam - auth method. It should look like - "arn:aws:iam::123456789012:user/MyUserName" or - "arn:aws:iam::123456789012:role/MyRoleName". This constraint is only - checked by the iam auth method. -
    • -
-
    -
  • - inferred_entity_type - optional - When set, instructs Vault to turn on inferencing. The only current valid - value is "ec2_instance" instructing Vault to infer that the role comes - from an EC2 instance in an IAM instance profile. This only applies to - the iam auth method. If you set this on an existing role where it had - not previously been set, tokens that had been created prior will not be - renewable; clients will need to get a new token. -
    • -
-
    -
  • - inferred_aws_region - optional - When role inferencing is activated, the region to search for the - inferred entities (e.g., EC2 instances). Required if role inferencing is - activated. This only applies to the iam auth method. -
    • -
-
    -
  • - resolve_aws_unique_ids - optional - When set, resolves the `bound_iam_principal_arn` to the [AWS Unique - ID](http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers.html#identifiers-unique-ids). - This requires Vault to be able to call `iam:GetUser` or `iam:GetRole` on - the `bound_iam_principal_arn` that is being bound. Resolving to - internal AWS IDs more closely mimics the behavior of AWS services in - that if an IAM user or role is deleted and a new one is recreated with - the same name, those new users or roles won't get access to roles in - Vault that were permissioned to the prior principals of the same name. - The default value for new roles is true, while the default value for - roles that existed prior to this option existing is false (you can - check the value for a given role using the GET method on the role). Any - authentication tokens created prior to this being supported won't - verify the unique ID upon token renewal. When this is changed from - false to true on an existing role, Vault will attempt to resolve the - role's bound IAM ARN to the unique ID and, if unable to do so, will - fail to enable this option. Changing this from `true` to `false` is - not supported; if absolutely necessary, you would need to delete the - role and recreate it explicitly setting it to `false`. However; the - instances in which you would want to do this should be rare. If the - role creation (or upgrading to use this) succeed, then Vault has - already been able to resolve internal IDs, and it doesn't need any - further IAM permissions to authenticate users. If a role has been - deleted and recreated, and Vault has cached the old unique ID, you - should just call this endpoint specifying the same - `bound_iam_principal_arn` and, as long as Vault still has the necessary - IAM permissions to resolve the unique ID, Vault will update the unique - ID. (If it does not have the necessary permissions to resolve the - unique ID, then it will fail to update.) If this option is set to - false, then you MUST leave out the path component in - bound_iam_principal_arn for **roles** only, but not IAM users. That is, - if your IAM role ARN is of the form - `arn:aws:iam::123456789012:role/some/path/to/MyRoleName`, you **must** - specify a bound_iam_principal_arn of - `arn:aws:iam::123456789012:role/MyRoleName` for authentication to - work. -
    • -
- -
    -
  • - ttl - optional - The TTL period of tokens issued using this role, provided as "1h", - where hour is the largest suffix. -
    • -
-
    -
  • - max_ttl - optional - The maximum allowed lifetime of tokens issued using this role. -
    • -
-
    -
  • - 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. At each renewal, the token's TTL will be set to the value - of this parameter. The maximum allowed lifetime of tokens issued using - this role. -
    • -
-
    -
  • - policies - optional - Policies to be set on tokens issued using this role. -
    • -
-
    -
  • - allow_instance_migration - optional - If set, allows migration of the underlying instance where the client - resides. This keys off of pendingTime in the metadata document, so - essentially, this disables the client nonce check whenever the instance - is migrated to a new host and pendingTime is newer than the - previously-remembered time. Use with caution. This only applies to - authentications via the ec2 auth method. -
    • -
-
    -
  • - disallow_reauthentication - optional - If set, only allows a single token to be granted per instance ID. In - order to perform a fresh login, the entry in whitelist for the instance - ID needs to be cleared using - 'auth/aws/identity-whitelist/' endpoint. Defaults to - 'false'. This only applies to authentications via the ec2 auth method. -
    • -
-
- -
Returns
-
`204` response code. -
-
- - -#### GET -
-
Description
-
- Returns the previously registered role configuration. -
- -
Method
-
GET
- -
URL
-
`/auth/aws/role/`
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "bound_ami_id": "ami-fce36987", - "role_tag": "", - "policies": [ - "default", - "dev", - "prod" - ], - "max_ttl": 1800000, - "disallow_reauthentication": false, - "allow_instance_migration": false - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- - -#### LIST -
-
Description
-
- Lists all the roles that are registered with the backend. -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/aws/roles` (LIST) or `/auth/aws/roles?list=true` (GET)
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "keys": [ - "dev-role", - "prod-role" - ] - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- - -#### DELETE -
-
Description
-
- Deletes the previously registered role. -
- -
Method
-
DELETE
- -
URL
-
`/auth/aws/role/`
- -
Parameters
-
- None. -
- -
Returns
-
`204` response code. -
-
- - -### /auth/aws/role/[role]/tag -#### POST -
-
Description
-
- Creates a role tag on the role, which help in restricting the capabilities - that are set on the role. Role tags are not tied to any specific ec2 - instance unless specified explicitly using the `instance_id` parameter. By - default, role tags are designed to be used across all instances that - satisfies the constraints on the role. Regardless of which instances have - role tags on them, capabilities defined in a role tag must be a strict - subset of the given role's capabilities. Note that, since adding and - removing a tag is often a widely distributed privilege, care needs to be - taken to ensure that the instances are attached with correct tags to not - let them gain more privileges than what were intended. If a role tag is - changed, the capabilities inherited by the instance will be those defined - on the new role tag. Since those must be a subset of the role - capabilities, the role should never provide more capabilities than any - given instance can be allowed to gain in a worst-case scenario. -
- -
Method
-
POST
- -
URL
-
`/auth/aws/role//tag`
- -
Parameters
-
-
    -
  • - role - required - Name of the role. -
    • -
-
    -
  • - policies - optional - Policies to be associated with the tag. If set, must be a subset of the - role's policies. If set, but set to an empty value, only the 'default' - policy will be given to issued tokens. -
    • -
-
    -
  • - max_ttl - optional - If set, specifies the maximum allowed token lifetime. -
    • -
-
    -
  • - instance_id - optional - Instance ID for which this tag is intended for. If set, the created tag - can only be used by the instance with the given ID. -
    • -
-
    -
  • - disallow_reauthentication - optional - If set, only allows a single token to be granted per instance ID. This - can be cleared with the auth/aws/identity-whitelist endpoint. - Defaults to 'false'. -
    • -
-
    -
  • - allow_instance_migration - optional - If set, allows migration of the underlying instance where the client - resides. This keys off of pendingTime in the metadata document, so - essentially, this disables the client nonce check whenever the instance - is migrated to a new host and pendingTime is newer than the - previously-remembered time. Use with caution. Defaults to 'false'. -
    • -
-
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "tag_value": "v1:09Vp0qGuyB8=:r=dev-role:p=default,prod:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/pJIdVyOI=", - "tag_key": "VaultRole" - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- - -### /auth/aws/login -#### POST -
-
Description
-
- Fetch a token. This endpoint verifies the pkcs7 signature of the instance - identity document or the signature of the signed GetCallerIdentity request. - With the ec2 auth method, or when inferring an EC2 instance, verifies that - the instance is actually in a running state. Cross checks the constraints - defined on the role with which the login is being performed. With the ec2 - auth method, as an alternative to pkcs7 signature, the identity document - along with its RSA digest can be supplied to this endpoint. -
- -
Method
-
POST
- -
URL
-
`/auth/aws/login`
- -
Parameters
-
-
    -
  • - role - optional - Name of the role against which the login is being attempted. - If `role` is not specified, then the login endpoint looks for a role - bearing the name of the AMI ID of the EC2 instance that is trying to - login if using the ec2 auth method, or the "friendly name" (i.e., role - name or username) of the IAM principal authenticated. - If a matching role is not found, login fails. -
    • -
-
    -
  • - identity - required - Base64 encoded EC2 instance identity document. This needs to be - supplied along with the `signature` parameter. If using `curl` for - fetching the identity document, consider using the option `-w 0` while - piping the output to `base64` binary. -
    • -
-
    -
  • - signature - required - Base64 encoded SHA256 RSA signature of the instance identity document. - This needs to be supplied along with `identity` parameter when using the - ec2 auth method. -
    • -
-
    -
  • - pkcs7 - required - PKCS7 signature of the identity document with all `\n` characters - removed. Either this needs to be set *OR* both `identity` and - `signature` need to be set when using the ec2 auth method. -
    • -
-
    -
  • - nonce - optional - The nonce to be used for subsequent login requests. If this parameter - is not specified at all and if reauthentication is allowed, then the - backend will generate a random nonce, attaches it to the instance's - identity-whitelist entry and returns the nonce back as part of auth - metadata. This value should be used with further login requests, to - establish client authenticity. Clients can choose to set a custom nonce - if preferred, in which case, it is recommended that clients provide a - strong nonce. If a nonce is provided but with an empty value, it - indicates intent to disable reauthentication. Note that, when - `disallow_reauthentication` option is enabled on either the role or the - role tag, the `nonce` holds no significance. This is ignored unless - using the ec2 auth method. -
    • -
-
    -
  • - iam_http_request_method - required - HTTP method used in the signed request. Currently only POST is - supported, but other methods may be supported in the future. This is - required when using the iam auth method. -
    • -
-
    -
  • - iam_request_url - required - Base64-encoded HTTP URL used in the signed request. Most likely just - `aHR0cHM6Ly9zdHMuYW1hem9uYXdzLmNvbS8=` (base64-encoding of - `https://sts.amazonaws.com/`) as most requests will probably use POST - with an empty URI. This is required when using the iam auth method. -
    • -
-
    -
  • - iam_request_body - required - Base64-encoded body of the signed request. Most likely - `QWN0aW9uPUdldENhbGxlcklkZW50aXR5JlZlcnNpb249MjAxMS0wNi0xNQ==` - which is the base64 encoding of - `Action=GetCallerIdentity&Version=2011-06-15`. This is required - when using the iam auth method. -
    • -
-
    -
  • - iam_request_headers - required - Base64-encoded, JSON-serialized representation of the - sts:GetCallerIdentity HTTP request - headers. The JSON serialization assumes that each header key maps to - either a string value or an - array of string values (though the length of that array will probably - only be one). If the `iam_server_id_header_value` is configured in Vault - for the aws auth mount, then the headers must include the - X-Vault-AWS-IAM-Server-ID header, its value must match the value - configured, and the header must be included in the signed headers. This - is required when using the iam auth method. -
    • -
-
- -
Returns
-
- -```javascript -{ - "auth": { - "renewable": true, - "lease_duration": 1800000, - "metadata": { - "role_tag_max_ttl": "0", - "instance_id": "i-de0f1344" - "ami_id": "ami-fce36983" - "role": "dev-role", - "auth_type": "ec2" - }, - "policies": [ - "default", - "dev", - ], - "accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e", - "client_token": "c9368254-3f21-aded-8a6f-7c818e81b17a" - }, - "warnings": null, - "data": null, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- - -### /auth/aws/roletag-blacklist/ -#### POST -
-
Description
-
- Places a valid role tag in a blacklist. This ensures that the role tag - cannot be used by any instance to perform a login operation again. Note - that if the role tag was previously used to perform a successful login, - placing the tag in the blacklist does not invalidate the already issued - token. -
- -
Method
-
POST
- -
URL
-
`/auth/aws/roletag-blacklist/`
- -
Parameters
-
-
    -
  • - role_tag - required - Role tag to be blacklisted. The tag can be supplied as-is. In order to - avoid any encoding problems, it can be base64 encoded. -
    • -
-
- -
Returns
-
`204` response code. -
-
- - -#### GET -
-
Description
-
- Returns the blacklist entry of a previously blacklisted role tag. -
- -
Method
-
GET
- -
URL
-
`/auth/aws/broletag-blacklist/`
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "expiration_time": "2016-04-25T10:35:20.127058773-04:00", - "creation_time": "2016-04-12T22:35:01.178348124-04:00" - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- - -#### LIST -
-
Description
-
- Lists all the role tags that are blacklisted. -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/aws/roletag-blacklist` (LIST) or `/auth/aws/roletag-blacklist?list=true` (GET)
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "keys": [ - "v1:09Vp0qGuyB8=:a=ami-fce3c696:p=default,prod:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/" - ] - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- - -#### DELETE -
-
Description
-
- Deletes a blacklisted role tag. -
- -
Method
-
DELETE
- -
URL
-
`/auth/aws/roletag-blacklist/`
- -
Parameters
-
- None. -
- -
Returns
-
`204` response code. -
-
- - -### /auth/aws/tidy/roletag-blacklist -#### POST -
-
Description
-
- Cleans up the entries in the blacklist based on expiration time on the - entry and `safety_buffer`. -
- -
Method
-
POST
- -
URL
-
`/auth/aws/tidy/roletag-blacklist`
- -
Parameters
-
-
    -
  • - safety_buffer - optional - The amount of extra time that must have passed beyond the `roletag` - expiration, before it is removed from the backend storage. Defaults to - 72h. -
    • -
-
- -
Returns
-
`204` response code. -
-
- - -### /auth/aws/identity-whitelist/ -#### GET -
-
Description
-
- Returns an entry in the whitelist. An entry will be created/updated by - every successful login. -
- -
Method
-
GET
- -
URL
-
`/auth/aws/identity-whitelist/`
- -
Parameters
-
-
    -
  • - instance_id - required - EC2 instance ID. A successful login operation from an EC2 instance gets - cached in this whitelist, keyed off of instance ID. -
    • -
-
- -
Returns
-
- -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "pending_time": "2016-04-14T01:01:41Z", - "expiration_time": "2016-05-05 10:09:16.67077232 +0000 UTC", - "creation_time": "2016-04-14 14:09:16.67077232 +0000 UTC", - "client_nonce": "5defbf9e-a8f9-3063-bdfc-54b7a42a1f95", - "role": "dev-role" - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- - -#### LIST -
-
Description
-
- Lists all the instance IDs that are in the whitelist of successful logins. -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/aws/identity-whitelist` (LIST) or `/auth/aws/identity-whitelist?list=true` (GET)
-
Parameters
-
- None. -
- -
Returns
-
`204` response code. - -```javascript -{ - "auth": null, - "warnings": null, - "data": { - "keys": [ - "i-aab47d37" - ] - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" -} -``` - -
-
- - -#### DELETE -
-
Description
-
- Deletes a cache of the successful login from an instance. -
- -
Method
-
DELETE
- -
URL
-
`/auth/aws/identity-whitelist/`
- -
Parameters
-
- None. -
- -
Returns
-
`204` response code. -
-
- - -### /auth/aws/tidy/identity-whitelist -#### POST -
-
Description
-
- Cleans up the entries in the whitelist based on expiration time and `safety_buffer`. -
- -
Method
-
POST
- -
URL
-
`/auth/aws/tidy/identity-whitelist`
- -
Parameters
-
-
    -
  • - safety_buffer - optional - The amount of extra time that must have passed beyond the identity - expiration, before it is removed from the backend storage. Defaults to - 72h. -
    • -
-
- -
Returns
-
`204` response code. -
-
+The AWS authentication backend has a full HTTP API. Please see the +[AWS Auth API](/api/auth/aws/index.html) for more +details. \ No newline at end of file diff --git a/website/source/docs/auth/cert.html.md b/website/source/docs/auth/cert.html.md index 4f094053e29d..0bfd90c37f82 100644 --- a/website/source/docs/auth/cert.html.md +++ b/website/source/docs/auth/cert.html.md @@ -124,350 +124,5 @@ of the header should be "X-Vault-Token" and the value should be the token. ## API -### /auth/cert/certs - -#### DELETE - -
-
Description
-
- Deletes the named role and CA cert from the backend mount. -
- -
Method
-
DELETE
- -
URL
-
`/auth/cert/certs/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Gets information associated with the named role. -
- -
Method
-
GET
- -
URL
-
`/auth/cert/certs/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----", - "display_name": "test", - "policies": "", - "allowed_names": "", - "ttl": 2764800 - }, - "warnings": null, - "auth": null - } - ``` - -
-
- -#### LIST - -
-
Description
-
- Lists configured certificate names. -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/cert/certs` (LIST) or `/auth/cert/certs?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "keys": ["cert1", "cert2"] - }, - "warnings": null, - "auth": null - } - ``` - -
-
- -#### POST - -
-
Description
-
- Sets a CA cert and associated parameters in a role name. -
- -
Method
-
POST
- -
URL
-
`/auth/cert/certs/`
- -
Parameters
-
-
    -
  • - certificate - required - The PEM-format CA certificate. -
    • -
  • - allowed_names - optional - Constrain the Common and Alternative Names in the client certificate - with a [globbed pattern](https://github.com/ryanuber/go-glob/blob/master/README.md#example). - Value is a comma-separated list of patterns. - Authentication requires at least one Name matching at least one pattern. - If not set, defaults to allowing all names. -
    • -
  • - policies - optional - A comma-separated list of policies to set on tokens issued when - authenticating against this CA certificate. -
    • -
  • - display_name - optional - The `display_name` to set on tokens issued when authenticating - against this CA certificate. If not set, defaults to the name - of the role. -
    • -
  • - ttl - optional - The TTL period of the token, provided as a number of seconds. If not - provided, the token is valid for the the mount or system default TTL - time, in that order. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /auth/cert/crls - -#### DELETE - -
-
Description
-
- Deletes the named CRL from the backend mount. -
- -
Method
-
DELETE
- -
URL
-
`/auth/cert/crls/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Gets information associated with the named CRL (currently, the serial - numbers contained within). As the serials can be integers up to an - arbitrary size, these are returned as strings. -
- -
Method
-
GET
- -
URL
-
`/auth/cert/crls/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "data": { - "serials": { - "13": {} - } - }, - "lease_duration": 0, - "lease_id": "", - "renewable": false, - "warnings": null - } - - ``` - -
-
- -#### POST - -
-
Description
-
- Sets a named CRL. -
- -
Method
-
POST
- -
URL
-
`/auth/cert/crls/`
- -
Parameters
-
-
    -
  • - crl - required - The PEM-format CRL. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /auth/cert/login - -#### POST - -
-
Description
-
- Log in and fetch a token. If there is a valid chain to a CA configured in - the backend and all role constraints are matched, a token will be issued. -
- -
Method
-
POST
- -
URL
-
`/auth/cert/login`
- -
Parameters
-
-
    -
  • - name - optional - Authenticate against only the named certificate role, returning its - policy list if successful. If not set, defaults to trying all - certificate roles and returning any one that matches. -
    • -
-
- -
Returns
-
- - ```javascript - { - "auth": { - "client_token": "ABCD", - "policies": ["web", "stage"], - "lease_duration": 3600, - "renewable": true, - } - } - ``` - -
-
- -### /auth/cert/config - -#### POST - -
-
Description
-
- Configuration options for the backend. -
- -
Method
-
POST
- -
URL
-
`/auth/cert/config`
- -
Parameters
-
-
    -
  • - disable_binding - optional - If set, during renewal, skips the matching of presented client identity with the client identity used during login. Defaults to false. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
+The TLS Certificate authentication backend has a full HTTP API. Please see the +[TLS Certificate API](/api/auth/cert/index.html) for more details. \ No newline at end of file diff --git a/website/source/docs/auth/ldap.html.md b/website/source/docs/auth/ldap.html.md index 4397a3abcfdf..b13601441e9b 100644 --- a/website/source/docs/auth/ldap.html.md +++ b/website/source/docs/auth/ldap.html.md @@ -263,524 +263,7 @@ default, foobar, zoobar It should be noted that user -> policy mapping happens at token creation time. And changes in group membership on the LDAP server will not affect tokens that have already been provisioned. To see these changes, old tokens should be revoked and the user should be asked to reauthenticate. ## API -### /auth/ldap/config -#### POST -
-
Description
-
- Configures the LDAP authentication backend. -
- -
Method
-
POST
- -
URL
-
`/auth/ldap/config`
- -
Parameters
-
-
    -
  • - url - required - The LDAP server to connect to. Examples: `ldap://ldap.myorg.com`, - `ldaps://ldap.myorg.com:636` -
    • -
-
    -
  • - starttls - optional - If true, issues a `StartTLS` command after establishing an unencrypted - connection. Defaults to `false`. -
    • -
-
    -
  • - tls_min_version - optional - Minimum TLS version to use. Accepted values are `tls10`, `tls11` or - `tls12`. Defaults to `tls12`. -
    • -
-
    -
  • - tls_max_version - optional - Maximum TLS version to use. Accepted values are `tls10`, `tls11` or - `tls12`. Defaults to `tls12`. -
    • -
-
    -
  • - insecure_tls - optional - If true, skips LDAP server SSL certificate verification - insecure, use - with caution! Defaults to `false`. -
    • -
-
    -
  • - certificate - optional - CA certificate to use when verifying LDAP server certificate, must be - x509 PEM encoded. -
    • -
-
    -
  • - binddn - optional - Distinguished name of object to bind when performing user search. - Example: `cn=vault,ou=Users,dc=example,dc=com` -
    • -
-
    -
  • - bindpass - optional - Password to use along with `binddn` when performing user search. -
    • -
-
    -
  • - userdn - optional - Base DN under which to perform user search. Example: - `ou=Users,dc=example,dc=com` -
    • -
-
    -
  • - userattr - optional - Attribute on user attribute object matching the username passed when - authenticating. Examples: `sAMAccountName`, `cn`, `uid` -
    • -
-
    -
  • - discoverdn - optional - Use anonymous bind to discover the bind DN of a user. Defaults to - `false`. -
    • -
-
    -
  • - deny_null_bind - optional - This option prevents users from bypassing authentication when providing - an empty password. Defaults to `true`. -
    • -
-
    -
  • - upndomain - optional - userPrincipalDomain used to construct the UPN string for the - authenticating user. The constructed UPN will appear as - `[username]@UPNDomain`. Example: `example.com`, which will cause - vault to bind as `username@example.com`. -
    • -
-
    -
  • - groupfilter - optional - Go template used when constructing the group membership query. The - template can access the following context variables: - \[`UserDN`, `Username`\]. The default is `(|(memberUid={{.Username}})(member={{.UserDN}})(uniqueMember={{.UserDN}}))`, - which is compatible with several common directory schemas. To support - nested group resolution for Active Directory, instead use the following - query: `(&(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))`. -
    • -
-
    -
  • - groupdn - optional - LDAP search base to use for group membership search. This can be the - root containing either groups or users. - Example: `ou=Groups,dc=example,dc=com` -
    • -
-
    -
  • - groupattr - optional - LDAP attribute to follow on objects returned by `groupfilter` in order - to enumerate user group membership. Examples: for groupfilter queries - returning _group_ objects, use: `cn`. For queries returning _user_ - objects, use: `memberOf`. The default is `cn`. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -#### GET -
-
Description
-
- Retrieves the LDAP configuration. -
- -
Method
-
GET
- -
URL
-
`/auth/ldap/config`
- -
Parameters
- None. - - -
Returns
-
- - ```javascript - { - "auth": null, - "warnings": null, - "wrap_info": null, - "data": { - "binddn": "cn=vault,ou=Users,dc=example,dc=com", - "bindpass": "", - "certificate": "", - "deny_null_bind": true, - "discoverdn": false, - "groupattr": "cn", - "groupdn": "ou=Groups,dc=example,dc=com", - "groupfilter": "(\u0026(objectClass=group)(member:1.2.840.113556.1.4.1941:={{.UserDN}}))", - "insecure_tls": false, - "starttls": false, - "tls_max_version": "tls12", - "tls_min_version": "tls12", - "upndomain": "", - "url": "ldaps://ldap.myorg.com:636", - "userattr": "samaccountname", - "userdn": "ou=Users,dc=example,dc=com" - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" - } - ``` - -
-
- -### /auth/ldap/groups -#### LIST -
-
Description
-
- Lists the existing groups in the backend. -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/ldap/groups` (LIST) or `/auth/ldap/groups?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "warnings": null, - "wrap_info": null, - "data": { - "keys": [ - "scientists", - "engineers" - ] - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" - } - ``` - -
-
- -### /auth/ldap/groups/[group_name] -#### POST -
-
Description
-
- Creates and updates the LDAP group policy associations. -
- -
Method
-
POST
- -
URL
-
`/auth/ldap/groups/[group_name]`
- -
Parameters
-
-
    -
  • - policies - required - Comma-separated list of policies associated to the group. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -#### GET -
-
Description
-
- Reads the LDAP group policy mappings. -
- -
Method
-
GET
- -
URL
-
`/auth/ldap/groups/[group_name]`
- -
Returns
-
- - ```javascript - { - "data": { - "policies": "admin,default" - }, - "renewable": false, - "lease_id": "" - "lease_duration": 0, - "warnings": null - } - ``` - -
-
- -#### DELETE -
-
Description
-
- Deletes an LDAP group. -
- -
Method
-
DELETE
- -
URL
-
`/auth/ldap/groups/[group_name]`
- -
Parameters
-
- None. -
- -
Returns
-
`204` response code. -
-
- -### /auth/ldap/users -#### LIST -
-
Description
-
- Lists the existing users in the backend. -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/ldap/users` (LIST) or `/auth/ldap/users?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "auth": null, - "warnings": null, - "wrap_info": null, - "data": { - "keys": [ - "tesla" - ] - }, - "lease_duration": 0, - "renewable": false, - "lease_id": "" - } - ``` - -
-
- -### /auth/ldap/users/[username] -#### POST -
-
Description
-
- Creates and updates the LDAP user group and policy mappings. -
- -
Method
-
POST
- -
URL
-
`/auth/ldap/users/[username]`
- -
Parameters
-
-
    -
  • - groups - optional - Comma-separated list of groups associated to the user. -
    • -
-
    -
  • - policies - optional - Comma-separated list of policies associated to the user. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -#### GET -
-
Description
-
- Reads the LDAP user. -
- -
Method
-
GET
- -
URL
-
`/auth/ldap/users/[username]`
- -
Returns
-
- - ```javascript - { - "data": { - "policies": "admins,default", - "groups": "" - }, - "renewable": false, - "lease_id": "" - "lease_duration": 0, - "warnings": null - } - ``` - -
-
- -#### DELETE -
-
Description
-
- Deletes an LDAP user. -
- -
Method
-
DELETE
- -
URL
-
`/auth/ldap/users/[username]`
- -
Parameters
-
- None. -
- -
Returns
-
`204` response code. -
-
- -### /auth/ldap/login/[username] -#### POST -
-
Description
-
- Creates and updates the LDAP user group and policy associations. -
- -
Method
-
POST
- -
URL
-
`/auth/ldap/login/[username]`
- -
Parameters
-
-
    -
  • - password - required - Password for the user. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": null, - "auth": { - "client_token": "c4f280f6-fdb2-18eb-89d3-589e2e834cdb", - "policies": [ - "admins", - "default" - ], - "metadata": { - "username": "mitchellh" - }, - "lease_duration": 0, - "renewable": false - } - } - ``` - -
-
+ +The LDAP authentication backend has a full HTTP API. Please see the +[LDAP auth backend API](/api/auth/ldap/index.html) for more +details. diff --git a/website/source/docs/auth/radius.html.md b/website/source/docs/auth/radius.html.md index 05a62c4c46d0..4cdc580eb82e 100644 --- a/website/source/docs/auth/radius.html.md +++ b/website/source/docs/auth/radius.html.md @@ -108,258 +108,7 @@ This is done through the `unregistered_user_policies` configuration parameter. ## API -### /auth/radius/config -#### POST - -
-
Description
-
- Configures the connection parameters and shard secret used to communicate with RADIUS -
- -
Method
-
POST
- -
URL
-
`/auth/radius/config`
- -
Parameters
-
-
    -
  • - host - required - The RADIUS server to connect to. Examples: `radius.myorg.com`, `127.0.0.1` -
    • -
  • - port - optional - The UDP port where the RADIUS server is listening on. Defaults is 1812 -
    • -
  • - secret - required - The RADIUS shared secret -
    • -
  • - unregistered_user_policies - optional - A Comma-Separated list of policies to be granted to unregistered users -
    • -
  • - dial_timeout - optional - Number of second to wait for a backend connection before timing out. Defaults is 10 -
    • -
  • - read_timeout - optional - Number of second to wait for a backend response before timing out. Defaults is 10 -
    • -
  • - nas_port - optional - The NAS-Port attribute of the RADIUS request. Defaults is 10 -
    • -
-
- -
Returns
-
`204` response code. -
-
- -### /auth/radius/users/[username] -#### POST - -
-
Description
-
- Registers a new user and maps a set of policies to it. - This path honors the distinction between the `create` and `update` capabilities inside ACL policies. -
- -
Method
-
POST
- -
URL
-
`/auth/radius/users/`
- -
Parameters
-
-
    -
  • - username - required - Username for this user. -
    • -
-
-
-
    -
  • - policies - optional - Comma-separated list of policies. - If set to empty string, only the `default` policy will be applicable to the user. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -#### GET -
-
Description
-
- Reads the properties of an existing username. -
- -
Method
-
GET
- -
URL
-
`/auth/radius/users/[username]`
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6", - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": { - "policies": "default,dev" - }, - "warnings": null -} -``` - -
-
- - -#### DELETE -
-
Description
-
- Deletes an existing username from the backend. -
- -
Method
-
DELETE
- -
URL
-
`/auth/radius/users/[username]`
- -
Parameters
-
- None. -
- -
Returns
-
`204` response code. -
-
- -### /auth/radius/login -### /auth/radius/login/[username] -#### POST -
-
Description
-
- Login with the username and password. -
- -
Method
-
POST
- -
URLS
-
`/auth/radius/login`
-
`/auth/radius/login/[username]`
- -
Parameters
-
-
    -
  • - username - required - Username for the authenticating user. -
    • -
  • - password - required - Password for the authenticating user. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": null, - "warnings": null, - "auth": { - "client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344", - "accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d", - "policies": ["default"], - "metadata": { - "username": "vishal" - }, - "lease_duration": 7200, - "renewable": true - } - } - ``` - -
-
- -### /auth/radius/users -#### LIST -
-
Description
-
-List the users registered with the backend. -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/radius/users` (LIST) `/auth/radius/users?list=true` (GET)
- -
Parameters
-
-None -
- -
Returns
-
- - ```javascript -[ - "devuser", - "produser" -] - ``` - -
-
- +The RADIUS authentication backend has a full HTTP API. Please see the +[RADIUS Auth API](/api/auth/radius/index.html) for more +details. diff --git a/website/source/docs/auth/token.html.md b/website/source/docs/auth/token.html.md index 713a3965201a..9718ad94db45 100644 --- a/website/source/docs/auth/token.html.md +++ b/website/source/docs/auth/token.html.md @@ -26,823 +26,20 @@ to tokens. ## Authentication -#### Via the CLI +### Via the CLI ``` $ vault auth ... ``` -#### Via the API +### Via the API The token is set directly as a header for the HTTP API. The name of the header should be "X-Vault-Token" and the value should be the token. ## API -### /auth/token/accessors -#### LIST - -
-
Description
-
- Lists token accessors. This requires `sudo` capability, and access to it - should be tightly controlled as the accessors can be used to revoke very - large numbers of tokens and their associated leases at once. -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/token/accessors` (LIST) or `/auth/token/accessors?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "keys": ["476ea048-ded5-4d07-eeea-938c6b4e43ec", "bb00c093-b7d3-b0e9-69cc-c4d85081165b"] - } - } - ``` - -
-
- -### /auth/token/create -### /auth/token/create-orphan -### /auth/token/create/[role_name] -#### POST - -
-
Description
-
- Creates a new token. Certain options are only available when called by a - root token. If used via the `/auth/token/create-orphan` endpoint, a root - token is not required to create an orphan token (otherwise set with the - `no_parent` option). If used with a role name in the path, the token will - be created against the specified role name; this may override options set - during this call. -
- -
Method
-
POST
- -
URLs
-
`/auth/token/create`
-
`/auth/token/create-orphan`
-
`/auth/token/create/`
- -
Parameters
-
-
    -
  • - id - optional - The ID of the client token. Can only be specified by a root token. - Otherwise, the token ID is a randomly generated UUID. -
    • -
  • - policies - optional - A list of policies for the token. This must be a subset of the - policies belonging to the token making the request, unless root. - If not specified, defaults to all the policies of the calling token. -
    • -
  • - meta - optional - A map of string to string valued metadata. This is passed through - to the audit backends. -
    • -
  • - no_parent - optional - If true and set by a root caller, the token will not have the - parent token of the caller. This creates a token with no parent. -
    • -
  • - no_default_policy - optional - If true the `default` policy will not be contained in this token's - policy set. -
    • -
  • - renewable - optional - Set to `false` to disable the ability of the token to be renewed past - its initial TTL. Specifying `true`, or omitting this option, will allow - the token to be renewable up to the system/mount maximum TTL. -
    • -
  • - lease - optional - DEPRECATED; use "ttl" instead. -
    • -
  • - ttl - optional - The TTL period of the token, provided as "1h", where hour is - the largest suffix. If not provided, the token is valid for the - [default lease TTL](/docs/configuration/index.html), or - indefinitely if the root policy is used. -
    • -
  • - explicit_max_ttl - optional - If set, the token will have an explicit max TTL set upon it. This - maximum token TTL *cannot* be changed later, and unlike with normal - tokens, updates to the system/mount max TTL value will have no effect - at renewal time -- the token will never be able to be renewed or used - past the value set at issue time. -
    • -
  • - display_name - optional - The display name of the token. Defaults to "token". -
    • -
  • - num_uses - optional - The maximum uses for the given token. This can be used to create - a one-time-token or limited use token. Defaults to 0, which has - no limit to the number of uses. -
    • -
  • - period - optional - If specified, the token will be periodic; it will have no maximum TTL - (unless an "explicit-max-ttl" is also set) but every renewal will use - the given period. Requires a root/sudo token to use. -
    • -
-
- -
Returns
-
- - ```javascript - { - "auth": { - "client_token": "ABCD", - "policies": ["web", "stage"], - "metadata": {"user": "armon"}, - "lease_duration": 3600, - "renewable": true, - } - } - ``` - -
-
- -### /auth/token/lookup[/token] -#### GET - -
-
Description
-
- Returns information about the client token provided in the request path. -
- -
Method
-
GET
- -
URL
-
`/auth/token/lookup/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "id": "ClientToken", - "policies": ["web", "stage"], - "path": "auth/github/login", - "meta": {"user": "armon", "organization": "hashicorp"}, - "display_name": "github-armon", - "num_uses": 0, - } - } - ``` - -
-
- -#### POST - -
-
Description
-
- Returns information about the client token provided in the request body. -
- -
Method
-
POST
- -
URL
-
`/auth/token/lookup`
- -
Parameters
-
-
    -
  • - token - required - Token to lookup. -
    • -
-
- -
Returns
-
- - ```javascript - { - "data": { - "id": "ClientToken", - "policies": ["web", "stage"], - "path": "auth/github/login", - "meta": {"user": "armon", "organization": "hashicorp"}, - "display_name": "github-armon", - "num_uses": 0, - } - } - ``` - -
-
- -### /auth/token/lookup-accessor[/accessor] -#### POST - -
-
Description
-
- Fetch the properties of the token associated with the accessor, except the token ID. - This is meant for purposes where there is no access to token ID but there is need - to fetch the properties of a token. -
- -
Method
-
POST
- -
URL
-
`/auth/token/lookup-accessor`
- -
Parameters
-
-
    -
  • - accessor - required - Accessor of the token to lookup. This can be part of the URL or the body. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": { - "creation_time": 1457533232, - "creation_ttl": 2764800, - "display_name": "token", - "id": "", - "meta": null, - "num_uses": 0, - "orphan": false, - "path": "auth/token/create", - "policies": ["default", "web"], - "ttl": 2591976 - }, - "warnings": null, - "auth": null - } - ``` - -
-
- -### /auth/token/lookup-self -#### GET - -
-
Description
-
- Returns information about the current client token. -
- -
Method
-
GET
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "accessor": "REDACTED", - "creation_time": 1484093665, - "creation_ttl": 3600, - "display_name": "github-armon", - "explicit_max_ttl": 0, - "id": "ClientToken", - "meta": {"user": "armon", "organization": "hashicorp"}, - "num_uses": 0, - "orphan": true, - "path": "auth/github/login", - "policies": ["web", "stage"], - "renewable": true, - "ttl": 3655 - } - } - ``` -
-
- -### /auth/token/renew[/token] -#### POST - -
-
Description
-
- Renews a lease associated with a token. This is used to prevent the - expiration of a token, and the automatic revocation of it. Token - renewal is possible only if there is a lease associated with it. -
- -
Method
-
POST
- -
URL
-
`/auth/token/renew`
- -
Parameters
-
-
    -
  • - token - required - Token to renew. This can be part of the URL or the body. -
    • -
-
-
-
    -
  • - increment - optional - An optional requested lease increment can be provided. This - increment may be ignored. -
    • -
-
- -
Returns
-
- - ```javascript - { - "auth": { - "client_token": "ABCD", - "policies": ["web", "stage"], - "metadata": {"user": "armon"}, - "lease_duration": 3600, - "renewable": true, - } - } - ``` - -
-
- -### /auth/token/renew-self -#### POST - -
-
Description
-
- Renews a lease associated with the calling token. This is used to prevent - the expiration of a token, and the automatic revocation of it. Token - renewal is possible only if there is a lease associated with it. -
- -
Method
-
POST
- -
URL
-
`/auth/token/renew-self`
- -
Parameters
-
-
    -
  • - increment - optional - An optional requested lease increment can be provided. This - increment may be ignored. -
    • -
-
- -
Returns
-
- - ```javascript - { - "auth": { - "client_token": "ABCD", - "policies": ["web", "stage"], - "metadata": {"user": "armon"}, - "lease_duration": 3600, - "renewable": true, - } - } - ``` - -
-
- -### /auth/token/revoke -#### POST - -
-
Description
-
- Revokes a token and all child tokens. When the token is revoked, - all secrets generated with it are also revoked. -
- -
Method
-
POST
- -
URL
-
`/auth/token/revoke`
- -
Parameters
-
-
    -
  • - token - required - Token to revoke. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -### /auth/token/revoke-accessor -#### POST - -
-
Description
-
- Revoke the token associated with the accessor and all the child tokens. - This is meant for purposes where there is no access to token ID but - there is need to revoke a token and its children. -
- -
Method
-
POST
- -
URL
-
`/auth/token/revoke-accessor`
- -
Parameters
-
-
    -
  • - accessor - required - Accessor of the token. -
    • -
-
- -
Returns
-
- A `204` response code. -
-
- -### /auth/token/revoke-orphan[/token] -#### POST - -
-
Description
-
- Revokes a token but not its child tokens. When the token is revoked, all - secrets generated with it are also revoked. All child tokens are orphaned, - but can be revoked sub-sequently using `/auth/token/revoke/`. This is a - root-protected endpoint. -
- -
Method
-
POST
- -
URL
-
`/auth/token/revoke-orphan`
- -
Parameters
-
-
    -
  • - token - required - Token to revoke. This can be part of the URL or the body. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -### /auth/token/revoke-self/ -#### POST - -
-
Description
-
- Revokes the token used to call it and all child tokens. - When the token is revoked, all dynamic secrets generated - with it are also revoked. -
- -
Method
-
POST
- -
URL
-
`/auth/token/revoke-self`
- -
Parameters
-
- None -
- -
Returns
-
`204` response code. -
-
- -### /auth/token/roles/[role_name] - -#### DELETE - -
-
Description
-
- Deletes the named role. -
- -
Method
-
DELETE
- -
URL
-
`/auth/token/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- A `204` response code. -
-
- -#### GET - -
-
Description
-
- Fetches the named role configuration. -
- -
Method
-
GET
- -
URL
-
`/auth/token/roles/`
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript -{ - "request_id": "075a19cd-4e56-a3ca-d956-7609819831ec", - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": { - "allowed_policies": [ - "dev" - ], - "disallowed_policies": [], - "explicit_max_ttl": 0, - "name": "nomad", - "orphan": false, - "path_suffix": "", - "period": 0, - "renewable": true - }, - "warnings": null -} - ``` - -
-
- -#### LIST - -
-
Description
-
- Lists available roles. -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/token/roles` (LIST) or `/auth/token/roles?list=true` (GET)
- -
Parameters
-
- None -
- -
Returns
-
- - ```javascript - { - "data": { - "keys": ["role1", "role2"] - } - } - ``` - -
-
- -#### POST - -
-
Description
-
- Creates (or replaces) the named role. Roles enforce specific behavior when - creating tokens that allow token functionality that is otherwise not - available or would require `sudo`/root privileges to access. Role - parameters, when set, override any provided options to the `create` - endpoints. The role name is also included in the token path, allowing all - tokens created against a role to be revoked using the `sys/revoke-prefix` - endpoint. -
- -
Method
-
POST
- -
URL
-
`/auth/token/roles/`
- -
Parameters
-
-
    -
  • - allowed_policies - optional - If set, tokens can be created with any subset of the policies in this - list, rather than the normal semantics of tokens being a subset of the - calling token's policies. The parameter is a comma-delimited string of - policy names. If at creation time `no_default_policy` is not set and - `"default"` is not contained in `disallowed_policies`, the `"default"` - policy will be added to the created token automatically. -
    • -
  • - disallowed_policies - optional - If set, successful token creation via this role will require that no - policies in the given list are requested. The parameter is a - comma-delimited string of policy names. Adding `"default"` to this list - will prevent `"default"` from being added automatically to created - tokens. -
    • -
  • - orphan - optional - If `true`, tokens created against this policy will be orphan tokens - (they will have no parent). As such, they will not be automatically - revoked by the revocation of any other token. -
    • -
  • - period - optional - If set, tokens created against this role will not have a maximum - lifetime. Instead, they will have a fixed TTL that is refreshed with - each renewal. So long as they continue to be renewed, they will never - expire. The parameter is an integer duration of seconds. Tokens issued - track updates to the role value; the new period takes effect upon next - renew. This cannot be used in conjunction with `explicit_max_ttl`. -
    • -
  • - renewable - optional - Set to `false` to disable the ability of token created against this - role to be renewed past their initial TTL. Defaults to `true`, which - allows tokens to be renewed up to the system/mount maximum TTL. -
    • -
  • - path_suffix - optional - If set, tokens created against this role will have the given suffix as - part of their path in addition to the role name. This can be useful in - certain scenarios, such as keeping the same role name in the future but - revoking all tokens created against it before some point in time. The - suffix can be changed, allowing new callers to have the new suffix as - part of their path, and then tokens with the old suffix can be revoked - via `sys/revoke-prefix`. -
    • -
  • - explicit_max_ttl - optional - If set, tokens created with this role have an explicit max TTL set upon - them. This maximum token TTL *cannot* be changed later, and unlike with - normal tokens, updates to the role or the system/mount max TTL value - will have no effect at renewal time -- the token will never be able to - be renewed or used past the value set at issue time. This cannot be - used in conjunction with `period`. -
    • -
-
- -
Returns
-
- A `204` return code. -
-
- -### /auth/token/tidy -#### POST - -
-
Description
-
- 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 backend so should be used sparingly. -
- -
Method
-
POST
- -
URL
-
`/auth/token/tidy`
- -
Parameters
-
- None -
- -
Returns
-
`204` response code. -
-
- - +The Token authentication backend has a full HTTP API. Please see the +[Token auth backend API](/api/auth/token/index.html) for more +details. diff --git a/website/source/docs/auth/userpass.html.md b/website/source/docs/auth/userpass.html.md index 7c697c18d04d..91f30c30c06c 100644 --- a/website/source/docs/auth/userpass.html.md +++ b/website/source/docs/auth/userpass.html.md @@ -98,303 +98,7 @@ necessary. ## API -### /auth/userpass/users/[username] -#### POST - -
-
Description
-
- Create a new user or update an existing user. - This path honors the distinction between the `create` and `update` capabilities inside ACL policies. -
- -
Method
-
POST
- -
URL
-
`/auth/userpass/users/`
- -
Parameters
-
-
    -
  • - username - required - Username for this user. -
    • -
-
-
-
    -
  • - password - required - Password for this user. -
    • -
-
-
-
    -
  • - policies - optional - Comma-separated list of policies. - If set to empty string, only the `default` policy will be applicable to the user. -
    • -
-
-
-
    -
  • - ttl - optional - The lease duration which decides login expiration. -
    • -
-
-
-
    -
  • - max_ttl - optional - Maximum duration after which login should expire. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -#### GET -
-
Description
-
- Reads the properties of an existing username. -
- -
Method
-
GET
- -
URL
-
`/auth/userpass/users/[username]`
- -
Parameters
-
- None. -
- -
Returns
-
- -```javascript -{ - "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6", - "lease_id": "", - "lease_duration": 0, - "renewable": false, - "data": { - "max_ttl": 0, - "policies": "default,dev", - "ttl": 0 - }, - "warnings": null -} -``` - -
-
- - -#### DELETE -
-
Description
-
- Deletes an existing username from the backend. -
- -
Method
-
DELETE
- -
URL
-
`/auth/userpass/users/[username]`
- -
Parameters
-
- None. -
- -
Returns
-
`204` response code. -
-
- - - - -### /auth/userpass/users/[username]/password -#### POST -
-
Description
-
- Update the password for an existing user. -
- -
Method
-
POST
- -
URL
-
`/auth/userpass/users//password`
- -
Parameters
-
-
    -
  • - username - required - Username for this user. -
    • -
-
-
-
    -
  • - password - required - Password for this user. -
    • -
-
- -
Returns
-
`204` response code. -
-
- -### /auth/userpass/users/[username]/policies -#### POST -
-
Description
-
- Update the policies associated with an existing user. -
- -
Method
-
POST
- -
URL
-
`/auth/userpass/users//policies`
- -
Parameters
-
-
    -
  • - username - required - Username for this user. -
    • -
-
-
-
    -
  • - policies - optional - Comma-separated list of policies. - If this is field is not supplied, the policies will be unchanged. - If set to empty string, only the `default` policy will be applicable to the user. -
    • -
-
- -
Returns
-
`204` response code. -
-
- - -### /auth/userpass/login/[username] -#### POST -
-
Description
-
- Login with the username and password. -
- -
Method
-
POST
- -
URL
-
`/auth/userpass/login/`
- -
Parameters
-
-
    -
  • - password - required - Password for this user. -
    • -
-
- -
Returns
-
- - ```javascript - { - "lease_id": "", - "renewable": false, - "lease_duration": 0, - "data": null, - "warnings": null, - "auth": { - "client_token": "64d2a8f2-2a2f-5688-102b-e6088b76e344", - "accessor": "18bb8f89-826a-56ee-c65b-1736dc5ea27d", - "policies": ["default"], - "metadata": { - "username": "vishal" - }, - "lease_duration": 7200, - "renewable": true - } - } - ``` - -
-
- -### /auth/userpass/users -#### LIST -
-
Description
-
-List the users registered with the backend. -
- -
Method
-
LIST/GET
- -
URL
-
`/auth/userpass/users` (LIST) `/auth/userpass/users?list=true` (GET)
- -
Parameters
-
-None -
- -
Returns
-
- - ```javascript -[ - "devuser", - "produser" -] - ``` - -
-
- +The Username & Password authentication backend has a full HTTP API. Please see the +[Userpass auth backend API](/api/auth/userpass/index.html) for more +details. diff --git a/website/source/layouts/api.erb b/website/source/layouts/api.erb index ee61f5ea5d06..0e54de6dc28f 100644 --- a/website/source/layouts/api.erb +++ b/website/source/layouts/api.erb @@ -10,19 +10,12 @@
- - > Secret Backends