diff --git a/content/vault/global/partials/important-changes/summary-tables/1_20.mdx b/content/vault/global/partials/important-changes/summary-tables/1_20.mdx index 4b03ba39b9..a83d30a418 100644 --- a/content/vault/global/partials/important-changes/summary-tables/1_20.mdx +++ b/content/vault/global/partials/important-changes/summary-tables/1_20.mdx @@ -30,6 +30,6 @@ Found | Fixed | Workaround | Edition | Issue 1.20.0 | 1.20.1 | **Yes** | All | [GUI navigation error for KV v2 secret paths containing underscores](/vault/docs/v1.20.x/updates/important-changes#ui-kvv2-underscore-secrets) 1.18.4 | No | **Yes** | All | [Failing credential refresh for Snowflake DB secrets engine key pair authentication](/vault/docs/v1.20.x/updates/important-changes#snowflake-keypair-refresh) 1.20.0 | 1.20.1 | **Yes** | All | [Duplicate LDAP password rotations on standby node check-in](/vault/docs/v1.20.x/updates/important-changes#ldap-checkin) -1.19.0 | No | No | All | [Writing configuration to local auth mount (ldap, aws, gcp, azure) ignores local flag](/vault/docs/v1.20.x/updates/important-changes#local-auth-known-issue) -1.19.0 | No | **Yes** | Enterprise | [Missed events with multiple event clients](/vault/docs/v1.20.x/updates/important-changes#missed-events) +1.20.0 | No | No | All | [Writing configuration to local auth mount (ldap, aws, gcp, azure) ignores local flag](/vault/docs/v1.20.x/updates/important-changes#local-auth-known-issue) +1.20.0 | No | **Yes** | Enterprise | [Missed events with multiple event clients](/vault/docs/v1.20.x/updates/important-changes#missed-events) 1.20.0 | No | No | Enterprise | [Full seal rewraps occur on DR/PR failover with multi-seal enabled](/vault/docs/v1.20.x/updates/important-changes#multi-seal-rewrap) \ No newline at end of file diff --git a/content/vault/global/partials/important-changes/summary-tables/1_21.mdx b/content/vault/global/partials/important-changes/summary-tables/1_21.mdx new file mode 100644 index 0000000000..5f644e5c43 --- /dev/null +++ b/content/vault/global/partials/important-changes/summary-tables/1_21.mdx @@ -0,0 +1,16 @@ +### Breaking changes + +Introduced | Recommendations | Edition | Change +---------- | --------------- | ---------- | ------ +1.21.0 | **Yes** | All | [Audiences required for Kubernetes authentication roles](/vault/docs/v1.21.x/updates/important-changes#k8-audience-required) + + +### New behavior + +None. + +### Known issues + +Found | Fixed | Workaround | Edition | Issue +------ |--------| ---------- | ---------- | ----- +1.21.0 | No | **Yes** | Enterprise | [Missed events with multiple event clients](/vault/docs/v1.21.x/updates/important-changes#missed-events) diff --git a/content/vault/v1.18.x/content/docs/auth/login-mfa/index.mdx b/content/vault/v1.18.x/content/docs/auth/login-mfa/index.mdx index dfff6f3dc4..d6d0798f9f 100644 --- a/content/vault/v1.18.x/content/docs/auth/login-mfa/index.mdx +++ b/content/vault/v1.18.x/content/docs/auth/login-mfa/index.mdx @@ -254,7 +254,7 @@ $ vault write identity/mfa/method/totp \ digits=6 ``` -Using the TOTP `method_id` and an `entity_id` from after a sucessful MFA login. Use these to generate a QR code. +Vault generates an `entity_id` for users after a successful login. Use the TOTP `method_id` and the `entity_id` of the target user to generate a QR code. ```shell-session $ vault write -field=barcode \ diff --git a/content/vault/v1.19.x/content/docs/auth/ldap.mdx b/content/vault/v1.19.x/content/docs/auth/ldap.mdx index 27dda923f6..f1d8fd0072 100644 --- a/content/vault/v1.19.x/content/docs/auth/ldap.mdx +++ b/content/vault/v1.19.x/content/docs/auth/ldap.mdx @@ -230,7 +230,7 @@ of the root credential until the field is reset to `false`. If you use `rotation_period`, setting `disable_automated_rotation` also resets the credential TTL. -For more details on rotating root credentials in the Azure plugin, refer to the +For more details on rotating root credentials in the LDAP plugin, refer to the [Root credential rotation](/vault/api-docs/auth/ldap#rotate-root) API docs. @include 'rotation-manager-logging.mdx' diff --git a/content/vault/v1.19.x/content/docs/auth/login-mfa/index.mdx b/content/vault/v1.19.x/content/docs/auth/login-mfa/index.mdx index 8f71cbb7d2..683ad116bd 100644 --- a/content/vault/v1.19.x/content/docs/auth/login-mfa/index.mdx +++ b/content/vault/v1.19.x/content/docs/auth/login-mfa/index.mdx @@ -258,7 +258,7 @@ $ vault write identity/mfa/method/totp \ digits=6 ``` -Using the TOTP `method_id` and an `entity_id` from after a sucessful MFA login. Use these to generate a QR code. +Vault generates an `entity_id` for users after a successful login. Use the TOTP `method_id` and the `entity_id` of the target user to generate a QR code. ```shell-session $ vault write -field=barcode \ diff --git a/content/vault/v1.19.x/content/docs/secrets/ldap.mdx b/content/vault/v1.19.x/content/docs/secrets/ldap.mdx index 76c13f1116..abe947a910 100644 --- a/content/vault/v1.19.x/content/docs/secrets/ldap.mdx +++ b/content/vault/v1.19.x/content/docs/secrets/ldap.mdx @@ -155,7 +155,7 @@ of the root credential until the field is reset to `false`. If you use `rotation_period`, setting `disable_automated_rotation` also resets the credential TTL. -For more details on rotating root credentials in the Azure plugin, refer to the +For more details on rotating root credentials in the LDAP plugin, refer to the [Root credential rotation](/vault/api-docs/secret/ldap#rotate-root) API docs. @include 'rotation-manager-logging.mdx' diff --git a/content/vault/v1.20.x/content/api-docs/system/secrets-sync.mdx b/content/vault/v1.20.x/content/api-docs/system/secrets-sync.mdx index f50aa72fc4..d1a2183fa3 100644 --- a/content/vault/v1.20.x/content/api-docs/system/secrets-sync.mdx +++ b/content/vault/v1.20.x/content/api-docs/system/secrets-sync.mdx @@ -403,7 +403,7 @@ This endpoint creates a destination to synchronize secrets with the GCP Secret M store replicated secrets. Note that secrets remain globally readable regardless of the selected locations. - `locational_kms_keys` `(map: nil)` - A map of location names to KMS key names to leverage customer-managed encryption keys for - encryption at rest. Each pair follows the format `location_name=encryption_key_resource_ID`. Refer to the + encryption at rest. Each pair follows the format `location_name=encryption_key_resource_name`. Refer to the [sample payloads](#sample-payloads) for more details. - `secret_name_template` `(string: "")` - Template to use when generating the secret names on the external system. diff --git a/content/vault/v1.20.x/content/docs/auth/ldap.mdx b/content/vault/v1.20.x/content/docs/auth/ldap.mdx index 1082ade2a6..d44f904f8d 100644 --- a/content/vault/v1.20.x/content/docs/auth/ldap.mdx +++ b/content/vault/v1.20.x/content/docs/auth/ldap.mdx @@ -240,7 +240,7 @@ of the root credential until the field is reset to `false`. If you use `rotation_period`, setting `disable_automated_rotation` also resets the credential TTL. -For more details on rotating root credentials in the Azure plugin, refer to the +For more details on rotating root credentials in the LDAP plugin, refer to the [Root credential rotation](/vault/api-docs/auth/ldap#rotate-root) API docs. @include 'rotation-manager-logging.mdx' diff --git a/content/vault/v1.20.x/content/docs/auth/login-mfa/index.mdx b/content/vault/v1.20.x/content/docs/auth/login-mfa/index.mdx index 8f71cbb7d2..683ad116bd 100644 --- a/content/vault/v1.20.x/content/docs/auth/login-mfa/index.mdx +++ b/content/vault/v1.20.x/content/docs/auth/login-mfa/index.mdx @@ -258,7 +258,7 @@ $ vault write identity/mfa/method/totp \ digits=6 ``` -Using the TOTP `method_id` and an `entity_id` from after a sucessful MFA login. Use these to generate a QR code. +Vault generates an `entity_id` for users after a successful login. Use the TOTP `method_id` and the `entity_id` of the target user to generate a QR code. ```shell-session $ vault write -field=barcode \ diff --git a/content/vault/v1.20.x/content/docs/license/product-usage-reporting.mdx b/content/vault/v1.20.x/content/docs/license/product-usage-reporting.mdx index a976130aec..341b56394e 100644 --- a/content/vault/v1.20.x/content/docs/license/product-usage-reporting.mdx +++ b/content/vault/v1.20.x/content/docs/license/product-usage-reporting.mdx @@ -169,9 +169,15 @@ All of these metrics are numerical, and contain no sensitive values or additiona | `vault.secret.engine.activedirectory.count` | The total number of Active Directory secret engines in Vault. | | `vault.secret.engine.alicloud.count` | The total number of Alicloud secret engines in Vault. | | `vault.secret.engine.aws.count` | The total number of AWS secret engines in Vault. | +| `vault.secret.engine.aws.dynamic.role.count` | The total number of AWS dynamic roles in Vault. | +| `vault.secret.engine.aws.static.role.count` | The total number of AWS static roles in Vault. | | `vault.secret.engine.azure.count` | The total number of Azure secret engines in Vault. | +| `vault.secret.engine.azure.dynamic.role.count` | The total number of Azure dynamic roles in Vault. | | `vault.secret.engine.consul.count` | The total number of Consul secret engines in Vault. | | `vault.secret.engine.gcp.count` | The total number of GCP secret engines in Vault. | +| `vault.secret.engine.gcp.impersonated.account.count` | The total number of GCP impersonated accounts in Vault. | +| `vault.secret.engine.gcp.roleset.count` | The total number of GCP rolesets in Vault. | +| `vault.secret.engine.gcp.static.role.count` | The total number of GCP static roles in Vault. | | `vault.secret.engine.gcpkms.count` | The total number of GCPKMS secret engines in Vault. | | `vault.secret.engine.kubernetes.count` | The total number of Kubernetes secret engines in Vault. | | `vault.secret.engine.cassandra.count` | The total number of Cassandra secret engines in Vault. | @@ -181,11 +187,15 @@ All of these metrics are numerical, and contain no sensitive values or additiona | `vault.secret.engine.mongodb.count` | The total number of MongoDB secret engines in Vault. | | `vault.secret.engine.mongodbatlas.count` | The total number of MongoDBAtlas secret engines in Vault. | | `vault.secret.engine.mssql.count` | The total number of MSSql secret engines in Vault. | -| `vault.secret.engine.mysql.count` | The total number of MySQL secret engines in Vault. | +| `vault.secret.engine.mysql.count` | The total number of MySQL secret engines in Vault. | | `vault.secret.engine.postgresql.count` | The total number of Postgresql secret engines in Vault. | | `vault.secret.engine.nomad.count` | The total number of Nomad secret engines in Vault. | | `vault.secret.engine.ldap.count` | The total number of LDAP secret engines in Vault. | +| `vault.secret.engine.ldap.dynamic.role.count` | The total number of LDAP dynamic roles in Vault. | +| `vault.secret.engine.ldap.static.role.count` | The total number of LDAP static roles in Vault. | | `vault.secret.engine.openldap.count` | The total number of OpenLDAP secret engines in Vault. | +| `vault.secret.engine.openldap.dynamic.role.count` | The total number of OpenLDAP dynamic roles in Vault. | +| `vault.secret.engine.openldap.static.role.count` | The total number of OpenLDAP static roles in Vault. | | `vault.secret.engine.pki.count` | The total number of PKI secret engines in Vault. | | `vault.secret.engine.rabbitmq.count` | The total number of RabbitMQ secret engines in Vault. | | `vault.secret.engine.ssh.count` | The total number of SSH secret engines in Vault. | @@ -194,6 +204,8 @@ All of these metrics are numerical, and contain no sensitive values or additiona | `vault.secret.engine.transform.count` | The total number of Transform secret engines in Vault. | | `vault.secret.engine.transit.count` | The total number of Transit secret engines in Vault. | | `vault.secret.engine.database.count` | The total number of Database secret engines in Vault. | +| `vault.secret.engine.database.dynamic.role.count` | The total number of Database dynamic roles in Vault. | +| `vault.secret.engine.database.static.role.count` | The total number of Database static roles in Vault. | | `vault.secret.engine.plugin.count` | The total number of custom plugin secret engines in Vault. | | `vault.secretsync.sources.count` | The total number of secret sources configured for secret sync. | | `vault.secretsync.destinations.count` | The total number of secret destinations configured for secret sync. | diff --git a/content/vault/v1.20.x/content/docs/sync/gcpsm.mdx b/content/vault/v1.20.x/content/docs/sync/gcpsm.mdx index 6f44c07b4c..64fdf08c5b 100644 --- a/content/vault/v1.20.x/content/docs/sync/gcpsm.mdx +++ b/content/vault/v1.20.x/content/docs/sync/gcpsm.mdx @@ -95,7 +95,9 @@ Prerequisites: ```shell-session $ vault write sys/sync/destinations/gcp-sm/my-dest/associations/set \ mount='my-kv' \ - secret_name='my-secret' + secret_name='my-secret' \ + replication_locations='us-east1' \ + locational_kms_keys='us-east1=projects/my-project/locations/us-east1/keyRings/my-east-keyring/cryptoKeys/my-east-key' ``` **Output:** @@ -137,7 +139,30 @@ corresponds with the planned replication policy. The key rings and keys must be When using a global KMS key, it must be the only key set on the destination and the replication locations must remain unset, meaning it can only be used with using GCP's automatic replication. When specifying regional keys, a key must be set for each region in the -replication location list. GCP key names are expected in the format of the entire resource ID, e.g. `projects//locations//keyRings//cryptoKeys/`. See the [API](#api) section for more details. +replication location list. + +You must specify GCP key names using the entire resource name. For example, +`projects//locations//keyRings//cryptoKeys/`. +GCP key names, including the `keyRings` and `cryptoKeys` segments, are +case-sensitive. +Refer to the [Secrets sync API examples](/vault/api-docs/system/secrets-sync#sync-secrets-to-gcp-with-a-global-kms-key) for more details. + +A service agent identity for the `secretsmanager` API must be created for GCP keys. +The correct IAM policy bindings must be granted to the service agents +with the `cloudkms.cryptoKeyEncrypterDecrypter` role. Be aware that you must +grant the CloudKMS role to the service agent for each key and its corresponding +replication location you want to use. + +Refer to the [GCP documentation](https://cloud.google.com/secret-manager/docs/cmek) +for more details on setting up your GCP key resources. + + + +Failure to establish the proper IAM policy bindings for all encryption keys and replication locations +typically causes GCP to silently ignore the customer-managed keys and fall back to Google-managed keys. Ensure you are using customer-managed encryption by validating the encryption type value on +the secrets from the gcloud CLI or the web console. + + ## Permissions diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/alicloud.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/alicloud.mdx new file mode 100644 index 0000000000..9dd6809676 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/alicloud.mdx @@ -0,0 +1,200 @@ +--- +layout: api +page_title: AliCloud - Auth Methods - HTTP API +description: This is the API documentation for the Vault AliCloud auth method. +--- + +# AliCloud auth method (API) + +This is the API documentation for the Vault AliCloud auth method. For +general information about the usage and operation of the AliCloud method, please +see the [Vault AliCloud auth method documentation](/vault/docs/auth/alicloud). + +This documentation assumes the AliCloud auth method is mounted at the `/auth/alicloud` +path in Vault. Since it is possible to enable auth methods at any location, +please update your API calls accordingly. + +## Create/Update role + +Registers a role. Only entities using the role registered using this endpoint +will be able to perform the login operation. + +| Method | Path | +| :----- | :-------------------------- | +| `POST` | `/auth/alicloud/role/:role` | + +### Parameters + +- `role` `(string: )` - Name of the role. Must correspond with the name of the role reflected in the arn. +- `arn` `(string: )` - The role's arn. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "arn": "acs:ram::5138828231865461:role/dev-role", + "policies": ["dev", "prod"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/alicloud/role/dev-role +``` + +## Read role + +Returns the previously registered role configuration. + +| Method | Path | +| :----- | :-------------------------- | +| `GET` | `/auth/alicloud/role/:role` | + +### Parameters + +- `role` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/alicloud/role/dev-role +``` + +### Sample response + +```json +{ + "data": { + "arn": "acs:ram::5138828231865461:role/dev-role", + "policies": ["default", "dev", "prod"], + "ttl": 1800000, + "max_ttl": 1800000, + "period": 0 + } +} +``` + +## List roles + +Lists all the roles that are registered with the method. + +| Method | Path | +| :----- | :--------------------- | +| `LIST` | `/auth/alicloud/roles` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/alicloud/roles +``` + +### Sample response + +```json +{ + "data": { + "keys": ["dev-role", "prod-role"] + } +} +``` + +## Delete role + +Deletes the previously registered role. + +| Method | Path | +| :------- | :-------------------------- | +| `DELETE` | `/auth/alicloud/role/:role` | + +### Parameters + +- `role` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/alicloud/role/dev-role +``` + +## Login + +Fetch a token. This endpoint verifies the signature of the signed +GetCallerIdentity request. + +| Method | Path | +| :----- | :--------------------- | +| `POST` | `/auth/alicloud/login` | + +### Parameters + +- `role` `(string: )` - Name of the role. +- `identity_request_url` `(string: )` - Base64-encoded HTTP URL used in + the signed request. +- `identity_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). + +### Sample payload + +```json +{ + "role": "dev-role", + "identity_request_url": "aWRlbnRpdHlabrVxdWVzdF91cmw=", + "identity_request_headers": "aWRlimRpdHlfcmVxdWVzdF9oZWFkZXJz" +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/alicloud/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", + "account_id": "5138828231865461", + "user_id": "216959339000654321", + "role_id": "4657-abcd", + "arn": "acs:ram::5138828231865461:assumed-role/dev-role/vm-ram-i-rj978rorvlg76urhqh7q", + "identity_type": "assumed-role", + "principal_id": "vm-ram-i-rj978rorvlg76urhqh7q", + "request_id": "D6E46F10-F26C-4AA0-BB69-FE2743D9AE62", + "role_name": "dev-role" + }, + "policies": ["default", "dev"], + "accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e", + "client_token": "d9368254-3f21-aded-8a6f-7c818e81b17a" + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/approle.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/approle.mdx new file mode 100644 index 0000000000..1f316073a0 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/approle.mdx @@ -0,0 +1,716 @@ +--- +layout: api +page_title: AppRole - Auth Methods - HTTP API +description: This is the API documentation for the Vault AppRole auth method. +--- + +# AppRole auth method (API) + +This is the API documentation for the Vault AppRole auth method. For +general information about the usage and operation of the AppRole method, please +see the [Vault AppRole method documentation](/vault/docs/auth/approle). + +This documentation assumes the AppRole method is mounted at the `/auth/approle` +path in Vault. Since it is possible to enable auth methods at any location, +please update your API calls accordingly. + +## List roles + +This endpoint returns a list the existing AppRoles in the method. + +| Method | Path | +| :----- | :------------------- | +| `LIST` | `/auth/approle/role` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/approle/role +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": ["dev", "prod", "test"] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Create/Update AppRole + +Creates a new AppRole or updates an existing AppRole. This endpoint +supports both `create` and `update` capabilities. There can be one or more +constraints enabled on the role. It is required to have at least one of them +enabled while creating or updating a role. + +| Method | Path | +| :----- | :------------------------------ | +| `POST` | `/auth/approle/role/:role_name` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes, accepted characters +include a-Z, 0-9, space, hyphen, underscore and periods. +- `bind_secret_id` `(bool: true)` - Require `secret_id` to be presented when + logging in using this AppRole. +- `secret_id_bound_cidrs` `(array: [])` - Comma-separated string or list of CIDR + blocks; if set, specifies blocks of IP addresses which can perform the login + operation. +- `secret_id_num_uses` `(integer: 0)` - Number of times any particular SecretID + can be used to fetch a token from this AppRole, after which the SecretID by default + will expire. A value of zero will allow unlimited uses. + However, this option may be overridden by the request's 'num_uses' field when generating a SecretID. +- `secret_id_ttl` `(string: "")` - Duration in either an integer number of + seconds (`3600`) or an integer time unit (`60m`) after which by default any SecretID + expires. A value of zero will allow the SecretID to not expire. + However, this option may be overridden by the request's 'ttl' field when generating a SecretID. +- `local_secret_ids` `(bool: false)` - If set, the secret IDs generated + using this role will be cluster local. This can only be set during role + creation and once set, it can't be reset later. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "token_type": "batch", + "token_ttl": "10m", + "token_max_ttl": "15m", + "token_policies": ["default"], + "period": 0, + "bind_secret_id": true +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/approle/role/application1 +``` + +## Read AppRole + +Reads the properties of an existing AppRole. + +| Method | Path | +| :----- | :------------------------------ | +| `GET` | `/auth/approle/role/:role_name` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/approle/role/application1 +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "token_ttl": 1200, + "token_max_ttl": 1800, + "secret_id_ttl": 600, + "secret_id_num_uses": 40, + "token_policies": ["default"], + "period": 0, + "bind_secret_id": true, + "secret_id_bound_cidrs": [] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Delete AppRole + +Deletes an existing AppRole from the method. + +| Method | Path | +| :------- | :------------------------------ | +| `DELETE` | `/auth/approle/role/:role_name` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/approle/role/application1 +``` + +## Read AppRole role ID + +Reads the RoleID of an existing AppRole. + +| Method | Path | +| :----- | :-------------------------------------- | +| `GET` | `/auth/approle/role/:role_name/role-id` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/approle/role/application1/role-id +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "role_id": "e5a7b66e-5d08-da9c-7075-71984634b882" + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Update AppRole role ID + +Updates the RoleID of an existing AppRole to a custom value. + +| Method | Path | +| :----- | :-------------------------------------- | +| `POST` | `/auth/approle/role/:role_name/role-id` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes. +- `role_id` `(string: )` - Value to be set as RoleID. + +### Sample payload + +```json +{ + "role_id": "custom-role-id" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/approle/role/application1/role-id +``` + +## Generate new secret ID + +Generates and issues a new SecretID on an existing AppRole. Similar to +tokens, the response will also contain a `secret_id_accessor` value which can +be used to read the properties of the SecretID without divulging the SecretID +itself, and also to delete the SecretID from the AppRole. + +| Method | Path | +| :----- | :---------------------------------------- | +| `POST` | `/auth/approle/role/:role_name/secret-id` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes. +- `metadata` `(string: "")` - Metadata to be tied to the SecretID. This should be + a JSON-formatted string containing the metadata in key-value pairs. This + metadata will be set on tokens issued with this SecretID, and is logged in + audit logs _in plaintext_. +- `cidr_list` `(array: [])` - Comma separated string or list of CIDR blocks + enforcing secret IDs to be used from specific set of IP addresses. If + `secret_id_bound_cidrs` is set on the role, then the list of CIDR blocks listed + here should be a subset of the CIDR blocks listed on the role. +- `token_bound_cidrs` `(array: [])` - Comma-separated string or list of CIDR + blocks; if set, specifies blocks of IP addresses which can use the auth tokens + generated by this SecretID. Overrides any role-set value but must be a subset. +- `num_uses` `(integer: 0)` - Number of times this SecretID can be used, after which + the SecretID expires. A value of zero will allow unlimited uses. + Overrides secret_id_num_uses role option when supplied. + May not be higher than role's secret_id_num_uses. +- `ttl` `(string: "")` - Duration in seconds (`3600`) or an integer time unit (`60m`) + after which this SecretID expires. A value of zero will allow the SecretID to not expire. + Overrides secret_id_ttl role option when supplied. + May not be longer than role's secret_id_ttl. + +### Sample payload + +```json +{ + "metadata": "{ \"tag1\": \"production\" }", + "ttl": 600, + "num_uses": 50 +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780", + "secret_id": "841771dc-11c9-bbc7-bcac-6a3945a69cd9", + "secret_id_ttl": 600, + "secret_id_num_uses": 50 + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## List secret ID accessors + +Lists the accessors of all the SecretIDs issued against the AppRole. +This includes the accessors for "custom" SecretIDs as well. + +| Method | Path | +| :----- | :---------------------------------------- | +| `LIST` | `/auth/approle/role/:role_name/secret-id` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": [ + "ce102d2a-8253-c437-bf9a-aceed4241491", + "a1c8dee4-b869-e68d-3520-2040c1a0849a", + "be83b7e2-044c-7244-07e1-47560ca1c787", + "84896a0c-1347-aa90-a4f6-aca8b7558780", + "239b1328-6523-15e7-403a-a48038cdc45a" + ] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Read AppRole secret ID + +Reads out the properties of a SecretID. + +| Method | Path | +| :----- | :----------------------------------------------- | +| `POST` | `/auth/approle/role/:role_name/secret-id/lookup` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes. +- `secret_id` `(string: )` - Secret ID attached to the role. + +### Sample payload + +```json +{ + "secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id/lookup +``` + +### Sample Response + +```json +{ + "request_id": "74752925-f309-6859-3d2d-0fcded95150e", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "cidr_list": [], + "creation_time": "2023-02-10T18:17:27.089757383Z", + "expiration_time": "0001-01-01T00:00:00Z", + "last_updated_time": "2023-02-10T18:17:27.089757383Z", + "metadata": { + "tag1": "production" + }, + "secret_id_accessor": "2be760a4-86bb-2fa9-1637-1b7fa9ba2896", + "secret_id_num_uses": 0, + "secret_id_ttl": 0, + "token_bound_cidrs": [] + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Destroy AppRole Secret ID + +Destroy an AppRole secret ID. + +| Method | Path | +| :----- | :------------------------------------------------ | +| `POST` | `/auth/approle/role/:role_name/secret-id/destroy` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes. +- `secret_id` `(string: )` - Secret ID attached to the role. + +### Sample payload + +```json +{ + "secret_id": "84896a0c-1347-aa90-a4f6-aca8b7558780" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id/destroy +``` + +## Read AppRole secret ID accessor + +Reads out the properties of a SecretID. + +| Method | Path | +| :----- | :-------------------------------------------------------- | +| `POST` | `/auth/approle/role/:role_name/secret-id-accessor/lookup` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes. +- `secret_id_accessor` `(string: )` - Secret ID accessor attached to the role. + +### Sample payload + +```json +{ + "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id-accessor/lookup +``` + +### Sample Response + +```json +{ + "request_id": "72836cd1-139c-fe66-1402-8bb5ca4044b8", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "cidr_list": [], + "creation_time": "2023-02-10T18:17:27.089757383Z", + "expiration_time": "0001-01-01T00:00:00Z", + "last_updated_time": "2023-02-10T18:17:27.089757383Z", + "metadata": { + "tag1": "production" + }, + "secret_id_accessor": "2be760a4-86bb-2fa9-1637-1b7fa9ba2896", + "secret_id_num_uses": 0, + "secret_id_ttl": 0, + "token_bound_cidrs": [] + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Destroy AppRole Secret ID Accessor + +Destroy an AppRole secret ID by its accessor. + +| Method | Path | +| :----- | :--------------------------------------------------------- | +| `POST` | `/auth/approle/role/:role_name/secret-id-accessor/destroy` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes. +- `secret_id_accessor` `(string: )` - Secret ID accessor attached to the role. + +### Sample payload + +```json +{ + "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/approle/role/application1/secret-id-accessor/destroy +``` + +## Create custom AppRole secret ID + +Assigns a "custom" SecretID against an existing AppRole. This is used in the +"Push" model of operation. + +| Method | Path | +| :----- | :----------------------------------------------- | +| `POST` | `/auth/approle/role/:role_name/custom-secret-id` | + +### Parameters + +- `role_name` `(string: )` - Name of the AppRole. Must be less than 4096 bytes. +- `secret_id` `(string: )` - SecretID to be attached to the Role. +- `metadata` `(string: "")` - Metadata to be tied to the SecretID. This should be + a JSON-formatted string containing the metadata in key-value pairs. This + metadata will be set on tokens issued with this SecretID, and is logged in + audit logs _in plaintext_. +- `cidr_list` `(array: [])` - Comma separated string or list of CIDR blocks + enforcing secret IDs to be used from specific set of IP addresses. If + `secret_id_bound_cidrs` is set on the role, then the list of CIDR blocks listed + here should be a subset of the CIDR blocks listed on the role. +- `token_bound_cidrs` `(array: [])` - Comma-separated string or list of CIDR + blocks; if set, specifies blocks of IP addresses which can use the auth tokens + generated by this SecretID. Overrides any role-set value but must be a subset. +- `num_uses` `(integer: 0)` - Number of times this SecretID can be used, after which + the SecretID expires. A value of zero will allow unlimited uses. + Overrides secret_id_num_uses role option when supplied. + May not be higher than role's secret_id_num_uses. +- `ttl` `(string: "")` - Duration in seconds (`3600`) or an integer time unit (`60m`) + after which this SecretID expires. A value of zero will allow the SecretID to not expire. + Overrides secret_id_ttl role option when supplied. + May not be longer than role's secret_id_ttl. + +### Sample payload + +```json +{ + "secret_id": "testsecretid", + "ttl": 600, + "num_uses": 50 +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/approle/role/application1/custom-secret-id +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "secret_id": "testsecretid", + "secret_id_accessor": "84896a0c-1347-aa90-a4f6-aca8b7558780", + "secret_id_ttl": 600, + "secret_id_num_uses": 50 + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Login with AppRole + +Issues a Vault token based on the presented credentials. `role_id` is always +required; if `bind_secret_id` is enabled (the default) on the AppRole, +`secret_id` is required too. Any other bound authentication values on the +AppRole (such as client IP CIDR) are also evaluated. + +| Method | Path | +| :----- | :-------------------- | +| `POST` | `/auth/approle/login` | + +### Parameters + +- `role_id` `(string: )` - 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 + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/approle/login +``` + +### Sample response + +```json +{ + "auth": { + "renewable": true, + "lease_duration": 1200, + "metadata": null, + "token_policies": ["default"], + "accessor": "fd6c9a00-d2dc-3b11-0be5-af7ae0e1d374", + "client_token": "5b1a0318-679c-9c45-e5c6-d1b9a9035d49" + }, + "warnings": null, + "wrap_info": null, + "data": null, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Read, update, or delete AppRole properties + +Updates the respective property in the existing AppRole. All of these +parameters of the AppRole can be updated using the `/auth/approle/role/:role_name` +endpoint directly. The endpoints for each field is provided separately +to be able to delegate specific endpoints using Vault's ACL system. + +| Method | Path | +| :---------------- | :---------------------------------------------------- | --------- | +| `GET/POST/DELETE` | `/auth/approle/role/:role_name/policies` | `200/204` | +| `GET/POST/DELETE` | `/auth/approle/role/:role_name/secret-id-num-uses` | `200/204` | +| `GET/POST/DELETE` | `/auth/approle/role/:role_name/secret-id-ttl` | `200/204` | +| `GET/POST/DELETE` | `/auth/approle/role/:role_name/token-ttl` | `200/204` | +| `GET/POST/DELETE` | `/auth/approle/role/:role_name/token-max-ttl` | `200/204` | +| `GET/POST/DELETE` | `/auth/approle/role/:role_name/bind-secret-id` | `200/204` | +| `GET/POST/DELETE` | `/auth/approle/role/:role_name/secret-id-bound-cidrs` | `200/204` | +| `GET/POST/DELETE` | `/auth/approle/role/:role_name/token-bound-cidrs` | `200/204` | +| `GET/POST/DELETE` | `/auth/approle/role/:role_name/period` | `200/204` | + +Refer to `/auth/approle/role/:role_name` endpoint. + +## Tidy tokens + +Performs some maintenance tasks to clean up invalid entries that may remain +in the token store. Generally, running this is not needed unless upgrade +notes or support personnel suggest it. This may perform a lot of I/O to the +storage method so should be used sparingly. + +| Method | Path | +| :----- | :----------------------------- | +| `POST` | `/auth/approle/tidy/secret-id` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/auth/approle/tidy/secret-id +``` + +### Sample response + +```json +{ + "request_id": "b20b56e3-4699-5b19-cc6b-e74f7b787bbf", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": null, + "wrap_info": null, + "warnings": [ + "Tidy operation successfully started. Any information from the operation will be printed to Vault's server logs." + ], + "auth": null +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/aws.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/aws.mdx new file mode 100644 index 0000000000..bd1a55f352 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/aws.mdx @@ -0,0 +1,1419 @@ +--- +layout: api +page_title: AWS - Auth Methods - HTTP API +description: This is the API documentation for the Vault AWS auth method. +--- + +# AWS auth method (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault AWS auth method. For +general information about the usage and operation of the AWS method, please +see the [Vault AWS method documentation](/vault/docs/auth/aws). + +This documentation assumes the AWS method is mounted at the `/auth/aws` +path in Vault. Since it is possible to enable auth methods at any location, +please update your API calls accordingly. + +~> **Vault 1.7** deprecated several AWS Auth URLs. The full +[list of affected endpoints](#deprecations-effective-in-vault-1-7) and their +replacements is provided at the end of this document. + +## 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, or [plugin workload identity federation](/vault/docs/auth/aws#plugin-workload-identity-federation-wif) +credentials are also not provided, 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 +method is configured on an EC2 instance with metadata querying +capabilities, the credentials are fetched automatically. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `/auth/aws/config/client` | + +### Parameters + +- `max_retries` `(int: -1)` - Number of max retries the client should use for + recoverable errors. The default (`-1`) falls back to the AWS SDK's default + behavior. +- `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. Mutually exclusive with `identity_token_audience`. +- `secret_key` `(string: "")` - AWS Secret key with permissions to query AWS + APIs. +- `role_arn` `(string: "")` – Role ARN to assume + for plugin workload identity federation. Required with `identity_token_audience`. +- `identity_token_audience` `(string: "")` - The + audience claim value for plugin identity tokens. Must match an allowed audience configured + for the target [IAM OIDC identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html#manage-oidc-provider-console). + Mutually exclusive with `access_key`. +- `identity_token_ttl` `(string/int: 3600)` - The + TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format). +- `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. If set, `sts_region` should also be set. +- `sts_region` `(string: "")` - Region to override the default region for making + AWS STS API calls. Should only be set if `sts_endpoint` is set. If so, should + be set to the region in which the custom `sts_endpoint` resides. +- `use_sts_region_from_client` `(boolean: false)` - If set, overrides both `sts_endpoint` + and `sts_region` to instead use the region specified in the client request headers for + IAM-based authentication . This can be useful when you have client requests coming from + different regions and want flexibility in which regional STS API is used. +- `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. +- `allowed_sts_header_values` `(string: "")` A comma separated list of + additional request headers permitted when providing the iam_request_headers for + an IAM based login call. In any case, a default list of headers AWS STS + expects for a GetCallerIdentity are allowed. + +@include 'rotationfields.mdx' + +### Sample payload + +```json +{ + "access_key": "VKIAJBRHKH6EVTTNXDHA", + "secret_key": "vCtSM8ZUEQ3mOFVlYPBQkf2sO6F/W7a5TVzrl3Oj" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/aws/config/client +``` + +## Read config + +Returns the previously configured AWS access credentials. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/auth/aws/config/client` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/aws/config/client +``` + +### Sample response + +```json +{ + "data": { + "access_key": "VKIAJBRHKH6EVTTNXDHA", + "endpoint": "", + "iam_endpoint": "", + "sts_endpoint": "", + "sts_region": "", + "use_sts_region_from_client": false, + "iam_server_id_header_value": "" + } +} +``` + +## Delete config + +Deletes the previously configured AWS access credentials. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `/auth/aws/config/client` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/aws/config/client +``` + +## Rotate root credentials + +When you have configured Vault with static credentials, you can use this +endpoint to have Vault rotate the access key it used. Note that, due to AWS +eventual consistency, after calling this endpoint, subsequent calls from Vault +to AWS may fail for a few seconds until AWS becomes consistent again. + +In order to call this endpoint, Vault's AWS access key MUST be the only access +key on the IAM user; otherwise, generation of a new access key will fail. Once +this method is called, Vault will now be the only entity that knows the AWS +secret key is used to access AWS. + +| Method | Path | +| :----- | :----------------------------- | +| `POST` | `/auth/aws/config/rotate-root` | + +### Parameters + +There are no parameters to this operation. + +### Sample request + +```$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/auth/aws/config/rotate-root +``` + +### Sample response + +```json +{ + "data": { + "access_key": "AKIA..." + } +} +``` + +The new access key Vault uses is returned by this operation. + +## Configure identity integration + +This configures the way that Vault interacts with the +[Identity](/vault/docs/secrets/identity) store. The default (as of Vault +1.0.3) is `role_id` for both values. + +| Method | Path | +| :----- | :-------------------------- | +| `POST` | `/auth/aws/config/identity` | + +### Parameters + +- `iam_alias` `(string: "role_id")` - How to generate the identity alias when + using the `iam` auth method. Valid choices are `role_id`, `unique_id`, `canonical_arn` and + `full_arn`. When `role_id` is selected, the randomly generated ID of the Vault role + is used. When `unique_id` is selected, the [IAM Unique + ID](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers#identifiers-unique-ids) + of the IAM principal (either the user or role) is used as the identity alias + name. When `canonical_arn` is selected, the role ARN returned by the `sts:GetCallerIdentity`call + will be used. This will be `arn:aws:iam:::role/`. When `full_arn` is selected, + the ARN returned by the `sts:GetCallerIdentity` call is used as the alias name. This is either + `arn:aws:iam:::user/` or + `arn:aws:sts:::assumed-role//`. + **Note**: if you select `canonical_arn` or `full_arn` and then delete and recreate the IAM role, + Vault won't be aware and any identity aliases set up for the role name will + still be valid. + +- `iam_metadata` `(string: "default")` - The metadata to include on the token + returned by the `login` endpoint. This metadata will be added to both audit logs, + and on the `iam_alias`. By default, it includes `account_id` and `auth_type`. + Additionally, `canonical_arn`, `client_arn`, `client_user_id`, `inferred_aws_region`, + `inferred_entity_id`, and `inferred_entity_type` are available. To include no metadata, + set to `""` via the CLI or `[]` via the API. To use only particular fields, select + the explicit fields. To restore to defaults, send only a field of `default`. + **Only select fields that will have a low rate of change** for your `iam_alias` because + each change triggers a storage write and can have a performance impact at scale. + +- `ec2_alias` `(string: "role_id")` - Configures how to generate the identity + alias when using the `ec2` auth method. Valid choices are `role_id`, + `instance_id`, and `image_id`. When `role_id` is selected, the randomly + generated ID of the Vault role is used. When `instance_id` is selected, the + instance identifier is used as the identity alias name. When `image_id` is + selected, AMI ID of the instance is used as the identity alias name. + +- `ec2_metadata` `(string: "default")` - The metadata to include on the token + returned by the `login` endpoint. This metadata will be added to both audit logs, + and on the `ec2_alias`. By default, it includes `account_id` and `auth_type`. + Additionally, `ami_id`, `instance_id`, and `region`, are available. To include no metadata, + set to `""` via the CLI or `[]` via the API. To use only particular fields, select + the explicit fields. To restore to defaults, send only a field of `default`. + **Only select fields that will have a low rate of change** for your `ec2_alias` because + each change triggers a storage write and can have a performance impact at scale. + +### Sample payload + +```json +{ + "iam_alias": "unique_id" +} +``` + +### Sample request + +```shell-session +$ curl \ + -- header "X-Vault-Token:..." \ + --request POST + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/aws/config/identity +``` + +## Read identity integration configuration + +Returns the previously configured Identity integration configuration + +| Method | Path | +| :----- | :-------------------------- | +| `GET` | `/auth/aws/config/identity` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token:..." \ + http://127.0.0.1:8200/v1/auth/aws/config/identity +``` + +### Sample response + +```json +{ + "data": { + "iam_alias": "full_arn" + } +} +``` + +## Create certificate configuration + +Registers an AWS public key to be used to verify the instance identity +documents. Indicate the type of the public key using the `type` parameter. +Vault has the default +[documented](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html) +set of AWS certificates built-in. + +The `pkcs7` type is used to verify PKCS#7 signatures from the AWS +`http://169.254.169.254/latest/dynamic/instance-identity/pkcs7` and +`http://169.254.169.254/latest/dynamic/instance-identity/rsa2048` endpoints. +Vault does not support X.509 certificates with SHA-1 signatures. If you use AWS +[`/rsa2048` signature endpoint](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/verify-rsa2048.html) +credentials, you must use the `pkcs7` login flow. + +The `identity` type is used to verify signatures from the +`http://169.254.169.254/latest/dynamic/instance-identity/document` and +`http://169.254.169.254/latest/dynamic/instance-identity/signature` endpoints. + +See the [AWS docs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html) +for more information on the signature types and the corresponding certificates. + +| Method | Path | +| :----- | :---------------------------------------- | +| `POST` | `/auth/aws/config/certificate/:cert_name` | + +### Parameters + +- `cert_name` `(string: )` - Name of the certificate. +- `aws_public_cert` `(string: )` - Base64-encoded AWS Public key required to verify + PKCS#7 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 can be a DSA digest from the + [/pkcs7](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/verify-pkcs7.html) + endpoint or an RSA-2048 signature from the + [/rsa2048](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/verify-rsa2048.html) + endpoint. + The identity signature is used to validate RSA signatures from the + [/signature](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/verify-signature.html) + endpoint. Defaults to "pkcs7". + +### Sample payload + +```json +{ + "aws_public_cert": "LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUM3VENDQXEwQ0NRQ1d1a2paNVY0YVp6QUpCZ2NxaGtqT09BUURNRnd4Q3pBSkJnTlZCQVlUQWxWVE1Sa3cKRndZRFZRUUlFeEJYWVhOb2FXNW5kRzl1SUZOMFlYUmxNUkF3RGdZRFZRUUhFd2RUWldGMGRHeGxNU0F3SGdZRApWUVFLRXhkQmJXRjZiMjRnVjJWaUlGTmxjblpwWTJWeklFeE1RekFlRncweE1qQXhNRFV4TWpVMk1USmFGdzB6Ck9EQXhNRFV4TWpVMk1USmFNRnd4Q3pBSkJnTlZCQVlUQWxWVE1Sa3dGd1lEVlFRSUV4QlhZWE5vYVc1bmRHOXUKSUZOMFlYUmxNUkF3RGdZRFZRUUhFd2RUWldGMGRHeGxNU0F3SGdZRFZRUUtFeGRCYldGNmIyNGdWMlZpSUZObApjblpwWTJWeklFeE1RekNDQWJjd2dnRXNCZ2NxaGtqT09BUUJNSUlCSHdLQmdRQ2prdmNTMmJiMVZRNHl0LzVlCmloNU9PNmtLL24xTHpsbHI3RDhad3RRUDhmT0VwcDVFMm5nK0Q2VWQxWjFnWWlwcjU4S2ozbnNzU05wSTZiWDMKVnlJUXpLN3dMY2xuZC9Zb3pxTk5tZ0l5WmVjTjdFZ2xLOUlUSEpMUCt4OEZ0VXB0M1FieVlYSmRtVk1lZ042UApodmlZdDVKSC9uWWw0aGgzUGExSEpkc2tnUUlWQUxWSjNFUjExK0tvNHRQNm53dkh3aDYrRVJZUkFvR0JBSTFqCmsrdGtxTVZIdUFGY3ZBR0tvY1Rnc2pKZW02LzVxb216SnVLRG1iSk51OVF4dzNyQW90WGF1OFFlK01CY0psL1UKaGh5MUtIVnBDR2w5ZnVlUTJzNklMMENhTy9idXljVTFDaVlRazQwS05IQ2NIZk5pWmJkbHgxRTlycFVwN2JuRgpsUmEydjFudE1YM2NhUlZEZGJ0UEVXbWR4U0NZc1lGRGs0bVpyT0xCQTRHRUFBS0JnRWJtZXZlNWY4TElFL0dmCk1ObVA5Q001ZW92UU9HeDVobzhXcUQrYVRlYnMrazJ0bjkyQkJQcWVacXBXUmE1UC8ranJkS21sMXF4NGxsSFcKTVhyczNJZ0liNitoVUlCK1M4ZHo4L21tTzBicHI3NlJvWlZDWFlhYjJDWmVkRnV0N3FjM1dVSDkrRVVBSDVtdwp2U2VEQ09VTVlRUjdSOUxJTll3b3VISXppcVFZTUFrR0J5cUdTTTQ0QkFNREx3QXdMQUlVV1hCbGs0MHhUd1N3CjdIWDMyTXhYWXJ1c2U5QUNGQk5HbWRYMlpCclZOR3JOOU4yZjZST2swazlLCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/aws/config/certificate/test-cert +``` + +## Read certificate configuration + +Returns the previously configured AWS public key. + +| Method | Path | +| :----- | :---------------------------------------- | +| `GET` | `/auth/aws/config/certificate/:cert_name` | + +### Parameters + +- `cert_name` `(string: )` - Name of the certificate. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/aws/config/certificate/test-cert +``` + +### Sample response + +```json +{ + "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", + "type": "pkcs7" + } +} +``` + +## Delete certificate configuration + +Removes the previously configured AWS public key. + +| Method | Path | +| :------- | :---------------------------------------- | +| `DELETE` | `/auth/aws/config/certificate/:cert_name` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/aws/config/certificate/test-cert +``` + +## List certificate configurations + +Lists all the AWS public certificates that are registered with the method. + +| Method | Path | +| :----- | :------------------------------ | +| `LIST` | `/auth/aws/config/certificates` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/aws/config/certificates +``` + +### Sample response + +```json +{ + "data": { + "keys": ["cert1"] + } +} +``` + +## 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.) Vault will use credentials obtained by assuming these STS roles +when validating IAM principals or EC2 instances in the particular AWS account. + +| Method | Path | +| :----- | :--------------------------------- | +| `POST` | `/auth/aws/config/sts/:account_id` | + +### 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. +- `external_id` `(string: "")` - The external ID expected by the STS role. The + associated STS role **must** be configured to require the external ID. + +### Sample payload + +```json +{ + "sts_role": "arn:aws:iam:111122223333:role/myRole" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/aws/config/sts/111122223333 +``` + +## Read STS role + +Returns the previously configured STS role. + +| Method | Path | +| :----- | :--------------------------------- | +| `GET` | `/auth/aws/config/sts/:account_id` | + +### Parameters + +- `account_id` `(string: )` - AWS account ID that has been + previously associated with STS role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/aws/config/sts/111122223333 +``` + +### Sample response + +```json +{ + "data": { + "sts_role ": "arn:aws:iam:111122223333:role/myRole" + } +} +``` + +## List STS roles + +Lists all the AWS Account IDs for which an STS role is registered. + +| Method | Path | +| :----- | :--------------------- | +| `LIST` | `/auth/aws/config/sts` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/aws/config/sts +``` + +### Sample response + +```json +{ + "data": { + "keys": ["111122223333", "999988887777"] + } +} +``` + +## Delete STS role + +Deletes a previously configured AWS account/STS role association. + +| Method | Path | +| :------- | :--------------------------------- | +| `DELETE` | `/auth/aws/config/sts/:account_id` | + +### Parameters + +- `account_id` `(string: )` - AWS account ID that has been + previously associated with STS role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/aws/config/sts/111122223333 +``` + +## Configure identity access list tidy operation + +Configures the periodic tidying operation of the access listed identity entries. + +| Method | Path | +| :----- | :------------------------------------------ | +| `POST` | `/auth/aws/config/tidy/identity-accesslist` | + +### Parameters + +- `safety_buffer` `(string: "72h")` - The amount of extra time that must have + passed beyond the `roletag` expiration, before it is removed from the method + storage. Defaults to 72h. +- `disable_periodic_tidy` `(bool: false)` - If set to 'true', disables the + periodic tidying of the `identity-accesslist/` entries. + +### Sample payload + +```json +{ + "safety_buffer": "48h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/aws/config/tidy/identity-accesslist +``` + +## Read identity access list tidy settings + +Returns the previously configured periodic access list tidying settings. + +| Method | Path | +| :----- | :------------------------------------------ | +| `GET` | `/auth/aws/config/tidy/identity-accesslist` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/aws/config/tidy/identity-accesslist +``` + +### Sample response + +```json +{ + "data": { + "safety_buffer": 600, + "disable_periodic_tidy": false + } +} +``` + +## Delete identity access list tidy settings + +Deletes the previously configured periodic access list tidying settings. + +| Method | Path | +| :------- | :------------------------------------------ | +| `DELETE` | `/auth/aws/config/tidy/identity-accesslist` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/aws/config/tidy/identity-accesslist +``` + +## Configure role tag deny list tidy operation + +Configures the periodic tidying operation of the deny listed role tag entries. + +| Method | Path | +| :----- | :--------------------------------------- | +| `POST` | `/auth/aws/config/tidy/roletag-denylist` | + +### Parameters + +- `safety_buffer` `(string: "72h")` - The amount of extra time that must have + passed beyond the `roletag` expiration, before it is removed from the method + storage. Defaults to 72h. +- `disable_periodic_tidy` `(bool: false)` - If set to 'true', disables the + periodic tidying of the `roletag-denylist/` entries. + +### Sample payload + +```json +{ + "safety_buffer": "48h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/aws/config/tidy/roletag-denylist +``` + +## Read role tag deny list tidy settings + +Returns the previously configured periodic deny list tidying settings. + +| Method | Path | +| :----- | :--------------------------------------- | +| `GET` | `/auth/aws/config/tidy/roletag-denylist` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/aws/config/tidy/roletag-denylist +``` + +### Sample response + +```json +{ + "data": { + "safety_buffer": 600, + "disable_periodic_tidy": false + } +} +``` + +## Delete role tag deny list tidy settings + +Deletes the previously configured periodic deny list tidying settings. + +| Method | Path | +| :------- | :--------------------------------------- | +| `DELETE` | `/auth/aws/config/tidy/roletag-denylist` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/aws/config/tidy/roletag-denylist +``` + +## Create/Update role + +Registers a role in the method. Only those instances or principals which +are using the role registered using this endpoint, will be able to perform +the login operation. Constraints can be specified on the role, that are +applied on the instances or principals attempting to login. At least one +constraint must 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. For the constraints which accept a list +of values, the authenticating instance/principal must match any one value in the +list in order to satisfy that constraint. + +| Method | Path | +| :----- | :--------------------- | +| `POST` | `/auth/aws/role/:role` | + +### Parameters + +- `role` `(string: )` - Name of the role. Vault normalizes all role + names to lower case. If you create two roles, "Web-Workers" and "WEB-WORKERS", + they will both be normalized to "web-workers" and will be regarded as the same role. + This is to prevent unexpected behavior due to casing differences. At all points, + Vault can be provided the role in any casing, and it will internally handle + sending it to lower case and seeking it inside its storage engine. +- `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` `(list: [])` - If set, defines a constraint on the EC2 + instances that they should be using one of 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. This is a comma-separated string or JSON + array. +- `bound_account_id` `(list: [])` - If set, defines a constraint on the EC2 + instances that the account ID in its identity document to match one of the ones + specified by this parameter. This constraint is checked during ec2 auth as + well as the iam auth method only when inferring an EC2 instance. This is a + comma-separated string or JSON array. +- `bound_region` `(list: [])` - If set, defines a constraint on the EC2 + instances that the region in its identity document must match one of the + regions 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. + This is a comma-separated string or JSON array. +- `bound_vpc_id` `(list: [])` - If set, defines a constraint on the EC2 + instance to be associated with a VPC ID that matches one of the values 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. This is a + comma-separated string or JSON array. +- `bound_subnet_id` `(list: [])` - If set, defines a constraint on the EC2 + instance to be associated with a subnet ID that matches one of the values 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. This is a + comma-separated string or a JSON array. +- `bound_iam_role_arn` `(list: [])` - If set, defines a constraint on the + authenticating EC2 instance that it must match one of the IAM role ARNs specified by + this parameter. Wildcards are supported at the end of the ARN to allow for + prefix matching. 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. This is a comma-separated string or a + JSON array. +- `bound_iam_instance_profile_arn` `(list: [])` - If set, defines a constraint + on the EC2 instances to be associated with an IAM instance profile ARN. + Wildcards are supported at the end of the ARN to allow for prefix matching. + This constraint is + checked by the ec2 auth method as well as the iam auth method only when + inferring an ec2 instance. This is a comma-separated string or a JSON array. +- `bound_ec2_instance_id` `(list: [])` - If set, defines a constraint on the + EC2 instances to have one of these instance IDs. This constraint is checked by + the ec2 auth method as well as the iam auth method only when inferring an ec2 + instance. This is a comma-separated string or a JSON array. +- `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 + `auth_type` is iam. +- `bound_iam_principal_arn` `(list: [])` - Defines the list of IAM principals + that are permitted to login to the role using the iam auth method. Individual + values should look like "arn:aws:iam::123456789012:user/MyUserName" or + "arn:aws:iam::123456789012:role/MyRoleName". Wildcards are supported at the + end of the ARN, e.g., "arn:aws:iam::123456789012:\*" will match any IAM + principal in the AWS account 123456789012. When `resolve_aws_unique_ids` is + `false` and you are binding to IAM roles (as opposed to users) and you are not + using a wildcard at the end, then you must specify the ARN by omitting any + path component; see the documentation for `resolve_aws_unique_ids` below. + This constraint is only checked by + the iam auth method. Wildcards are supported at the end of the ARN, e.g., + "arn:aws:iam::123456789012:role/\*" will match all roles in the AWS account. + This is a comma-separated string or JSON array. +- `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: true)` - When set, resolves the + `bound_iam_principal_arn` to the + [AWS Unique ID](http://docs.aws.amazon.com/IAM/latest/UserGuide/reference_identifiers#identifiers-unique-ids) + for the bound principal ARN. This field is ignored when + `bound_iam_principal_arn` ends with a wildcard character. + 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** that do not specify a wildcard at the end, but not IAM users or + role bindings that have a wildcard. That is, if your IAM role ARN is of the + form `arn:aws:iam::123456789012:role/some/path/to/MyRoleName`, and + `resolve_aws_unique_ids` is `false`, you **must** specify a + `bound_iam_principal_arn` of `arn:aws:iam::123456789012:role/MyRoleName` for + authentication to work. +- `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. This is mutually exclusive with + `disallow_reauthentication`. +- `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 the access list for the instance ID needs to be cleared using + `auth/aws/identity-accesslist/` endpoint. Defaults to 'false'. + This only applies to authentications via the ec2 auth method. This is mutually + exclusive with `allow_instance_migration`. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "bound_ami_id": ["ami-fce36987"], + "bound_ec2_instance_id": ["i-12345678901234567"], + "role_tag": "", + "policies": ["default", "dev", "prod"], + "max_ttl": 1800000, + "disallow_reauthentication": false, + "allow_instance_migration": false +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/aws/role/dev-role +``` + +## Read role + +Returns the previously registered role configuration. + +| Method | Path | +| :----- | :--------------------- | +| `GET` | `/auth/aws/role/:role` | + +### Parameters + +- `role` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/aws/role/dev-role +``` + +### Sample response + +```json +{ + "data": { + "bound_ami_id": ["ami-fce36987"], + "role_tag": "", + "policies": ["default", "dev", "prod"], + "max_ttl": 1800000, + "disallow_reauthentication": false, + "allow_instance_migration": false + } +} +``` + +## List roles + +Lists all the roles that are registered with the method. + +| Method | Path | +| :----- | :---------------- | +| `LIST` | `/auth/aws/roles` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/aws/roles +``` + +### Sample response + +```json +{ + "data": { + "keys": ["dev-role", "prod-role"] + } +} +``` + +## Delete role + +Deletes the previously registered role. + +| Method | Path | +| :------- | :--------------------- | +| `DELETE` | `/auth/aws/role/:role` | + +### Parameters + +- `role` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/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 | +| :----- | :------------------------- | +| `POST` | `/auth/aws/role/:role/tag` | + +### 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'. + Mutually exclusive with `disallow_reauthentication`. +- `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-accesslist endpoint. Defaults to 'false'. Mutually exclusive + with `allow_instance_migration`. + +### Sample payload + +```json +{ + "policies": ["default", "dev-api"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/aws/role/dev-api-and-web-role/tag +``` + +### Sample response + +```json +{ + "data": { + "tag_value": "v1:09Vp0qGuyB8=:r=dev-role:p=default,dev-api:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/pJIdVyOI=", + "tag_key": "VaultRole" + } +} +``` + +## Login + +Fetch a token. This endpoint verifies the PKCS#7 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 PKCS#7 signature, the identity document +along with its RSA signature can be supplied to this endpoint. + +See the [AWS docs](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instance-identity-documents.html) +for more information on the signature types. + +| Method | Path | +| :----- | :---------------- | +| `POST` | `/auth/aws/login` | + +### Parameters + +- `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, which can usually be obtained from the + `http://169.254.169.254/latest/dynamic/instance-identity/document` endpoint. + When using `curl` for fetching the identity document, consider using the option + `-w 0` while piping the output to `base64` binary. + Either both of this and `signature` must be set _OR_ `pkcs7` must be set + when using the ec2 auth method. +- `signature` `(string: )` - Base64-encoded SHA256 RSA signature of + the instance identity document, which can usually be obtained from the + `http://169.254.169.254/latest/dynamic/instance-identity/signature` endpoint. + Either both this _AND_ `identity` must be set _OR_ `pkcs7` must be set + when using the ec2 auth method. +- `pkcs7` `(string: )` - PKCS#7 signature of the identity document + with all `\n` characters removed. This supports signatures from the AWS + `http://169.254.169.254/latest/dynamic/instance-identity/rsa2048` + or `http://169.254.169.254/latest/dynamic/instance-identity/pkcs7` endpoints. + 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 method will generate a random nonce, attaches it to the instance's + identity-accesslist 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. 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. If using GET method this will contain + the authentication headers that have been hoisted out of the message body. + 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 with POST signed requests. +- `iam_request_headers` `(string: )` - Key/value pairs of headers + for use in the `sts:GetCallerIdentity` HTTP requests headers. Can be either a + Base64-encoded, JSON-serialized string, or a JSON object of key/value pairs. 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 +{ + "iam_http_request_method": "POST", + "iam_request_body": "QWN0aW9uPUdldENhbG...", + "iam_request_headers": "eyJBdXRob3JpemF0aW9uIj...", + "iam_request_url": "aHR0cHM6L...", + "role": "dev-role" +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/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" + } +} +``` + +## Place role tags in deny list + +Places a valid role tag in a deny list. 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 deny list does not invalidate the already issued +token. + +| Method | Path | +| :----- | :------------------------------------- | +| `POST` | `/auth/aws/roletag-denylist/:role_tag` | + +### Parameters + +- `role_tag` `(string: )` - Role tag to be deny listed. This is the `tag_value` returned when the role tag is + created. The tag can be supplied as-is. In order to avoid any encoding problems, it can be base64 + encoded. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/auth/aws/roletag-denylist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo= +``` + +### Read role tag deny list information + +Returns the deny list entry of a previously deny listed role tag. + +| Method | Path | +| :----- | :------------------------------------- | +| `GET` | `/auth/aws/roletag-denylist/:role_tag` | + +### Parameters + +- `role_tag` `(string: )` - Role tag to be deny listed. The tag can be + supplied as-is. In order to avoid any encoding problems, it can be base64 + encoded. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/aws/roletag-denylist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo= +``` + +### Sample response + +```json +{ + "data": { + "expiration_time": "2016-04-25T10:35:20.127058773-04:00", + "creation_time": "2016-04-12T22:35:01.178348124-04:00" + } +} +``` + +## List deny list tags + +Lists all the role tags that are deny listed. + +| Method | Path | +| :----- | :--------------------------- | +| `LIST` | `/auth/aws/roletag-denylist` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/aws/roletag-denylist +``` + +### Sample response + +```json +{ + "data": { + "keys": [ + "v1:09Vp0qGuyB8=:a=ami-fce3c696:p=default,prod:d=false:t=300h0m0s:uPLKCQxqsefRhrp1qmVa1wsQVUXXJG8UZP/" + ] + } +} +``` + +## Delete deny list tags + +Deletes a deny listed role tag. + +| Method | Path | +| :------- | :------------------------------------- | +| `DELETE` | `/auth/aws/roletag-denylist/:role_tag` | + +### Parameters + +- `role_tag` `(string: )` - Role tag to be deny listed. The tag can be + supplied as-is. In order to avoid any encoding problems, it can be base64 + encoded. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/aws/roletag-denylist/djE6MDlWcDBxR3V5Qjg9OmE9YW1pLWZjZTNjNjk2OnA9ZGVmYXVsdCxwcm9kOmQ9ZmFsc2U6dD0zMDBoMG0wczp1UExLQ1F4cXNlZlJocnAxcW1WYTF3c1FWVVhYSkc4VVpQLwo= +``` + +## Tidy deny list tags + +Cleans up the entries in the deny listed based on expiration time on the entry and +`safety_buffer`. + +| Method | Path | +| :----- | :-------------------------------- | +| `POST` | `/auth/aws/tidy/roletag-denylist` | + +### Parameters + +- `safety_buffer` `(string: "72h")` - The amount of extra time that must have + passed beyond the `roletag` expiration, before it is removed from the method + storage. Defaults to 72h. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/auth/aws/tidy/roletag-denylist +``` + +### Read identity access list information + +Returns an entry in the identity access list. An entry will be created/updated by every +successful login. + +| Method | Path | +| :----- | :------------------------------------------- | +| `GET` | `/auth/aws/identity-accesslist/:instance_id` | + +### Parameters + +- `instance_id` `(string: )` - EC2 instance ID. A successful login + operation from an EC2 instance gets cached in th access list, keyed off of + instance ID. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/aws/identity-accesslist/i-aab47d37 +``` + +### Sample response + +```json +{ + "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" + } +} +``` + +## List identity access list entries + +Lists all the instance IDs that are in the access list of successful logins. + +| Method | Path | +| :----- | :------------------------------ | +| `LIST` | `/auth/aws/identity-accesslist` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/aws/identity-accesslist +``` + +### Sample response + +```json +{ + "data": { + "keys": ["i-aab47d37"] + } +} +``` + +## Delete identity access list entries + +Deletes a cache of the successful login from an instance. + +| Method | Path | +| :------- | :------------------------------------------- | +| `DELETE` | `/auth/aws/identity-accesslist/:instance_id` | + +### Parameters + +- `instance_id` `(string: )` - EC2 instance ID. A successful login + operation from an EC2 instance gets cached in this access list, keyed off of + instance ID. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/aws/identity-accesslist/i-aab47d37 +``` + +## Tidy identity access list entries + +Cleans up the entries in the access list based on expiration time and +`safety_buffer`. + +| Method | Path | +| :----- | :----------------------------------- | +| `POST` | `/auth/aws/tidy/identity-accesslist` | + +### Parameters + +- `safety_buffer` `(string: "72h")` - The amount of extra time that must have + passed beyond the `roletag` expiration, before it is removed from the method + storage. Defaults to 72h. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/auth/aws/tidy/identity-accesslist +``` + +## Deprecations effective in Vault 1.7 + +Vault 1.7 introduced new URLs for a number of AWS Auth APIs. The previous +URLs are deprecated. The affected APIs include: + +| Current | Deprecated in 1.7 | +| :------------------------------------------ | :----------------------------------------- | +| `/auth/aws/roletag-denylist` | `/auth/aws/roletag-blacklist` | +| `/auth/aws/identity-accesslist` | `/auth/aws/identity-whitelist` | +| `/auth/aws/tidy/identity-accesslist` | `/auth/aws/tidy/identity-whitelist` | +| `/auth/aws/tidy/roletag-denylist` | `/auth/aws/tidy/roletag-blacklist` | +| `/auth/aws/config/tidy/identity-accesslist` | `/auth/aws/config/tidy/identity-whitelist` | +| `/auth/aws/config/tidy/roletag-denylist` | `/auth/aws/config/tidy/roletag-blacklist` | diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/azure.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/azure.mdx new file mode 100644 index 0000000000..9c28c6f5e3 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/azure.mdx @@ -0,0 +1,368 @@ +--- +layout: api +page_title: Azure - Auth Methods - HTTP API +description: |- + This is the API documentation for the Vault Azure authentication + method plugin. +--- + +# Azure auth method (API) + +This is the API documentation for the Vault Azure auth method +plugin. To learn more about the usage and operation, see the +[Vault Azure method documentation](/vault/docs/auth/azure). + +This documentation assumes the plugin method is mounted at the +`/auth/azure` path in Vault. Since it is possible to enable auth methods +at any location, please update your API calls accordingly. + +## Configure + +Configures the credentials required for the plugin to perform API calls +to Azure. These credentials will be used to query the metadata about the +virtual machine. + +You can configure the auth engine with account credentials or plugin workload +identity federation (WIF). + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/auth/azure/config` | + +### Parameters + +- `tenant_id` `(string: )` - The tenant id for the Azure Active Directory organization. + This value can also be provided with the `AZURE_TENANT_ID` environment variable. +- `resource` `(string: )` - The resource URL for the application registered in Azure Active Directory. + The value is expected to match the audience (`aud` claim) of the [JWT](/vault/api-docs/auth/azure#jwt) + provided to the login API. See the [resource](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token#get-a-token-using-http) + parameter for how the audience is set when requesting a JWT access token from the Azure Instance Metadata Service (IMDS) endpoint. + This value can also be provided with the `AZURE_AD_RESOURCE` environment variable. +- `environment` `(string: 'AzurePublicCloud')` - The Azure cloud environment. Valid values: AzurePublicCloud, AzureUSGovernmentCloud, AzureChinaCloud, AzureGermanCloud. + This value can also be provided with the `AZURE_ENVIRONMENT` environment variable. +- `client_id` `(string: '')` - The client id for credentials to query the Azure APIs. Currently read permissions to query compute resources are required. + This value can also be provided with the `AZURE_CLIENT_ID` environment variable. +- `client_secret` `(string: '')` - The client secret for credentials to query the Azure APIs. + This value can also be provided with the `AZURE_CLIENT_SECRET` environment variable. + Mutually exclusive with `identity_token_audience`. +- `identity_token_audience` `(string: "")` - The + audience claim value for plugin identity tokens. Must match the allowed audiences configured + for the target [Federated Identity Credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app). + Mutually exclusive with `client_secret`. +- `identity_token_ttl` `(string/int: 3600)` - The + TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format). +- `max_retries` `(int: 3)` - The maximum number of attempts a failed operation will be + retried before producing an error. +- `max_retry_delay` `(string: '60s')` - The maximum delay, in seconds, allowed before retrying an operation. +- `retry_delay` `(string: '4s')` - The initial amount of delay, in seconds, to use before retrying an operation. Increases exponentially. + +@include 'rotationfields.mdx' + +### Sample payload + +```json +{ + "tenant_id": "kd83...", + "resource": "https://management.azure.com/", + "client_id": "12ud...", + "client_secret": "DUJDS3..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/azure/config +``` + +# Read config + +Returns the previously configured config, including credentials. + +| Method | Path | +| :----- | :------------------- | +| `GET` | `/auth/azure/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/auth/azure/config +``` + +### Sample response + +```json +{ + "data":{ + "tenant_id": "kd83...", + "resource": "https://management.azure.com/", + "client_id": "12ud...", + "client_secret": "DUJDS3..." + }, + ... +} + +``` + +## Delete config + +Deletes the previously configured Azure config and credentials. + +| Method | Path | +| :------- | :------------------- | +| `DELETE` | `/auth/azure/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/auth/azure/config +``` + +## Rotate root + +This endpoint generates a new client secret for the root account defined in the config. The +value generated will only be known by Vault. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/azure/rotate-root` | + +### Parameters + +There are no parameters to this operation. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://127.0.0.1:8200/v1/auth/azure/rotate-root +``` + +## Create/Update role + +Registers a role in the method. Role types have specific entities +that can perform login operations against this endpoint. Constraints specific +to the role type must be set on the role. These are applied to the authenticated +entities attempting to login. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/auth/azure/role/:name` | + +### Parameters + +- `name` `(string: )` - Name of the role. +- `bound_service_principal_ids` `(array: [])` - The list of Service Principal IDs + that login is restricted to. Either this parameter or `bound_group_ids` must be set. +- `bound_group_ids` `(array: [])` - The list of group ids that login is restricted + to. Either this parameter or `bound_service_principal_ids` must be set. +- `bound_locations` `(array: [])` - The list of locations that login is restricted to. +- `bound_subscription_ids` `(array: [])` - The list of subscription IDs that login + is restricted to. +- `bound_resource_groups` `(array: [])` - The list of resource groups that + login is restricted to. +- `bound_scale_sets` `(array: [])` - The list of scale set names that the + login is restricted to. + +@include 'tokenfields.mdx' + +~> **Note:** When creating a role, you must specify either `bound_service_principal_ids` or `bound_group_ids`. These parameters are mutually exclusive - you cannot set both, but you must set one of them. + +### Sample payload + +```json +{ + "token_policies": ["default", "dev", "prod"], + "max_ttl": 1800000, + "max_jwt_exp": 10000, + "bound_resource_groups": ["vault-dev", "vault-staging", "vault-prod"], + "bound_service_principal_ids": ["3cb88732-1356-4782-b671-4877166be01a"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/azure/role/dev-role +``` + +## Read role + +Returns the previously registered role configuration. + +| Method | Path | +| :----- | :----------------------- | +| `GET` | `/auth/azure/role/:name` | + +### Parameters + +- `name` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/auth/azure/role/dev-role +``` + +### Sample response + +```json +{ + "data":{ + "token_policies": [ + "default", + "dev", + "prod" + ], + "max_ttl": 1800000, + "max_jwt_exp": 10000, + "bound_resource_groups": [ + "vault-dev", + "vault-staging", + "vault-prod" + ] + }, + ... +} + +``` + +## List roles + +Lists all the roles that are registered with the plugin. + +| Method | Path | +| :----- | :----------------- | +| `LIST` | `/auth/azure/role` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/auth/azure/role +``` + +### Sample response + +```json +{ + "data": { + "keys": [ + "dev-role", + "prod-role" + ] + }, + ... +} +``` + +## Delete role + +Deletes the previously registered role. + +| Method | Path | +| :------- | :----------------------- | +| `DELETE` | `/auth/azure/role/:name` | + +### Parameters + +- `name` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/auth/azure/role/dev-role +``` + +## Login + +Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and +a role name for some entity. It verifies the JWT signature to authenticate that +entity and then authorizes the entity for the given role. + +| Method | Path | +| :----- | :------------------ | +| `POST` | `/auth/azure/login` | + +### Sample payload + +- `role` `(string: )` - Name of the role against which the login is being + attempted. +- `jwt` `(string: )` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT) + from Azure MSI. See [Azure documentation](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/how-to-use-vm-token) + for details on how to acquire a JWT access token through instance metadata. +- `subscription_id` `(string: )` - The subscription ID for the machine that + generated the MSI token. This information can be obtained through instance + metadata. +- `resource_group_name` `(string: )` - The resource group for the machine that + generated the MSI token. This information can be obtained through instance + metadata. +- `vm_name` `(string: "")` - The virtual machine name for the machine that + generated the MSI token. This information can be obtained through instance + metadata. If `vmss_name` is provided, this value is ignored. +- `vmss_name` `(string: "")` - The virtual machine scale set name for the machine + that generated the MSI token. This information can be obtained through instance + metadata. +- `resource_id` `(string: "")` - The fully qualified ID of the Azure resource that + generated the MSI token, including the resource name and resource type. Use + the format /subscriptions/{guid}/resourceGroups/{resource-group-name}/{resource-provider-namespace}/{resource-type}/{resource-name}. + If `vm_name` or `vmss_name` is provided, this value is ignored. + +### Sample payload + +```json +{ + "role": "dev-role", + "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/azure/login +``` + +### Sample response + +```json +{ + "auth":{ + "client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c", + "accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d", + "token_policies":[ + "default", + "dev", + "prod" + ], + "lease_duration":2764800, + "renewable":true + }, + ... +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/cert.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/cert.mdx new file mode 100644 index 0000000000..8581ff41b3 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/cert.mdx @@ -0,0 +1,448 @@ +--- +layout: api +page_title: TLS Certificate - Auth Methods - HTTP API +description: |- + This is the API documentation for the Vault TLS Certificate authentication + method. +--- + +# TLS certificate auth method (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault TLS Certificate authentication +method. For general information about the usage and operation of the TLS +Certificate method, please see the [Vault TLS Certificate method documentation](/vault/docs/auth/cert). + +This documentation assumes the TLS Certificate method is mounted at the +`/auth/cert` path in Vault. Since it is possible to enable auth methods 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 | +| :----- | :----------------------- | +| `POST` | `/auth/cert/certs/:name` | + +### Parameters + +- `name` `(string: )` - The name of the certificate role. +- `certificate` `(string: )` - The PEM-format CA certificate. +- `allowed_names` `(string: "")` - DEPRECATED: Please use the individual + `allowed_X_sans` parameters instead. 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. +- `allowed_common_names` `(string: "" or array: [])` - Constrain the Common + 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. +- `allowed_dns_sans` `(string: "" or array: [])` - Constrain the 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 DNS + matching at least one pattern. If not set, defaults to allowing all dns. +- `allowed_email_sans` `(string: "" or array: [])` - Constrain the 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 + Email matching at least one pattern. If not set, defaults to allowing all + emails. +- `allowed_uri_sans` `(string: "" or array: [])` - Constrain the 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 URI patterns. Authentication requires at least one + URI matching at least one pattern. If not set, defaults to allowing all URIs. +- `allowed_organizational_units` `(string: "" or array: [])` - Constrain the + Organizational Units (OU) 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 OU patterns. Authentication requires at least one + OU matching at least one pattern. If not set, defaults to allowing all OUs. +- `required_extensions` `(string: "" or array: [])` - Require specific Custom + Extension OIDs to exist and match the pattern. Value is a comma separated + string or array of `oid:value`. Expects the extension value to be some type + of ASN1 encoded string. All conditions _must_ be met. To match on the hex-encoded + value of the extension, including non-string extensions, use the format + `hex::`.Supports globbing on `value`. +- `allowed_metadata_extensions` `(array:[])` - A comma separated string or + array of oid extensions. Upon successful authentication, these extensions + will be added as metadata if they are present in the certificate. The + metadata key will be the string consisting of the oid numbers separated + by a dash (-) instead of a dot (.) to allow usage in ACL templates. +- `ocsp_enabled` `(bool: false)` - If enabled, validate certificates' revocation + status using OCSP. +- `ocsp_ca_certificates` `(string: "")` Any additional OCSP responder certificates needed to + verify OCSP responses. Provided as base64 encoded PEM data. +- `ocsp_servers_override` `(array: [])`: A comma-separated list of OCSP server + addresses. If unset, the OCSP server is determined from the AuthorityInformationAccess + extension on the certificate being inspected. +- `ocsp_fail_open` `(bool: false)` - If true and an OCSP response cannot be fetched + or is of an unknown status, the login will proceed as if the certificate has not + been revoked. +- `ocsp_this_update_max_age` `(integer:0 or string: "")` - If greater than 0, specifies + the maximum age of an OCSP thisUpdate field. This avoids accepting old responses + without a nextUpdate field. +- `ocsp_max_retries` `(integer: 4)` - The number of retries attempted before giving + up on an OCSP request. 0 will disable retries +- `ocsp_query_all_servers` `(bool: false)` - If set to true, rather than accepting + the first successful OCSP response, query all servers and consider the certificate + valid only if all servers agree. + + ~> **Note**: When using Vault's PKI engine with Performance Replication clusters + as the OCSP provider, and without `unified_crls=true` set on the source mount + or when using cluster-local OCSP resolvers, we recommend enabling this option. + +- `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. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "certificate": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----", + "display_name": "test", + "bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --cacert vault-ca.pem \ + --data @payload.json + https://127.0.0.1:8200/v1/auth/cert/certs/test-ca +``` + +## Read CA certificate role + +Gets information associated with the named role. + +| Method | Path | +| :----- | :----------------------- | +| `GET` | `/auth/cert/certs/:name` | + +### Parameters + +- `name` `(string: )` - The name of the certificate role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --cacert vault-ca.pem \ + https://127.0.0.1:8200/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": "", + "required_extensions": "", + "ttl": 2764800, + "max_ttl": 2764800, + "period": 0 + }, + "warnings": null, + "auth": null +} +``` + +## List certificate roles + +Lists configured certificate names. + +| Method | Path | +| :----- | :----------------- | +| `LIST` | `/auth/cert/certs` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + --cacert vault-ca.pem \ + https://127.0.0.1:8200/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 method mount. + +| Method | Path | +| :------- | :----------------------- | +| `DELETE` | `/auth/cert/certs/:name` | + +### Parameters + +- `name` `(string: )` - The name of the certificate role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + --cacert vault-ca.pem \ + https://127.0.0.1:8200/v1/auth/cert/certs/cert1 +``` + +## List CRLs + +Lists configured certificate revocation lists. + +| Method | Path | +| :----- | :---------------- | +| `LIST` | `/auth/cert/crls` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + --cacert vault-ca.pem \ + https://127.0.0.1:8200/v1/auth/cert/crls +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": ["crl1", "crl2"] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Create CRL + +Sets a named CRL. + +| Method | Path | +| :----- | :---------------------- | +| `POST` | `/auth/cert/crls/:name` | + +### Parameters + +- `name` `(string: )` - The name of the CRL. +- `crl` `(string: "")` - The PEM format CRL. +- `url` `(string: "")` - The URL of a CRL distribution point. + +**Note**: Either 'crl' or 'url' parameters must be provided, if both are provided, 'crl' is used. + +### Sample payload + +```json +{ + "crl": "-----BEGIN X509 CRL-----\n...\n-----END X509 CRL-----" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --cacert vault-ca.pem \ + --data @payload.json \ + https://127.0.0.1:8200/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 | +| :----- | :---------------------- | +| `GET` | `/auth/cert/crls/:name` | + +### Parameters + +- `name` `(string: )` - The name of the CRL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --cacert vault-ca.pem \ + https://127.0.0.1:8200/v1/auth/cert/crls/custom-crl +``` + +### Sample response + +```json +{ + "auth": null, + "data": { + "serials": { + "13": {} + } + }, + "lease_duration": 0, + "lease_id": "", + "renewable": false, + "warnings": null +} +``` + +## Delete CRL + +Deletes the named CRL from the auth method mount. + +| Method | Path | +| :------- | :---------------------- | +| `DELETE` | `/auth/cert/crls/:name` | + +### Parameters + +- `name` `(string: )` - The name of the CRL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + --cacert vault-ca.pem \ + https://127.0.0.1:8200/v1/auth/cert/crls/cert1 +``` + +## Configure TLS certificate method + +Configuration options for the method. + +| Method | Path | +| :----- | :------------------ | +| `POST` | `/auth/cert/config` | + +### Parameters + +- `disable_binding` `(boolean: false)` - If set, during renewal, skips the + matching of presented client identity with the client identity used during + login. +- `enable_identity_alias_metadata` `(boolean: false)` - If set, metadata of + the certificate including the metadata corresponding to + `allowed_metadata_extensions` will be stored in the alias +- `ocsp_cache_size` `(int: 100)` - The size of the OCSP response LRU cache. Note + that this cache is used for all configured certificates. +- `role_cache_size` `(int: 200)` - The size of the role cache. Use `-1` to disable + role caching. +- `enable_metadata_on_failures` `(boolean: false)` - If set, metadata of the client + certificate such as common name, serial, subject key id and authority key id will + be returned on authentication failures and appear in auditing records. + +### Sample payload + +```json +{ + "disable_binding": true +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --cacert vault-ca.pem \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/cert/config +``` + +## Login with TLS certificate method + +Log in and fetch a token. If there is a valid chain to a CA configured in the +method and all role constraints are matched, a token will be issued. If the +certificate has DNS SANs in it, each of those will be verified. If Common Name +is required to be verified, then it should be a fully qualified DNS domain name +and must be duplicated as a DNS SAN (see +https://tools.ietf.org/html/rfc6125#section-2.3) + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/auth/cert/login` | + +### 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 + +~> **NOTE** The `--cacert` value used here is for the Vault TLS Listener CA +certificate, not the CA that issued the client authentication certificate. This +can be omitted if the CA used to issue the Vault server certificate is trusted +by the local system executing this command. + +```shell-session +$ curl \ + --request POST \ + --cacert vault-ca.pem \ + --cert cert.pem \ + --key key.pem \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/cert/login +``` + +### Sample response + +```json +{ + "auth": { + "client_token": "cf95f87d-f95b-47ff-b1f5-ba7bff850425", + "policies": ["web", "stage"], + "lease_duration": 3600, + "renewable": true + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/cf.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/cf.mdx new file mode 100644 index 0000000000..f3b2c5f3a6 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/cf.mdx @@ -0,0 +1,340 @@ +--- +layout: api +page_title: Cloud Foundry - Auth Methods - HTTP API +description: This is the API documentation for the Vault Cloud Foundry auth method. +--- + +# Pivotal Cloud Foundry (CF) auth method (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault CF auth method. For +general information about the usage and operation of the CF method, please +see the [Vault CF method documentation](/vault/docs/auth/cf). + +This documentation assumes the CF method is mounted at the `/auth/cf` +path in Vault. Since it is possible to enable auth methods at any location, +please update your API calls accordingly. + +## Create configuration + +Configure the root CA certificate to be used for verifying instance identity +certificates, and configure access to the CF API. For detailed instructions +on how to obtain these values, please see the [Vault CF method +documentation](/vault/docs/auth/cf). + +| Method | Path | +| :----- | ----------------- | +| `POST` | `/auth/cf/config` | + +### Parameters + +- `identity_ca_certificates` `(array: [], required)` - The root CA certificate(s) + to be used for verifying that the `CF_INSTANCE_CERT` presented for logging in was + issued by the proper authority. +- `cf_api_addr` `(string: required)`: CF's full API address, to be used for verifying + that a given `CF_INSTANCE_CERT` shows an application ID, space ID, and organization ID + that presently exist. +- `cf_username` `(string: required)`: The username for authenticating to the CF API. +- `cf_password` `(string: required)`: The password for authenticating to the CF API. +- `cf_api_trusted_certificates` `(array: [])`: The certificate that's presented by the + CF API. This configures Vault to trust this certificate when making API calls, resolving + `x509: certificate signed by unknown authority` errors. +- `login_max_seconds_not_before` `(int: 300)`: The maximum number of seconds in the past when a + signature could have been created. The lower the value, the lower the risk of replay + attacks. +- `login_max_seconds_not_after` `(int: 60)`: In case of clock drift, the maximum number of + seconds in the future when a signature could have been created. The lower the value, + the lower the risk of replay attacks. +- `cf_timeout` `(duration: 0s)`: The timeout for the CF API. If not set, the default + timeout is 0, which means no timeout. + +### Sample payload + +```json +{ + "identity_ca_certificates": [ + "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----" + ], + "cf_api_addr": "https://api.sys.somewhere.cf-app.com", + "cf_username": "vault", + "cf_password": "pa55w0rd", + "cf_api_trusted_certificates": [ + "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----" + ], + "login_max_seconds_not_before": 5, + "login_max_seconds_not_after": 1 +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/cf/config +``` + +## Read config + +Returns the present CF configuration. + +| Method | Path | +| :----- | ----------------- | +| `GET` | `/auth/cf/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/cf/config +``` + +### Sample response + +```json +{ + "identity_ca_certificates": [ + "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----" + ], + "cf_api_addr": "https://api.sys.somewhere.cf-app.com", + "cf_username": "vault", + "cf_api_trusted_certificates": [ + "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----" + ], + "login_max_seconds_not_before": 5, + "login_max_seconds_not_after": 1 +} +``` + +## Delete config + +Deletes the present CF configuration. + +| Method | Path | +| :------- | ----------------- | +| `DELETE` | `/auth/cf/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/cf/config +``` + +## Create/Update role + +Create a role in Vault granting a particular level of access to a particular group +of CF instances. We recommend using the CF API or the CF CLI to gain the IDs you +wish to target. + +If you list no `bound` parameters, then any entity with a valid +`CF_INSTANCE_CERT` that's been issued by any configured `identity_ca_certificates` +will be able to authenticate against this role. + +| Method | Path | +| :----- | ---------------------- | +| `POST` | `/auth/cf/roles/:role` | + +### Parameters + +- `role` `(string: required)` - The name of the role. +- `bound_application_ids` `(array: [])` - An optional list of application IDs + an instance must be a member of to qualify as a member of this role. +- `bound_space_ids` `(array: [])` - An optional list of space IDs + an instance must be a member of to qualify as a member of this role. +- `bound_organization_ids` `(array: [])` - An optional list of organization IDs + an instance must be a member of to qualify as a member of this role. +- `bound_instance_ids` `(array: [])` - An optional list of instance IDs + an instance must be a member of to qualify as a member of this role. Please note that + every time you use `cf push` on an app, its instance ID changes. Also, instance IDs + are not verifiable as being presently alive using the CF API. Thus, we recommend against + using this setting for most use cases. +- `disable_ip_matching` `(bool: false)` - If set to true, disables the default behavior + that logging in must be performed from an acceptable IP address described by the + certificate presented. Should only be set to true if required, generally when a proxy + is used to perform logins. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "bound_application_ids": ["09d7eb6a-afc2-49a0-bb32-858c22f2b346"], + "bound_space_ids": ["21005ebb-8943-433e-84e6-d9d9d7338853"], + "bound_organization_ids": ["9785a884-5e93-49bd-97ee-57bf7c2b20e0"], + "bound_instance_ids": ["f3e0f176-3f83-4efb-5842-2ff4"], + "bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"], + "policies": ["default"], + "ttl": "1h", + "max_ttl": "1h", + "period": "1h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/cf/roles/:role +``` + +## Read role + +Returns a CF role. + +| Method | Path | +| :----- | ---------------------- | +| `GET` | `/auth/cf/roles/:role` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/cf/roles/:role +``` + +### Sample response + +```json +{ + "bound_application_ids": ["09d7eb6a-afc2-49a0-bb32-858c22f2b346"], + "bound_space_ids": ["21005ebb-8943-433e-84e6-d9d9d7338853"], + "bound_organization_ids": ["9785a884-5e93-49bd-97ee-57bf7c2b20e0"], + "bound_instance_ids": ["f3e0f176-3f83-4efb-5842-2ff4"], + "bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"], + "policies": ["default"], + "ttl": 2764790, + "max_ttl": 2764790, + "period": 2764790 +} +``` + +## Delete role + +Deletes a CF role. + +| Method | Path | +| :------- | ---------------------- | +| `DELETE` | `/auth/cf/roles/:role` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/cf/roles/:role +``` + +## List roles + +Returns a CF role. + +| Method | Path | +| :----- | ---------------- | +| `LIST` | `/auth/cf/roles` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST + http://127.0.0.1:8200/v1/auth/cf/roles +``` + +### Sample response + +```json +{ + "data": { + "keys": ["role1", "role2"] + } +} +``` + +## Login + +Log in to CF. + +Vault provides both an agent and a CLI tool for logging in that +eliminates the need to build a signature yourself. However, if you do wish to +build the signature, its signing algorithm is viewable [here](https://github.com/hashicorp/vault-plugin-auth-cf/tree/master/signatures). +The [plugin repo](https://github.com/hashicorp/vault-plugin-auth-cf) also contains +a command-line tool (`generate-signature`) that can be compiled as a binary for generating a signature, +and a test that outputs steps in generating the signature so they can be duplicated. + +However, at a high level, these are the steps for generating a signature: + +- Get and format the current time, ex. `2006-01-02T15:04:05Z`. +- Get the full body of the file located at `CF_INSTANCE_CERT`. +- Get the name of the role. +- Concatenate them together in the above order, with no extra string used for joining them. +- Create a SHA256 checksum of the resulting string (`checksum` below). +- Sign the string using the key located at `CF_INSTANCE_KEY`. In Go, this is performed using + the following line of code which you can more deeply inspect: + +``` +rsa.SignPSS(rand.Reader, rsaPrivateKey, crypto.SHA256, checksum, nil) +``` + +- Convert the signature to a string. + +| Method | Path | +| :----- | ---------------- | +| `POST` | `/auth/cf/login` | + +### Parameters + +- `role` `(string: required)` - The name of the role. +- `cf_instance_cert` `(string: required)` - The full body of the file available at + the path denoted by `CF_INSTANCE_CERT`. +- `signing_time` `(string: required)` - The date and time used to construct the signature. +- `signature` `(string: required)` - The signature generated by the algorithm described + above using the `CF_INSTANCE_KEY`. + +### Sample payload + +```json +{ + "role": "test-role", + "cf_instance_cert": "-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIIEtzCCA5+.......ZRtAfQ6r\nwlW975rYa1ZqEdA=\n-----END CERTIFICATE-----", + "signing_time": "2006-01-02T15:04:05Z", + "signature": "MmyUjQ1OqxQmF0W6raVQDL-hlqqe1oG-7abA6Oi3NHwT-9lMfrYxsCwMnd2HKGMly2tCgetcoA2orfquoe6MkMuksx_KGH_KLObcAykt53z4rHceHKGvm7eGj60cjWFYtiNPic-lzUGERLbUeKLMi6NlThm9ueb7hhpyTUpEYtphV3gorbVxvlkrnuYSbgy2NGpOUY1N8dRzcxmHkYjh12XoWEw4Is5aFr6eFKbZ0vmLWBzhJ7_w20CFyTpRYB-6heGz1iR9qEG8mZk3_x4rZpT5mejJ5zmH2xlUjBJMndfcz47btEi2BO9pFVxK2wK-tKeUUFgx6RcomAopTskkmg==" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/cf/login +``` + +### Sample response + +```json +{ + "auth": { + "renewable": true, + "lease_duration": 1800000, + "policies": ["default", "dev"], + "accessor": "20b89871-e6f2-1160-fb29-31c2f6d4645e", + "client_token": "c9368254-3f21-aded-8a6f-7c818e81b17a" + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/gcp.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/gcp.mdx new file mode 100644 index 0000000000..bd8ebf1ec0 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/gcp.mdx @@ -0,0 +1,564 @@ +--- +layout: api +page_title: Google Cloud - Auth Methods - HTTP API +description: |- + This is the API documentation for the Vault Google Cloud authentication + method. +--- + +# Google Cloud auth method (API) + +This is the API documentation for the Vault Google Cloud auth method. To learn +more about the usage and operation, see the +[Vault Google Cloud method documentation](/vault/docs/auth/gcp). + +This documentation assumes the plugin method is mounted at the +`/auth/gcp` path in Vault. Since it is possible to enable auth methods +at any location, please update your API calls accordingly. + +## Configure + +Configures the credentials required for the plugin to perform API calls +to Google Cloud. These credentials will be used to query the status of IAM +entities and get service account or other Google public certificates +to confirm signed JWTs passed in during login. You can configure +credentials either with Application Credentials for a privileged service account, +or using Plugin Workload Identity Federation (WIF). + +### IAM +Vault uses the official Google Cloud SDK to source credentials from environment variables and shared files. + +From the highest precedence to lowest, you can pass root credentials to the Vault server in the following ways: + +1. Provide static credentials to the API as a payload. + +1. Use [plugin workload identity federation](/vault/docs/auth/gcp#plugin-workload-identity-federation-wif) credentials. + +1. Set [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials) +as environment variables on the Vault server. + + + Passing Vault new root credentials overwrites any preexisting root credentials. + + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/auth/gcp/config` | + +### Parameters + +- `credentials` `(string: "")` - A JSON string containing the contents of a GCP + service account credentials file. The service account associated with the credentials + file must have the following [permissions](/vault/docs/auth/gcp#required-gcp-permissions). + If this value is empty, Vault will try to use [Application Default Credentials][gcp-adc] + from the machine on which the Vault server is running. Mutually exclusive with `identity_token_audience`. + +@include 'rotationfields.mdx' + +- `service_account_email` `(string: "")` – Service Account + to impersonate for plugin workload identity federation. Required with `identity_token_audience`. + +- `identity_token_audience` `(string: "")` - The + audience claim value for plugin identity tokens. Must match an allowed audience configured + for the target [Workload Identity Pool](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#prepare). + Mutually exclusive with `credentials`. + +- `identity_token_ttl` `(string/int: 3600)` - The + TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format). + +- `iam_alias` `(string: "role_id")` - Must be either `unique_id` or `role_id`. + If `unique_id` is specified, the service account's unique ID will be used for + alias names during login. If `role_id` is specified, the ID of the Vault role + will be used. Only used if role `type` is `iam`. + +- `iam_metadata` `(string: "default")` - The metadata to include on the token + returned by the `login` endpoint. This metadata will be added to both audit logs, + and on the `iam_alias`. By default, it includes `project_id`, `role`, + `service_account_id`, and `service_account_email`. To include no metadata, + set to `""` via the CLI or `[]` via the API. To use only particular fields, select + the explicit fields. To restore to defaults, send only a field of `default`. + **Only select fields that will have a low rate of change** for your `iam_alias` because + each change triggers a storage write and can have a performance impact at scale. + Only used if role `type` is `iam`. + +- `gce_alias` `(string: "role_id")` - Must be either `instance_id` or `role_id`. + If `instance_id` is specified, the GCE instance ID will be used for alias names + during login. If `role_id` is specified, the ID of the Vault role will be used. + Only used if role `type` is `gce`. + +- `gce_metadata` `(string: "default")` - The metadata to include on the token + returned by the `login` endpoint. This metadata will be added to both audit logs, + and on the `gce_alias`. By default, it includes `instance_creation_timestamp`, + `instance_id`, `instance_name`, `project_id`, `project_number`, `role`, + `service_account_id`, `service_account_email`, and `zone`. To include no metadata, + set to `""` via the CLI or `[]` via the API. To use only particular fields, select + the explicit fields. To restore to defaults, send only a field of `default`. + **Only select fields that will have a low rate of change** for your `gce_alias` because + each change triggers a storage write and can have a performance impact at scale. + Only used if role `type` is `gce`. + +- `custom_endpoint` `(map: )` - Specifies overrides to + [service endpoints](https://cloud.google.com/apis/design/glossary#api_service_endpoint) + used when making API requests. This allows specific requests made during authentication + to target alternative service endpoints for use in [Private Google Access](https://cloud.google.com/vpc/docs/configure-private-google-access) + environments. + + Overrides are set at the subdomain level using the following keys: + - `api` - Replaces the service endpoint used in API requests to `https://www.googleapis.com`. + - `iam` - Replaces the service endpoint used in API requests to `https://iam.googleapis.com`. + - `crm` - Replaces the service endpoint used in API requests to `https://cloudresourcemanager.googleapis.com`. + - `compute` - Replaces the service endpoint used in API requests to `https://compute.googleapis.com`. + + The endpoint value provided for a given key has the form of `scheme://host:port`. + The `scheme://` and `:port` portions of the endpoint value are optional. + +### Sample payload + +```json +{ + "credentials": "{ \"type\": \"service_account\", \"project_id\": \"project-123456\", ...}" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/gcp/config +``` + +## Rotate root credentials + +Request to rotate the GCP service account credentials used by Vault +for this mount. A new key will be generated for the service account, +replacing the internal value, and then a deletion of the old service +account key is scheduled. Note that this does not create a new service +account, only a new version of the service account key. + +This path is only valid if Vault has been configured to use GCP credentials via +the `config/` endpoint where "credentials" were specified. Additionally, the +provided service account must have permissions to create and delete service +account keys. + +| Method | Path | +| :----- | :----------------------------- | +| `POST` | `/auth/gcp/config/rotate-root` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://127.0.0.1:8200/v1/auth/gcp/config/rotate-root +``` + +## Read config + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/auth/gcp/config` | + +Credentials will be omitted from returned data. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/auth/gcp/config +``` + +### Sample response + +```json +{ + "data": { + "ttl": "1h", + "max_ttl": "4h" + } +} +``` + +## Read config + +Returns the configuration, if any, including credentials. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/auth/gcp/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/gcp/config +``` + +### Sample response + +```json +{ + "data": { + "client_email": "service-account@project-123456.iam.gserviceaccount.com", + "client_id": "123456789101112131415", + "private_key_id": "97fd7ba59a96e1f3830296aedb4f50879e4d5382", + "project_id": "project-123456" + } +} +``` + +## Create/Update role + +Registers a role in the method. Role types have specific entities +that can perform login operations against this endpoint. Constraints specific +to the role type must be set on the role. These are applied to the authenticated +entities attempting to login. + +| Method | Path | +| :----- | :--------------------- | +| `POST` | `/auth/gcp/role/:name` | + +### Parameters + +- `name` `(string: )` - The name of the role. + +- `type` `(string: )` - The type of this role. Certain fields + correspond to specific roles and will be rejected otherwise. Please see below + for more information. + +- `bound_service_accounts` `(array: )` - An array of + service account emails or IDs that login is restricted to, + either directly or through an associated instance. If set to + `*`, all service accounts are allowed (you can bind this further using + `bound_projects`.) + +- `bound_projects` `(array: [])` - An array of GCP project IDs. Only entities + belonging to this project can authenticate under the role. + +- `add_group_aliases` `(bool: false)` - If true, any auth token + generated under this token will have associated group aliases, namely + `project-$PROJECT_ID`, `folder-$PROJECT_ID`, and `organization-$ORG_ID` + for the entities project and all its folder or organization ancestors. This + requires Vault to have IAM permission `resourcemanager.projects.get`. + +@include 'tokenfields.mdx' + +#### `iam`-only parameters + +The following parameters are only valid when the role is of type `"iam"`: + +- `max_jwt_exp` `(string: "15m")` - The number of seconds past the time of + authentication that the login param JWT must expire within. For example, if a + user attempts to login with a token that expires within an hour and this is + set to 15 minutes, Vault will return an error prompting the user to create a + new signed JWT with a shorter `exp`. The GCE metadata tokens currently do not + allow the `exp` claim to be customized. + +- `allow_gce_inference` `(bool: true)` - A flag to determine if this role should + allow GCE instances to authenticate by inferring service accounts from the + GCE identity metadata token. + +#### `gce`-only parameters + +The following parameters are only valid when the role is of type `"gce"`: + +- `bound_zones` `(array: [])`: The list of zones that a GCE instance must belong + to in order to be authenticated. If `bound_instance_groups` is provided, it is + assumed to be a zonal group and the group must belong to this zone. + +- `bound_regions` `(array: [])`: The list of regions that a GCE instance must + belong to in order to be authenticated. If `bound_instance_groups` is + provided, it is assumed to be a regional group and the group must belong to + this region. If `bound_zones` are provided, this attribute is ignored. + +- `bound_instance_groups` `(array: [])`: The instance groups that an authorized + instance must belong to in order to be authenticated. If specified, either + `bound_zones` or `bound_regions` must be set too. + +- `bound_labels` `(array: [])`: A comma-separated list of GCP labels formatted + as "key:value" strings that must be set on authorized GCE instances. Because + GCP labels are not currently ACL'd, we recommend that this be used in + conjunction with other restrictions. + +### Sample payload + +Example `iam` role: + +```json +{ + "type": "iam", + "project_id": "project-123456", + "policies": ["prod"], + "ttl": "30m", + "max_ttl": "24h", + "max_jwt_exp": "5m", + "bound_service_accounts": ["dev-1@project-123456.iam.gserviceaccount.com"] +} +``` + +Example `gce` role: + +```json +{ + "type": "gce", + "project_id": "project-123456", + "policies": ["prod"], + "bound_zones": ["us-east1-b", "eu-west2-a"], + "ttl": "30m", + "max_ttl": "24h", + "bound_service_accounts": ["dev-1@project-123456.iam.gserviceaccount.com"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/gcp/role/my-role +``` + +## Edit service accounts on IAM role + +Edit service accounts for an existing IAM role in the method. +This allows you to add or remove service accounts from the list of +service accounts on the role. + +| Method | Path | +| :----- | :-------------------------------------- | +| `POST` | `/auth/gcp/role/:name/service-accounts` | + +### Parameters + +- `name` `(string: )` - The name of an existing `iam` type role. This + will return an error if role is not an `iam` type role. + +- `add` `(array: [])` - The list of service accounts to add to the role's + service accounts. + +- `remove` `(array: [])` - The list of service accounts to remove from the + role's service accounts. + +### Sample payload + +```json +{ + "add": ["dev-1@project-123456.iam.gserviceaccount.com", "123456789"], + "remove": ["dev-2@project-123456.iam.gserviceaccount.com"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/gcp/role/my-role +``` + +## Edit labels on GCE role + +Edit labels for an existing GCE role in the backend. This allows you to add or +remove labels (keys, values, or both) from the list of keys on the role. + +| Method | Path | +| :----- | :---------------------------- | +| `POST` | `/auth/gcp/role/:name/labels` | + +### Parameters + +- `name` `(string: )` - The name of an existing `gce` role. This will + return an error if role is not a `gce` type role. + +- `add` `(array: [])` - The list of `key:value` labels to add to the GCE role's + bound labels. + +- `remove` `(array: [])` - The list of label _keys_ to remove from the role's + bound labels. If any of the specified keys do not exist, no error is returned + (idempotent). + +### Sample payload + +```json +{ + "add": ["foo:bar", "env:dev", "key:value"], + "remove": ["key1", "key2"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/gcp/role/my-role +``` + +## Read role + +Returns the previously registered role configuration. + +| Method | Path | +| :----- | :--------------------- | +| `GET` | `/auth/gcp/role/:name` | + +### Parameters + +- `name` `(string: )` - The name of the role to read. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/gcp/role/my-role +``` + +### Sample response + +```json +{ + "data": { + "bound_labels": { + "env": "dev", + "foo": "bar", + "key": "value" + }, + "bound_service_accounts": ["dev-1@project-123456.iam.gserviceaccount.com"], + "bound_zones": ["eu-west2-a", "us-east1-b"], + "gce_alias": "instance_id", + "max_ttl": 86400, + "policies": ["prod"], + "project_id": "project-123456", + "role_id": "6bbfab2b-ca32-6044-4829-4515728d87b1", + "type": "gce", + "ttl": 1800 + } +} +``` + +## List roles + +Lists all the roles that are registered with the plugin. + +| Method | Path | +| :----- | :---------------- | +| `LIST` | `/auth/gcp/roles` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/gcp/roles +``` + +### Sample response + +```json +{ + "data": { + "keys": ["my-role", "my-other-role"] + } +} +``` + +## Delete role + +Deletes the previously registered role. + +| Method | Path | +| :------- | :--------------------- | +| `DELETE` | `/auth/gcp/role/:role` | + +### Parameters + +- `role` `(string: )` - The name of the role to delete. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/gcp/role/my-role +``` + +## Login + +Login to retrieve a Vault token. This endpoint takes a signed JSON Web Token +(JWT) and a role name for some entity. It verifies the JWT signature with Google +Cloud to authenticate that entity and then authorizes the entity for the given +role. + +| Method | Path | +| :----- | :---------------- | +| `POST` | `/auth/gcp/login` | + +### Sample payload + +- `role` `(string: )` - The name of the role against which the login + is being attempted. + +- `jwt` `(string: )` - A Signed [JSON Web Token][jwt]. + + - For `iam` type roles, this is a JWT signed with the + [`signJwt` method][signjwt-method] or a self-signed JWT. + + - For `gce` type roles, this is an [identity metadata token][instance-token]. + +### Sample payload + +```json +{ + "role": "my-role", + "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/gcp/login +``` + +### Sample response + +```json +{ + "auth": { + "client_token": "f33f8c72-924e-11f8-cb43-ac59d697597c", + "accessor": "0e9e354a-520f-df04-6867-ee81cae3d42d", + "policies": ["default", "dev", "prod"], + "metadata": { + "project_id": "my-project", + "role": "my-role", + "service_account_email": "dev1@project-123456.iam.gserviceaccount.com", + "service_account_id": "111111111111111111111" + }, + "lease_duration": 2764800, + "renewable": true + } +} +``` + +[gcp-adc]: https://developers.google.com/identity/protocols/application-default-credentials +[jwt]: https://tools.ietf.org/html/rfc7519 +[signjwt-method]: https://cloud.google.com/iam/docs/reference/credentials/rest/v1/projects.serviceAccounts/signJwt +[instance-token]: https://cloud.google.com/compute/docs/instances/verifying-instance-identity#request_signature diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/github.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/github.mdx new file mode 100644 index 0000000000..d8e12c8c55 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/github.mdx @@ -0,0 +1,278 @@ +--- +layout: api +page_title: GitHub - Auth Methods - HTTP API +description: This is the API documentation for the Vault GitHub auth method. +--- + +# GitHub auth method (API) + +This is the API documentation for the Vault GitHub auth method. For +general information about the usage and operation of the GitHub method, please +see the [Vault GitHub method documentation](/vault/docs/auth/github). + +This documentation assumes the GitHub method is enabled at the `/auth/github` +path in Vault. Since it is possible to enable auth methods at any location, +please update your API calls accordingly. + +## Configure method + +Configures the connection parameters for GitHub. This path honors the +distinction between the `create` and `update` capabilities inside ACL policies. + +| Method | Path | +| :----- | :-------------------- | +| `POST` | `/auth/github/config` | + +### Parameters + +- `organization` `(string: )` - The organization users must be part + of. +- `organization_id` `(int: 0)` - The ID of the organization users must be part + of. Vault will attempt to fetch and set this value if it is not provided. +- `base_url` `(string: "")` - The API endpoint to use. Useful if you are running + GitHub Enterprise or an API-compatible authentication server. + +### Environment variables +- `VAULT_AUTH_CONFIG_GITHUB_TOKEN` `(string: "")` - An optional GitHub token used to make + authenticated GitHub API requests. This can be useful for bypassing GitHub's + rate-limiting during automation flows when the `organization_id` is not provided. + We encourage you to provide the `organization_id` instead of relying on this environment variable. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "organization": "acme-org" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/github/config +``` + +## Read configuration + +Reads the GitHub configuration. + +| Method | Path | +| :----- | :-------------------- | +| `GET` | `/auth/github/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/github/config +``` + +### Sample response + +```json +{ + "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "organization": "acme-org", + "base_url": "", + "ttl": "", + "max_ttl": "" + }, + "warnings": null +} +``` + +## Map GitHub teams + +Map a list of policies to a team that exists in the configured GitHub organization. + +| Method | Path | +| :----- | :---------------------------------- | +| `POST` | `/auth/github/map/teams/:team_name` | + +### Parameters + +- `team_name` `(string)` - GitHub team name in "slugified" format +- `value` `(string)` - Comma separated list of policies to assign + +### Sample payload + +```json +{ + "value": "dev-policy" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/github/map/teams/dev +``` + +## Read team mapping + +Reads the GitHub team policy mapping. + +| Method | Path | +| :----- | :---------------------------------- | +| `GET` | `/auth/github/map/teams/:team_name` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/github/map/teams/dev +``` + +### Sample response + +```json +{ + "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "key": "dev", + "value": "dev-policy" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Map GitHub users + +Map a list of policies to a specific GitHub user exists in the configured +organization. + +| Method | Path | +| :----- | :---------------------------------- | +| `POST` | `/auth/github/map/users/:user_name` | + +### Parameters + +- `user_name` `(string)` - GitHub user name +- `value` `(string)` - Comma separated list of policies to assign + +### Sample payload + +```json +{ + "value": "sethvargo-policy" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/github/map/users/sethvargo +``` + +The user with username `sethvargo` will be assigned the `sethvargo-policy` +policy **in addition to** any team policies. + +## Read user mapping + +Reads the GitHub user policy mapping. + +| Method | Path | +| :----- | :---------------------------------- | +| `GET` | `/auth/github/map/users/:user_name` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/github/map/users/sethvargo +``` + +### Sample response + +```json +{ + "request_id": "764b6f88-efba-51bd-ed62-cf1c9e80e37a", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "key": "sethvargo", + "value": "sethvargo-policy" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Login + +Login using GitHub access token. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/auth/github/login` | + +### Parameters + +- `token` `(string: )` - GitHub personal API token. + +### Sample payload + +```json +{ + "token": "ABC123..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + http://127.0.0.1:8200/v1/auth/github/login +``` + +### 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": "fred", + "org": "acme-org" + }, + }, + "lease_duration": 7200, + "renewable": true +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/index.mdx new file mode 100644 index 0000000000..2cc48c1d92 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/index.mdx @@ -0,0 +1,17 @@ +--- +layout: api +page_title: Auth Methods - HTTP API +description: |- + Each auth method publishes its own set of API paths and methods. + These endpoints are documented in this section. +--- + +# Auth methods + +Each auth method publishes its own set of API paths and methods. These endpoints +are documented in this section. Auth methods are enabled at a path, but the +documentation will assume the default paths for simplicity. If you are enabling +at a different path, you should adjust your API calls accordingly. + +For the API documentation for a specific auth method, please choose a auth +method from the navigation. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/jwt.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/jwt.mdx new file mode 100644 index 0000000000..85a3e051f4 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/jwt.mdx @@ -0,0 +1,444 @@ +--- +layout: api +page_title: JWT/OIDC - Auth Methods - HTTP API +description: |- + This is the API documentation for the Vault JWT/OIDC authentication + method plugin. +--- + +# JWT/OIDC auth method (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault JWT/OIDC auth method +plugin. To learn more about the usage and operation, see the +[Vault JWT/OIDC method documentation](/vault/docs/auth/jwt). + +This documentation assumes the plugin method is mounted at the +`/auth/jwt` path in Vault. Since it is possible to enable auth methods +at any location, please update your API calls accordingly. + +## Configure + +Configures the validation information to be used globally across all roles. One +(and only one) of `oidc_discovery_url`, `jwks_url`, and `jwt_validation_pubkeys` must be +set. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/auth/jwt/config` | + +### Parameters + +- `oidc_discovery_url` `(string: )` - The OIDC Discovery URL, without any .well-known component (base path). Cannot be used with "jwks_url" or "jwt_validation_pubkeys". +- `oidc_discovery_ca_pem` `(string: )` - The contents of a CA certificate or chain of certificates, in PEM format, to use to validate connections to the OIDC Discovery URL. If not set, system certificates are used. +- `oidc_client_id` `(string: )` - The OAuth Client ID from the provider for OIDC roles. +- `oidc_client_secret` `(string: )` - The OAuth Client Secret from the provider for OIDC roles. +- `oidc_response_mode` `(string: )` - The response mode to be used in the OAuth2 request. Allowed values are "query" and "form_post". Defaults to "query". If using Vault namespaces, and oidc_response_mode is "form_post", then "namespace_in_state" should be set to false. +- `oidc_response_types` `(comma-separated string, or array of strings: )` - The response types to request. Allowed values are "code" and "id_token". Defaults to "code". + Note: "id_token" may only be used if "oidc_response_mode" is set to "form_post". +- `jwks_url` `(string: )` - JWKS URL to use to authenticate signatures. Cannot be used with "oidc_discovery_url" or "jwt_validation_pubkeys". +- `jwks_ca_pem` `(string: )` - The contents of a CA certificate or chain of certificates, in PEM format, to use to validate connections to the JWKS URL. If not set, system certificates are used. +- `jwks_pairs` `(list of JSON object: )` - List of JWKS URL and optional CA certificate pairs. CA certificates must be in PEM format. Must be a list of JSON objects with format `[{"jwks_url": "", "jwks_ca_pem": ""}]`. Cannot be used with "jwks_url" or "jwks_ca_pem". +- `jwt_validation_pubkeys` `(comma-separated string, or array of strings: )` - A list of PEM-encoded public keys to use to authenticate signatures locally. Cannot be used with "jwks_url" or "oidc_discovery_url". +- `bound_issuer` `(string: )` - The value against which to match the `iss` claim in a JWT. Cannot be configured when `jwks_pairs` is set. +- `jwt_supported_algs` `(comma-separated string, or array of strings: )` - A list of supported signing algorithms. Defaults to [RS256] for OIDC roles. Defaults to all [available algorithms](https://github.com/hashicorp/cap/blob/main/jwt/algs.go) for JWT roles. +- `default_role` `(string: )` - The default role to use if none is provided during login. +- `provider_config` `(map: )` - Configuration options for provider-specific handling. Providers with specific handling include: Azure, Google, SecureAuth, IBM ISAM. The options are described in each provider's section in [OIDC Provider Setup](/vault/docs/auth/jwt/oidc-providers). +- `namespace_in_state` `(bool: true)` - Pass namespace in the OIDC state parameter instead of as a separate query parameter. With this setting, the allowed redirect URL(s) in Vault and on the provider side should not contain a namespace query parameter. This means only one redirect URL entry needs to be maintained on the provider side for all vault namespaces that will be authenticating against it. Defaults to true for new configs. + +### Sample payload + +```json +{ + "oidc_discovery_url": "https://myco.auth0.com/", + "bound_issuer": "https://myco.auth0.com/" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/jwt/config +``` + +## Read config + +Returns the previously configured config. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/auth/jwt/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/auth/jwt/config +``` + +### Sample response + +```json +{ + "data":{ + "oidc_discovery_url": "https://myco.auth0.com/", + "oidc_discovery_ca_pem": [], + "bound_issuer": "https://myco.auth0.com/", + "jwt_validation_pubkeys": [] + }, + ... +} +``` + +## Create/Update role + +Registers a role in the method. Role types have specific entities +that can perform login operations against this endpoint. Constraints specific +to the role type must be set on the role. These are applied to the authenticated +entities attempting to login. At least one of the bound values must be set. + +| Method | Path | +| :----- | :--------------------- | +| `POST` | `/auth/jwt/role/:name` | + +### Parameters + +- `name` `(string: )` - Name of the role. +- `role_type` `(string: )` - Type of role, either "oidc" (default) or "jwt". +- `bound_audiences` `(array: )` - List of `aud` claims to match against. + The `bound_audiences` parameter is required for "jwt" roles that contain an + audience (typical case) and **must** match at least one of the associated JWT + `aud` claims. +- `user_claim` `(string: )` - The claim to use to uniquely identify + the user; this will be used as the name for the Identity entity alias created + due to a successful login. The claim value must be a string. +- `user_claim_json_pointer` `(bool: false)` - Specifies if the `user_claim` value uses + [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer) syntax for + referencing claims. By default, the `user_claim` value will not use JSON pointer. +- `clock_skew_leeway` `(int or string: )` - The amount of leeway to add to all claims to + account for clock skew, in seconds. Defaults to `60` seconds if set to `0` and can be disabled + if set to `-1`. Accepts an integer number of seconds, or a Go duration format string. Only applicable + with "jwt" roles. +- `expiration_leeway` `(int or string: )` - The amount of leeway to add to expiration (`exp`) claims to + account for clock skew, in seconds. Defaults to `150` seconds if set to `0` and can be disabled + if set to `-1`. Accepts an integer number of seconds, or a Go duration format string. Only applicable + with "jwt" roles. +- `not_before_leeway` `(int or string: )` - The amount of leeway to add to not before (`nbf`) claims to + account for clock skew, in seconds. Defaults to `150` seconds if set to `0` and can be disabled + if set to `-1`. Accepts an integer number of seconds, or a Go duration format string. Only applicable + with "jwt" roles. +- `bound_subject` `(string: )` - If set, requires that the `sub` + claim matches this value. +- `bound_claims` `(map: )` - If set, a map of claims (keys) to match against respective claim values (values). + Each expected value may be a string, integer, boolean or a list of strings. The interpretation of the bound + claim values is configured with `bound_claims_type`. Keys support [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer) + syntax for referencing claims. +- `bound_claims_type` `(string: "string")` - Configures the interpretation of the bound_claims values. + If `"string"` (the default), the values will be treated as literals and must match exactly. + If set to `"glob"`, the values will be interpreted as globs, with `*` matching any number of + characters. +- `groups_claim` `(string: )` - The claim to use to uniquely identify + the set of groups to which the user belongs; this will be used as the names + for the Identity group aliases created due to a successful login. The claim + value must be a list of strings. Supports [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer) + syntax for referencing claims. +- `claim_mappings` `(map: )` - If set, a map of claims (keys) to be copied to + specified metadata fields (values). Keys support [JSON pointer](/vault/docs/auth/jwt#claim-specifications-and-json-pointer) + syntax for referencing claims. +- `oidc_scopes` `(list: )` - If set, a list of OIDC scopes to be used with an OIDC role. + The standard scope "openid" is automatically included and need not be specified. +- `allowed_redirect_uris` `(list: )` - The list of allowed values for redirect_uri + during OIDC logins. +- `verbose_oidc_logging` `(bool: false)` - Log received OIDC tokens and claims when debug-level + logging is active. Not recommended in production since sensitive information may be present + in OIDC responses. +- `max_age` `(int or string: )` - Specifies the allowable elapsed time in seconds since the last + time the user was actively authenticated with the OIDC provider. If set, the `max_age` request parameter + will be included in the authentication request. See [AuthRequest](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) + for additional details. Accepts an integer number of seconds, or a Go duration format string. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "policies": ["dev", "prod"], + "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients", + "bound_audiences": "https://myco.test", + "user_claim": "https://vault/user", + "groups_claim": "https://vault/groups", + "bound_claims": { + "department": "engineering", + "sector": "7g" + }, + "claim_mappings": { + "preferred_language": "language", + "group": "group" + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/jwt/role/dev-role +``` + +## Read role + +Returns the previously registered role configuration. + +| Method | Path | +| :----- | :--------------------- | +| `GET` | `/auth/jwt/role/:name` | + +### Parameters + +- `name` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/auth/jwt/role/dev-role +``` + +### Sample response + +```json +{ + "data":{ + "bound_subject": "sl29dlldsfj3uECzsU3Sbmh0F29Fios1@clients", + "bound_audiences": [ + "https://myco.test" + ], + "bound_cidrs": [], + "user_claim": "https://vault/user", + "groups_claim": "https://vault/groups", + "policies": [ + "dev", + "prod" + ], + "period": 0, + "ttl": 0, + "num_uses": 0, + "max_ttl": 0 + }, + ... +} + +``` + +## List roles + +Lists all the roles that are registered with the plugin. + +| Method | Path | +| :----- | :--------------- | +| `LIST` | `/auth/jwt/role` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/auth/jwt/role +``` + +### Sample response + +```json +{ + "data": { + "keys": [ + "dev-role", + "prod-role" + ] + }, + ... +} +``` + +## Delete role + +Deletes the previously registered role. + +| Method | Path | +| :------- | :--------------------- | +| `DELETE` | `/auth/jwt/role/:name` | + +### Parameters + +- `name` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/auth/jwt/role/dev-role +``` + +## OIDC authorization URL request + +Obtain an authorization URL from Vault to start an OIDC login flow. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `/auth/jwt/oidc/auth_url` | + +### Parameters + +- `role` `(string: )` - Name of the role against which the login is being + attempted. Defaults to configured `default_role` if not provided. +- `redirect_uri` `(string: )` - Path to the callback to complete the login. This will be + of the form, "https://.../oidc/callback" where the leading portion is dependent on your Vault + server location, port, and the mount of the JWT plugin. This must be configured with Vault and the + provider. See [Redirect URIs](/vault/docs/auth/jwt#redirect-uris) for more information. +- `client_nonce` `(string: )` - Optional client-provided nonce that + must match the `client_nonce` value provided during a subsequent request to the + [callback](/vault/api-docs/auth/jwt#oidc-callback) API. + +### Sample payload + +```json +{ + "role": "dev-role", + "redirect_uri": "https://vault.myco.com:8200/ui/vault/auth/jwt/oidc/callback" +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/jwt/oidc/auth_url +``` + +### Sample response + +```json +{ + "request_id": "c701169c-64f8-26cc-0315-078e8c3ce897", + "data": { + "auth_url": "https://myco.auth0.com/authorize?client_id=r3qXcK2bezU3Sbmh0K16fatW6&nonce=851b69a9bfa5a6a5668111314414e3687891a599&redirect_uri=https%3A%2F%2Fvault.myco.com3A8200%2Fui%2Fvault%2Fauth%2Fjwt%2Foidc%2Fcallback&response_type=code&scope=openid+email+profile&state=1011e726d24960e09cfca2e04b36b38593cb6a22" + }, + ... +} +``` + +## OIDC callback + +Exchange an authorization code for an OIDC ID Token. The ID token will be further validated +against any bound claims, and if valid a Vault token will be returned. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/auth/jwt/oidc/callback` | + +### Parameters + +- `state` `(string: )` - Opaque state ID that is part of the Authorization URL and will + be included in the the redirect following successful authentication on the provider. +- `nonce` `(string: )` - Opaque nonce that is part of the Authorization URL and will + be included in the the redirect following successful authentication on the provider. +- `code` `(string: )` - Provider-generated authorization code that Vault will exchange for + an ID token. +- `client_nonce` `(string: )` - Optional client-provided nonce that must + match the `client_nonce` value provided during the prior request to the + [auth_url](/vault/api-docs/auth/jwt#oidc-authorization-url-request) API. + +### Sample request + +```shell-session +$ curl \ + https://127.0.0.1:8200/v1/auth/jwt/oidc/callback?state=n2kfh3nsl&code=mn2ldl2nv98h2jl&nonce=ni42i2idj2jj +``` + +### Sample response + +```json +{ + "auth":{ + "client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c", + "accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d", + "policies":[ + "default", + "dev", + "prod" + ], + "lease_duration":2764800, + "renewable":true + }, + ... +} +``` + +## JWT login + +Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and +a role name for some entity. It verifies the JWT signature to authenticate that +entity and then authorizes the entity for the given role. + +| Method | Path | +| :----- | :---------------- | +| `POST` | `/auth/jwt/login` | + +### Parameters + +- `role` `(string: )` - Name of the role against which the login is being + attempted. Defaults to configured `default_role` if not provided. +- `jwt` `(string: )` - Signed [JSON Web Token](https://tools.ietf.org/html/rfc7519) (JWT). + +### Sample payload + +```json +{ + "role": "dev-role", + "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/auth/jwt/login +``` + +### Sample response + +```json +{ + "auth":{ + "client_token":"f33f8c72-924e-11f8-cb43-ac59d697597c", + "accessor":"0e9e354a-520f-df04-6867-ee81cae3d42d", + "policies":[ + "default", + "dev", + "prod" + ], + "lease_duration":2764800, + "renewable":true + }, + ... +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/kerberos.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/kerberos.mdx new file mode 100644 index 0000000000..d4eba3baf2 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/kerberos.mdx @@ -0,0 +1,410 @@ +--- +layout: api +page_title: Kerberos - Auth Methods - HTTP API +description: This is the API documentation for the Vault Kerberos auth method plugin. +--- + +# Kerberos auth method (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault Kerberos auth method plugin. To +learn more about the usage and operation, see the +[Vault Kerberos auth method](/vault/docs/auth/kerberos). + +This documentation assumes the Kerberos auth method is mounted at the +`auth/kerberos` path in Vault. Since it is possible to enable auth methods at +any location, please update your API calls accordingly. + +The Kerberos auth method validates both Kerberos and LDAP authorization, +so both configurations are required. + +## Configure Vault Kerberos + +This endpoint configures the keytab and service account to be used by Vault +for verifying inbound SPNEGO tokens. + +| Method | Path | +| :----- | :---------------------- | +| `POST` | `/auth/kerberos/config` | + +- `keytab` `(string: )` – A base 64 representation of the contents + of the Kerberos keytab that will be used for verifying inbound SPNEGO tokens. + It should contain an entry matching the service account given. This can be + created through the following command: `$ base64 vault.keytab > vault.keytab.base64`. +- `service_account` `(string: )` – The service account associated + with both the keytab entry and an LDAP service account created for Vault. Ex.: + `"vault_svc"`. +- `remove_instance_name` - Removes any instance names from a Kerberos service + principal name when parsing the keytab file. For example when this is set to true, + if a keytab has the service principal name `foo/localhost@example.com`, Vault + will strip the service principal name to just be `foo@example.com`. +- `add_group_aliases` - When set to true, Vault will add any LDAP groups found for + the user as group aliases. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/kerberos/config +``` + +### Sample payload + +```json +{ + "add_group_aliases": false, + "keytab": "BQIAAAA6AAEACk1BVFJJWC5MQU4ACXZhdWx0X3N2YwAAAAFdzZSjAgAXABDwhEyRR9nRqkpP8KTn2A83AAAAAg==", + "remove_instance_name": false, + "service_account": "vault_svc" +} +``` + +## Read Vault Kerberos + +This endpoint retrieves the service account for the Kerberos auth method. +The keytab is not returned because it is sensitive information. + +| Method | Path | +| :----- | :---------------------- | +| `GET` | `/auth/kerberos/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/kerberos/config +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "add_group_aliases": false, + "remove_instance_name": false, + "service_account": "vault_svc" + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Configure Kerberos LDAP + +This endpoint configures LDAP in the Kerberos auth method. + +| Method | Path | +| :----- | :--------------------------- | +| `POST` | `/auth/kerberos/config/ldap` | + +### Parameters + +- `url` `(string: )` – The LDAP server to connect to. Examples: + `ldap://ldap.myorg.com`, `ldaps://ldap.myorg.com:636`. Multiple URLs can be + specified with commas, e.g. `ldap://ldap.myorg.com,ldap://ldap2.myorg.com`; + these will be tried in-order. +- `case_sensitive_names` `(bool: false)` – If set, user and group names + assigned to policies within the backend will be case sensitive. Otherwise, + names will be normalized to lower case. Case will still be preserved when + sending the username to the LDAP server at login time; this is only for + matching local user/group definitions. +- `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`, `tls12` or `tls13`. +- `tls_max_version` `(string: tls12)` – Maximum TLS version to use. Accepted + values are `tls10`, `tls11`, `tls12` or `tls13`. +- `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`. + +@include 'tokenfields.mdx' + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/kerberos/config/ldap +``` + +### 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 Kerberos LDAP configuration + +This endpoint retrieves the LDAP configuration for the Kerberos auth method. + +| Method | Path | +| :----- | :--------------------------- | +| `GET` | `/auth/kerberos/config/ldap` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/kerberos/config/ldap +``` + +### 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 Kerberos LDAP groups + +This endpoint returns a list of existing LDAP groups in the Kerberos auth method. + +| Method | Path | +| :----- | :---------------------- | +| `LIST` | `/auth/kerberos/groups` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/kerberos/groups +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": ["scientists", "engineers"] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Read Kerberos LDAP group + +This endpoint returns the policies associated with a Kerberos LDAP group. + +| Method | Path | +| :----- | :---------------------------- | +| `GET` | `/auth/kerberos/groups/:name` | + +### Parameters + +- `name` `(string: )` – The name of the LDAP group. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/kerberos/groups/admins +``` + +### Sample response + +```json +{ + "data": { + "policies": ["admin", "default"] + }, + "renewable": false, + "lease_id": "", + "lease_duration": 0, + "warnings": null +} +``` + +## Create/Update Kerberos LDAP group + +This endpoint creates or updates LDAP group policies. + +| Method | Path | +| :----- | :---------------------------- | +| `POST` | `/auth/kerberos/groups/:name` | + +### 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 + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/kerberos/groups/admins +``` + +## Delete Kerberos LDAP group + +This endpoint deletes the LDAP group and policy association. + +| Method | Path | +| :------- | :---------------------------- | +| `DELETE` | `/auth/kerberos/groups/:name` | + +### Parameters + +- `name` `(string: )` – The name of the LDAP group. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/kerberos/groups/admins +``` + +## Login with Kerberos + +This endpoint allows you to log in with a valid Kerberos SPNEGO +token. This token is obtained by the client, marshalled, and +converted to base 64 using standard encoding. + +Example SPNEGO token (newlines added for readability): + +``` +YIIFSwYGKwYBBQUCoIIFPzCCBTugDTALBgkqhkiG9xIBAgKiggUoBIIFJGCCBSAGCSq +GSIb3EgECAgEAboIFDzCCBQugAwIBBaEDAgEOogcDBQAgAAAAo4IEB2GCBAMwggP/oA +MCAQWhDBsKTUFUUklYLkxBTqIvMC2gAwIBA6EmMCQbBEhUVFAbHDdlZmNjZTg4MGVkM +y5tYXRyaXgubGFuOjgyMDCjggO3MIIDs6ADAgEXoQMCAQKiggOlBIIDoXky+VDSMXqT +Z8XqUiIfzX3+t1ROgO49WYQPoqW1EJLA6vOVtsLITTuDUw8WaLIexki07up3wiO7bKn +unPFN3Y6VaKZfGoubVBFnLwrxqiEqytk19fiuc0bUJD5fNX+BUeHjePPmE73kRcuchC +L5+WkbY0X37cH5uKwCWI6TxpuEc74+mvmGOdAOdisC31MO6EBnOpTlxvKOXzShVk5Xa +rkkHjTJyjoUslgm8JVdj/uB/+x16k0bFVOuWybfeCkn4FY7OeIxypxDJgk6uHU+5jpy +XsdXK4w5GG+TK5BI6LXW8ZH6NOhcTZnRyt1/S4Wihd6HKhL8lH6H+wPWAnN4Ym8jiSg +7O0nIkp9su1l/umJWnLnyUdsC9ekKmCYS9MLrmaUREnKMFfrYOF283gWVmfuSWd832Q +9PIE93vUVTfetw1OwbJXEbG7ex3BotXPJ8yaDUAz4Zv0a6zQlj6JutE7LF3JvuuQeot +QnwPhrZTrmv7ZbmGO3GmkzbMzIwcTXCCKX8ocOo8GLmtEigAPK23FOW2Y0p1meYjF0U +xPzU6MPxfQWiXTWflqabXug7uZh8u76rzSEEceosPxoBqMm6hSmGc85+0bzy/E7AGJM +5ELa2Ny2KpyniPiYCap44GsFZbGM1FwJeh1bG3dJungIn7po4X2wlg00wZVlbHsBzhP +Hys0oxVzOQfrvx88G0fH80+vyzQiQAq4ZqmZqkO0zFSsdqG8ReJvpY0eGzN6/lGwcRl +eav7Vum/s5MalXhYUdOjB4K3A5yQArHbbLfeZlhb7d4vttzPNkmaZ9ZNTyW1GSuqDtd ++YJ0g70aN82KQMWiK3cbJcx/1jcmaN5gjSDm0xk19G2eb8VlRpwLFAazOlpPGozPl0Y +PD45h3Yv3AA5aMVXvEi+NvSYR3z9VXxk6A8wFJxV5NZxV2hYwmxt0S+TYXFeudXzT+W +ySoykcsxIU6rUevmJlEqZDyD3VcdnUOE9pxrIY/cqpdBBwatorF+jIK/ytcTBjvoM6c +LL4g4n/isWMu8Xs6lSMxZzrC3Ewv9VYMzOEFxaHUXlyIC8GCN6t9DHZNzT91TC0u5Rj +XuLqXENczg33dACvr+yhvin/0QNBQG+EXz/E4NiBBWqtTFa0BiTVTwyrKL5OyiLcIVe +v4l8l9vyj/ABwDacr9ZGjhFbOShCTuFFWBPNnBwPqiRBV4y1gPP4abYBmeboLrUiqwZ +81UrP2L8rCTEtYu9q3GmW/pIHqMIHnoAMCAReigd8EgdxwBViqyCyL0+J/k2bw0upNL +h+4wzJcFBFC/wxX2aMvvIYdQv5nWwdNLMII3l/zQ0+eRdzpKfg1ZRT6x0D5278eQLto +9r1CqKNW515u4kD5+pE8VOwZJMVe3FmduaH2gnTLAcoYXkBUE24hcr0ExSY6kTTBWPj +U5dsmUsj3+qrN9JruEADqw99t/EWnN3iTsHh1rOQOd9jIJ1wCIkgvnLB8Rad+q5jguG +8qQh1WDObTlNOnezDtiuLtRb03QDo8Q4Sm72IIcLDlffVvl7WAog5TpC8qM97+Wmv0C +sWw +``` + +| Method | Path | +| :----- | :--------------------- | +| `POST` | `/auth/kerberos/login` | + +### Sample request + +```shell-session +$ curl \ + --header "Authorization: Negotiate YIIFSw...sWw" \ + --request POST \ + http://127.0.0.1:8200/v1/auth/kerberos/login +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/kubernetes.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/kubernetes.mdx new file mode 100644 index 0000000000..4337123e69 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/kubernetes.mdx @@ -0,0 +1,344 @@ +--- +layout: api +page_title: Kubernetes - Auth Methods - HTTP API +description: This is the API documentation for the Vault Kubernetes auth method plugin. +--- + +# Kubernetes auth method (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault Kubernetes auth method plugin. To +learn more about the usage and operation, see the +[Vault Kubernetes auth method](/vault/docs/auth/kubernetes). + +This documentation assumes the Kubernetes method is mounted at the +`/auth/kubernetes` path in Vault. Since it is possible to enable auth methods at +any location, please update your API calls accordingly. + +## Configure method + +The Kubernetes auth method validates service account JWTs and verifies their +existence with the Kubernetes TokenReview API. This endpoint configures the +public key used to validate the JWT signature and the necessary information to +access the Kubernetes API. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `/auth/kubernetes/config` | + +### Parameters + +- `kubernetes_host` `(string: )` - Host must be a host string, a host:port pair, or a URL to the base of the Kubernetes API server. +- `kubernetes_ca_cert` `(string: "")` - Optional PEM encoded CA cert that the TLS client can use to talk with the Kubernetes API. + **Every line must end with a newline `\n`.** + If `kubernetes_ca_cert` is unset, the TLS client uses the local CA cert if Vault is running in a Kubernetes pod. + If `kubernetes_ca_cert` is unset and `disable_local_ca_jwt` set to true, the TLS client uses the system's trusted CA certificate pool. +- `token_reviewer_jwt` `(string: "")` - A service account JWT (or other token) used as a bearer + token to access the TokenReview API to validate other JWTs during login. If not set, + the local service account token is used if running in a Kubernetes pod, otherwise + the JWT submitted in the login payload will be used to access the Kubernetes TokenReview API. +- `pem_keys` `(array: [])` - Optional list of PEM-formatted public keys or certificates + used to verify the signatures of Kubernetes service account + JWTs. If a certificate is given, its public key will be + extracted. Not every installation of Kubernetes exposes these + keys. +- `disable_local_ca_jwt` `(bool: false)` - Disable defaulting to the local CA cert and service account JWT when running in a Kubernetes pod. +- `use_annotations_as_alias_metadata` `(bool: false)` - Use annotations from the client token's associated service account + as alias metadata for the Vault entity. Only annotations with the + `vault.hashicorp.com/alias-metadata-` key prefix are targeted as alias metadata and + your annotations must be 512 characters or less due to the Vault alias + metadata value limit. For example, if you configure the annotation + `vault.hashicorp.com/alias-metadata-foo`, Vault saves the string "foo" along + with the annotation value to the alias metadata. **To save alias metadata, + Vault must have permission to read service accounts from the Kubernetes API**. + +### Deprecated parameters + +-> The following fields have been deprecated and will be removed in a future release: + +- `disable_iss_validation` `(bool: true)` **Deprecated** Disable JWT issuer validation. Allows to skip ISS validation. + +- `issuer` `(string: "")` **Deprecated** Optional JWT issuer. If no issuer is specified, then this plugin will use `kubernetes/serviceaccount` as the default issuer. +See [these instructions](/vault/docs/auth/kubernetes#discovering-the-service-account-issuer) for looking up the issuer for a given Kubernetes cluster. + +### Caveats + +If Vault is running in a Kubernetes Pod, the `kubernetes_ca_cert` and +`token_reviewer_jwt` parameters will automatically default to the local CA cert +(`/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`) and local service +account JWT (`/var/run/secrets/kubernetes.io/serviceaccount/token`). + +If you override the default local CA cert behavior by setting `disable_local_ca_jwt` to `true`, +the plugin's TLS client will automatically default to using the system's trust store for TLS certificate verification. + +### Sample payload + +```json +{ + "kubernetes_host": "https://192.168.99.100:8443", + "kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----\n.....\n-----END CERTIFICATE-----", + "pem_keys": "-----BEGIN CERTIFICATE-----\n.....\n-----END CERTIFICATE-----" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/kubernetes/config +``` + +## Read config + +Returns the previously configured config, excluding credentials. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/auth/kubernetes/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/kubernetes/config +``` + +### Sample response + +```json +{ + "data":{ + "kubernetes_host": "https://192.168.99.100:8443", + "kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----.....-----END CERTIFICATE-----", + "pem_keys": ["-----BEGIN CERTIFICATE-----.....", .....], + "disable_local_ca_jwt": false, + "token_reviewer_jwt_set": false + } +} +``` + +## Create/Update role + +Registers a role in the auth method. Role types have specific entities +that can perform login operations against this endpoint. Constraints specific +to the role type must be set on the role. These are applied to the authenticated +entities attempting to login. + +| Method | Path | +| :----- | :---------------------------- | +| `POST` | `/auth/kubernetes/role/:name` | + +### Parameters + +- `name` `(string: )` - Name of the role. +- `bound_service_account_names` `(array: )` - List of service account + names able to access this role. If set to "\*" all names are allowed. +- `bound_service_account_namespaces` `(array: [])` - List of namespaces + allowed to access this role. If set to "\*" all namespaces are allowed. +- `bound_service_account_namespace_selector` `(string: "")` - A label selector for Kubernetes + namespaces allowed to access this role. Accepts either a JSON or YAML object. The value + should be of type + [LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#labelselector-v1-meta). Currently, label selectors with `matchExpressions` are not supported. + To use label selectors, **Vault must have permission to read namespaces** on the Kubernetes + cluster. If set with `bound_service_account_namespaces`, the conditions are `OR`ed. +- `audience` `(string: "")` - Audience claim to verify in the JWT. +- `alias_name_source` `(string: "serviceaccount_uid")` - Configures how identity aliases are generated. + Valid choices are: `serviceaccount_uid` and `serviceaccount_name`. + + When you specify `serviceaccount_uid`, Vault uses a machine generated UID from + the service account as the identity alias name. Using a service account UID is + both the default and the recommended method as it the more secure option. + + When you specify `serviceaccount_name`, Vault uses the name and namespace from + the service account as the identity alias name (e.g., `vault/vault-auth`). You + should only use `serviceaccount_name` if you consider the risk acceptable or + can mitigate the risk with strong controls around the creation/deletion/access + of your Kubernetes service accounts and need one of the following capabilities: + + 1. fine-grained control over the mapping between Kubernetes service accounts + and Vault identities. + 1. a simpler process for setting entity aliases before creating Kubernetes + service account creation. + + See the [Create an Entity Alias](/vault/api-docs/secret/identity/entity-alias#create-an-entity-alias) document + which further expands on the potential security implications mentioned above. + +@include 'tokenfields.mdx' + +### Sample Payload 1 + +```json +{ + "bound_service_account_names": "vault-auth", + "bound_service_account_namespaces": "default", + "policies": ["dev", "prod"], + "max_ttl": 1800000 +} +``` + +### Sample Payload 2 + +```json +{ + "bound_service_account_names": "vault-auth", + "bound_service_account_namespace_selector": "\"{\"matchLabels\":{\"stage\":\"dev\",\"vault-role\":\"dev-role\"}}", + "policies": ["dev", "prod"], + "max_ttl": 1800000 +} +``` + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/kubernetes/role/dev-role +``` + +## Read role + +Returns the previously registered role configuration. + +| Method | Path | +| :----- | :---------------------------- | +| `GET` | `/auth/kubernetes/role/:name` | + +### Parameters + +- `name` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/kubernetes/role/dev-role +``` + +### Sample response + +```json +{ + "data": { + "bound_service_account_names": "vault-auth", + "bound_service_account_namespaces": "default", + "max_ttl": 1800000, + "ttl": 0, + "period": 0, + "policies": ["dev", "prod"] + } +} +``` + +## List roles + +Lists all the roles that are registered with the auth method. + +| Method | Path | +| :----- | :-------------------------------- | +| `LIST` | `/auth/kubernetes/role` | +| `GET` | `/auth/kubernetes/role?list=true` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/kubernetes/role +``` + +### Sample response + +```json +{ + "data": { + "keys": ["dev-role", "prod-role"] + } +} +``` + +## Delete role + +Deletes the previously registered role. + +| Method | Path | +| :------- | :---------------------------- | +| `DELETE` | `/auth/kubernetes/role/:role` | + +### Parameters + +- `role` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/kubernetes/role/dev-role +``` + +## Login + +Fetch a token. This endpoint takes a signed JSON Web Token (JWT) and +a role name for some entity. It verifies the JWT signature to authenticate that +entity and then authorizes the entity for the given role. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/auth/kubernetes/login` | + +### Parameters + +- `role` `(string: )` - Name of the role against which the login is being + attempted. +- `jwt` `(string: )` - Signed [JSON Web + Token](https://tools.ietf.org/html/rfc7519) (JWT) for authenticating a service + account. + +### Sample payload + +```json +{ + "role": "dev-role", + "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/kubernetes/login +``` + +### Sample response + +```json +{ + "auth": { + "client_token": "62b858f9-529c-6b26-e0b8-0457b6aacdb4", + "accessor": "afa306d0-be3d-c8d2-b0d7-2676e1c0d9b4", + "policies": ["default"], + "metadata": { + "role": "test", + "service_account_name": "vault-auth", + "service_account_namespace": "default", + "service_account_secret_name": "vault-auth-token-pd21c", + "service_account_uid": "aa9aa8ff-98d0-11e7-9bb7-0800276d99bf" + }, + "lease_duration": 2764800, + "renewable": true + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/ldap.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/ldap.mdx new file mode 100644 index 0000000000..be84745da8 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/ldap.mdx @@ -0,0 +1,500 @@ +--- +layout: api +page_title: LDAP - Auth Methods - HTTP API +description: This is the API documentation for the Vault LDAP auth method. +--- + +# LDAP auth method (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault LDAP auth method. For +general information about the usage and operation of the LDAP method, please +see the [Vault LDAP method documentation](/vault/docs/auth/ldap). + +This documentation assumes the LDAP method is mounted at the `/auth/ldap` +path in Vault. Since it is possible to enable auth methods at any location, +please update your API calls accordingly. + +## Configure LDAP + +This endpoint configures the LDAP auth method. + +| Method | Path | +| :----- | :------------------ | +| `POST` | `/auth/ldap/config` | + +### Parameters + +- `url` `(string: ldap://127.0.0.1)` – The LDAP server to connect to. Examples: + `ldap://ldap.myorg.com`, `ldaps://ldap.myorg.com:636`. Multiple URLs can be + specified with commas, e.g. `ldap://ldap.myorg.com,ldap://ldap2.myorg.com`; + these will be tried in-order. +- `case_sensitive_names` `(bool: false)` – If set, user and group names + assigned to policies within the backend will be case sensitive. Otherwise, + names will be normalized to lower case. Case will still be preserved when + sending the username to the LDAP server at login time; this is only for + matching local user/group definitions. +- `connection_timeout` `(integer: 30 or string: "30s")` - Timeout, in seconds, + when attempting to connect to the LDAP server before trying the next URL in + the configuration. +- `request_timeout` `(integer: 90 or string: "90s")` - Timeout, in seconds, for + the connection when making requests against the server before returning back + an error. +- `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`, `tls12` or `tls13`. +- `tls_max_version` `(string: tls12)` – Maximum TLS version to use. Accepted + values are `tls10`, `tls11`, `tls12` or `tls13`. +- `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. +- `client_tls_cert` `(string "")` - Client certificate to provide to the LDAP + server, must be x509 PEM encoded (optional). +- `client_tls_key` `(string "")` - Client certificate key to provide to the LDAP + server, must be x509 PEM encoded (optional). +- `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: "cn")` – 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`. +- `userfilter` `(string: "")` – An optional LDAP user search filter. + The template can access the following context variables: UserAttr, Username. + The default is `({{.UserAttr}}={{.Username}})`, or `({{.UserAttr}}={{.Username@.upndomain}})` + if `upndomain` is set. In order for the `userfilter` to be applied, + both `binddn` and `bindpass` must be set, or `discoverdn` must be set to `true`. +- `anonymous_group_search` `(bool: false)` - Use anonymous binds when performing + LDAP group searches (note: even when `true`, the initial credentials will still + be used for the initial connection test). +- `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`. +- `username_as_alias` `(bool: false)` - If set to true, forces the auth method + to use the username passed by the user as the alias name. +- `dereference_aliases` `(string: never)` - When aliases should be dereferenced + on search operations. Accepted values are 'never', 'finding', 'searching', + 'always'. Defaults to 'never'. +- `max_page_size` `(int: 0)` - If set to a value greater than 0, the LDAP + backend will use the LDAP server's paged search control to request pages of + up to the given size. This can be used to avoid hitting the LDAP server's + maximum result size limit. Otherwise, the LDAP backend will not use the + paged search control. +- `use_token_groups` `(bool: true)` - (Optional) Use the Active Directory tokenGroups + constructed attribute of the user to find the group memberships. +- `enable_samaccountname_login` `(bool: false)` - (Optional) Lets Active Directory + LDAP users log in using `sAMAccountName` or `userPrincipalName` when the + `upndomain` parameter is set. +- `rotation_url` `(string: "")` – The LDAP + server to connect to for password rotation if it is different from `url` parameter. + Examples: `ldap://ldap.myorg.com`, `ldaps://ldap.myorg.com:636`. + +@include 'rotationfields.mdx' + +@include 'tokenfields.mdx' + +@include 'ldap-auth-userfilter-warning.mdx' + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/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", + "username_as_alias": false, + "userattr": "samaccountname", + "userdn": "ou=Users,dc=example,dc=com", + "max_page_size": 1000 +} +``` + +## Read LDAP configuration + +This endpoint retrieves the LDAP configuration for the auth method. + +| Method | Path | +| :----- | :------------------ | +| `GET` | `/auth/ldap/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/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", + "username_as_alias": false, + "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 method. + +| Method | Path | +| :----- | :------------------ | +| `LIST` | `/auth/ldap/groups` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/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 | +| :----- | :------------------------ | +| `GET` | `/auth/ldap/groups/:name` | + +### Parameters + +- `name` `(string: )` – The name of the LDAP group + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/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 | +| :----- | :------------------------ | +| `POST` | `/auth/ldap/groups/:name` | + +### 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 + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/ldap/groups/admins +``` + +## Delete LDAP group + +This endpoint deletes the LDAP group and policy association. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `/auth/ldap/groups/:name` | + +### Parameters + +- `name` `(string: )` – The name of the LDAP group + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/ldap/groups/admins +``` + +## List LDAP users + +This endpoint returns a list of existing users in the method. + +| Method | Path | +| :----- | :----------------- | +| `LIST` | `/auth/ldap/users` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/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 | +| :----- | :--------------------------- | +| `GET` | `/auth/ldap/users/:username` | + +### Parameters + +- `username` `(string: )` – The username of the LDAP user + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/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 | +| :----- | :--------------------------- | +| `POST` | `/auth/ldap/users/:username` | + +### 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 + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/ldap/users/mitchellh +``` + +## Delete LDAP user + +This endpoint deletes the LDAP user and policy association. + +| Method | Path | +| :------- | :--------------------------- | +| `DELETE` | `/auth/ldap/users/:username` | + +### Parameters + +- `username` `(string: )` – The username of the LDAP user + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/ldap/users/mitchellh +``` + +## Login with LDAP user + +This endpoint allows you to log in with LDAP credentials + +| Method | Path | +| :----- | :--------------------------- | +| `POST` | `/auth/ldap/login/:username` | + +### Parameters + +- `username` `(string: )` – The username of the LDAP user +- `password` `(string: )` – The password for the LDAP user. +When authenticating with the Vault CLI, i.e. `vault login -method=ldap username=mitchellh` +the password can alternatively be supplied via the `VAULT_LDAP_PASSWORD` environment variable. + +### Sample payload + +```json +{ + "password": "MyPassword1" +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/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/content/vault/v1.21.x (rc)/content/api-docs/auth/oci.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/oci.mdx new file mode 100644 index 0000000000..ed3886ebd2 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/oci.mdx @@ -0,0 +1,243 @@ +--- +layout: api +page_title: OCI - Auth Methods - HTTP API +description: This is the API documentation for the Vault OCI auth method plugin. +--- + +# OCI auth method (API) + +This is the API documentation for the Vault OCI auth method plugin. To +learn more about the usage and operation, see the +[Vault OCI auth method](/vault/docs/auth/oci). + +This documentation assumes the OCI method is mounted at the +`/auth/oci` path in Vault. Since it is possible to enable auth methods at +any location, please update your API calls accordingly. + +## Configure home tenancy method + +Configure your home tenancy in the Vault, so that only users or instances from your tenancy will be allowed to log into Vault, through the OCI Auth method. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/auth/oci/config` | + +### Parameters + +- `home_tenancy_id` `(string: )` - The Tenancy OCID of your OCI account. + +### Sample payload + +```json +{ + "home_tenancy_id": "ocid1.tenancy.oc1..aaaaaaaah7zkvaffv26pzyauoe2zbnionqvhvsexamplee557wakiofi4ysgqq" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/oci/config +``` + +## Read config + +Returns the previously configured config. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/auth/oci/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/oci/config +``` + +### Sample response + +```json +{ + "data": { + "home_tenancy_id": "ocid1.tenancy.oc1..aaaaaaaah7zkvaffv26pzyauoe2zbnionqvhvsexamplee557wakiofi4ysgqq" + } +} +``` + +## Create/Update role + +Create a Vault administrator role in the OCI Auth method. + +| Method | Path | +| :----- | :--------------------- | +| `POST` | `/auth/oci/role/:name` | + +### Parameters + +- `name` `(string: )` - Name of the role. +- `ocid_list` `(string: )` - A comma separated list of Group or Dynamic Group OCIDs that can take this role. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "ocid_list": "ocid1.group.oc1..aaaaaaaaiqnblimpvmegkqh3bxilrdvjobr7qd223g275idcqhexamplefq,ocid1.dynamicgroup.oc1..aaaaaaaa5hmfyrdaxvmt52ekju5n7ffamn2pdvxaq6esb2vzzoduexamplea", + "token_policies": ["dev", "prod"], + "token_ttl": 1800 +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/oci/role/devrole +``` + +## Read role + +Returns the previously registered role configuration. + +| Method | Path | +| :----- | :--------------------- | +| `GET` | `/auth/oci/role/:name` | + +### Parameters + +- `name` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/oci/role/devrole +``` + +### Sample response + +```json +{ + "data": { + "ocid_list": [ + "ocid1.group.oc1..aaaaaaaaiqnblimpvmegkqh3bxilrdvjobr7qd223g275idcqhexamplefq", + "ocid1.dynamicgroup.oc1..aaaaaaaa5hmfyrdaxvmt52ekju5n7ffamn2pdvxaq6esb2vzzoduexamplea" + ], + "token_ttl": 1800, + "token_policies": ["dev", "prod"] + } +} +``` + +## List roles + +Lists all the roles that are registered with the auth method. + +| Method | Path | +| :----- | :------------------------- | +| `LIST` | `/auth/oci/role` | +| `GET` | `/auth/oci/role?list=true` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/oci/role +``` + +### Sample response + +```json +{ + "data": { + "keys": ["devrole", "prodrole"] + } +} +``` + +## Delete role + +Deletes the previously registered role. + +| Method | Path | +| :------- | :--------------------- | +| `DELETE` | `/auth/oci/role/:role` | + +### Parameters + +- `role` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/oci/role/devrole +``` + +## Login + +Fetch a token. This endpoint takes signed request headers and +a role name for some entity. It verifies the signed request headers to authenticate that +entity and then authorizes the entity for the given role. + +| Method | Path | +| :----- | :---------------------- | +| `POST` | `/auth/oci/login/:role` | + +### Parameters + +- `role` `(string: )` - Name of the role against which the login is being attempted. +- `request_headers` `(list: [])` - Signed request headers for authenticating. For details on signing, see [signing the request](https://docs.cloud.oracle.com/iaas/Content/API/Concepts/signingrequests.htm) + +### Sample payload + +```json +{ + "request_headers": { + "date": ["Fri, 22 Aug 2019 21:02:19 GMT"], + "(request-target)": ["get /v1/auth/oci/login/devrole"], + "host": ["127.0.0.1"], + "content-type": ["application/json"], + "authorization": [ + "Signature algorithm=\"rsa-sha256\",headers=\"date (request-target) host\",keyId=\"ocid1.tenancy.oc1..aaaaaaaaba3pv6wkcr4jqae5f15p2b2m2yt2j6rx32uzr4h25vqstifsfdsq/ocid1.user.oc1..aaaaaaaat5nvwcna5j6aqzjcaty5eqbb6qt2jvpkanghtgdaqedqw3rynjq/73:61:a2:21:67:e0:df:be:7e:4b:93:1e:15:98:a5:b7\",signature=\"GBas7grhyrhSKHP6AVIj/h5/Vp8bd/peM79H9Wv8kjoaCivujVXlpbKLjMPeDUhxkFIWtTtLBj3sUzaFj34XE6YZAHc9r2DmE4pMwOAy/kiITcZxa1oHPOeRheC0jP2dqbTll8fmTZVwKZOKHYPtrLJIJQHJjNvxFWeHQjMaR7M=\",version=\"1\"" + ] + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/oci/login/devrole +``` + +### Sample response + +```json +{ + "auth": { + "token": "62b8ssf9-529c-6b26-e0b8-045fcdb4", + "token_accessor": "afaff6d0-be3d-c8d2-b0d7-2676sss0d9b4", + "token_policies": ["dev"], + "token_duration": 1800 + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/okta.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/okta.mdx new file mode 100644 index 0000000000..5a6ad1eed7 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/okta.mdx @@ -0,0 +1,434 @@ +--- +layout: api +page_title: Okta - Auth Methods - HTTP API +description: This is the API documentation for the Vault Okta auth method. +--- + +# Okta auth method (API) + +This is the API documentation for the Vault Okta auth method. For +general information about the usage and operation of the Okta method, please +see the [Vault Okta method documentation](/vault/docs/auth/okta). + +This documentation assumes the Okta method is mounted at the `/auth/okta` +path in Vault. Since it is possible to enable auth methods at any location, +please update your API calls accordingly. + +## Create configuration + +Configures the connection parameters for Okta. This path honors the +distinction between the `create` and `update` capabilities inside ACL policies. + +| Method | Path | +| :----- | :------------------ | +| `POST` | `/auth/okta/config` | + +### Parameters + +- `org_name` `(string: )` - Name of the organization to be used in the + Okta API. +- `api_token` `(string: "")` - Okta API token. This is required to query Okta + for user group membership. If this is not supplied only locally configured + groups will be enabled. + **Support for okta auth without api_token is deprecated in Vault 1.4** +- `base_url` `(string: "")` - If set, will be used as the base domain + for API requests. If unset, "okta.com" will be used. Other valid examples + are oktapreview.com, and okta-emea.com. +- `bypass_okta_mfa` `(bool: false)` - Whether to bypass an Okta MFA request. + Useful if using one of Vault's built-in MFA mechanisms, but this will also + cause certain other statuses to be ignored, such as `PASSWORD_EXPIRED`. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "org_name": "example", + "api_token": "abc123" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/okta/config +``` + +## Read configuration + +Reads the Okta configuration. + +| Method | Path | +| :----- | :------------------ | +| `GET` | `/auth/okta/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/okta/config +``` + +### Sample response + +```json +{ + "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "base_url": "okta.com", + "bypass_okta_mfa": false, + "org_name": "example", + "token_bound_cidrs": [], + "token_explicit_max_ttl": 0, + "token_max_ttl": 0, + "token_no_default_policy": false, + "token_num_uses": 0, + "token_period": 0, + "token_policies": [], + "token_ttl": 0, + "token_type": "default" + }, + "warnings": null +} +``` + +## List users + +List the users configured in the Okta method. + +| Method | Path | +| :----- | :----------------- | +| `LIST` | `/auth/okta/users` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/okta/users +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": ["fred", "jane"] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Register user + +Registers a new user and maps a set of policies to it. + +| Method | Path | +| :----- | :--------------------------- | +| `POST` | `/auth/okta/users/:username` | + +### Parameters + +- `username` `(string: )` - Name of the user. +- `groups` `(array: [])` - List or comma-separated string of groups associated with the user. +- `policies` `(array: [])` - List or comma-separated string of policies associated with the user. + +```json +{ + "policies": ["dev", "prod"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/okta/users/fred +``` + +## Read user + +Reads the properties of an existing username. + +| Method | Path | +| :----- | :--------------------------- | +| `GET` | `/auth/okta/users/:username` | + +### Parameters + +- `username` `(string: )` - Username for this user. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/okta/users/test-user +``` + +### Sample response + +```json +{ + "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "policies": ["default", "dev"], + "groups": [] + }, + "warnings": null +} +``` + +## Delete user + +Deletes an existing username from the method. + +| Method | Path | +| :------- | :--------------------------- | +| `DELETE` | `/auth/okta/users/:username` | + +### Parameters + +- `username` `(string: )` - Username for this user. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/okta/users/test-user +``` + +## List groups + +List the groups configured in the Okta method. + +| Method | Path | +| :----- | :------------------ | +| `LIST` | `/auth/okta/groups` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/okta/groups +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": ["admins", "dev-users"] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Register group + +Registers a new group and maps a set of policies to it. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `/auth/okta/groups/:name` | + +### Parameters + +- `name` `(string: )` - The name of the group. +- `policies` `(array: [])` - The list or comma-separated string of policies associated with the group. + +```json +{ + "policies": ["dev", "prod"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/okta/groups/admins +``` + +## Read group + +Reads the properties of an existing group. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/auth/okta/groups/:name` | + +### Parameters + +- `name` `(string: )` - The name for the group. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/okta/groups/admins +``` + +### Sample response + +```json +{ + "request_id": "812229d7-a82e-0b20-c35b-81ce8c1b9fa6", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "policies": ["default", "admin"] + }, + "warnings": null +} +``` + +## Delete group + +Deletes an existing group from the method. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `/auth/okta/groups/:name` | + +### Parameters + +- `name` `(string: )` - The name for the group. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/okta/users/test-user +``` + +## Login + +Login with the username and password. + +| Method | Path | +| :----- | :--------------------------- | +| `POST` | `/auth/okta/login/:username` | + +### Parameters + +- `username` `(string: )` - Username for this user. +- `password` `(string: )` - Password for the authenticating user. +- `totp` `(string: )` - Okta Verify TOTP passcode. +- `provider` `(string: )` - MFA TOTP factor provider. `GOOGLE` and `OKTA` are currently supported. +- `nonce` `(string: )` - Nonce provided during a login request to + retrieve the number verification challenge for the matching request. + +### Sample payload + +```json +{ + "password": "Password!" +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/okta/login/fred +``` + +### 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": "fred", + "policies": "default" + }, + "lease_duration": 7200, + "renewable": true + } +} +``` + +## Verify + +Verify a number challenge that may result from an Okta Verify Push challenge. + +| Method | Path | +| :----- | :--------------------------- | +| `GET` | `/auth/okta/verify/:nonce` | + +### Parameters + +- `nonce` `(string: )` - Nonce provided if performing login that +requires number verification challenge. Logins through the vault login CLI +command will automatically generate a nonce. + +### Sample request + +```shell-session +$ curl \ + http://127.0.0.1:8200/v1/auth/okta/verify/nonce/BCR66Ru6oJKPtC00PxJJ +``` + +### Sample response + +```json +{ + "request_id": "de6a8029-79e5-1dd1-dbe9-6405166b3f94", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "correct_answer": 94 + }, + "warnings": null +} +``` + diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/radius.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/radius.mdx new file mode 100644 index 0000000000..ba71ec2ceb --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/radius.mdx @@ -0,0 +1,233 @@ +--- +layout: api +page_title: RADIUS - Auth Methods - HTTP API +description: This is the API documentation for the Vault RADIUS auth method. +--- + +# RADIUS auth method (API) + +This is the API documentation for the Vault RADIUS auth method. For +general information about the usage and operation of the RADIUS method, please +see the [Vault RADIUS method documentation](/vault/docs/auth/radius). + +This documentation assumes the RADIUS method is mounted at the `/auth/radius` +path in Vault. Since it is possible to enable auth methods at any location, +please update your API calls accordingly. + +## Configure RADIUS + +Configures the connection parameters and shared secret used to communicate with +RADIUS. + +| Method | Path | +| :----- | :-------------------- | +| `POST` | `/auth/radius/config` | + +### 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. Default is 10. +- `nas_port` `(integer: 10)` - The NAS-Port attribute of the RADIUS request. + Defaults is 10. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "host": "radius.myorg.com", + "port": 1812, + "secret": "mySecret" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/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 | +| :----- | :----------------------------- | +| `POST` | `/auth/radius/users/:username` | + +### 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 + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/radius/users/test-user +``` + +## Read user + +Reads the properties of an existing username. + +| Method | Path | +| :----- | :----------------------------- | +| `GET` | `/auth/radius/users/:username` | + +### Parameters + +- `username` `(string: )` - Username for this user. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/radius/users/test-user +``` + +### Sample response + +```json +{ + "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 method. + +| Method | Path | +| :------- | :----------------------------- | +| `DELETE` | `/auth/radius/users/:username` | + +### Parameters + +- `username` `(string: )` - Username for this user. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/radius/users/test-user +``` + +## List users + +List the users registered with the method. + +| Method | Path | +| :----- | :------------------- | +| `LIST` | `/auth/radius/users` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/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 | +| :----- | :----------------------------- | +| `POST` | `/auth/radius/login` | +| `POST` | `/auth/radius/login/:username` | + +### Parameters + +- `username` `(string: )` - Username for this user. +- `password` `(string: )` - Password for the authenticating user. + +### Sample payload + +```json +{ + "password": "Password!" +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/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 +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/saml.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/saml.mdx new file mode 100644 index 0000000000..e553b54467 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/saml.mdx @@ -0,0 +1,455 @@ +--- +layout: api +page_title: SAML - Auth Methods - HTTP API +description: |- + This is the API documentation for the Vault SAML auth method. +--- + +# SAML auth method (API) + + + +This is the API documentation for the Vault SAML auth method. To learn more about the +usage and operation, see the [Vault SAML auth method documentation](/vault/docs/auth/saml). + +This documentation assumes the SAML auth method is mounted at the `/auth/saml` path in +Vault. Since it is possible to enable auth methods at any location, please update your +API calls accordingly. + +## Create or update configuration + +Configures the auth method with a SAML identity provider. + +| Method | Path | +|:-----------| :------------------ | +| `POST/PUT` | `/auth/saml/config` | + +### Parameters + +- `idp_metadata_url` `(string, )` - The metadata URL of the identity provider. + Mutually exclusive with `idp_sso_url`, `idp_issuer` and `idp_cert`. Must be a + well-formatted URL. +- `idp_sso_url` `(string, )` - The SSO URL of the + identity provider. Mutually exclusive with `idp_metadata_url`. Must be a + well-formatted URL. +- `idp_entity_id` `(string, )` - The entity ID of + the identity provider. Mutually exclusive with `idp_metadata_url`. +- `idp_cert` `(string, )` - The PEM-encoded + certificate of the identity provider used to verify response and assertion signatures. + Mutually exclusive with `idp_metadata_url`. +- `entity_id` `(string, )` - The entity ID of the SAML authentication + service provider. Must match entity ID configured for the application in the + SAML identity provider. +- `acs_urls` `(list, )` - The well-formated URLs of your Assertion + Consumer Service (ACS) that should receive a response from the identity + provider. Vault returns a security warning if any of the given URLs lack TLS + protection. +- `default_role` `(string, )` - The role to use if no role is provided during login. + If not set, a role is required during login. +- `verbose_logging` `(bool, false)` - **Not recommended for production**. Log + additional, **potentially sensitive** information during the SAML exchange + according to the current logging level. When `verbose_logging` is `true`, + debug-level logs provide user attributes and trace-level logs provide the full + SAML response. +- `validate_response_signature` `(bool, false)` - Enables validation of signature + for at least response in the SAML response. If your IDP allows signing both response + and assertion, then recommendation is to opt in for validating signatures of both + by enabling both options. +- `validate_assertion_signature` `(bool, false)` - Enables validation of signature + for at least assertion in the SAML response. If your IDP allows signing both response + and assertion, then recommendation is to opt in for validating signatures of both + by enabling both options. + +### Sample payload + +```json +{ + "acs_urls": "https://my.vault/v1/auth/saml/callback", + "default_role": "admin", + "entity_id": "https://my.vault/v1/auth/saml", + "idp_metadata_url": "https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml/metadata" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/saml/config +``` + +## Read configuration + +Reads the auth method configuration. + +| Method | Path | +| :------ | :------------------ | +| `GET` | `/auth/saml/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/saml/config +``` + +### Sample response + +```json +{ + "request_id": "09c907d2-2dbe-8a5c-ca97-fad83195738b", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "acs_urls": [ + "https://my.vault/v1/auth/saml/callback" + ], + "default_role": "admin", + "entity_id": "https://my.vault/v1/auth/saml", + "idp_metadata_url": "https://company.okta.com/app/abc123eb9xnIfzlaf697/sso/saml/metadata" + "validate_assertion_signature" : false, + "validate_response_signature" : false + }, + "warnings": null +} +``` + +## Create or update role + +Configures a role in the auth method. Roles define specific constraints required for +authentication and properties of resulting Vault tokens. + +| Method | Path | +|:-----------|:-------------------------| +| `POST/PUT` | `/auth/saml/role/:name` | + +### Parameters + +- `name` `(string: )` - URL parameter that provides the name of the role to create. +- `bound_subjects` `(string: )` - The subject being asserted for SAML + authentication. One of the provided values must match the subject returned in + the SAML assertion from the identity provider. +- `bound_subjects_type` `(string: )` - The type of matching assertion to perform + on `bound_subjects`. If `string`, requires a direct string match. If `glob`, allows for + wildcard matching using the `*` character. +- `bound_attributes` `(map: )` - Mapping of attribute names to values that are + expected to exist in the SAML assertion. The expected value may be a single string or a + comma-separated list of strings. The user will be authenticated if the SAML attributes + match at least one of the expected values. +- `bound_attributes_type` `(string: "string")` - The type of matching assertion to perform + on the key-value pairs provided by `bound_attributes`. If set to `string`, a direct string + match is required. If set to `glob`, allows for wildcard matching using the `*` character. +- `groups_attribute` `(string: )` - The attribute to use to identify the set of + groups to which the user belongs. This will be used as the names for the Identity group + aliases created due to a successful login. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "bound_attributes": "group=admin", + "bound_subjects": "*@hashicorp.com", + "bound_subjects_type": "glob", + "token_policies": "writer", + "ttl": "1h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/saml/role/admin +``` + +## Read role + +Reads a configured role. + +| Method | Path | +| :----- |:------------------------| +| `GET` | `/auth/saml/role/:name` | + +### Parameters + +- `name` `(string: )` - URL parameter that provides the name of the + role to read. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/auth/saml/role/admin +``` + +### Sample response + +```json +{ + "request_id": "3148ca9a-286e-a0a4-5a4b-31b6abb63d37", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "bound_attributes": { + "group": [ + "admin" + ] + }, + "bound_attributes_type": "string", + "bound_subjects": [ + "*@hashicorp.com" + ], + "bound_subjects_type": "glob", + "groups_attribute": "", + "token_bound_cidrs": [], + "token_explicit_max_ttl": 0, + "token_max_ttl": 0, + "token_no_default_policy": false, + "token_num_uses": 0, + "token_period": 0, + "token_policies": [ + "writer" + ], + "token_ttl": 0, + "token_type": "default" + }, + "warnings": null +} +``` + +## List roles + +Lists all the configured roles. + +| Method | Path | +| :----- | :---------------- | +| `LIST` | `/auth/saml/role` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/auth/saml/role?list=true +``` + +### Sample response + +```json +[ + "admin", + "operations" +] +``` + +## Delete Role + +Deletes a configured role. + +| Method | Path | +| :------- | :---------------------- | +| `DELETE` | `/auth/saml/role/:name` | + +### Parameters + +- `name` `(string: )` - URL parameter that provides the name of the + role to delete. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/saml/role/admin +``` + +## Obtain SSO service URL + +Starts a login flow by providing a SAML Single Sign-On (SSO) Service URL for the +configured identity provider. The returned `token_poll_id` can be used to obtain +the Vault token after the user is authenticated with the identity provider and the +SAML response has passed validation. + + +A Vault token is not required to interact with this API. + + +| Method | Path | +|:--------|:-----------------------------| +| `POST` | `/auth/saml/sso_service_url` | + +### Parameters + +- `role` `(string, )` - The role name to use for the login flow. + Defaults to the role configured with `default_role`. +- `client_challenge` `(string, )` - The client challenge value. Must be the + output of a base64-encoded, sha256 digest of the `client_verifier` eventually provided + to the [Token API](/vault/api-docs/auth/saml#obtain-vault-token). Must be at least 44 + bytes in length. +- `client_type` `(string, )` - The type of the requesting client. The response + from the Assertion Consumer Service [Callback API](/vault/api-docs/auth/saml#assertion-consumer-service-callback) + will differ based on the provided type. If `cli`, an HTML success page will be returned + in the response. If `browser`, a blank HTML page will be returned in the response. +- `acs_url` `(string, )` - The URL where the identity provider will send its + SAML response. Must be in the set of configured [`acs_urls`](/vault/api-docs/auth/saml#acs_urls). + +### Sample payload + +```json +{ + "acs_url": "https://my.vault/v1/auth/saml/callback", + "client_challenge": "Z6+7owP80d1aHTha1kdixtT99JkvmG4TPSgbvDwZ70A=", + "client_type": "cli", + "role": "admin" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/saml/sso_service_url +``` + +### Sample response + +```json +{ + "sso_service_url": "https://example.okta.com/app/abc123eb9xnIfzlaf697/id/sso/saml?RelayState=...&SAMLRequest=...", + "token_poll_id": "ee442348-159b-df10-4c59-63050069df4d" +} +``` + +## Assertion consumer service callback + +The assertion consumer service URL of the auth method. Completes the round trip from +the identity provider and performs validations on the SAML response. + + +A Vault token is not required to interact with this API. + + +| Method | Path | +|:--------|:----------------------| +| `POST` | `/auth/saml/callback` | + +### Parameters + +- `RelayState` `(string, )` - The relay state from the original SAML + authentication request that was returned by the identity provider. +- `SAMLResponse` `(string, )` - The signed SAML response from the identity + provider. + +### Sample payload + +```json +{ + "RelayState": "0afe62a9-7b83-a182-0650-c749badfb900", + "SAMLResponse": "..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/saml/callback +``` + +## Obtain vault token + +The token endpoint completes the login flow by returning a Vault token. + + +A Vault token is not required to interact with this API. + + +| Method | Path | +|:--------|:-------------------| +| `POST` | `/auth/saml/token` | + +### Parameters + +- `client_verifier` `(string, )` - The value which produced the `client_challenge` + provided to the [SSO Service URL API](/vault/api-docs/auth/saml#obtain-sso-service-url) + at the start of the authentication flow. Its base64-encoded, sha256 digest must match the + `client_challenge` value. +- `token_poll_id` `(string, )` - The `token_poll_id` value returned from the + [SSO Service URL API](/vault/api-docs/auth/saml#obtain-sso-service-url) at the start of + the authentication flow. + +### Sample payload + +```json +{ + "client_verifier": "59634224-5869-6002-e0b1-35370b8f6b82", + "token_poll_id": "ee442348-159b-df10-4c59-63050069df4d" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/saml/token +``` + +### Sample response + +```json +{ + "request_id": "b16f7cf9-0970-2e64-69d6-f00d055e93c4", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": null, + "warnings": null, + "auth": { + "client_token": "hvs.CAES...", + "accessor": "Rl4gU4amxzBFpFBJixv8xJBK", + "policies": [ + "default", + "writer" + ], + "token_policies": [ + "default", + "writer" + ], + "identity_policies": null, + "metadata": { + "role": "admin" + }, + "orphan": true, + "entity_id": "afd74442-6c48-3d2f-9449-689ce050ba88", + "lease_duration": 3600, + "renewable": true, + "mfa_requirement": null + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/scep.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/scep.mdx new file mode 100644 index 0000000000..0111fb545e --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/scep.mdx @@ -0,0 +1,206 @@ +--- +layout: api +page_title: SCEP - Auth Methods - HTTP API +description: |- + This is the API documentation for the Vault SCEP authentication + method. +--- + +# SCEP auth method (API) + +Use the SCEP authentication plugin API to interact with a mounted plugin +instance. For general information about the usage and operation of the +SCEP method, refer to the [Vault SCEP method documentation](/vault/docs/auth/scep). + + +## Create SCEP role + +Creates or updates a named SCEP role. + +| Method | Path | +|:-------|:------------------------| +| `POST` | `/auth/{mount_path}/role/:name` | + +### Parameters + +- `name` `(string: )` - The name of the SCEP role. +- `display_name` `(string: "")` - The `display_name` value for tokens + issued when authenticating against the role. Defaults to `name`. +- `auth_type` `(enum: )` - Required authentication type for the SCEP + role. Must be one of: `static-challenge`, `intune`. +- `challenge` `(string: "")` - The authentication challenge to use when + `auth_type` is `static-challenge`. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "auth_type": "static-challenge", + "challenge": "super-secret-challenge", + "display_name": "test", + "token_policies": ["access-scep"], + "token_type": "batch" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json + http://127.0.0.1:8200/v1/auth/scep/role/static-challenge-1 +``` + +### Sample response + +```json +{ + "request_id": "c22d68ec-ac3d-ea24-d5d0-efe07dcc0ef6", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "auth_type": "static-challenge", + "display_name": "test", + "name": "static-challenge-1", + "token_bound_cidrs": [], + "token_explicit_max_ttl": 0, + "token_max_ttl": 0, + "token_no_default_policy": false, + "token_num_uses": 0, + "token_period": 0, + "token_policies": [ + "access-scep" + ], + "token_ttl": 0, + "token_type": "batch" + }, + "wrap_info": null, + "warnings": null, + "auth": null, + "mount_type": "scep" +} +``` + +## Read SCEP role + +Get information associated with the named role. + +| Method | Path | +|:-------|:------------------------| +| `GET` | `/auth/{mount_path}/role/:name` | + +### Parameters + +- `name` `(string: )` - The name of the SCEP role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/scep/role/static-challenge-1 +``` + +### Sample response + +```json +{ + "request_id": "07c9bfcc-ee30-6ba9-fce8-07bae5033989", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "auth_type": "static-challenge", + "display_name": "static-challenge-1", + "name": "static-challenge-1", + "token_bound_cidrs": [], + "token_explicit_max_ttl": 0, + "token_max_ttl": 0, + "token_no_default_policy": false, + "token_num_uses": 0, + "token_period": 0, + "token_policies": [ + "access-scep" + ], + "token_ttl": 0, + "token_type": "batch" + }, + "wrap_info": null, + "warnings": null, + "auth": null, + "mount_type": "scep" +} +``` + +## List SCEP roles + +List all currently configured SCEP role names. + +| Method | Path | +| :----- | :----------------- | +| `LIST` | `/auth/{mount_path}/role` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/scep/role +``` + +### Sample response + +```json +{ + "auth": null, + "warnings": null, + "wrap_info": null, + "data": { + "keys": ["static-challenge-1", "intune-1"] + }, + "lease_duration": 0, + "renewable": false, + "lease_id": "" +} +``` + +## Delete SCEP role + +Delete the named role. + +| Method | Path | +|:---------|:------------------------| +| `DELETE` | `/auth/{mount_path}/role/:name` | + +### Parameters + +- `name` `(string: )` - The name of the SCEP role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/scep/role/static-challenge-1 +``` + +## Login + +SCEP authentication endpoint for delegated authentication from a PKI mount. + +| Method | Path | +|:-------|:-------------------| +| `POST` | `/auth/{mount_path}/login` | + +### Parameters + +- `name` `(string: "")` - The SCEP role associated with the PKI mount. Leaving + `name` unset tells Vault to try all SCEP roles and return the first one that + matches. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/spiffe.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/spiffe.mdx new file mode 100644 index 0000000000..ebdaf2bf01 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/spiffe.mdx @@ -0,0 +1,286 @@ +--- +layout: api +page_title: SPIFFE - Auth Methods - HTTP API +description: This is the API documentation for the Vault SPIFFE authentication method. +--- + +# SPIFFE auth method (API) + +Use the SPIFFE plugin to support authentication with JWT or x.509 based SPIFFE +SVIDs. The example code below assumes you mounted the SPIFFE plugin at +`/auth/spiffe`. Since it is possible to enable auth methods at any location, +please update your API calls accordingly. + +## Create configuration + +Configure or refresh the SPIFFE trust domain and associated trust bundle for the +plugin. To refresh an existing cached bundle, call the endpoint with an empty +payload. + +If you use profiles that fetch the trust bundle from a remote endpoint, Vault +immediately fetches a trust bundle when you create the configuration unless you +set `defer_bundle_fetch` to `true`. If the initial fetch fails, Vault returns an +error and rolls back any configuration changes. + +| Method | Path | +|:-------|:----------------------| +| `POST` | `/auth/spiffe/config` | + +### Request parameters + +- `trust_domain` `(string: )` - The SPIFFE trust domain used by the + plugin. You can omit the `spiffe://` prefix. +- `profile` `(string: )` - The profile to use to fetch the trust bundle, see profile section below +for associated parameters based on the selected profile. Valid values are `static`, +- `profile` `(string: )` - Set the profile type and fetch mechanism + for the profile used to fetch the trust bundle. Must be one of: + - `https_spiffe_bundle` - fetch the trust bundle in JWKS format from a + SPIFFE endpoint. + - `https_web_bundle` - fetch the trust bundle in JWKS format from an HTTPS + endpoint. + - `https_web_pem` - fetch a valid X.509 certificate as the trust bundle + from an HTTPS endpoint. + - `static` - use the trust bundle explicilty configured in the profile + definition. +- `audience` `(array: [])` - A list of allowed audience values for JWT based + SVIDs. Vault rejects any JWT-based SVIDS not provided in the audience list. + Leave `audience` empty to deny all JWT-based SVIDS. +- `defer_bundle_fetch` `(bool: false)` - Tells Vault not to fetch the remote + trust bundle to validate the configuration. For example, you can set + `defer_bundle_fetch` to `true` when you need to update your Vault + configuration before the remote endpoint is available. + +#### Profile parameters + +In addition to the common request parameters, you must set the following profile-specific parameters based on the value of `profile`. + +##### Static profile (`static`) + +Provide the trust bundle directly as part of the configuration. + +- `bundle` `(string: )` - A PEM encoded X.509 certificate or a JWKS document following +the SPIFFE Trust Domain and Bundle specification. + +##### Remote HTTPS Web PEM profile (`https_web_pem`) + +Provide HTTPS connection details so Vault can fetch an X.509 certificate +to use as a trust bundle. + +- `endpoint_url` `(string: )` - URL of an HTTPS server that can + provide the PEM encoded X.509 certificate. +- `endpoint_root_ca_truststore_pem` `(string: "")` - A PEM encoded X.509 + certificate Vault can use as a root CA to validate the TLS certificate provided + by the remote server. Leave `endpoint_root_ca_truststore_pem` unset to use the + system root CAs. + +##### Remote HTTPS Web Bundle profile (`https_web_bundle`) + +Provide HTTPS connection details so Vault can fetch a SPIFFE bundle in JWKS +format from a remote server. To use the remote HTTPS web bundle profile with a +SPIRE server, the server must support a SPIRE Federation API endpoint of type +`https_web`. + +- `endpoint_url` `(string: )` - URL of an HTTPS server that can + provide the PEM encoded X.509 certificate. +- `endpoint_root_ca_truststore_pem` `(string: "")` - A PEM encoded X.509 + certificate Vault can use as a root CA to validate the TLS certificate provided + by the remote server. Leave `endpoint_root_ca_truststore_pem` unset to use the + system root CAs. + +##### Remote HTTPS SPIFFE Bundle profile (`https_spiffe_bundle`) + +Provide HTTPS connection details so Vault can fetch a SPIFFE bundle in JWKS +format from a remote SPIFFE endpoint. To use the remote HTTPS SPIFFE profile +with a SPIRE server, the server must support a SPIRE Federation API endpoint of +type `https_spiffe`. + +- `endpoint_spiffe_id` `(string: )` - The SPIFFE ID of the remote endpoint to connect to. +- `endpoint_url` `(string: )` - URL of an HTTPS server that can +provide the PEM encoded X.509 certificate. +- `bundle` `(string: )` - A SPIFFE bundle in JKWS format that Vault + can use as a trust anchor to validate the TLS certificate from the SPIFFE + endpoint. + +### Sample payload + +```json +{ + "trust_domain": "example.org", + "profile": "https_web_bundle", + "endpoint_url": "https://spire.example.org", + "endpoint_root_ca_truststore_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n", + "audience": ["vault"] +} +``` + +## Read configuration + +Fetch the SPIFFE configuration details and relevant metadata about the currently +cached trust bundle. + +| Method | Path | +|:-------|:----------------------| +| `GET` | `/auth/spiffe/config` | + +### Request parameters + +None. + +### Sample response + +```json +{ + "cached_bundle_config_version": 1, + "cached_bundle_fetched_at": "2025-09-18T14:02:21.730308-04:00", + "cached_bundle_refresh_hint": "15m0s", + "cached_bundle_sequence_number": 11, + "endpoint_root_ca_truststore_pem": "-----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE-----\n", + "endpoint_url": "https://192.168.1.65:8443", + "profile": "https_web_bundle", + "trust_domain": "spiffe://test.dadgarcorp.org", + "version": 1 +} +``` + +## Create role + +Create or update a named role that maps SPIFFE IDs to Vault policies. + +Different roles may not have the same workload ID patterns. Vault uses standard +[policy priority matching](vault/docs/concepts/policies#priority-matching) logic +to determine the appropriate role when there are overlapping patterns across +different roles (e.g. role1 has `team1/*` and role2 has `team1/service1`). + +| Method | Path | +|:-------|:---------------------------| +| `POST` | `/auth/spiffe/role/:name` | + +### Path parameters + +- `name` `(string: )` - The unique name of the SPIFFE role you want to + update. + +### Request parameters + +- `display_name` `(string: "")` - The human-readable name for tokens +issued when authenticating against the role. Defaults to the value provided for +`name`. +- `workload_id_patterns` `(array: )` - A comma separated list of + patterns that match an incoming workload ID associated with the SPIFFE role. + You can find the workload ID by stripping the trust domain prefix and slash + separator from the associated SPIFFE ID. You can use the following special + characters with the workload ID: + + - `*` - matches to any number of characters at the end of an ID to perform + prefix matching + - `+` - matches to any number of characters within a single path segment to + perform wildcard matching. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "workload_id_patterns": ["service1", "team1/*", "team2/+/service1"], + "display_name": "example-role", + "token_policies": ["spiffe-service1"] +} +``` + +## Read role + +Read the named SPIFFE role. + +| Method | Path | +|:-------|:--------------------------| +| `GET` | `/auth/spiffe/role/:name` | + +### Path parameters + +- `name` `(string: )` - The unique name of the SPIFFE role you want to + read. + +### Sample response + +```json +{ + "alias_metadata": {}, + "display_name": "example-role", + "name": "example-role", + "token_bound_cidrs": [], + "token_explicit_max_ttl": 0, + "token_max_ttl": 0, + "token_no_default_policy": false, + "token_num_uses": 0, + "token_period": 0, + "token_policies": [ + "spiffe-service1" + ], + "token_ttl": 0, + "token_type": "default", + "workload_id_patterns": [ + "service1", + "team1/*", + "team2/+/service1" + ] +} +``` + +## Delete role + +Delete the named SPIFFE role. + +| Method | Path | +|:---------|:--------------------------| +| `DELETE` | `/auth/spiffe/role/:name` | + +### Path parameters + +- `name` `(string: )` - The unique name of the SPIFFE role you want to + delete. + +## List roles + +List the names of all SPIFFE roles. + +| Method | Path | +|:-------|:--------------------| +| `LIST` | `/auth/spiffe/role` | + +### Request parameters + +None. + +### Sample response + +```json +{ + "keys": [ + "example-role" + ] +} +``` + +## Login with SPIFFE ID + +Authenticate a client using a SPIFFE JWT or x.509 SVID. To use JWT, set the SVID +in the `Authorization` header as the bearer token and set the `Authorization` +header as a passthrough request header in the SPIFFE backend. + +| Method | Path | +|:-------|:---------------------| +| `POST` | `/auth/spiffe/login` | + +### Request parameters + +- `role` `(string: "")` - The name of the role to use for authentication. Leave + `role` unset to have Vault iterate over all configured roles. +- `type` `(string: "auto")` - Set the SVID source for authentication. Must be one of: + - `auto` - use JWT SVIDs if provided, otherwise use SVIDs from the peer x.509 + certificate. + - `cert` - only use SVIDs from x.509 certificates. + - `jwt` - only use JWT SVIDs. + + + diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/token.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/token.mdx new file mode 100644 index 0000000000..5301b17702 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/token.mdx @@ -0,0 +1,851 @@ +--- +layout: api +page_title: Token - Auth Methods - HTTP API +description: This is the API documentation for the Vault token auth method. +--- + +# Token auth method (API) + +This is the API documentation for the Vault token auth method. For +general information about the usage and operation of the token method, please +see the [Vault Token method documentation](/vault/docs/auth/token). + +## 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 | +| :----- | :---------------------- | +| `LIST` | `/auth/token/accessors` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/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 | +| :----- | :------------------------------ | +| `POST` | `/auth/token/create` | +| `POST` | `/auth/token/create-orphan` | +| `POST` | `/auth/token/create/:role_name` | + +### Parameters + +- `id` `(string: "")` – The ID of the client token. Can only be specified by a + root token. The ID provided may not contain a `.` character. Otherwise, the + token ID is a randomly generated value. + + _Note:_ The ID should not start with the `s.` prefix. + +- `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 + the calling token is root or contains `sudo` capabilities to `auth/token/create`. + 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 devices. +- `no_parent` `(bool: false)` - This argument only has effect if used by a root + or sudo caller. When set to true, the token created will not have a 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](/vault/docs/configuration), or indefinitely if the + root policy is used. +- `type` `(string: "")` - The token type. Can be "batch" or "service". Defaults + to the type specified by the role configuration named by `role_name`. +- `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 token or one with the sudo capability. +- `entity_alias` `(string: "")` - Name of the entity alias to associate with + during token creation. Only works in combination with `role_name` argument + and used entity alias must be listed in `allowed_entity_aliases`. If this has + been specified, the entity will not be inherited from the parent. + +### Sample payload + +```json +{ + "policies": ["web", "stage"], + "meta": { + "user": "armon" + }, + "ttl": "1h", + "renewable": true +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/token/create +``` + +### Sample response + +```json +{ + "request_id": "f00341c1-fad5-f6e6-13fd-235617f858a1", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": null, + "wrap_info": null, + "warnings": [ + "Policy \"stage\" does not exist", + "Policy \"web\" does not exist" + ], + "auth": { + "client_token": "s.wOrq9dO9kzOcuvB06CMviJhZ", + "accessor": "B6oixijqmeR4bsLOJH88Ska9", + "policies": ["default", "stage", "web"], + "token_policies": ["default", "stage", "web"], + "metadata": { + "user": "armon" + }, + "lease_duration": 3600, + "renewable": true, + "entity_id": "", + "token_type": "service", + "orphan": false, + "num_uses": 0 + } +} +``` + +## Lookup a token + +Returns information about the client token. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/auth/token/lookup` | + +### Parameters + +- `token` `(string: )` - Token to lookup. + +### Sample payload + +```json +{ + "token": "ClientToken" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/token/lookup +``` + +### Sample response + +```json +{ + "data": { + "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed", + "creation_time": 1523979354, + "creation_ttl": 2764800, + "display_name": "ldap2-tesla", + "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9", + "expire_time": "2018-05-19T11:35:54.466476215-04:00", + "explicit_max_ttl": 0, + "id": "cf64a70f-3a12-3f6c-791d-6cef6d390eed", + "identity_policies": ["dev-group-policy"], + "issue_time": "2018-04-17T11:35:54.466476078-04:00", + "meta": { + "username": "tesla" + }, + "num_uses": 0, + "orphan": true, + "path": "auth/ldap2/login/tesla", + "policies": ["default", "testgroup2-policy"], + "renewable": true, + "ttl": 2764790 + } +} +``` + +## Lookup a token (Self) + +Returns information about the current client token. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/auth/token/lookup-self` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/token/lookup-self +``` + +### Sample response + +```json +{ + "data": { + "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed", + "creation_time": 1523979354, + "creation_ttl": 2764800, + "display_name": "ldap2-tesla", + "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9", + "expire_time": "2018-05-19T11:35:54.466476215-04:00", + "explicit_max_ttl": 0, + "id": "cf64a70f-3a12-3f6c-791d-6cef6d390eed", + "identity_policies": ["dev-group-policy"], + "issue_time": "2018-04-17T11:35:54.466476078-04:00", + "meta": { + "username": "tesla" + }, + "num_uses": 0, + "orphan": true, + "path": "auth/ldap2/login/tesla", + "policies": ["default", "testgroup2-policy"], + "renewable": true, + "ttl": 2764790 + } +} +``` + +## Lookup a token (Accessor) + +Returns information about the client token from the accessor. + +| Method | Path | +| :----- | :---------------------------- | +| `POST` | `/auth/token/lookup-accessor` | + +### Parameters + +- `accessor` `(string: )` - Token accessor to lookup. + +### Sample payload + +```json +{ + "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/token/lookup-accessor +``` + +### Sample response + +```json +{ + "data": { + "accessor": "8609694a-cdbc-db9b-d345-e782dbb562ed", + "creation_time": 1523979354, + "creation_ttl": 2764800, + "display_name": "ldap2-tesla", + "entity_id": "7d2e3179-f69b-450c-7179-ac8ee8bd8ca9", + "expire_time": "2018-05-19T11:35:54.466476215-04:00", + "explicit_max_ttl": 0, + "id": "", + "identity_policies": ["dev-group-policy"], + "issue_time": "2018-04-17T11:35:54.466476078-04:00", + "meta": { + "username": "tesla" + }, + "num_uses": 0, + "orphan": true, + "path": "auth/ldap2/login/tesla", + "policies": ["default", "testgroup2-policy"], + "renewable": true, + "ttl": 2763902 + } +} +``` + +## 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 | +| :----- | :------------------ | +| `POST` | `/auth/token/renew` | + +### Parameters + +- `token` `(string: )` - Token to renew. This can be part of the URL + or the body. +- `increment` `(string: "")` - An optional requested increment duration can be + provided. This increment may not be honored, for instance in the case of periodic tokens. + If not supplied, Vault will use the default TTL. This is specified as a numeric string + with suffix like "30s" or "5m". + +### Sample payload + +```json +{ + "token": "ClientToken" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/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 | +| :----- | :----------------------- | +| `POST` | `/auth/token/renew-self` | + +### Parameters + +- `increment` `(string: "")` - An optional requested increment duration can be + provided. This increment may not be honored, for instance in the case of periodic tokens. + If not supplied, Vault will use the default TTL. This is specified as a numeric string + with suffix like "30s" or "5m". + +### Sample payload + +```json +{ + "increment": "1h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/token/renew-self +``` + +### Sample response + +```json +{ + "auth": { + "client_token": "ABCD", + "policies": ["web", "stage"], + "metadata": { + "user": "armon" + }, + "lease_duration": 3600, + "renewable": true + } +} +``` + +## Renew a token (Accessor) + +Renews a lease associated with a token using its accessor. 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 | +| :----- | :--------------------------- | +| `POST` | `/auth/token/renew-accessor` | + +### Parameters + +- `accessor` `(string: )` - Accessor associated with the token to + renew. +- `increment` `(string: "")` - An optional requested lease increment can be + provided. This increment may be ignored. + +### Sample payload + +```json +{ + "accessor": "7JFKXuXKXa2D44YfDiovZ9aq" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/token/renew-accessor +``` + +### Sample response + +```json +{ + "auth": { + "client_token": "", + "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 dynamic secrets +generated with it are also revoked. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/auth/token/revoke` | + +### Parameters + +- `token` `(string: )` - Token to revoke. + +### Sample payload + +```json +{ + "token": "ClientToken" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/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 | +| :----- | :------------------------ | +| `POST` | `/auth/token/revoke-self` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/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 | +| :----- | :---------------------------- | +| `POST` | `/auth/token/revoke-accessor` | + +### Parameters + +- `accessor` `(string: )` - Accessor of the token. + +### Sample payload + +```json +{ + "accessor": "2c84f488-2133-4ced-87b0-570f93a76830" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/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 | +| :----- | :-------------------------- | +| `POST` | `/auth/token/revoke-orphan` | + +### Parameters + +- `token` `(string: )` - Token to revoke. This can be part of the URL + or the body. + +### Sample payload + +```json +{ + "token": "ClientToken" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/token/revoke-orphan +``` + +## Read token role + +Fetches the named role configuration. + +| Method | Path | +| :----- | :----------------------------- | +| `GET` | `/auth/token/roles/:role_name` | + +### Parameters + +- `role_name` `(string: )` - The name of the token role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/token/roles/nomad +``` + +### Sample response + +```javascript +{ + "request_id": "075a19cd-4e56-a3ca-d956-7609819831ec", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "allowed_entity_aliases": [ + "my-entity-alias" + ], + "allowed_policies": [], + "disallowed_policies": [], + "allowed_policies_glob": [], + "disallowed_policies_glob": [], + "explicit_max_ttl": 0, + "name": "nomad", + "orphan": false, + "path_suffix": "", + "period": 0, + "renewable": true, + "token_explicit_max_ttl": 0, + "token_no_default_policy": false, + "token_period": 0, + "token_type": "default-service" + }, + "warnings": null +} +``` + +## List token roles + +List available token roles. + +| Method | Path | +| :----- | :------------------ | +| `LIST` | `/auth/token/roles` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST + http://127.0.0.1:8200/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/leases/revoke-prefix` endpoint. + +| Method | Path | +| :----- | :----------------------------- | +| `POST` | `/auth/token/roles/:role_name` | + +### 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` or glob matched in `disallowed_policies_glob`, + 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. +- `allowed_policies_glob` `(list: [])` – If set, tokens can be created with any + subset of glob matched 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 name globs. If at creation time + `no_default_policy` is not set and `"default"` is not contained in + `disallowed_policies` or glob matched in `disallowed_policies_glob`, + the `"default"` policy will be added to the created token automatically. + If combined with `allowed_policies` policies need to only match one of the two + lists to be permitted. Note that unlike `allowed_policies` the policies listed + in `allowed_policies_glob` will not be added to the token when no policies are + specified in the call to `/auth/token/create/:role_name`. +- `disallowed_policies_glob` `(list: [])` – If set, successful token creation via + this role will require that no requested policies glob match any of policies in + this list. The parameter is a comma-delimited string of policy name globs. + Adding any glob that matches `"default"` to this list will prevent `"default"` + from being added automatically to created tokens. + If combined with `disallowed_policies` policies need to only match one of the + two lists to be blocked. +- `orphan` `(bool: false)` - 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. +- `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. +- `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/leases/revoke-prefix`. +- `allowed_entity_aliases` `(string: "", or list: [])` - String or JSON list + of allowed entity aliases. If set, specifies the entity aliases which are + allowed to be used during token generation. This field supports globbing. + Note that `allowed_entity_aliases` is not case sensitive. + +@include 'tokenstorefields.mdx' + +### Sample payload + +```json + "allowed_policies": [ + "dev" + ], + "name": "nomad", + "orphan": false, + "bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"], + "renewable": true, + "allowed_entity_aliases": ["web-entity-alias", "app-entity-*"] +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST + --data @payload.json + http://127.0.0.1:8200/v1/auth/token/roles/nomad +``` + +## Delete token role + +This endpoint deletes the named token role. + +| Method | Path | +| :------- | :----------------------------- | +| `DELETE` | `/auth/token/roles/:role_name` | + +### Parameters + +- `role_name` `(string: )` - The name of the token role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/token/roles/admins +``` + +## Tidy tokens + +Performs some maintenance tasks to clean up invalid entries that may remain +in the token store. On Enterprise, Tidy will only impact the tokens in the +specified namespace, or the root namespace if unspecified. + +Generally, running this is not needed unless upgrade notes or support personnel +suggest it. There are two potential dangers to running tidy: first, this will +perform a lot of read I/O to the storage method, as it will essentially reload the +entirety of the token store into memory. Depending on how much cleanup is +required (usually very little) there may also be a large number of writes. +Second, this will cause Vault's memory usage to balloon up, because the default +Vault internal cache is unlimited in size and every value read from storage will +be cached. Listing the `/auth/token/accessors` endpoint is a good way to get +some sense of the potential impact: tidy does this and more, so if this call creates problems +for your cluster, it would be wise to give Vault more resources before attempting +tidy. Note that the request may time out depending on +[max duration](/vault/docs/configuration#default_max_request_duration) +and your client's timeout configuration, make sure to allow it run to completion +to properly judge the impact. + +Tidy will load every token accessor and cubbyhole in the namespace, as well +as all the secondary index entries that are used to group tokens into trees so +that parent token revocation also revokes child tokens. + +For each parent token listed in the secondary index, tidy will check if the token +still exists in storage, and if not its child tokens that still exist will be +made orphans, then the parent token will be removed from the secondary index. + +For each accessor found, tidy will check if the corresponding token still exists +in storage, and if not will delete the accessor. If the token still exists in +storage but shouldn't, tidy will try to revoke it and any child leases it might +have, then delete the accessor. + +Finally, any cubbyhole entries that are associated with tokens which weren't deemed +valid in the above steps will be deleted. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/auth/token/tidy` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/auth/token/tidy +``` + +### Sample response + +```json +{ + "request_id": "84437c7f-36a1-6c1d-381d-14ec99217e94", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": null, + "wrap_info": null, + "warnings": [ + "Tidy operation successfully started. Any information from the operation will be printed to Vault's server logs." + ], + "auth": null +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/auth/userpass.mdx b/content/vault/v1.21.x (rc)/content/api-docs/auth/userpass.mdx new file mode 100644 index 0000000000..6625f9528c --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/auth/userpass.mdx @@ -0,0 +1,294 @@ +--- +layout: api +page_title: Userpass - Auth Methods - HTTP API +description: |- + This is the API documentation for the Vault username and password + auth method. +--- + +# Userpass auth method (HTTP API) + +This is the API documentation for the Vault Username & Password auth method. For +general information about the usage and operation of the Username and Password method, please +see the [Vault Userpass method documentation](/vault/docs/auth/userpass). + +This documentation assumes the Username & Password method is mounted at the `/auth/userpass` +path in Vault. Since it is possible to enable auth methods 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 | +| :----- | :------------------------------- | +| `POST` | `/auth/userpass/users/:username` | + +### Parameters + +- `username` `(string: )` – The username for the user. Accepted characters: alphanumeric plus "_", "-", "." (underscore, hyphen and period); username cannot begin with a hyphen, nor can it begin or end with a period. +- `password` `(string: )` - Password for the current user. Only required when creating the user. Mutually exclusive with `password_hash`. +- `password_hash` `(string: )` - Pre-hashed password for the current user in bcrypt format. Mutually exclusive with `password`. + +@include 'tokenfields.mdx' + +### Sample payload + +```json +{ + "password": "superSecretPassword", + "token_policies": ["admin", "default"], + "token_bound_cidrs": ["127.0.0.1/32", "128.252.0.0/16"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh +``` + +### Examples + +Set role-level TTL values for a user named "alice" so the generated lease has a +default TTL of 8 hours (28800 seconds) and maximum TTL of 12 hours +(43200 seconds): + +```shell-session +$ curl \ + --header "X-Vault-Token: $VAULT_TOKEN" \ + --request POST \ + --data '{"token_ttl":"8h","token_max_ttl":"12h"}' \ + $VAULT_ADDR/v1/auth/userpass/users/alice +``` + +## Read user + +Reads the properties of an existing username. + +| Method | Path | +| :----- | :------------------------------- | +| `GET` | `/auth/userpass/users/:username` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh +``` + +### Sample response + +```json +{ + "request_id": "0ad1be52-9398-4b3c-f58b-98e427406471", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "token_bound_cidrs": [ + "127.0.0.1", + "128.252.0.0/16" + ], + "token_explicit_max_ttl": 0, + "token_max_ttl": 0, + "token_no_default_policy": false, + "token_num_uses": 0, + "token_period": 0, + "token_policies": [ + "admin", + "default" + ], + "token_ttl": 0, + "token_type": "default" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Delete user + +This endpoint deletes the user from the method. + +| Method | Path | +| :------- | :------------------------------- | +| `DELETE` | `/auth/userpass/users/:username` | + +### Parameters + +- `username` `(string: )` - The username for the user. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh +``` + +## Update password on user + +Update password for an existing user. + +| Method | Path | +| :----- | :---------------------------------------- | +| `POST` | `/auth/userpass/users/:username/password` | + +### Parameters + +- `username` `(string: )` – The username for the user. +- `password` `(string: )` - The password for the user. + +### Sample payload + +```json +{ + "password": "superSecretPassword2" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh/password +``` + +## Update policies on user + +Update policies for an existing user. + +| Method | Path | +| :----- | :---------------------------------------- | +| `POST` | `/auth/userpass/users/:username/policies` | + +### Parameters + +- `username` `(string: )` – The username for the user. +- `token_policies` `(array: [] or comma-delimited string: "")` - List of + policies to encode onto generated tokens. Depending on the auth method, this + list may be supplemented by user/group/other values. + +### Sample payload + +```json +{ + "token_policies": ["policy1", "policy2"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/userpass/users/mitchellh/policies +``` + +## List users + +List available userpass users. + +| Method | Path | +| :----- | :--------------------- | +| `LIST` | `/auth/userpass/users` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/auth/userpass/users +``` + +### Sample response + +```json +{ + "data": { + "keys": ["mitchellh", "armon"] + } +} +``` + +## Login + +Login with the username and password. + +| Method | Path | +| :----- | :------------------------------- | +| `POST` | `/auth/userpass/login/:username` | + +### Parameters + +- `username` `(string: )` – The username for the user. +- `password` `(string: )` - The password for the user. + +### Sample payload + +```json +{ + "password": "superSecretPassword2" +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/auth/userpass/login/mitchellh +``` + +### Sample response + +```json +{ + "request_id": "ae1882ba-f60a-7629-ce1a-6618c482de3e", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": null, + "wrap_info": null, + "warnings": null, + "auth": { + "client_token": "hvs.CAESIJyeFmhLYRWVXPJStT3fDP1ZdFkon_otuk1sJUpkfk_WGh4KHGh2cy5xdW9XVHBnVUwwbzB1ZEhzZkpkRmVoU08", + "accessor": "iP2Lw1JXpjlALbgJSeIx51n7", + "policies": [ + "default", + "policy1", + "policy2" + ], + "token_policies": [ + "default", + "policy1", + "policy2" + ], + "metadata": { + "username": "mitchellh" + }, + "lease_duration": 2764800, + "renewable": true, + "entity_id": "0660dce5-4f2c-926a-8b15-158901557d9d", + "token_type": "service", + "orphan": true, + "mfa_requirement": null, + "num_uses": 0 + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/index.mdx new file mode 100644 index 0000000000..298b68d25e --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/index.mdx @@ -0,0 +1,358 @@ +--- +layout: api +page_title: HTTP API +description: Vault has an HTTP API that can be used to control every aspect of Vault. +--- + +# HTTP API + +The Vault HTTP API gives you full access to Vault using [REST like HTTP verbs](https://en.wikipedia.org/wiki/Representational_state_transfer). +Every aspect of Vault can be controlled using the APIs. The Vault CLI uses the +HTTP API to access Vault similar to all other consumers. + +All API routes are prefixed with `/v1/`. + +This documentation is only for the v1 API, which is currently the only version. + +~> **Backwards compatibility:** At the current version, Vault does not yet +promise backwards compatibility even with the v1 prefix. We'll remove this +warning when this policy changes. At this point in time the core API (that +is, `sys/` routes) change very infrequently, but various secrets engines/auth +methods/etc. sometimes have minor changes to accommodate new features as +they're developed. + +## Transport + +The API is expected to be accessed over a TLS connection at all times, with a +valid certificate that is verified by a well-behaved client. It is possible to +disable TLS verification for listeners, however, so API clients should expect +to have to do both depending on user settings. + +## Authentication + +Once Vault is unsealed, almost every other operation requires a _client token_. +A user may have a client token sent to them. The client token must be sent as +either the `X-Vault-Token` HTTP Header or as `Authorization` HTTP Header using +the `Bearer ` scheme. + +Otherwise, a client token can be retrieved using an [authentication +engine](/vault/docs/auth). + +Each auth method has one or more unauthenticated login endpoints. These +endpoints can be reached without any authentication, and are used for +authentication to Vault itself. These endpoints are specific to each auth +method. + +Responses from auth login methods that generate an authentication token are +sent back to the client in JSON. The resulting token should be saved on the +client or passed via the `X-Vault-Token` or `Authorization` header for future requests. + +## Parameter restrictions + +Several Vault APIs require specifying path parameters. The path parameter cannot end +in periods. Otherwise, Vault will return a 404 unsupported path error. + +## Namespaces + +@include 'alerts/enterprise-and-hcp.mdx' + +When using [Namespaces](/vault/docs/enterprise/namespaces) the final path of the API +request is relative to the `X-Vault-Namespace` header. For instance, if a +request URI is `secret/foo` with the `X-Vault-Namespace` header set as `ns1/ns2/`, +then the resulting request path to Vault will be `ns1/ns2/secret/foo`. + +Note that it is semantically equivalent to use the full path rather than the +`X-Vault-Namespace` header, Vault will match the corresponding namespace +based on correlating user input. Similar path results may be achieved if +`X-Vault-Namespace` is set to `ns1/` with the request path of `ns2/secret/foo` +as well, or otherwise if `X-Vault-Namespace` is omitted entirely and instead a +complete path is provided such as: `ns1/ns2/secret/foo`. + +For example, the following two commands result in equivalent requests: + +```shell-session +$ curl \ + -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ + -H "X-Vault-Namespace: ns1/ns2/" \ + -X GET \ + http://127.0.0.1:8200/v1/secret/foo +``` + +```shell-session +$ curl \ + -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ + -X GET \ + http://127.0.0.1:8200/v1/ns1/ns2/secret/foo +``` + +Some APIs are only available in a limited number of namespaces. More details +are available in the Namespace +[documentation](/vault/docs/enterprise/namespaces#restricted-api-paths). + + + +When you are working with HCP Vault Dedicated, your request must specify the +target namespace. In absence of an explicit namespace, Vault tries to send +the request to `root` namespace which results in an error. + +The top-level namespace for HCP Vault Dedicated clusters is `admin`, so the +requests must include `-H "X-Vault-Namespace: admin"` header or `admin` in the +API endpoint path. + + + +## API operations + +Typically the request data, body and response data to and from Vault is in JSON. +Vault sets the `Content-Type` header appropriately with its response and does +not require it from the clients request. + +The demonstration below uses the [`KVv1` secrets engine](/vault/api-docs/secret/kv/kv-v1), which is a +simple Key Value store. Please read [the API documentation of KV secret engines](/vault/api-docs/secret/kv) +for details of `KVv1` compared to `KVv2` and how they differ in their URI paths +as well as the features available in version 2 of the KV secrets engine. + +For `KVv1`, reading a secret using the HTTP API is done by issuing a GET: + +```text +/v1/secret/foo +``` + +This maps to `secret/foo` where `foo` is the key in the `secret/` mount, which +is mounted by default on a fresh Vault install and is of type `kv`. + +Here is an example of reading a secret using cURL: + +```shell-session +$ curl \ + -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ + -X GET \ + http://127.0.0.1:8200/v1/secret/foo +``` + +A few endpoints consume calls with `GET` query string parameters, but only if +those parameters are not sensitive, especially since some load balancers will +be able log these. Most endpoints that accept `POST` query string parameters +expect those parameters in the request body. + +You can list secrets as well. To do this, either issue a `GET` with the query +string parameter `list=true`, or you use the `LIST` HTTP verb. For the `kv` secrets +engine, listing is allowed on directories only, which returns the keys at the +requested path: + +```shell-session +$ curl \ + -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ + -X LIST \ + http://127.0.0.1:8200/v1/secret/ +``` + +The API documentation uses `LIST` as the HTTP verb, but you can still use `GET` +with the `?list=true` query string. + +If the list result is an empty set, Vault responds with status code 404 and the following JSON: + +```json +{"errors":[]} +``` + +To make an API with specific data in request body, issue a `POST`: + +```text +/v1/secret/foo +``` + +with a JSON body like: + +```javascript +{ + "value": "bar" +} +``` + +Here is an example of writing a secret using cURL: + +```shell-session +$ curl \ + -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ + -H "Content-Type: application/json" \ + -X POST \ + -d '{"data":{"value":"bar"}}' \ + http://127.0.0.1:8200/v1/secret/baz +``` + +Vault currently considers `PUT` and `POST` to be synonyms. Rather than trust a +client's stated intentions, Vault engines can implement an existence check to +discover whether an operation is actually a create or update operation based on +the data already stored within Vault. This makes permission management via ACLs +more flexible. + +A [KVv2 example](/vault/api-docs/secret/kv/kv-v2#sample-request-3) for the engine path of `secret` requires that URI is +appended with ***`data/`*** prior to the secret name (`baz`) such as: + +```shell-session +$ curl \ + -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ + -H "Content-Type: application/json" \ + -X POST \ + -d '{"data":{"value":"bar"}}' \ + http://127.0.0.1:8200/v1/secret/data/baz +``` + +For more examples, please look at the Vault API client. + +## The `X-Vault-Request` header + +Requests that are sent to a [Vault Proxy][proxy] that is configured to use the +`require_request_header` option must include the `X-Vault-Request` header +entry, e.g.: + +```shell-session +$ curl \ + -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ + -H "X-Vault-Request: true" \ + -H "Content-Type: application/json" \ + -X POST \ + -d '{"value":"bar"}' \ + http://127.0.0.1:8200/v1/secret/baz +``` + +The Vault CLI always adds this header to every request, regardless of whether +the request is being sent to a Vault Agent or directly to a Vault Server. In +addition, the Vault SDK always adds this header to every request. + +## Help + +To retrieve the help for any API within Vault, including mounted engines, auth +methods, etc. then append `?help=1` to any URL. If you have valid permission to +access the path, then the help text will be returned as a markdown-formatted block +in the `help` attribute of the response. + +Additionally, with the [OpenAPI generation](/vault/api-docs/system/internal-specs-openapi) in Vault, you will get back a small +OpenAPI document in the `openapi` attribute. This document is relevant for the +path you're looking up and any paths under it - also note paths in the OpenAPI +document are relative to the initial path queried. + + +Example request: + +```shell-session +$ curl \ + -H "X-Vault-Token: f3b09679-3001-009d-2b80-9c306ab81aa6" \ + http://127.0.0.1:8200/v1/secret?help=1 +``` + +Example response: + +```javascript +{ + "help": "## DESCRIPTION\n\nThis backend provides a versioned key-value store. The kv backend reads and\nwrites arbitrary secrets to the storage backend. The secrets are\nencrypted/decrypted by Vault: they are never stored unencrypted in the backend\nand the backend never has an opportunity to see the unencrypted value. Each key\ncan have a configured number of versions, and versions can be retrieved based on\ntheir version numbers.\n\n## PATHS\n\nThe following paths are supported by this backend. To view help for\nany of the paths below, use the help command with any route matching\nthe path pattern. Note that depending on the policy of your auth token,\nyou may or may not be able to access certain paths.\n\n ^.*$\n\n\n ^config$\n Configures settings for the KV store\n\n ^data/(?P.*)$\n Write, Read, and Delete data in the Key-Value Store.\n\n ^delete/(?P.*)$\n Marks one or more versions as deleted in the KV store.\n\n ^destroy/(?P.*)$\n Permanently removes one or more versions in the KV store\n\n ^metadata/(?P.*)$\n Configures settings for the KV store\n\n ^undelete/(?P.*)$\n Undeletes one or more versions from the KV store.", + "openapi": { + "openapi": "3.0.2", + "info": { + "title": "HashiCorp Vault API", + "description": "HTTP API that gives you full access to Vault. All API routes are prefixed with `/v1/`.", + "version": "1.0.0", + "license": { + "name": "Mozilla Public License 2.0", + "url": "https://www.mozilla.org/en-US/MPL/2.0" + } + }, + "paths": { + "/.*": {}, + "/config": { + "description": "Configures settings for the KV store", + "x-vault-create-supported": true, + "get": { + "summary": "Read the backend level settings.", + "tags": [ + "secrets" + ], + "responses": { + "200": { + "description": "OK" + } + } + }, + ...[output truncated]... + } + } +} +``` + +## Error response + +A common JSON structure is always returned to return errors: + +```javascript +{ + "errors": [ + "message", + "another message" + ] +} +``` + +This structure will be returned for any HTTP status greater than or equal to 400. + +## HTTP status codes + +The following HTTP status codes are used throughout the API. Vault tries to +adhere to these whenever possible, but in case it doesn't -- then feel free to +[raise a bug](https://github.com/hashicorp/vault/issues) for our attention! + +~> _Note_: Applications should be prepared to accept both `200` and `204` as +success. `204` is simply an indication that there is no response body to parse, +but API endpoints that indicate that they return a `204` may return a `200` if +warnings are generated during the operation. + +- `200` - Success with data. +- `204` - Success, no data returned. +- `400` - Invalid request, missing or invalid data. +- `403` - Forbidden, your authentication details are either incorrect, you + don't have access to this feature, or - if CORS is enabled - you made a + cross-origin request from an origin that is not allowed to make such + requests. +- `404` - Invalid path. This can both mean that the path truly doesn't exist or + that you don't have permission to view a specific path. We use 404 in some + cases to avoid state leakage. LIST requests with no results will also return 404s. +- `405` - Unsupported operation. You tried to use a method inappropriate to + the request path, e.g. a POST on an endpoint that only accepts GETs. +- `412` - Precondition failed. Returned on Enterprise when a request can't be + processed yet due to some missing eventually consistent data. Should be retried, + perhaps with a little backoff. + See [Vault Eventual Consistency](/vault/docs/enterprise/consistency). +- `429` - Default return code for health status of standby nodes. This will + likely change in the future. +- `472` - Default return code for disaster recovery mode replication secondary and active. +- `473` - Default return code for health status of performance standby nodes. +- `500` - Internal server error. An internal error has occurred, try again + later. If the error persists, report a bug. +- `501` - Vault is not initialized. +- `502` - A request to Vault required Vault making a request to a third party; + the third party responded with an error of some kind. +- `503` - Vault is down for maintenance or is currently sealed. Try again + later. + +## Limits + +A maximum request size of 32MB is imposed to prevent a denial of service attack +with arbitrarily large requests; this can be tuned per `listener` block in +Vault's server configuration file. + +Vault also supports several listener options to enforce payload size limits for to incoming JSON +request bodies. + +You can configure the payload limits individullly on each listener and give +administrators granular control over the: + +- maximum allowed nesting depth of a JSON object or array (`max_json_depth`). +- maximum allowed length for any single string value in the payload (`max_json_string_value_length`.) +- maximum number of key-value pairs allowed in a single JSON object (`max_json_object_entry_count`). +- maximum number of elements permitted in a single JSON array `max_json_array_element_count`. + +The configuration defaults provide intentionally generous limits to accommodate +a wide range of legitimate use cases while still guarding against most malicious +or malformed requests. + +[proxy]: /vault/docs/agent-and-proxy/proxy#listener-stanza diff --git a/content/vault/v1.21.x (rc)/content/api-docs/libraries.mdx b/content/vault/v1.21.x (rc)/content/api-docs/libraries.mdx new file mode 100644 index 0000000000..d7bd86dfa7 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/libraries.mdx @@ -0,0 +1,223 @@ +--- +layout: api +page_title: 'HTTP API: Libraries' +description: >- + List of official and community contributed libraries for interacting with the + Vault HTTP API. +--- + +# Libraries + +The programming libraries listed on this page can be used to consume the API more conveniently. +Some are officially maintained while others are provided by the community. + +For a step-by-step walkthrough on using these client libraries, see the [developer quickstart](/vault/docs/get-started/developer-qs). +For copy-pastable code examples, see the [vault-examples](https://github.com/hashicorp/vault-examples) repo. + +## Official + +These libraries are officially maintained by HashiCorp. + +### Go + +- [Vault Go Client](https://github.com/hashicorp/vault/tree/main/api) + +```shell-session +$ go get github.com/hashicorp/vault/api +``` + +[Example application](https://github.com/hashicorp/hello-vault-go) + +### Ruby + +@include 'alerts/deprecated.mdx' + +- [Vault Ruby Client](https://github.com/hashicorp/vault-ruby) + +```shell-session +$ gem install vault +``` + +## Community + +These libraries are provided by the community. + +### Ansible + +- [ansible-vault](https://github.com/jhaals/ansible-vault) - Lookup plugin without third-party dependencies. +- [Ansible Modules Hashivault](https://pypi.python.org/pypi/ansible-modules-hashivault) + +```shell-session +$ pip install ansible-modules-hashivault +``` + +### C# + +- [VaultSharp](https://github.com/rajanadar/VaultSharp) + - Supports .NET 4.6.x, 4.7.x, 4.8.x, .NET Standard 2.x, .NET 6.0, 7.0, and 8.0. + - Supports every auth and secret backend supported by Vault, along with several system APIs. + +```shell-session +$ Install-Package VaultSharp +``` + +- [Vault.NET](https://github.com/Chatham/Vault.NET) + +```shell-session +$ Install-Package Vault +``` + +[Example application](https://github.com/hashicorp/hello-vault-dotnet) + +### C++ + +- [libvault](https://github.com/abedra/libvault) + +### Clojure + +- [vault-clj](https://github.com/amperity/vault-clj) + +### Elixir + +- [libvault](https://hex.pm/packages/libvault) +- [vaultex](https://hex.pm/packages/vaultex) + +### Erlang + +- [canal](https://github.com/rkallos/canal) + +### Go + +- [vaultgo](https://github.com/mittwald/vaultgo) + +```shell-session +$ go get github.com/mittwald/vaultgo +``` + +### Haskell + +- [vault-tool](https://hackage.haskell.org/package/vault-tool) + +```shell-session +$ cabal install vault-tool +``` + +- [gothic](http://hackage.haskell.org/package/gothic) + +```shell-session +$ stack install gothic +``` + +### Java + +- [Quarkus Vault](https://github.com/quarkiverse/quarkus-vault) +- [Spring Vault](https://github.com/spring-projects/spring-vault) +- [vault-java-driver](https://github.com/jopenlibs/vault-java-driver) + +### Kotlin + +- [kault](https://github.com/Hansanto/kault) +- [vault-kotlin](https://github.com/kunickiaj/vault-kotlin) + +### Node.js + +- [node-vault](https://github.com/kr1sp1n/node-vault) + +```shell-session +$ npm install node-vault +``` + +- [node-vault](https://github.com/shahradelahi/node-vault) (Typescript) + +```shell-session +$ npm install @litehex/node-vault +``` + +- [vaulTS](https://github.com/mittwald/vaulTS) (Github NPM Registry) + +```shell-session +$ npm install @mittwald/vaults +``` + +- [vault-api](https://github.com/SaiHemanthBR/vault-api) (Typescript. Axios-like API) + +```shell-session +$ npm install vault-api +``` + +- [loopback4-vault](https://github.com/sourcefuse/loopback4-vault) (LoopBack 4 Extension) + +```shell-session +$ npm i @sourceloop/vault +``` + +### PHP + +- [vault-php-sdk](https://github.com/jippi/vault-php-sdk) + +```shell-session +$ composer require jippi/vault-php-sdk +``` + +- [vault-php-sdk](https://github.com/violuke/vault-php-sdk) extended from jipppi + +```shell-session +$ composer require violuke/vault-php-sdk +``` + +- [vault-php](https://github.com/CSharpRU/vault-php) + +```shell-session +$ composer require csharpru/vault-php +``` + +- [vault-php](https://github.com/mittwald/vaultPHP) + +```shell-session +$ composer require mittwald/vault-php +``` + +### PowerShell + +- [Zyborg.Vault](https://github.com/zyborg/Zyborg.Vault) + +```PowerShell +Install-Module Zyborg.Vault +``` + +### Python + +- [HVAC](https://github.com/ianunruh/hvac) + +```shell-session +$ pip install hvac +``` + +### R + +- [vaultr](https://github.com/vimc/vaultr) + +### Rust + +- [HashicorpVault](https://crates.io/crates/hashicorp_vault) +- [vaultrs](https://crates.io/crates/vaultrs) + +### Scala + +- [scala-vault](https://github.com/janstenpickle/scala-vault) + +## Experimental + +### C# + +- [Vault DotNet Client](https://github.com/hashicorp/vault-client-dotnet) - +Note that this is an experimental approach to auto-generating libraries from +OpenAPI content and is not production-ready. We do not have plans to make +this production-ready at this time. + +```shell-session +# Install-Package HashiCorp.Vault +``` + +[Example application](https://github.com/hashicorp/vault-client-dotnet#getting-started) + diff --git a/content/vault/v1.21.x (rc)/content/api-docs/relatedtools.mdx b/content/vault/v1.21.x (rc)/content/api-docs/relatedtools.mdx new file mode 100644 index 0000000000..12b0732b11 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/relatedtools.mdx @@ -0,0 +1,40 @@ +--- +layout: api +page_title: Related Tools +description: Short list of third-party tools that work with or are related to Vault. +--- + +# Related tools + +## HashiCorp tools + +- [Vault Agent](/vault/docs/agent-and-proxy/agent) can render Vault secrets either to files or directly into a child process as environment variables using `consul-template` templating syntax +- [Vault Proxy](/vault/docs/agent-and-proxy/proxy) acts as an API Proxy for Vault, and can optionally allow or force interacting clients to use its automatically authenticated token +- [Terraform Vault Provider](https://registry.terraform.io/providers/hashicorp/vault/latest/docs) can read from, write to, and configure Vault from [HashiCorp Terraform](https://www.terraform.io/) +- [consul-template](https://github.com/hashicorp/consul-template) is a template renderer, notifier, and supervisor for HashiCorp Consul and Vault data +- [vault-ssh-helper](https://github.com/hashicorp/vault-ssh-helper) can be used to enable one-time passwords for SSH authentication via Vault + +## Third-Party tools + +The following list of tools is maintained by the community of Vault users; HashiCorp has not tested or approved them and makes no claims as to their suitability or security. + +- [HashiCorp Vault Jenkins plugin](https://plugins.jenkins.io/hashicorp-vault-plugin) - a Jenkins plugin for injecting Vault secrets into the build environment +- [Spring Vault](http://projects.spring.io/spring-vault/) - a Java Spring project for working with Vault secrets +- [vault-exec](https://github.com/kmanning/vault_exec) - a shell wrapper to execute arbitrary scripts using temporary AWS credentials managed by Vault +- [pouch](https://github.com/tuenti/pouch) - A set of tools to manage provisioning of secrets on hosts based on the AppRole authentication method of Vault +- [vault-aws-creds](https://github.com/jantman/vault-aws-creds) - Python helper to export Vault-provided temporary AWS creds into the environment +- [goldfish](https://github.com/Caiyeon/goldfish) - A Vault UI panel written with VueJS and Vault native Go API. +- [vault-migrator](https://github.com/nebtex/vault-migrator) - A tool to migrate data between different Vault storage mechanisms +- [Cryptr](https://github.com/adobe/cryptr) - a desktop Vault UI for Mac, Windows and Linux +- [sequelize-vault](https://github.com/linyows/sequelize-vault) - A Sequelize plugin for easily integrating Vault secrets. +- [ansible-modules-hashivault](https://github.com/TerryHowe/ansible-modules-hashivault) - An Ansible module for configuring most things in Vault including secrets, backends and policies. +- [Docker credential helper](https://github.com/morningconsult/docker-credential-vault-login) - A program that automatically reads Docker credentials from your Vault server and passes them to the Docker daemon to authenticate to your Docker registry when pulling an image +- [Cruise Daytona](https://github.com/cruise-automation/daytona) - An alternative implementation of the Vault client CLI for services and containers. Its core features are the ability to automate authentication, fetching of secrets, and automated token renewal. Support for AWS, GCP, & Kubernetes Vault Auth Backends. +- [Vault-CRD](https://vault.koudingspawn.de/) - Synchronize secrets stored in HashiCorp Vault to Kubernetes Secrets for better GitOps without secrets stored in git manifest files. +- [vsh](https://github.com/fishi0x01/vsh) - Interactive shell with tab-completion. Allows recursive operations on paths. Allows migration of secrets between both KV versions. +- [vault-cli](https://github.com/IBM/vault-cli) - A yaml based automation tool that bootstraps Vault cluster(s) with the desired configuration (namespaces, endpoints, policies, roles, endpoint) +- [vault-go](https://github.com/IBM/vault-go) - Helper Golang Vault types as Kubernetes Custom Resource Definitions (CRD) +- [HashiBox](https://github.com/nunchistudio/hashibox) - Vagrant environment to simulate highly-available cloud with Consul, Nomad, Vault, and optional support for Waypoint. Community & Enterprise supported. +- [vkv](https://github.com/FalcoSuessgott/vkv) - Recursively list key-values entries from Vaults KV2 engine in various formats. + +Want to add your own project, or one that you use? Additions are welcome via [pull requests](https://github.com/hashicorp/vault/blob/main/website/content/api-docs/relatedtools.mdx). diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/alicloud.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/alicloud.mdx new file mode 100644 index 0000000000..48bb366f96 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/alicloud.mdx @@ -0,0 +1,215 @@ +--- +layout: api +page_title: AliCloud - Secrets Engines - HTTP API +description: This is the API documentation for the Vault AliCloud secrets engine. +--- + +# AliCloud secrets engine (API) + +This is the API documentation for the Vault AliCloud secrets engine. For general +information about the usage and operation of the AliCloud secrets engine, please see +the [Vault AliCloud documentation](/vault/docs/secrets/alicloud). + +This documentation assumes the AliCloud secrets engine is enabled at the `/alicloud` path +in Vault. Since it is possible to enable secrets engines at any location, please +update your API calls accordingly. + +## Config management + +This endpoint configures the root RAM credentials to communicate with AliCloud. AliCloud +will use credentials in the following order: + +1. [Environment variables](https://github.com/aliyun/alibaba-cloud-sdk-go/blob/master/sdk/auth/credentials/providers/env.go) +2. A static credential configuration set at this endpoint +3. Instance metadata (recommended) + +To use instance metadata, leave the static credential configuration unset. + +At present, this endpoint does not confirm that the provided AliCloud credentials are +valid AliCloud credentials with proper permissions. + +Please see the [Vault AliCloud documentation](/vault/docs/secrets/alicloud) for +the policies that should be attached to the access key you provide. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/alicloud/config` | +| `GET` | `/alicloud/config` | + +### Parameters + +- `access_key` (string, required) - The ID of an access key with appropriate policies. +- `secret_key` (string, required) - The secret for that key. + +### Sample post request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/alicloud/config +``` + +### Sample post payload + +```json +{ + "access_key": "0wNEpMMlzy7szvai", + "secret_key": "PupkTg8jdmau1cXxYacgE736PJj4cA" +} +``` + +### Sample get response data + +```json +{ + "access_key": "0wNEpMMlzy7szvai" +} +``` + +## Role management + +The `role` endpoint configures how Vault will generate credentials for users of each role. + +### Parameters + +- `name` (string, required) – Specifies the name of the role to generate credentials against. This is part of the request URL. +- `remote_policies` (string, optional) - The names and types of a pre-existing policies to be applied to the generate access token. Example: "name:AliyunOSSReadOnlyAccess,type:System". +- `inline_policies` (string, optional) - The policy document JSON to be generated and attached to the access token. +- `role_arn` (string, optional) - The ARN of a role that will be assumed to obtain STS credentials. See [Vault AliCloud documentation](/vault/docs/secrets/alicloud) regarding trusted actors. +- `ttl` (int, optional) - The duration in seconds after which the issued token should expire. Defaults to 0, in which case the value will fallback to the system/mount defaults. +- `max_ttl` (int, optional) - The maximum allowed lifetime of tokens issued using this role. + +| Method | Path | +| :------- | :-------------------------- | +| `GET` | `/alicloud/role` | +| `POST` | `/alicloud/role/:role_name` | +| `GET` | `/alicloud/role/:role_name` | +| `DELETE` | `/alicloud/role/:role_name` | + +### Sample post request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/alicloud/role/my-application +``` + +### Sample post payload using policies + +```json +{ + "remote_policies": [ + "name:AliyunOSSReadOnlyAccess,type:System", + "name:AliyunRDSReadOnlyAccess,type:System" + ], + "inline_policies": "[{\"Statement\": [{\"Action\": [\"ram:Get*\",\"ram:List*\"],\"Effect\": \"Allow\",\"Resource\": \"*\"}],\"Version\": \"1\"}]" +} +``` + +### Sample get role response using policies + +```json +{ + "inline_policies": [ + { + "hash": "49796debb24d39b7a61485f9b0c97e04", + "policy_document": { + "Statement": [ + { + "Action": ["ram:Get*", "ram:List*"], + "Effect": "Allow", + "Resource": "*" + } + ], + "Version": "1" + } + } + ], + "max_ttl": 0, + "remote_policies": [ + { + "name": "AliyunOSSReadOnlyAccess", + "type": "System" + }, + { + "name": "AliyunRDSReadOnlyAccess", + "type": "System" + } + ], + "role_arn": "", + "ttl": 0 +} +``` + +### Sample post payload using Assume-Role + +```json +{ + "role_arn": "acs:ram::5138828231865461:role/hastrustedactors" +} +``` + +### Sample get role response using Assume-Role + +```json +{ + "inline_policies": null, + "max_ttl": 0, + "remote_policies": null, + "role_arn": "acs:ram::5138828231865461:role/hastrustedactors", + "ttl": 0 +} +``` + +### Sample list roles response + +Performing a `LIST` on the `/alicloud/roles` endpoint will list the names of all the roles Vault contains. + +```json +["policy-based", "role-based"] +``` + +## Generate RAM credentials + +This endpoint generates dynamic RAM credentials based on the named role. This +role must be created before queried. + +| Method | Path | +| :----- | :---------------------- | +| `GET` | `/alicloud/creds/:name` | + +### Parameters + +- `name` (string, required) – Specifies the name of the role to generate credentials against. This is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/alicloud/creds/example-role +``` + +### Sample response for roles using policies + +```json +{ + "access_key": "0wNEpMMlzy7szvai", + "secret_key": "PupkTg8jdmau1cXxYacgE736PJj4cA" +} +``` + +### Sample response for roles using Assume-Role + +```json +{ + "access_key": "STS.L4aBSCSJVMuKg5U1vFDw", + "expiration": "2018-08-15T22:04:07Z", + "secret_key": "wyLTSmsyPGP1ohvvw8xYgB29dlGI8KMiH2pKCNZ9", + "security_token": "CAESrAIIARKAAShQquMnLIlbvEcIxO6wCoqJufs8sWwieUxu45hS9AvKNEte8KRUWiJWJ6Y+YHAPgNwi7yfRecMFydL2uPOgBI7LDio0RkbYLmJfIxHM2nGBPdml7kYEOXmJp2aDhbvvwVYIyt/8iES/R6N208wQh0Pk2bu+/9dvalp6wOHF4gkFGhhTVFMuTDRhQlNDU0pWTXVLZzVVMXZGRHciBTQzMjc0KgVhbGljZTCpnJjwySk6BlJzYU1ENUJuCgExGmkKBUFsbG93Eh8KDEFjdGlvbkVxdWFscxIGQWN0aW9uGgcKBW9zczoqEj8KDlJlc291cmNlRXF1YWxzEghSZXNvdXJjZRojCiFhY3M6b3NzOio6NDMyNzQ6c2FtcGxlYm94L2FsaWNlLyo=" +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/aws.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/aws.mdx new file mode 100644 index 0000000000..83e5e7f276 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/aws.mdx @@ -0,0 +1,859 @@ +--- +layout: api +page_title: AWS - Secrets Engines - HTTP API +description: This is the API documentation for the Vault AWS secrets engine. +--- + +# AWS secrets engine (API) + +This is the API documentation for the Vault AWS secrets engine. For general +information about the usage and operation of the AWS secrets engine, please see +the [Vault AWS documentation](/vault/docs/secrets/aws). + +This documentation assumes the AWS secrets engine is enabled at the `/aws` path +in Vault. Since it is possible to enable secrets engines at any location, please +update your API calls accordingly. + +## Configure root credentials + +This endpoint configures the root credentials to communicate with AWS. Credentials +can be configured either with IAM access keys for a privileged AWS account, or using +Plugin Workload Identity Federation (WIF). + +### IAM + +There are multiple ways to pass root IAM credentials to the Vault server, specified +below with the highest precedence first. If credentials already exist, this will +overwrite them. + +The official AWS SDK is used for sourcing credentials from env vars, shared +files, or IAM/ECS instances. + +- Static credentials provided to the API as a payload + +- [Plugin workload identity federation](/vault/docs/secrets/aws#plugin-workload-identity-federation-wif) + credentials + +- Credentials in the `AWS_ACCESS_KEY`, `AWS_SECRET_KEY`, and `AWS_REGION` + environment variables **on the server** + +- Shared credentials files + +- Assigned IAM role or ECS task role credentials + +At present, this endpoint does not confirm that the provided AWS credentials are +valid AWS credentials with proper permissions. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/aws/config/root` | + +### Parameters + +- `max_retries` `(int: -1)` - Number of max retries the client should use for + recoverable errors. The default (`-1`) falls back to the AWS SDK's default + behavior. + +- `access_key` `(string: "")` – Specifies the AWS access key ID. Mutually exclusive with + `identity_token_audience`. + +- `secret_key` `(string: "")` – Specifies the AWS secret access key. Must be provided with + `access_key`. + +- `role_arn` `(string: "")` – Role ARN to assume + for plugin workload identity federation. Required with `identity_token_audience`. + +- `identity_token_audience` `(string: "")` - The + audience claim value for plugin identity tokens. Must match an allowed audience configured + for the target [IAM OIDC identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html#manage-oidc-provider-console). + Mutually exclusive with `access_key`. + +- `identity_token_ttl` `(string/int: 3600)` - The + TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format). + +- `region` `(string: )` – Specifies the AWS region. If not set it + will use the `AWS_REGION` env var, `AWS_DEFAULT_REGION` env var, or + `us-east-1` in that order. + +- `iam_endpoint` `(string: )` – Specifies a custom HTTP IAM endpoint to use. + +- `sts_endpoint` `(string: )` – Specifies a custom HTTP STS endpoint to use. + +- `sts_region` `(string: )` - Specifies a custom STS region to use (should match `sts_endpoint`) + +- `sts_fallback_endpoints` `(list: )` - Specifies an ordered list of fallback STS endpoints to use + +- `sts_fallback_regions` `(list: )` - Specifies an ordered list of fallback STS regions to use (should match fallback endpoints) + +- `username_template` `(string: )` - [Template](/vault/docs/concepts/username-templating) describing how + dynamic usernames are generated. The username template is used to generate both IAM usernames (capped at 64 characters) + and STS usernames (capped at 32 characters). Longer usernames result in a 500 error. + + To ensure generated usernames are within length limits for both STS/IAM, the template must adequately handle + both conditional cases (see [Conditional Templates](https://pkg.go.dev/text/template)). As an example, if no template + is provided the field defaults to the template below. It is to be noted that, DisplayName is the name of the vault + authenticated user running the AWS credential generation and PolicyName is the name of the Role for which the + credential is being generated for: + + ``` + {{ if (eq .Type "STS") }} + {{ printf "vault-%s-%s" (unix_time) (random 20) | truncate 32 }} + {{ else }} + {{ printf "vault-%s-%s-%s" (printf "%s-%s" (.DisplayName) (.PolicyName) | truncate 42) (unix_time) (random 20) | truncate 64 }} + {{ end }} + ``` + +@include 'rotationfields.mdx' + +### Sample payload + +```json +{ + "access_key": "AKIA...", + "secret_key": "2J+...", + "region": "us-east-1" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/aws/config/root +``` + +## Read root configuration + +This endpoint allows you to read non-secure values that have been configured in the +`config/root` endpoint. In particular, the `secret_key` parameter is never returned. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/aws/config/root` | + +### Sample request + +```shell-session +$ curl + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/aws/config/root + +``` + +### Sample response + +```json +{ + "data": { + "access_key": "AKIAEXAMPLE", + "region": "us-west-2", + "iam_endpoint": "https://iam.amazonaws.com", + "sts_endpoint": "https://sts.us-west-2.amazonaws.com", + "max_retries": -1 + } +} +``` + +## Rotate root IAM credentials + +When you have configured Vault with static credentials, you can use this +endpoint to have Vault rotate the access key it used. Note that, due to AWS +eventual consistency, after calling this endpoint, subsequent calls from Vault +to AWS may fail for a few seconds until AWS becomes consistent again. + +In order to call this endpoint, Vault's AWS access key MUST be the only access +key on the IAM user; otherwise, generation of a new access key will fail. Once +this method is called, Vault will now be the only entity that knows the AWS +secret key is used to access AWS. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `/aws/config/rotate-root` | + +### Parameters + +There are no parameters to this operation. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/aws/config/rotate-root +``` + +### Sample response + +```json +{ + "data": { + "access_key": "AKIA..." + } +} +``` + +The new access key Vault uses is returned by this operation. + +## Configure lease + +This endpoint configures lease settings for the AWS secrets engine. It is +optional, as there are default values for `lease` and `lease_max`. + +| Method | Path | +| :----- | :------------------ | +| `POST` | `/aws/config/lease` | + +### Parameters + +- `lease` `(string: )` – Specifies the lease value provided as a + string duration with time suffix. "h" (hour) is the largest suffix. + +- `lease_max` `(string: )` – Specifies the maximum lease value + provided as a string duration with time suffix. "h" (hour) is the largest + suffix. + +### Sample payload + +```json +{ + "lease": "30m", + "lease_max": "12h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/aws/config/lease +``` + +## Read lease + +This endpoint returns the current lease settings for the AWS secrets engine. + +| Method | Path | +| :----- | :------------------ | +| `GET` | `/aws/config/lease` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/aws/config/lease +``` + +### Sample response + +```json +{ + "data": { + "lease": "30m0s", + "lease_max": "12h0m0s" + } +} +``` + +## Create/Update role + +This endpoint creates or updates the role with the given `name`. If a role with +the name does not exist, it will be created. If the role exists, it will be +updated with the new attributes. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/aws/roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This + is part of the request URL. + +- `credential_type` `(string: )` – Specifies the type of credential to be used when + retrieving credentials from the role. Must be one of `iam_user`, + `assumed_role`, `federation_token`, or `session_token`. + +- `role_arns` `(list: [])` – Specifies the ARNs of the AWS roles this Vault role + is allowed to assume. Required when `credential_type` is `assumed_role` and + prohibited otherwise. This is a comma-separated string or JSON array. + +- `policy_arns` `(list: [])` – Specifies a list of AWS managed policy ARN. The + behavior depends on the credential type. With `iam_user`, the policies will + be attached to IAM users when they are requested. With `assumed_role` and + `federation_token`, the policy ARNs will act as a filter on what the + credentials can do, similar to `policy_document`. + When `credential_type` is `iam_user` or `federation_token`, at + least one of `policy_arns` or `policy_document` must be specified. This is a + comma-separated string or JSON array. When using `session_token`, this field + is disallowed. + +- `policy_document` `(string)` – The IAM policy document for the role. The + behavior depends on the credential type. With `iam_user`, the policy document + will be attached to the IAM user generated and augment the permissions the IAM + user has. With `assumed_role` and `federation_token`, the policy document will + act as a filter on what the credentials can do, similar to `policy_arns`. With + `session_token`, this field is disallowed. + +- `iam_groups` `(list: [])` - A list of IAM group names. IAM users generated + against this vault role will be added to these IAM Groups. For a credential + type of `assumed_role` or `federation_token`, the policies sent to the + corresponding AWS call (sts:AssumeRole or sts:GetFederation) will be the + policies from each group in `iam_groups` combined with the `policy_document` + and `policy_arns` parameters. + +- `iam_tags` `(list: [])` - A list of strings representing a key/value pair to be used as a + tag for any `iam_user` user that is created by this role. Format is a key and value + separated by an `=` (e.g. `test_key=value`). Note: when using the CLI multiple tags + can be specified in the role configuration by adding another `iam_tags` assignment + in the same command. + +- `default_sts_ttl` `(string)` - The default TTL for STS credentials. When a TTL is not + specified when STS credentials are requested, and a default TTL is specified + on the role, then this default TTL will be used. Valid only when + `credential_type` is one of `assumed_role` or `federation_token`. + +- `max_sts_ttl` `(string)` - The max allowed TTL for STS credentials (credentials + TTL are capped to `max_sts_ttl`). Valid only when `credential_type` is one of + `assumed_role` or `federation_token`. + +- `session_tags` `(list: [])` - The set of key-value pairs to be included as tags for the STS session. + Allowed formats are a map of strings or a list of strings in the format `key=value`. + Valid only when `credential_type` is set to `assumed_role`. + +- `external_id` `(string)` - The external ID to use when assuming the role. + Valid only when `credential_type` is set to `assumed_role`. + +- `user_path` `(string)` - The path for the user name. Valid only when + `credential_type` is `iam_user`. Default is `/` + +- `permissions_boundary_arn` `(string)` - The ARN of the [AWS Permissions + Boundary](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_boundaries.html) + to attach to IAM users created in the role. Valid only when `credential_type` + is `iam_user`. If not specified, then no permissions boundary policy will be + attached. + +- `mfa_serial_number` `(string)` - The ARN or hardware device number of the device configured + to the IAM user for multi-factor authentication. Only required if the IAM user has an MFA device + set up in AWS. + +Legacy parameters: + +These parameters are supported for backwards compatibility only. They cannot be +mixed with the parameters listed above. + +- `policy` `(string: )` – Specifies the IAM policy + in JSON format. + +- `arn` `(string: )` – Specifies the full ARN + reference to the desired existing policy. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/aws/roles/example-role +``` + +### Sample payloads + +Using an inline IAM policy: + +```json +{ + "credential_type": "federation_token", + "policy_document": "{\"Version\": \"...\"}" +} +``` + +Using a Session Token: + +```json +{ + "credential_type": "session_token" +} +``` + +Using an ARN: + +```json +{ + "credential_type": "assumed_role", + "role_arns": "arn:aws:iam::123456789012:role/DeveloperRole" +} +``` + +Using groups: + +```json +{ + "credential_type": "assumed_role", + "iam_groups": ["group1", "group2"] +} +``` + +Using tags: + + + + + ```json + { + "credential_type": "iam_user", + "iam_tags": [ + "first_key=first_value", + "second_key=second_value" + ] + } + ``` + + or + + ```json + { + "credential_type": "iam_user", + "iam_tags": { + "first_key": "first_value", + "second_key": "second_value" + } + } + ``` + + + + + ```bash + vault write aws/roles/example-role \ + credential_type=iam_user \ + iam_tags="first_key=first_value" \ + iam_tags="second_key=second_value" \ + ``` + + or + + ```bash + vault write aws/roles/example-role \ + credential_type=iam_user \ + iam_tags=@test.json + ``` + + where `test.json` is: + + ```json + ["tag1=42", "tag2=something"] + ``` + + + + +## Read role + +This endpoint queries an existing role by the given name. If the role does not +exist, a 404 is returned. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/aws/roles/:name` | + +If invalid role data was supplied to the role from an earlier version of Vault, +then it will show up in the response as `invalid_data`. + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/aws/roles/example-role +``` + +### Sample responses + +For an inline IAM policy: + +```json +{ + "data": { + "policy_document": "{\"Version\": \"...\"}", + "policy_arns": [], + "credential_types": ["assumed_role"], + "role_arns": [], + "iam_groups": [] + } +} +``` + +For a role ARN: + +```json +{ + "data": { + "policy_document": "", + "policy_arns": [], + "credential_types": ["assumed_role"], + "role_arns": ["arn:aws:iam::123456789012:role/example-role"], + "iam_groups": [] + } +} +``` + +For IAM groups: + +```json +{ + "data": { + "policy_document": "", + "policy_arns": [], + "credential_types": ["assumed_role"], + "role_arns": [], + "iam_groups": ["group1", "group2"] + } +} +``` + +## List roles + +This endpoint lists all existing roles in the secrets engine. + +| Method | Path | +| :----- | :----------- | +| `LIST` | `/aws/roles` | + +### Sample request + +```shell-session +$ curl + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/aws/roles +``` + +### Sample response + +```json +{ + "data": { + "keys": ["example-role"] + } +} +``` + +## Delete role + +This endpoint deletes an existing role by the given name. If the role does not +exist, a 404 is returned. + +| Method | Path | +| :------- | :----------------- | +| `DELETE` | `/aws/roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/aws/roles/example-role +``` + +## Generate credentials + +This endpoint generates credentials based on the named role. This role must be +created before queried. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/aws/creds/:name` | +| `POST` | `/aws/sts/:name` | + +The `/aws/creds` and `/aws/sts` endpoints are almost identical. The exception is +when retrieving credentials for a role that was specified with the legacy `arn` +or `policy` parameter. In this case, credentials retrieved through `/aws/sts` +must be of either the `assumed_role` or `federation_token` types, and +credentials retrieved through `/aws/creds` must be of the `iam_user` type. + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to generate + credentials against. This is part of the request URL. + +- `role_arn` `(string)` – The ARN of the role to assume if `credential_type` on + the Vault role is `assumed_role`. Must match one of the allowed role ARNs in + the Vault role. Optional if the Vault role only allows a single AWS role ARN; + required otherwise. + +- `role_session_name` `(string)` - The role session name to attach to the assumed role ARN. + `role_session_name` is limited to 64 characters; if exceeded, the `role_session_name` in the + assumed role ARN will be truncated to 64 characters. If `role_session_name` is not provided, + then it will be generated dynamically by default. + +- `ttl` `(string: "3600s")` – Specifies the TTL for the use of the STS token. + This is specified as a string with a duration suffix. Valid only when + `credential_type` is `assumed_role` `federation_token`, or `session_token`. When not specified, + the `default_sts_ttl` set for the role will be used. If that is also not set, then + the default value of `3600s` will be used. AWS places limits + on the maximum TTL allowed. See the AWS documentation on the `DurationSeconds` + parameter for + [AssumeRole](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRole.html) + (for `assumed_role` credential types), + [GetFederationToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetFederationToken.html) + (for `federation_token` credential types), or + [GetSessionToken](https://docs.aws.amazon.com/STS/latest/APIReference/API_GetSessionToken.html) + (for `session_token` credential types) for more details. + +- `mfa_code` `(string)` - The TOTP generated by the MFA device configured on the IAM user and set + on the Vault role. This is optional based on whether the Vault role has the `mfa_serial_number` + field set or not. Only required if the Vault role has the `mfa_serial_number` set on it. + +### Sample AssumeRole request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/aws/creds/example-role +``` + +### Sample response + +```json +{ + "data": { + "access_key": "AKIA...", + "secret_key": "xlCs...", + "session_token": null, + "arn": "arn:aws:sts::123456789012:assumed-role/DeveloperRole/some-user-supplied-role-session-name" + } +} +``` + +### Sample Session Token request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/aws/creds/example-role?mfa_code=123456 +``` + +### Sample response + +```json +{ + "data": { + "access_key": "AKIA...", + "secret_key": "xlCs...", + "session_token": "FwoG..." + } +} +``` + +## Create/Update static role +This endpoint creates or updates static role definitions. A static role is a 1-to-1 mapping +with an AWS IAM User, which will be adopted and managed by Vault, including rotating it according +to the configured `rotation_period`. + +In addition, this endpoint supports cross-account management. +Vault will use the credentials obtained by assuming a role in another AWS account to perform AWS operations. +Make sure that the IAM role configured in Vault has the necessary permissions to manage the IAM user within the target account. + + + + Vault will create a new credential upon configuration, and if the maximum number of access keys already exist, + Vault will rotate the oldest one. Vault must do this to know the credential. At each rotation period, Vault will + continue to prioritize rotating the oldest-existing credential. + + For example, if an IAM User has no access keys when onboarded into Vault, then Vault will generate its first access + key for the user. On the first rotation, Vault will generate a second access key for the user. It is only upon the + next rotation cycle that the first access key will now be rotated. + + + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `/aws/static-roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This +is specified as part of the URL. + +- `username` `(string: )` – Specifies the username of the IAM user to be managed. + +- `rotation_period` `(string/int: )` – Specifies the amount of time +Vault should wait before rotating the password. The minimum is 1 minute. Can be +specified in either `24h` or `86400` format (see [duration format strings](/vault/docs/concepts/duration-format)). +Updating the rotation period will 'reset' the next rotation to occur at `now` + `rotation_period`. + +- `assume_role_arn` `(string)` – Specifies the ARN of the IAM role in the target AWS account that Vault should assume. +When provided, Vault uses the assumed IAM role to generate temporary credentials. +When set, `assume_role_session_name` must also be provided. + +- `assume_role_session_name` `(string)` – Specifies the session name to use when assuming the role. +When set, `assume_role_arn` must also be provided. + +- `external_id` `(string)` – Specifies the external ID to use when assuming the role, if one was set on the IAM role. + +### Sample payload + +```json +{ + "username": "example-user", + "rotation_period": "11h30m" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/aws/static-roles/my-static-role +``` + +### Sample response + +```json +{ + "data": { + "assume_role_arn": "", + "assume_role_session_name": "", + "external_id": "", + "id": "AIDA...", + "name": "my-static-role", + "rotation_period": 41400, + "username": "example-user" + } +} +``` + +## Read static role + +This endpoint queries the static role definition. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/aws/static-roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the static role to read. +This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/aws/static-roles/my-static-role +``` +### Sample response + +```json +{ + "name": "my-static-role", + "username": "example-user", + "rotation_period": "11h30m" +} +``` + +## List static roles + +Use the list static roles endpoint to fetch all existing static roles in the secrets engine. + +| Method | Path | +| :----- | :------------------ | +| `LIST` | `/aws/static-roles` | + +### Sample request + +```shell-session +$ curl + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/aws/static-roles +``` + +### Sample response + +```json +{ + "data": { + "keys": ["example-role"] + } +} +``` + +## Delete static role + +This endpoint deletes the static role definition. The user, having been defined externally, +must be cleaned up manually. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `/aws/static-roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the static role to +delete. This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/aws/static-roles/my-static-role +``` + +## Get static credentials + +This endpoint returns the current credentials based on the named static role. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/aws/static-creds/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the static role to get +credentials for. This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/aws/static-creds/my-static-role +``` + +### Sample response + +```json +{ + "access_key": "AKIA...", + "expiration": "2024-10-25T15:02:10Z", + "secret_key": "..." +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/azure.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/azure.mdx new file mode 100644 index 0000000000..fa583a1699 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/azure.mdx @@ -0,0 +1,654 @@ +--- +layout: api +page_title: Azure - Secrets Engines - HTTP API +description: This is the API documentation for the Vault Azure secrets engine. +--- + +# Azure secrets engine (API) + +This is the API documentation for the Vault Azure +secrets engine. For general information about the usage and operation of +the Azure secrets engine, please see the main [Azure secrets documentation][docs]. + +This documentation assumes the Azure secrets engine is enabled at the `/azure` path +in Vault. Since it is possible to mount secrets engines at any path, please +update your API calls accordingly. + +## Configure access + +Configures the credentials required for the plugin to perform API calls +to Azure. These credentials will be used to query roles and create/delete +service principals. Environment variables will override any parameters set in the config. + +You can configure the secrets engine with account credentials or using +plugin workload identity federation (WIF). + +| Method | Path | +| :----- | :-------------- | +| `POST` | `/azure/config` | + +- `subscription_id` (`string: `) - The subscription id for the Azure Active Directory. + This value can also be provided with the AZURE_SUBSCRIPTION_ID environment variable. +- `tenant_id` (`string: `) - The tenant id for the Azure Active Directory. + This value can also be provided with the AZURE_TENANT_ID environment variable. +- `client_id` (`string:""`) - The OAuth2 client id to connect to Azure. This value can also be provided + with the AZURE_CLIENT_ID environment variable. See [authentication](/vault/docs/secrets/azure#authentication) for more details. +- `client_secret` (`string:""`) - The OAuth2 client secret to connect to Azure. This value can also be + provided with the AZURE_CLIENT_SECRET environment variable. See [authentication](/vault/docs/secrets/azure#authentication) for more details. + Mutually exclusive with `identity_token_audience`. +- `identity_token_audience` `(string: "")` - The + audience claim value for plugin identity tokens. Must match the allowed audiences configured + for the target [Federated Identity Credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app). + Mutually exclusive with `client_secret`. +- `identity_token_ttl` `(string/int: 3600)` - The + TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format). +- `environment` (`string:""`) - The Azure environment. This value can also be provided with the AZURE_ENVIRONMENT + environment variable. If not specified, Vault will use Azure Public Cloud. +- `root_password_ttl` `(string: 182d)` - Specifies how long the root password is valid for in Azure when + rotate-root generates a new client secret. Uses [duration format strings](/vault/docs/concepts/duration-format). +- `metadata` (`map[string]string: {}`) - A map of string to string key/value pairs that will be stored + as metadata for the mount. This can be used to store additional information about the + mount for reference purposes. + +@include 'rotationfields.mdx' + +### Sample payload + +```json +{ + "subscription_id": "94ca80...", + "tenant_id": "d0ac7e...", + "client_id": "e607c4...", + "client_secret": "9a6346...", + "environment": "AzureGermanCloud", + "root_password_ttl": "48d" +} +``` + +### Sample request + + + + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/azure/config +``` + + + + +```shell-session +$ vault write azure/config \ + subscription_id="94ca80..." \ + tenant_id="d0ac7e...", + client_id="e607c4...", + client_secret="9a6346...", + environment="AzureGermanCloud", +``` + + + + +## Read config + +Return the stored configuration, omitting `client_secret`. + +| Method | Path | +| :----- | :-------------- | +| `GET` | `/azure/config` | + +### Sample request + + + + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/azure/config +``` + + + + +```shell-session +$ vault read azure/config +``` + + + + +### Sample response + +```json +{ + "data": { + "subscription_id": "94ca80...", + "tenant_id": "d0ac7e...", + "client_id": "e607c4...", + "environment": "AzureGermanCloud" + }, + ... +} +``` + +## Delete config + +Deletes the stored Azure configuration and credentials. + +| Method | Path | +| :------- | :-------------- | +| `DELETE` | `/azure/config` | + +### Sample request + + + + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/azure/config +``` + + + + +```shell-session +$ vault delete azure/config +``` + + + + +## Rotate root + +This endpoint generates a new client secret for the root account defined in the config. The +value generated will only be known by Vault. + +~> Due to the eventual consistency of Microsoft Azure client secret APIs, the plugin +may briefly stop authenticating to Azure as the password propagates through their +datacenters. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/azure/rotate-root` | + +### Parameters + +There are no parameters to this operation. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/azure/rotate-root +``` + +## Create/Update role + +Create or update a Vault role. Either `application_object_id` or +`azure_roles` must be provided, and these resources must exist for this +call to succeed. See the Azure secrets [roles docs][roles] for more +information about roles. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/azure/roles/:name` | + +### Parameters + +- `azure_roles` (`string: ""`) - List of Azure roles to be assigned to the generated service + principal. The array must be in JSON format, properly escaped as a string. See [roles docs][roles] + for details on role definition. +- `azure_groups` (`string: ""`) - List of Azure groups that the generated service principal will be + assigned to. The array must be in JSON format, properly escaped as a string. See [groups docs][groups] + for more details. +- `application_object_id` (`string: ""`) - Application Object ID for an existing service principal that will + be used instead of creating dynamic service principals. If present, `azure_roles` will be ignored. See + [roles docs][roles] for details on role definition. +- `persist_app` (`bool: "false"`) – If set to true, persists the created service principal and application for the lifetime of the role. + Useful for when the Service Principal needs to maintain ownership of objects it creates +- `ttl` (`string: ""`) – Specifies the default TTL for service principals generated using the role. + Accepts time suffixed strings ("1h") or an integer number of seconds. Defaults to the system/engine default TTL time. +- `max_ttl` (`string: "0"`) – Specifies the maximum TTL for service principals + generated using the role. Accepts time suffixed strings ("1h") or an integer + number of seconds. The default (`0`) defers to the system/engine max TTL time. +- `explicit_max_ttl` (`string: "0"`) – Limits the lifetime of the service + principal secret in Azure and sets an upper bound on the TTL for the + corresponding lease. You cannot update the service principle lifetime of an + existing lease and clients cannot renew a lease once the lifetime expires. + Use the default (`0`) to create the service principal with a max TTL of 10 + years. When the lifetime ends, Vault deletes the service principal and all + corresponding leases. +- `permanently_delete` (`bool: false`) - Specifies whether to permanently delete Applications and Service Principals that are dynamically + created by Vault. If `application_object_id` is present, `permanently_delete` must be `false`. +- `sign_in_audience` (`string: ""`) - Specifies the security principal types that are allowed to sign in to the application. + Valid values are: AzureADMyOrg, AzureADMultipleOrgs, AzureADandPersonalMicrosoftAccount, PersonalMicrosoftAccount. +- `tags` (`string: ""`) - A comma-separated string of Azure tags to attach to an application. + +### Sample payload + +```json +{ + "azure_roles": "[ + { + \"role_name\": \"Contributor\", + \"scope\": \"/subscriptions//resourceGroups/Website\" + }, + { + \"role_id\": \"/subscriptions//providers/Microsoft.Authorization/roleDefinitions/\", + \"scope\": \"/subscriptions/\" + } + ]", + "ttl": 3600, + "max_ttl": "24h", + "sign_in_audience": "AzureADMyOrg", + "tags": "team:engineering, environment:development" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/azure/roles/my-role +``` + +## Read role + +The Read Role endpoint returns information about the named role: + +- Configuration details for the role +- The constant `invalid_data` for roles created in earlier versions of Vault. +- A `404` error if the named role does not exist. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/azure/roles/:name` | + + +### Path parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/azure/roles/example-role +``` + +### Sample response + +```json +{ + "data": { + "application_object_id": "", + "azure_groups": null, + "azure_roles": [ + { + "role_name": "Contributor", + "scope": "/subscriptions/>/resourceGroups/Website" + }, + { + "role_id": "/subscriptions/>/providers/Microsoft.Authorization/roleDefinitions/", + "scope": "/subscriptions/" + } + ], + "ttl": 3600, + "max_ttl": 0, + "explicit_max_ttl": 0, + "permanently_delete": false, + "persist_app": false, + "sign_in_audience": "AzureADMyOrg", + "tags": [ + "team:engineering", + "team:development" + ], + } +} +``` + + +## List roles + +Lists all of the roles that are registered with the plugin. + +| Method | Path | +| :----- | :------------- | +| `LIST` | `/azure/roles` | + +### Sample request + + + + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/azure/roles +``` + + + + +```shell-session +$ vault list azure/roles +``` + + + + +### Sample response + +```json +{ + "data": { + "keys": ["my-role-one", "my-role-two"] + } +} +``` + +## Delete role + +This endpoint deletes an existing role by the given name. If the role does not +exist, a 404 is returned. + +| Method | Path | +| :------- | :----------------- | +| `DELETE` | `/azure/roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/azure/roles/example-role +``` + +## Generate credentials + +This endpoint generates a new service principal based on the named role. + +| Method | Path | +| :----- | :------------------- | +| `GET` | `/azure/creds/:name` | + +### Parameters + +- `name` (`string: `) - Specifies the name of the role to create credentials against. + +### Sample request + + + + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/azure/creds/my-role +``` + + + + +```shell-session +$ vault read azure/creds/my-role +``` + + + + +### Sample response + +```json +{ + "data": { + "client_id": "408bf248-dd4e-4be5-919a-7f6207a307ab", + "client_secret": "9PfdaDP9qcf98ggw8WSttfVreFcN4q9c4m4x", + ... + } +} +``` + +## Revoking/Renewing secrets + +See docs on how to [renew](/vault/api-docs/system/leases#renew-lease) and [revoke](/vault/api-docs/system/leases#revoke-lease) leases. + +[docs]: /vault/docs/secrets/azure +[roles]: /vault/docs/secrets/azure#roles +[groups]: /vault/docs/secrets/azure#azure-groups + +## Create/Update static role + +@include 'alerts/enterprise-only.mdx' + +Create or update static role definitions used to manage pre-existing + service principals in Azure. + +| Method | Path | +| :----- | :-------------------------- | +| `POST` | `/azure/static-roles/:name` | + +### Path parameters + +- `name` `(string: )` – Name of the static role you want to + create or update. + +### Request parameters + +- `application_object_id` (`string: `) - Application object ID for + an existing service principal that is managed by the static role. +- `ttl` (`string: ""`) - Timespan of 1 year (`8760h`) or more during + which the role credentials are valid. You can specify timespans + as time suffixed strings (`"1h"`) or an integer number of + seconds. Leave `ttl` unset or set to `0` to use the default value + of 2 years (`17520h`). +- `metadata` (`map[string]string: {}`) - A map of string to string key/value pairs that will be stored + as metadata for the mount. This can be used to store additional information about the + mount for reference purposes. The data stored here is displayed in the response of + `/azure/static-roles/:name` and `/azure/static-creds/:name` in the `metadata` field. + When also setting the `metadata` parameter on `/azure/static-creds/:name`, the two + maps will be merged in the response of `/azure/static-creds/:name`, with the values from `/azure/static-roles/:name` + taking precedence in the event of key collisions. +- `secret_id` (`string: ""`) - The secret ID of the Azure password credential you want to import. + Required if you provide `client_secret` or `expiration`. +- `client_secret` (`string: ""`) - The plaintext secret value of the credential you want to import. + If unset, you must rotate the imported credential before you can use it with Vault. +- `expiration` (`string: ""`) - A future expiration time for the imported + credential, in RFC3339 format. +- `skip_import_rotation` (`bool: false`) – If set to true, Vault stores the + imported credential values without automatically rotating them. You cannot + read the imported credentials until you manually rotate them. + +### Sample payload + +```json +{ + "application_object_id": "408bf248-dd4e-4be5-919a-7f6207a307ab", + "ttl": "8760h", + "metadata": { + "team": "engineering", + "environment": "development" + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/azure/static-roles/my-static-role +``` + +## Read static role + +Retrieve the named static role definition. + +| Method | Path | +| :----- | :-------------------------- | +| `GET` | `/azure/static-roles/:name` | + +### Path parameters + +- `name` `(string: )` – Name of the static role you want to read. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/azure/static-roles/my-static-role +``` + +### Sample response + +```json +{ + ... + "data": { + "application_object_id": "408bf248-dd4e-4be5-919a-7f6207a307ab", + "ttl": 8760, + }, + "metadata": { + "team": "engineering", + "environment": "development" + } + ... +} +``` + +## List static roles + +List all existing static roles in the Azure secrets engine. + +| Method | Path | +| :----- | :-------------------- | +| `LIST` | `/azure/static-roles` | + +### Sample request + +```shell-session +$ curl + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/azure/static-roles +``` + +### Sample response + +```json +{ + "data": { + "keys": ["my-static-role1", "my-static-role2"] + } +} +``` + +## Delete static role + +Delete an existing static role by name. + +| Method | Path | +| :------- | :-------------------------- | +| `DELETE` | `/azure/static-roles/:name` | + +### Path parameters + +- `name` `(string: )` – Name of the static role you want to delete. + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/azure/static-roles/my-static-role +``` + +## Get static credentials + +Generate credentials associated with the named static role. + +| Method | Path | +| :----- | :------------------------- | +| `GET` | `/azure/static-creds/:name` | + +### Path parameters + +- `name` `(string: )` – Name of the static role to get credentials for. +- `metadata` (`map[string]any: {}`) - A map of string to string key/value pairs that will be stored + as metadata for the mount. This can be used to store additional information about the + mount for reference purposes. The data stored here is displayed in the response of + `/azure/static-roles/:name` and `/azure/static-creds/:name` in the `metadata` field. + When also setting the `metadata` parameter on `/azure/static-creds/:name`, the two + maps will be merged in the response of `/azure/static-creds/:name`, with the values from `/azure/static-roles/:name` + taking precedence in the event of key collisions. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/azure/static-creds/my-static-role +``` + +### Sample response + +```json +{ + "data": { + "client_id": "408bf248-dd4e-4be5-919a-7f6207a307ab", + "client_secret": "9PfdaDP9qcf98ggw8WSttfVreFcN4q9c4m4x", + "metadata": { + "team": "engineering", + "environment": "development" + }, + ... + } +} +``` + +## Manually rotate static role password + +Rotate the password of an existing static role. + +| Method | Path | +| :----- | :--------------------------| +| `POST` | `/azure/rotate-role/:name` | + +### Path parameters + +- `name` `(string: )` – Name of the static role you want to rotate the password for. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/azure/rotate-role/:name +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/cassandra.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/cassandra.mdx new file mode 100644 index 0000000000..24762fb1df --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/cassandra.mdx @@ -0,0 +1,249 @@ +--- +layout: api +page_title: Cassandra - Secrets Engines - HTTP API +description: This is the API documentation for the Vault Cassandra secrets engine. +--- + +# Cassandra secrets engine (API) + +@include 'x509-sha1-deprecation.mdx' + +~> **Deprecation Note:** This backend is deprecated in favor of the +combined databases backend added in v0.7.1. See the API documentation for +the new implementation of this backend at +[Cassandra database plugin HTTP API](/vault/api-docs/secret/databases/cassandra). + +This is the API documentation for the Vault Cassandra secrets engine. For +general information about the usage and operation of the Cassandra backend, +please see the +[Vault Cassandra backend documentation](/vault/docs/secrets/databases/cassandra). + +This documentation assumes the Cassandra backend is mounted at the `/cassandra` +path in Vault. Since it is possible to enable secrets engines at any location, +please update your API calls accordingly. + +## Configure connection + +This endpoint configures the connection information used to communicate with +Cassandra. + +| Method | Path | +| :----- | :----------------------------- | +| `POST` | `/cassandra/config/connection` | + +### Parameters + +- `hosts` `(string: )` – Specifies a set of comma-delineated Cassandra + hosts to connect to. + +- `username` `(string: )` – Specifies the username to use for + superuser access. + +- `password` `(string: )` – Specifies the password corresponding to + the given username. + +- `tls` `(bool: true)` – Specifies whether to use TLS when connecting to + Cassandra. + +- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the + server certificate when using TLS. + +- `pem_bundle` `(string: "")` – Specifies concatenated PEM blocks containing a + certificate and private key; a certificate, private key, and issuing CA + certificate; or just a CA certificate. + +- `pem_json` `(string: "")` – Specifies JSON containing a certificate and + private key; a certificate, private key, and issuing CA certificate; or just a + CA certificate. For convenience format is the same as the output of the + `issue` command from the `pki` backend; see + [the pki documentation](/vault/docs/secrets/pki). + +- `protocol_version` `(int: 2)` – Specifies the CQL protocol version to use. + +- `connect_timeout` `(string: "5s")` – Specifies the connection timeout to use. + +- `consistency` `(string: "")` – Specifies the consistency option to use. See + the [gocql + definition](https://github.com/gocql/gocql/blob/master/frame.go#L188) for + valid options. + +TLS works as follows: + +- If `tls` is set to true, the connection will use TLS; this happens + automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set + +- If `insecure_tls` is set to true, the connection will not perform verification + of the server certificate; this also sets `tls` to true + +- If only `issuing_ca` is set in `pem_json`, or the only certificate in + `pem_bundle` is a CA certificate, the given CA certificate will be used for + server certificate verification; otherwise the system CA certificates will be + used + +- If `certificate` and `private_key` are set in `pem_bundle` or `pem_json`, + client auth will be turned on for the connection + +`pem_bundle` should be a PEM-concatenated bundle of a private key + client +certificate, an issuing CA certificate, or both. `pem_json` should contain the +same information; for convenience, the JSON format is the same as that output by +the issue command from the PKI backend. + +### Sample payload + +```json +{ + "hosts": "cassandra1.local", + "username": "user", + "password": "pass" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/cassandra/config/connection +``` + +## Create role + +This endpoint creates or updates the role definition. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/cassandra/roles/:name` | + +### Parameters + +- `creation_cql` `(string: "")` – Specifies the CQL statements executed to + create and configure the new user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The '{{username}}' and + '{{password}}' values will be substituted; it is required that these + parameters are in single quotes. The default creates a non-superuser user with + no authorization grants. + +- `rollback_cql` `(string: "")` – Specifies the CQL statements executed to + attempt a rollback if an error is encountered during user creation. The + default is to delete the user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The '{{username}}' and + '{{password}}' values will be substituted; it is required that these + parameters are in single quotes. + +- `lease` `(string: "")` – Specifies the lease value provided as a string + duration with time suffix. "h" hour is the largest suffix. + +- `consistency` `(string: "Quorum")` – Specifies the consistency level value + provided as a string. Determines the consistency level used for operations + performed on the Cassandra database. + +### Sample payload + +```json +{ + "creation_cql": "CREATE USER ..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/cassandra/roles/my-role +``` + +## Read role + +This endpoint queries the role definition. + +| Method | Path | +| :----- | :----------------------- | +| `GET` | `/cassandra/roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/cassandra/roles/my-role +``` + +### Sample response + +```json +{ + "data": { + "creation_cql": "CREATE USER...", + "rollback_cql": "DROP USER...", + "lease": "12h", + "consistency": "Quorum" + } +} +``` + +## Delete role + +This endpoint deletes the role definition. + +| Method | Path | | +| :------- | :----------------------- | --------------- | +| `DELETE` | `/cassandra/roles/:name` | `204 (no body)` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/cassandra/roles/my-role +``` + +## Generate credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | +| :----- | :----------------------- | +| `GET` | `/cassandra/creds/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/cassandra/creds/my-role +``` + +### Sample response + +```json +{ + "data": { + "username": "vault-root-1430158508-126", + "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/consul.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/consul.mdx new file mode 100644 index 0000000000..ad0875ada0 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/consul.mdx @@ -0,0 +1,350 @@ +--- +layout: api +page_title: Consul - Secrets Engines - HTTP API +description: This is the API documentation for the Vault Consul secrets engine. +--- + +# Consul secrets engine (API) + +@include 'x509-sha1-deprecation.mdx' + +@include 'consul-dataplane-compat.mdx' + +This is the API documentation for the Vault Consul secrets engine. For general +information about the usage and operation of the Consul secrets engine, please +see the [Vault Consul documentation](/vault/docs/secrets/consul). + +This documentation assumes the Consul secrets engine is enabled at the `/consul` +path in Vault. Since it is possible to enable secrets engines at any location, +please update your API calls accordingly. + +## Configure access + +This endpoint configures the access information for Consul. This access +information is used so that Vault can communicate with Consul and generate +Consul tokens. + +| Method | Path | +| :----- | :---------------------- | +| `POST` | `/consul/config/access` | + +### Parameters + +- `address` `(string: )` – Specifies the address of the Consul + instance, provided as `"host:port"` like `"127.0.0.1:8500"`. + +- `scheme` `(string: "http")` – Specifies the URL scheme to use. + +- `token` `(string: "")` – Specifies the Consul ACL token to use. This + must be a management type token. If this is not provided, Vault will try to + bootstrap the ACL system of the Consul cluster automatically. + +- `ca_cert` `(string: "")` - CA certificate to use when verifying Consul server certificate, + must be x509 PEM encoded. + +- `client_cert` `(string: "")` - Client certificate used for Consul's TLS communication, + must be x509 PEM encoded and if this is set you need to also set client_key. + +- `client_key` `(string: "")` - Client key used for Consul's TLS communication, + must be x509 PEM encoded and if this is set you need to also set client_cert. + +### Sample payload + +```json +{ + "address": "127.0.0.1:8500", + "scheme": "https", + "token": "adha..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ..." \ + --data @payload.json \ + http://127.0.0.1:8200/v1/consul/config/access +``` + +## Create/Update role + +This endpoint creates or updates the Consul role definition. If the role does +not exist, it will be created. If the role already exists, it will receive +updated attributes. At least one of `consul_policies`, `consul_roles`, +`service_identities`, or `node_identities` is required depending on the +Consul version. + +| Method | Path | +| :----- | :-------------------- | +| `POST` | `/consul/roles/:name` | + +### Parameters for consul versions 1.11 and above + +- `partition` `(string: "")` - Specifies the Consul admin partition in which the token is generated. + The partition must exist, and the Consul policies or roles assigned to the + Vault role must also exist inside the given partition. If not provided, the partition `default` + is used. + +To create a client token within a particular Consul admin partition: + +```json +{ + "partition": "admin1" +} +``` + +### Parameters for consul versions 1.8 and above + +- `node_identities` `(list: )` - The list of node identities to assign to the generated + token. This may be a comma-separated list to attach multiple node identities to a token. + +To create a client token with node identities attached: + +```json +{ + "node_identities": [ + "client-1:dc1", + "client-2:dc1" + ] +} +``` + +### Parameters for consul versions 1.7 and above + +- `consul_namespace` `(string: "")` - Specifies the Consul namespace in which the token is generated. + The namespace must exist, and the Consul policies or roles assigned to the Vault role must also exist + inside the given Consul namespace. If not provided, the namespace `default` is used. + +To create a client token within a particular Consul namespace: + +```json +{ + "consul_namespace": "ns1" +} +``` + +### Parameters for consul version 1.5 and above + +- `service_identities` `(list: )` - The list of service identities to assign to the generated + token. This may be a comma-separated list to attach multiple service identities to a token. + +- `consul_roles` `(list: )` – The list of Consul roles to attach to the + token generated by Vault. + + To create a client token with roles defined in Consul: + +### Sample payload + +```json +{ + "consul_roles": "role-a,role-b" +} +``` + +To create a client token with service identities attached: + +```json +{ + "service_identities": [ + "myservice-1:dc1,dc2", + "myservice-2:dc1" + ] +} +``` + +### Parameters for consul versions 1.4 and above + +- `name` `(string: )` – Specifies the name of an existing role against + which to create this Consul credential. This is part of the request URL. + +- `token_type` DEPRECATED (1.11) `(string: "client")` - Specifies the type of token to create + when using this role. Valid values are `"client"` or `"management"`. If a `"management"` + token, the `policy` parameter is not required. Defaults to `"client`". [Deprecated from Consul as of 1.4 and + removed as of Consul 1.11.](/consul/api-docs/acl/legacy) + +- `policy` DEPRECATED (1.11) `(string: "")` – Specifies the base64-encoded ACL policy. + This is required unless the `token_type` is `"management"`. [Deprecated from Consul as of 1.4 and + removed as of Consul 1.11.](/consul/api-docs/acl/legacy) + +- `policies` DEPRECATED (1.11) `(list: )` - Same as `consul_policies`. + Deprecated in favor of using `consul_policies`. + +- `consul_policies` `(list: )` – The list of Consul policies to assign + to the generated token. This field is required if using using Consul 1.4. + +- `local` `(bool: false)` - Indicates that the token should not be replicated + globally and instead be local to the current datacenter. Only available in Consul + 1.4 and greater. + +- `ttl` `(duration: "")` – Specifies the TTL for this role. If not + provided, the default Vault TTL is used. Uses [duration format strings](/vault/docs/concepts/duration-format). + +- `max_ttl` `(duration: "")` – Specifies the max TTL for this role. If not + provided, the default Vault Max TTL is used. Uses [duration format strings](/vault/docs/concepts/duration-format). + +### Sample payload + +To create a client token with policies defined in Consul: + +```json +{ + "consul_policies": "policy-1,policy-2" +} +``` + +### Parameters for consul version below 1.4 + +- `lease` DEPRECATED (1.11) `(string: "")` – Specifies the lease for this role. + Uses [duration format strings](/vault/docs/concepts/duration-format). If not + provided, the default Vault lease is used. + +- `policy` DEPRECATED (1.11) `(string: )` – Specifies the base64-encoded ACL policy. The + ACL format can be found in the [Consul ACL + documentation](/consul/docs/security/acl/acl-legacy). This is + required unless the `token_type` is `"management"`. + +### Sample payload + +To create a client token with a base64-encoded policy: + +```json +{ + "policy": "a2V5ICIi...==" +} +``` + +To create management tokens: + +```json +{ + "token_type": "management" +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ..." \ + --data @payload.json \ + http://127.0.0.1:8200/v1/consul/roles/example-role +``` + +## Read role + +This endpoint queries for information about a Consul role with the given name. +If no role exists with that name, a 404 is returned. + +| Method | Path | +| :----- | :-------------------- | +| `GET` | `/consul/roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to query. This + is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/consul/roles/example-role +``` + +### Sample response + +```json +{ + "data": { + "policy": "abd2...==", + "lease": "1h0m0s", + "token_type": "client" + } +} +``` + +## List roles + +This endpoint lists all existing roles in the secrets engine. + +| Method | Path | +| :----- | :-------------- | +| `LIST` | `/consul/roles` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/consul/roles +``` + +### Sample response + +```json +{ + "data": { + "keys": ["example-role"] + } +} +``` + +## Delete role + +This endpoint deletes a Consul role with the given name. Even if the role does +not exist, this endpoint will still return a successful response. + +| Method | Path | +| :------- | :-------------------- | +| `DELETE` | `/consul/roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --request DELETE \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/consul/roles/example-role +``` + +## Generate credential + +This endpoint generates a dynamic Consul token based on the given role +definition. + +| Method | Path | +| :----- | :-------------------- | +| `GET` | `/consul/creds/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of an existing role against + which to create this Consul credential. This is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/consul/creds/example-role +``` + +### Sample response + +```json +{ + "data": { + "token": "973a31ea-1ec4-c2de-0f63-623f477c2510" + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/cubbyhole.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/cubbyhole.mdx new file mode 100644 index 0000000000..460ab69656 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/cubbyhole.mdx @@ -0,0 +1,202 @@ +--- +layout: api +page_title: Cubbyhole - Secrets Engines - HTTP API +description: This is the API documentation for the Vault Cubbyhole secrets engine. +--- + +# Cubbyhole secrets engine (API) + +This is the API documentation for the Vault Cubbyhole secrets engine. For +general information about the usage and operation of the Cubbyhole secrets +engine, please see the [Vault Cubbyhole documentation](/vault/docs/secrets/cubbyhole). + +This documentation assumes the Cubbyhole secrets engine is enabled at the +`/cubbyhole` path in Vault. Since it is possible to enable secrets engines at +any location, please update your API calls accordingly. + +## Read secret + +This endpoint retrieves the secret at the specified location. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/cubbyhole/:path` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to read as + part of the URL. +- `read_snapshot_id` `(string: )` - Query parameter specifing a loaded snapshot ID to +read the secret. + +### Sample requests + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/cubbyhole/my-secret +``` + +To read the secret from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`: + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/cubbyhole/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a +``` + + +### Sample response + +```json +{ + "auth": null, + "data": { + "foo": "bar" + }, + "lease_duration": 0, + "lease_id": "", + "renewable": false +} +``` + +## List secrets + +This endpoint returns a list of secret entries at the specified location. +Folders are suffixed with `/`. The input must be a folder; list on a file will +not return a value. The values themselves are not accessible via this command. + +| Method | Path | +| :----- | :----------------- | +| `LIST` | `/cubbyhole/:path` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to list. + This is specified as part of the URL. +- `read_snapshot_id` `(string: )` - Query parameter specifying the loaded snapshot ID from which Vault should read secrets for the provided path. + +### Sample requests + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/cubbyhole/my-secret +``` + +To list the secrets from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`: + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/cubbyhole/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a" +``` + + +### Sample response + +The example below shows output for a query path of `cubbyhole/` when there are +secrets at `cubbyhole/foo` and `cubbyhole/foo/bar`; note the difference in the +two entries. + +```json +{ + "auth": null, + "data": { + "keys": ["foo", "foo/"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Create/Update secret + +This endpoint stores a secret at the specified location. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/cubbyhole/:path` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to + create/update. This is specified as part of the URL. + +- `:key` `(string: "")` – Specifies a key in the payload, paired with an associated value, to + be held at the given location. Multiple key/value pairs can be specified, and + all will be returned on a read operation. + +### Sample payload + +```json +{ + "foo": "bar", + "zip": "zap" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/cubbyhole/my-secret +``` + +## Recover secret + +[Recover](/vault/docs/sysadmin/snapshots/recover-a-secret) a secret at the +specified location from the given loaded snapshot. + +| Method | Path | +|:----------|:-------------------| +| `RECOVER` | `/cubbyhole/:path` | + +### Query parameters + +- `path` `(string: )` – The target path of the secrets you want to recover. + +### Headers + +- `X-Vault-Recover-Snapshot-Id` `(string: )` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path. +- `X-Vault-Recover-Source-Path` `(string: )` - The original path of the data in the snapshot, if different from the target path. + + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request RECOVER \ + --header "X-Vault-Recover-Snapshot-Id: 2403d301-94f2-46a1-a39d-02be83e2831a" \ + --header "X-Vault-Recover-Source-Path: cubbyhole/my-old-secret" \ + https://127.0.0.1:8200/v1/cubbyhole/my-secret +``` + +## Delete secret + +This endpoint deletes the secret at the specified location. + +| Method | Path | +| :------- | :----------------- | +| `DELETE` | `/cubbyhole/:path` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to delete. + This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/cubbyhole/my-secret +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/cassandra.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/cassandra.mdx new file mode 100644 index 0000000000..5e265979f0 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/cassandra.mdx @@ -0,0 +1,218 @@ +--- +layout: api +page_title: Cassandra - Database - Secrets Engines - HTTP API +description: >- + The Cassandra plugin for Vault's database secrets engine generates database + credentials to access Cassandra servers. +--- + +# Cassandra database plugin HTTP API + +@include 'x509-sha1-deprecation.mdx' + +The Cassandra database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the Cassandra database. + +## Configure connection + +In addition to the parameters defined by the [Database +Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `hosts` `(string: )` – Specifies a set of comma-delineated Cassandra + hosts to connect to. + +- `port` `(int: 9042)` – Specifies the default port to use if none is provided + as part of the host URI. Defaults to Cassandra's default transport port, 9042. + +- `username` `(string: )` – Specifies the username to use for + superuser access. + +- `password` `(string: )` – Specifies the password corresponding to + the given username. + +- `tls` `(bool: true)` – Specifies whether to use TLS when connecting to + Cassandra. + +- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the + server certificate when using TLS. + +- `tls_server_name` `(string: "")` – Specifies the name to use as the SNI host when + connecting to the Cassandra server via TLS. + +- `pem_bundle` `(string: "")` – Specifies concatenated PEM blocks containing a + certificate and private key; a certificate, private key, and issuing CA + certificate; or just a CA certificate. Only one of `pem_bundle` or `pem_json` can be specified. + +- `pem_json` `(string: "")` – Specifies JSON containing a certificate and + private key; a certificate, private key, and issuing CA certificate; or just a + CA certificate. The value in this field must be an encoded JSON object. For convenience format is the + same as the output of the `issue` command from the `pki` secrets engine; see + [the pki documentation](/vault/docs/secrets/pki). Only one of `pem_bundle` or `pem_json` can be specified. + +
+pem_json example + +```json +{ + "certificate": "", + "private_key": "", + "ca_chain": ["", " pem_json=@/path/to/file.json +``` + +
+ +- `skip_verification` `(bool: false)` - Skip permissions checks when a connection to Cassandra + is first created. These checks ensure that Vault is able to create roles, but can be resource + intensive in clusters with many roles. + +- `protocol_version` `(int: 2)` – Specifies the CQL protocol version to use. + +- `connect_timeout` `(string: "5s")` – Specifies the timeout to use, both for + connections and in general. + +- `local_datacenter` `(string: "")` – If set, enables host selection policy + which will prioritize and use hosts which are in the local datacenter before + hosts in all other datacenters (for example `dc-01`). + +- `socket_keep_alive` `(string: "0s")` – the keep-alive period for an active + network connection. If zero, keep-alives are not enabled. + +- `consistency` `(string: "")` – Specifies the consistency option to use. See + the [gocql + definition](https://github.com/gocql/gocql/blob/master/frame.go#L188) for + valid options. + +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how + dynamic usernames are generated. + +
+Default Username Template + +``` +{{ printf "v_%s_%s_%s_%s" (.DisplayName | truncate 15) (.RoleName | truncate 15) (random 20) (unix_time) | truncate 100 | replace "-" "_" | lowercase }} +``` + +
+Example Usernames: + +| Example | | +| ------------- | ---------------------------------------------------- | +| `DisplayName` | `token` | +| `RoleName` | `myrolename` | +| Username | `v_token_myrolename_uszt1n4cyhal4m0xtgx3_1614294836` | + +| Example | | +| ------------- | ------------------------------------------------------------------- | +| `DisplayName` | `amuchlonger_dispname` | +| `RoleName` | `role-name-with-dashes` | +| Username | `v_amuchlonger_dis_role_name_with__s0t9xb0jsab9nqz7yj40_1614294836` | + +
+
+ +TLS works as follows: + +- If `tls` is set to true, the connection will use TLS; this happens + automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set + +- If `insecure_tls` is set to true, the connection will not perform verification + of the server certificate; this also sets `tls` to true + +- If only `issuing_ca` is set in `pem_json`, or the only certificate in + `pem_bundle` is a CA certificate, the given CA certificate will be used for + server certificate verification; otherwise the system CA certificates will be + used + +- If `certificate` and `private_key` are set in `pem_bundle` or `pem_json`, + client auth will be turned on for the connection + +`pem_bundle` should be a PEM-concatenated bundle of a private key + client +certificate, an issuing CA certificate, or both. `pem_json` should contain the +same information; for convenience, the JSON format is the same as that output by +the issue command from the PKI secrets engine. + +### Sample payload + +```json +{ + "plugin_name": "cassandra-database-plugin", + "allowed_roles": "readonly", + "hosts": "cassandra1.local", + "username": "user", + "password": "pass" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/cassandra/config/connection +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(list: [])` – Specifies the database + statements executed to create and configure a user. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{username}}` and `{{password}}` values will be substituted. If not + provided, defaults to a generic create user statements that creates a + non-superuser. + +- `revocation_statements` `(list: [])` – Specifies the database statements to + be executed to revoke a user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The `{{username}}` value will be + substituted. If not provided defaults to a generic drop user statement. + +- `rollback_statements` `(list: [])` – Specifies the database statements to be + executed to rollback a create operation in the event of an error. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{username}}` value will be substituted. If not provided, defaults to + a generic drop user statement + +- `root_rotation_statements` `(list: [])` - Specifies the database statements + to be executed when rotating the root user's password. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{username}}` value will be substituted. If not provided, defaults to + a reasonable default alter user statement. + +~> Prior to Vault 1.7.1 and 1.6.4 the default `root_rotation_statements` does not + allow for usernames with special characters in them due to missing quotes + around the username. To fix this issue in versions prior to Vault 1.7.1/1.6.4, + specify the following `root_rotation_statements`: + + ```sql + ALTER USER '{{username}}' WITH PASSWORD '{{password}}'; + ``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/couchbase.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/couchbase.mdx new file mode 100644 index 0000000000..addd5bdcd2 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/couchbase.mdx @@ -0,0 +1,115 @@ +--- +layout: api +page_title: Couchbase - Database - Secrets Engines - HTTP API +description: >- + The Couchbase plugin for Vault's database secrets engine generates database + credentials to access Couchbase servers. +--- + +# Couchbase database plugin HTTP API + +@include 'x509-sha1-deprecation.mdx' + +The Couchbase database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the Couchbase database. + +## Configure connection + +In addition to the parameters defined by the [Database +Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `hosts` `(string: )` – Specifies a set of comma-delimited Couchbase + hosts to connect to. Must use `couchbase://` scheme if `tls` is `true`. + +- `username` `(string: )` – Specifies the username for Vault to use. + +- `password` `(string: )` – Specifies the password corresponding to + the given username. + +- `tls` `(bool: false)` – Specifies whether to use TLS when connecting to + Couchbase. + +- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the + server certificate when using TLS. + +- `base64pem` `(string: "")` – Required if `tls` is `true`. Specifies the + certificate authority of the Couchbase server, as a PEM certificate that has + been base64 encoded. + +- `bucket_name` `(string: "")` - Required for Couchbase versions prior to 6.5.0. This + is only used to verify vault's connection to the server. + +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how + dynamic usernames are generated. + +
+Default Username Template + +``` +V_{{.DisplayName | uppercase | truncate 64}}_{{.RoleName | uppercase | truncate 64}}_{{random 20 | uppercase}}_{{unix_time}} +``` + +
+ Example Usernames: + +| Example | | +| ------------- | ---------------------------------------------------- | +| `DisplayName` | `token` | +| `RoleName` | `myrolename` | +| Username | `V_TOKEN_MYROLENAME_USZT1N4CYHAL4M0XTGX3_1614294836` | + +| Example | | +| ------------- | ------------------------------------------------------------------------------ | +| `DisplayName` | `amuchlonger_dispname` | +| `RoleName` | `role-name-with-dashes` | +| Username | `V_AMUCHLONGER_DISPNAME_ROLE-NAME-WITH-DASHES_S0T9XB0JSAB9NQZ7YJ40_1614294836` | + +
+
+ +### Sample payload + +```json +{ + "plugin_name": "couchbase-database-plugin", + "hosts": "couchbase://127.0.0.1", + "username": "user", + "password": "pass", + "allowed-roles": "my-*-role" +} +``` + +### Sample request + +```bash +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/couchbase +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(list: [])` – Specifies a JSON string containing + Couchbase RBAC roles to assign to created users. Any groups specified must + already exist. Must be a single JSON string. If not provided, defaults to + read-only admin. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/elasticdb.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/elasticdb.mdx new file mode 100644 index 0000000000..5b849e8ff2 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/elasticdb.mdx @@ -0,0 +1,109 @@ +--- +layout: api +page_title: Elasticsearch - Database - Secrets Engines - HTTP API +description: >- + The Elasticsearch plugin for Vault's database secrets engine generates + database credentials to access Elasticsearch. +--- + +# Elasticsearch database plugin HTTP API + +@include 'x509-sha1-deprecation.mdx' + +The Elasticsearch database plugin is one of the supported plugins for the database +secrets engine. This plugin generates credentials dynamically based on +configured roles for Elasticsearch. + +## Configure connection + +In addition to the parameters defined by the [Database +Backend](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `url` `(string: )` - The URL for Elasticsearch's API (`http://localhost:9200`). +- `username` `(string: )` - The username to be used in the connection URL (`vault`). +- `password` `(string: )` - The password to be used in the connection URL (`pa55w0rd`). +- `ca_cert` `(string: "")` - The path to a PEM-encoded CA cert file to use to verify the Elasticsearch server's identity. +- `ca_path` `(string: "")` - The path to a directory of PEM-encoded CA cert files to use to verify the Elasticsearch server's identity. +- `client_cert` `(string: "")` - The path to the certificate for the Elasticsearch client to present for communication. +- `client_key` `(string: "")` - The path to the key for the Elasticsearch client to use for communication. +- `tls_server_name` `(string: "")` - This, if set, is used to set the SNI host when connecting via TLS. +- `insecure` `(bool: false)` - Not recommended. Default to `false`. Can be set to `true` to disable certificate verification. +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how dynamic usernames are generated. +- `use_old_xpack` `(bool: false)` - Can be set to `true` to use the `/_xpack/security` base API path when managing Elasticsearch. May be required for Elasticsearch server versions prior to 6. + +### Sample payload + +```json +{ + "plugin_name": "elasticsearch-database-plugin", + "allowed_roles": "internally-defined-role,externally-defined-role", + "url": "http://localhost:9200", + "username": "vault", + "password": "myPa55word", + "ca_cert": "/usr/share/ca-certificates/extra/elastic-stack-ca.crt.pem", + "client_cert": "$ES_HOME/config/certs/elastic-certificates.crt.pem", + "client_key": "$ES_HOME/config/certs/elastic-certificates.key.pem" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/my-elasticsearch-database +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(string: )` – Using JSON, either defines an + `elasticsearch_role_definition` or a group of pre-existing `elasticsearch_roles`. + + The object specified by the `elasticsearch_role_definition` is the JSON directly + passed through to the Elasticsearch API, so you can pass through anything shown + [here](https://www.elastic.co/guide/en/elasticsearch/reference/6.6/security-api-put-role.html). + + For `elasticsearch_roles`, add the names of the roles only. They must pre-exist + in Elasticsearch. Defining roles in Vault is more secure than using pre-existing + roles because a privilege escalation could be performed by editing the roles used + out-of-band in Elasticsearch. + +### Sample creation statements + +```json +{ + "elasticsearch_role_definition": { + "indices": [ + { + "names": ["*"], + "privileges": ["read"] + } + ] + } +} +``` + +```json +{ + "elasticsearch_roles": ["pre-existing-role-in-elasticsearch"] +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/hanadb.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/hanadb.mdx new file mode 100644 index 0000000000..6c4368068f --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/hanadb.mdx @@ -0,0 +1,104 @@ +--- +layout: api +page_title: HANA - Database - Secrets Engines - HTTP API +description: >- + The HANA plugin for Vault's database secrets engine generates database + credentials to access HANA servers. +--- + +# HANA database plugin HTTP API + +The HANA database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the HANA database. + +## Configure connection + +In addition to the parameters defined by the [database +secrets engine](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | Produces | +| :----- | :----------------------- | -------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `connection_url` `(string: )` - Specifies the HANA DSN. This field + can be templated and supports passing the username and password + parameters in the following format `{{field_name}}`. A templated connection URL is + required when using root credential rotation. + +- `max_open_connections` `(int: 4)` - Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of + time a connection may be reused. If ≤ `0s`, connections are reused forever. + +- `username` `(string: "")` - The root credential username used in the connection URL. + +- `password` `(string: "")` - The root credential password used in the connection URL. + +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how dynamic usernames are generated. + +- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username + and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping) + for more information. Defaults to `false`. + +### Sample payload + +```json +{ + "plugin_name": "hana-database-plugin", + "allowed_roles": "readonly", + "connection_url": "hdb://{{username}}:{{password}}@localhost:1433", + "max_open_connections": 5, + "max_connection_lifetime": "5s", + "username": "username", + "password": "password" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/hana +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(list: )` – Specifies the database + statements executed to create and configure a user. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}`, `{{password}}`, and `{{expiration}}` values will be + substituted. + + - The expiration time will be HANA server time plus the role's `default_ttl`. + If `default_ttl` is 0 or not set, a SQL HdbError 438 will be returned. + +- `revocation_statements` `(list: [])` – Specifies the database statements to + be executed to revoke a user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The `{{name}}` value will be + substituted. If not provided, defaults to dropping the user only if they have + no dependent objects. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/index.mdx new file mode 100644 index 0000000000..954173b3d0 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/index.mdx @@ -0,0 +1,874 @@ +--- +layout: api +page_title: Database - Secrets Engines - HTTP API +description: Top page for database secrets engine information +--- + +# Database secrets engine (API) + +This is the API documentation for the Vault Database secrets engine. For +general information about the usage and operation of the database secrets engine, +please see the +[Vault database secrets engine documentation](/vault/docs/secrets/databases). + +This documentation assumes the database secrets engine is enabled at the +`/database` path in Vault. Since it is possible to enable secrets engines at any +location, please update your API calls accordingly. + +## Configure connection + +This endpoint configures the connection string used to communicate with the +desired database. In addition to the parameters listed here, each Database +plugin has additional, database plugin specific, parameters for this endpoint. +Please read the HTTP API for the plugin you'd wish to configure to see the full +list of additional parameters. + +~> This endpoint distinguishes between `create` and `update` ACL capabilities. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name for this database + connection. This is specified as part of the URL. + +- `plugin_name` `(string: )` - Specifies the name of the plugin to use + for this connection. + +- `plugin_version` `(string: "")` - Specifies the semantic version of the plugin + to use for this connection. + +- `verify_connection` `(bool: true)` – Specifies if the connection is verified + during initial configuration. Defaults to true. + +- `allowed_roles` `(list: [])` - List of the roles allowed to use this connection. + Defaults to empty (no roles), if contains a `*` any role can use this connection. + +- `root_rotation_statements` `(list: [])` - Specifies the database statements to be + executed to rotate the root user's credentials. See the plugin's API page for more + information on support and formatting for this parameter. + +- `password_policy` `(string: "")` - The name of the + [password policy](/vault/docs/concepts/password-policies) to use when generating passwords + for this database. If not specified, this will use a default policy defined as: + 20 characters with at least 1 uppercase, 1 lowercase, 1 number, and 1 dash character. + +- `skip_static_role_import_rotation` `(bool: false)` – + Specifies if a given static account's password should be rotated on creation + of the static roles associated with this database config. This is can be + overridden at the role-level by the static role's [skip_import_rotation](#skip_import_rotation) + field. The default is false. + +@include 'rotationfields.mdx' + +~> We highly recommended that you use a Vault-specific user rather than the admin user +in your database when configuring the plugin. This user will be used to +create/update/delete users within the database so it will need to have the appropriate +permissions to do so. If the plugin supports +[rotating the root credentials](#rotate-root-credentials), we highly recommended +you perform that action after configuring the plugin. This will change the password +of the user configured in this step. The new password will **not** be viewable by users. + +### Common fields + +There are several common fields that you will see across many of the database plugins. +Please reference the individual plugin documentation for details on whether these fields +are supported and any additional details about them. + +- `connection_url` `(string)` - Specifies the connection string used to connect to the + database. Some plugins use `url` rather than `connection_url`. This allows for simple + templating of the username and password of the root user. Typically, this is done by + including a `{{username}}`, `{{name}}`, and/or `{{password}}` field within the string. + These fields are typically be replaced with the values in the `username` and + `password` fields. + +- `username` `(string)` - Specifies the name of the user to use as the "root" user when + connecting to the database. This "root" user is used to create/update/delete users + managed by these plugins, so you will need to ensure that this user has permissions to + manipulate users appropriate to the database. This is typically used in the + `connection_url` field via the templating directive `{{username}}` or `{{name}}`. + +- `password` `(string)` - Specifies the password to use when connecting with the + `username`. This value will not be returned by Vault when performing a read upon the + configuration. This is typically used in the `connection_url` field via the templating + directive `{{password}}`. + +- `disable_escaping` `(boolean: false)` - Determines whether special characters in the + username and password fields will be escaped. Useful for alternate connection string + formats like ADO. More information regarding this parameter can be found on the + [databases secrets engine docs.](/vault/docs/secrets/databases#disable-character-escaping) + Defaults to `false`. + +### Sample payload + +```json +{ + "plugin_name": "mysql-database-plugin", + "allowed_roles": "readonly", + "connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/", + "username": "vaultuser", + "password": "secretpassword" +} +``` + +### Sample cURL request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/mysql +``` + +### Sample CLI request + +```shell-session +$ vault write database/config/mysql \ + plugin_name="mysql-database-plugin" \ + allowed_roles="readonly" \ + connection_url="{{username}}:{{password}}@tcp(127.0.0.1:3306)/" \ + username="vaultuser" \ + password="secretpassword" +``` + +### Sample CLI request with ADO-style connection string + +```shell-session +$ vault write database/config/mssql \ + plugin_name="mssql-database-plugin" \ + connection_url='server=localhost;port=1433;user id={{username}};password={{password}};database=mssql;' \ + username="vaultuser" \ + password='your#StrongPassword%' \ + disable_escaping="true" +``` + +## Read connection + +This endpoint returns the configuration settings for a connection. + +| Method | Path | +| :----- | :----------------------- | +| `GET` | `/database/config/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the connection to read. + This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/database/config/mysql +``` + +### Sample response + +```json +{ + "data": { + "allowed_roles": ["readonly"], + "connection_details": { + "connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/", + "username": "vaultuser" + }, + "password_policy": "", + "plugin_name": "mysql-database-plugin", + "plugin_version": "", + "root_credentials_rotate_statements": [], + "skip_static_role_import_rotation": false + } +} +``` + +## List connections + +This endpoint returns a list of available connections. Only the connection names +are returned, not any values. + +| Method | Path | +| :----- | :----------------- | +| `LIST` | `/database/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/database/config +``` + +### Sample response + +```json +{ + "data": { + "keys": ["db-one", "db-two"] + } +} +``` + +## Delete connection + +This endpoint deletes a connection. + +| Method | Path | +| :------- | :----------------------- | +| `DELETE` | `/database/config/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the connection to delete. + This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/database/config/mysql +``` + +## Reset connection + +This endpoint closes a connection and it's underlying plugin and restarts it +with the configuration stored in the barrier. + +| Method | Path | +| :----- | :---------------------- | +| `POST` | `/database/reset/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the connection to reset. + This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/database/reset/mysql +``` + +## Reload plugin + +This endpoint performs the same operation as +[reset connection](/vault/api-docs/secret/databases#reset-connection) but for +all connections that reference a specific plugin name. This can be useful to +restart a specific plugin after it's been upgraded in the plugin catalog. + +| Method | Path | +| :----- | :------------------------------ | +| `POST` | `/database/reload/:plugin_name` | + +### Parameters + +- `plugin_name` `(string: )` – Specifies the name of the plugin for + which all connections should be reset. This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/database/reload/postgresql-database-plugin +``` + +### Sample response + +```json +{ + "data": { + "connections": ["pg1", "pg2"], + "count": 2 + } +} +``` + +## Rotate root credentials + +This endpoint is used to rotate the "root" user credentials stored for +the database connection. This user must have permissions to update its own +password. + +| Method | Path | +| :----- | :---------------------------- | +| `POST` | `/database/rotate-root/:name` | + +!> **Use caution:** the root user's password will not be accessible once rotated so it is highly +recommended that you create a user for Vault to utilize rather than using the actual root user. + +### Parameters + +- `name` `(string: )` – Specifies the name of the connection to rotate. + This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/database/rotate-root/mysql +``` + +## Create role + +This endpoint creates or updates a role definition. + +~> This endpoint distinguishes between `create` and `update` ACL capabilities. + +| Method | Path | +| :----- | :---------------------- | +| `POST` | `/database/roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This + is specified as part of the URL. + +- `db_name` `(string: )` - The name of the database connection to use + for this role. + +- `default_ttl` `(string/int: 0)` - Specifies the TTL for the leases + associated with this role. Accepts time suffixed strings (`1h`) or an integer + number of seconds. Defaults to system/engine default TTL time. + +- `max_ttl` `(string/int: 0)` - Specifies the maximum TTL for the leases + associated with this role. Accepts time suffixed strings (`1h`) or an integer + number of seconds. Defaults to `sys/mounts`'s default TTL time; this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL), but it is not allowed to be longer. See also [The TTL General Case](/vault/docs/concepts/tokens#the-general-case). + +- `creation_statements` `(list: )` – Specifies the database + statements executed to create and configure a user. See the plugin's API page + for more information on support and formatting for this parameter. + +- `revocation_statements` `(list: [])` – Specifies the database statements to + be executed to revoke a user. See the plugin's API page for more information + on support and formatting for this parameter. + +- `rollback_statements` `(list: [])` – Specifies the database statements to be + executed to rollback a create operation in the event of an error. Not every + plugin type will support this functionality. See the plugin's API page for + more information on support and formatting for this parameter. + +- `renew_statements` `(list: [])` – Specifies the database statements to be + executed to renew a user. Not every plugin type will support this + functionality. See the plugin's API page for more information on support and + formatting for this parameter. + +@include 'db-secrets-credential-types.mdx' + +### Sample payload + +```json +{ + "db_name": "mysql", + "creation_statements": [ + "CREATE USER '{{name}}'@'%' IDENTIFIED BY '{{password}}'", + "GRANT SELECT ON *.* TO '{{name}}'@'%'" + ], + "default_ttl": "1h", + "max_ttl": "24h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/roles/my-role +``` + +## Read role + +This endpoint queries the role definition. + +| Method | Path | +| :----- | :---------------------- | +| `GET` | `/database/roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to read. This + is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/database/roles/my-role +``` + +### Sample response + +```json +{ + "data": { + "creation_statements": [ + "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';", + "GRANT SELECT ON ALL TABLES IN SCHEMA public TO \"{{name}}\";" + ], + "credential_type": "password", + "db_name": "mysql", + "default_ttl": 3600, + "max_ttl": 86400, + "renew_statements": [], + "revocation_statements": [], + "rollback_statements": [] + } +} +``` + +## List roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. + +| Method | Path | +| :----- | :---------------- | +| `LIST` | `/database/roles` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/database/roles +``` + +### Sample response + +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Delete role + +This endpoint deletes the role definition. + +| Method | Path | +| :------- | :---------------------- | +| `DELETE` | `/database/roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/database/roles/my-role +``` + +## Generate credentials + +This endpoint generates a new set of dynamic credentials based on the named +role. + +| Method | Path | +| :----- | :---------------------- | +| `GET` | `/database/creds/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create + credentials against. This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/database/creds/my-role +``` + +### Sample response + +```json +{ + "data": { + "username": "root-1430158508-126", + "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21" + } +} +``` + +## Create static role + +This endpoint creates or updates a static role definition. Static Roles are a +1-to-1 mapping of a Vault Role to a user in a database which are automatically +rotated based on the configured `rotation_period` or `rotation_schedule`. + +~> This endpoint distinguishes between `create` and `update` ACL capabilities. + +~> Vault will rotate the password when creating a static role. Vault must do +this in order to know the password. + +| Method | Path | +| :----- | :----------------------------- | +| `POST` | `/database/static-roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to create. This + is specified as part of the URL. + +- `username` `(string: )` – Specifies the database username that this + Vault role corresponds to. + +- `password` `(string)` – + The password corresponding to the username in the database. Required when using + the Rootless Password Rotation workflow or the Skip Automatic Import Rotation + workflow for static roles. + +- `self_managed_password` `(string)` – + The password corresponding to the username in the database. Required when using + the Rootless Password Rotation workflow for static roles. Only enabled for select + DB engines (Postgres, Oracle). The `self_managed_password` parameter is deprecated in favor of `password`. + +- `db_name` `(string: )` - The name of the database connection to use + for this role. + +- `rotation_period` `(string/int)` – Specifies the amount of time Vault should + wait before rotating the password. The minimum is 5 seconds. Uses [duration + format strings](/vault/docs/concepts/duration-format). Mutually exclusive + with `rotation_schedule`. + +- `rotation_schedule` `(string)` – A cron-style string that will define the + schedule on which rotations should occur. This should be a "standard" + [cron-style](https://en.wikipedia.org/wiki/Cron) string made of five fields + of which each entry defines the minute, hour, day of month, month, and day of + week respectively. For example, a value of `0 0 * * SAT` will set rotations + to occur on Saturday at 00:00. Vault interprets the schedule in UTC. + Mutually exclusive with `rotation_period`. + + ~> **Warning**: The `rotation_period` and `rotation_schedule` fields are + mutually exclusive. One of them must be set but not both. + +- `rotation_window` `(string/int)` – Specifies the amount of time in which the + rotation is allowed to occur starting from a given `rotation_schedule`. If + the credential is not rotated during this window, due to a failure or + otherwise, it will not be rotated until the next scheduled rotation. The + minimum is 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format). + Optional when `rotation_schedule` is set and disallowed when `rotation_period` + is set. + +- `rotation_statements` `(list: [])` – Specifies the database statements to be + executed to rotate the password for the configured database user. Not every + plugin type will support this functionality. See the plugin's API page for + more information on support and formatting for this parameter. + +- `skip_import_rotation` `(bool: false)` – + Specifies if the static account's password should be rotated on creation of + the static role. This overrides the config-level field + [skip_static_role_import_rotation](#skip_static_role_import_rotation). The + default is false. + + +@include 'db-secrets-credential-types.mdx' + +### Sample payload with rotation period + +```json +{ + "db_name": "mysql", + "username": "static-database-user", + "rotation_statements": [ + "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';" + ], + "rotation_period": "1h" +} +``` + +### Sample payload with rotation schedule + +```json +{ + "db_name": "mysql", + "username": "static-database-user", + "rotation_statements": [ + "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';" + ], + "rotation_schedule": "0 0 * * SAT", + "rotation_window": "1h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/static-roles/my-static-role +``` + +## Read static role + +This endpoint queries the static role definition. + +| Method | Path | +| :----- | :----------------------------- | +| `GET` | `/database/static-roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the static role to read. + This is specified as part of the URL. +- `read_snapshot_id` `(string: )` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains the role at the provided path. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/database/static-roles/my-static-role +``` + +To read the role from a loaded snapshot with ID 2403d301-94f2-46a1-a39d-02be83e2831a: + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/database/static-roles/my-static-role?read_s +``` + +### Sample response with rotation period + +```json +{ + "data": { + "credential_type": "password", + "db_name": "mysql", + "username": "static-user", + "rotation_statements": [ + "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';" + ], + "rotation_period": 3600, + "skip_import_rotation": false + } +} +``` + +### Sample response with rotation schedule + +```json +{ + "data": { + "credential_type": "password", + "db_name": "mysql", + "username": "static-user", + "rotation_statements": [ + "ALTER USER \"{{name}}\" IDENTIFIED BY '{{password}}';" + ], + "rotation_schedule": "0 0 * * SAT", + "rotation_window": 3600, + "skip_import_rotation": false + } +} +``` + +## List static roles + +This endpoint returns a list of available static roles. Only the role names are +returned, not any values. + +| Method | Path | +| :----- | :----------------------- | +| `LIST` | `/database/static-roles` | + +### Parameters + +- `read_snapshot_id` `(string: )` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains the roles at the provided path. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/database/static-roles +``` +To list the roles from a loaded snapshot with ID 2403d301-94f2-46a1-a39d-02be83e2831a: + +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/database/static-roles?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a +``` +### Sample response + +```json +{ + "auth": null, + "data": { + "keys": ["dev-static", "prod-static"] + } +} +``` + +## Recover static role + +[Recover](/vault/docs/concepts/integrated-storage/snapshot-recover) a role at the specified location from the given loaded snapshot. + +~> The static role can only be recovered if the role doesn't already exist in the live cluster. A static role cannot be updated via a recover operation. + +| Method | Path | +|:----------|:-------------------------------| +| `RECOVER` | `/database/static-roles/:name` | + +### Query parameters + +- `name` `(string: )` – Specifies the name of the static role to read. +This is specified as part of the URL. + +### Headers + +- `X-Vault-Recover-Snapshot-Id` `(string: )` - The ID of a snapshot previously loaded into Vault that contains the role at the provided path. +- `X-Vault-Recover-Source-Path` `(string: )` - The source path in the snapshot to recover from. If not provided, defaults to the request path. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request RECOVER \ + --header "X-Vault-Recover-Snapshot-Id: 2403d301-94f2-46a1-a39d-02be83e2831a" \ + --header "X-Vault-Recover-Source-Path: database/static-roles/my-old-role" \ + https://127.0.0.1:8200/v1/database/static-roles/my-role +``` + +## Delete static role + +This endpoint deletes the static role definition. The user, having been defined externally, +must be cleaned up manually. + +| Method | Path | +| :------- | :----------------------------- | +| `DELETE` | `/database/static-roles/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the static role to + delete. This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/database/static-roles/my-role +``` + +## Get static credentials + +This endpoint returns the current credentials based on the named static role. + +| Method | Path | +| :----- | :----------------------------- | +| `GET` | `/database/static-creds/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the static role to get + credentials for. This is specified as part of the URL. +- `read_snapshot_id` `(string: )` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains credentials at the provided path. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/database/static-creds/my-static-role +``` + +To read the credentials from a loaded snapshot with ID 2403d301-94f2-46a1-a39d-02be83e2831a: + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/database/static-creds/my-static-role?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a +``` + +### Sample response with rotation period + +```json +{ + "data": { + "username": "static-user", + "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21", + "last_vault_rotation": "2019-05-06T15:26:42.525302-05:00", + "rotation_period": 30, + "ttl": 28 + } +} +``` + +### Sample response with rotation schedule + +```json +{ + "data": { + "username": "static-user", + "password": "132ae3ef-5a64-7499-351e-bfe59f3a2a21", + "last_vault_rotation": "2019-05-06T15:26:42.525302-05:00", + "rotation_schedule": "0 0 * * SAT", + "rotation_window": 3600, + "ttl": 5000 + } +} +``` + +## Rotate static role credentials + +This endpoint is used to rotate the Static Role credentials stored for a given +role name. While Static Roles are rotated automatically by Vault at configured +rotation periods, users can use this endpoint to manually trigger a rotation to +change the stored password and reset the TTL of the Static Role's password. + +| Method | Path | +| :----- | :---------------------------- | +| `POST` | `/database/rotate-role/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the Static Role to + trigger the password rotation for. The name is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/database/rotate-role/my-static-role +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/influxdb.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/influxdb.mdx new file mode 100644 index 0000000000..7f46340385 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/influxdb.mdx @@ -0,0 +1,136 @@ +--- +layout: api +page_title: Influxdb - Database - Secrets Engines - HTTP API +description: >- + The Influxdb plugin for Vault's database secrets engine generates database + credentials to access Influxdb servers. +--- + +# Influxdb database plugin HTTP API + +@include 'x509-sha1-deprecation.mdx' + +The Influxdb database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the Influxdb database. + +## Configure connection + +In addition to the parameters defined by the [Database +Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `host` `(string: )` – Specifies a Influxdb + host to connect to. + +- `port` `(int: 8086)` – Specifies the default port to use if none is provided + as part of the host URI. Defaults to Influxdb's default transport port, 8086. + +- `username` `(string: )` – Specifies the username to use for + superuser access. + +- `password` `(string: )` – Specifies the password corresponding to + the given username. + +- `tls` `(bool: true)` – Specifies whether to use TLS when connecting to + Influxdb. + +- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the + server certificate when using TLS. + +- `pem_bundle` `(string: "")` – Specifies concatenated PEM blocks containing a + certificate and private key; a certificate, private key, and issuing CA + certificate; or just a CA certificate. + +- `pem_json` `(string: "")` – Specifies JSON containing a certificate and + private key; a certificate, private key, and issuing CA certificate; or just a + CA certificate. For convenience format is the same as the output of the + `issue` command from the `pki` secrets engine; see + [the pki documentation](/vault/docs/secrets/pki). + +- `connect_timeout` `(string: "5s")` – Specifies the connection timeout to use. + +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how +dynamic usernames are generated. + +TLS works as follows: + +- If `tls` is set to true, the connection will use TLS; this happens + automatically if `pem_bundle`, `pem_json`, or `insecure_tls` is set + +- If `insecure_tls` is set to true, the connection will not perform verification + of the server certificate; this also sets `tls` to true + +- If only `issuing_ca` is set in `pem_json`, or the only certificate in + `pem_bundle` is a CA certificate, the given CA certificate will be used for + server certificate verification; otherwise the system CA certificates will be + used + +- If `certificate` and `private_key` are set in `pem_bundle` or `pem_json`, + client auth will be turned on for the connection + +`pem_bundle` should be a PEM-concatenated bundle of a private key + client +certificate, an issuing CA certificate, or both. `pem_json` should contain the +same information; for convenience, the JSON format is the same as that output by +the issue command from the PKI secrets engine. + +### Sample payload + +```json +{ + "plugin_name": "influxdb-database-plugin", + "allowed_roles": "readonly", + "host": "influxdb1.local", + "username": "user", + "password": "pass" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/influxdb/config/connection +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(list: [])` – Specifies the database + statements executed to create and configure a user. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{username}}` and `{{password}}` values will be substituted. If not + provided, defaults to a generic create user statements that creates a + non-superuser. + +- `revocation_statements` `(list: [])` – Specifies the database statements to + be executed to revoke a user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The `{{username}}` value will be + substituted. If not provided defaults to a generic drop user statement. + +- `rollback_statements` `(list: [])` – Specifies the database statements to be + executed to rollback a create operation in the event of an error. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{username}}` value will be substituted. If not provided, defaults to + a generic drop user statement. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mongodb.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mongodb.mdx new file mode 100644 index 0000000000..6cdbc50c0e --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mongodb.mdx @@ -0,0 +1,151 @@ +--- +layout: api +page_title: MongoDB - Database - Secrets Engines - HTTP API +description: >- + The MongoDB plugin for Vault's database secrets engine generates database + credentials to access MongoDB servers. +--- + +# MongoDB database plugin HTTP API + +@include 'x509-sha1-deprecation.mdx' + +The MongoDB database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the MongoDB database. + +## Configure connection + +In addition to the parameters defined by the [Database +Backend](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `connection_url` `(string: )` – Specifies the MongoDB standard + connection string (URI). This field can be templated and supports passing the + username and password parameters in the following format {{field_name}}. A + templated connection URL is required when using root credential rotation. + +- `write_concern` `(string: "")` - Specifies the MongoDB [write + concern][mongodb-write-concern]. This is set for the entirety of the session, + maintained for the lifecycle of the plugin process. Must be a serialized JSON + object, or a base64-encoded serialized JSON object. The JSON payload values + map to the values in the [Safe][mgo-safe] struct from the mgo driver. + +- `username` `(string: "")` - The root credential username used in the connection URL. + +- `password` `(string: "")` - The root credential password used in the connection URL. + +- `tls_certificate_key` `(string: "")` - x509 certificate for connecting to the database. + This must be a PEM encoded version of the private key and the certificate combined. + +- `tls_ca` `(string: "")` - x509 CA file for validating the certificate presented by the + MongoDB server. Must be PEM encoded. + +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how + dynamic usernames are generated. + +
+Default Username Template + +``` +{{ printf "v-%s-%s-%s-%s" (.DisplayName | truncate 15) (.RoleName | truncate 15) (random 20) (unix_time) | replace "." "-" | truncate 100 }} +``` + +
+ Example Usernames: + +| Example | | +| ------------- | ---------------------------------------------------- | +| `DisplayName` | `token` | +| `RoleName` | `myrolename` | +| Username | `v-token-myrolename-jNFRlKsZZMxJEx60o66i-1614294836` | + +| Example | | +| ------------- | ------------------------------------------------------------------- | +| `DisplayName` | `amuchlonger_dispname` | +| `RoleName` | `role-name-with-dashes` | +| Username | `v-amuchlonger_dis-role-name-with--jNFRlKsZZMxJEx60o66i-1614294836` | + +
+
+ +### Sample payload + +```json +{ + "plugin_name": "mongodb-database-plugin", + "allowed_roles": "readonly", + "connection_url": "mongodb://{{username}}:{{password}}@mongodb.acme.com:27017/admin?ssl=true", + "write_concern": "{ \"wmode\": \"majority\", \"wtimeout\": 5000 }", + "username": "admin", + "password": "Password!" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/mongodb +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(string: )` – Specifies the database + statements executed to create and configure a user. Must be a + serialized JSON object, or a base64-encoded serialized JSON object. + The object can optionally contain a `db` string for session connection, + and must contain a `roles` array. This array contains objects that holds + a `role`, and an optional `db` value, and is similar to the BSON document that + is accepted by MongoDB's `roles` field. Vault will transform this array into + such format. For more information regarding the `roles` field, refer to + [MongoDB's documentation](https://docs.mongodb.com/manual/reference/method/db.createUser/). + +- `revocation_statements` `(string: "")` – Specifies the database statements to + be executed to revoke a user. Must be a serialized JSON object, or a base64-encoded + serialized JSON object. The object can optionally contain a `db` string. If no + `db` value is provided, it defaults to the `admin` database. + +### Sample creation statement + +```json +{ + "db": "admin", + "roles": [ + { + "role": "read", + "db": "foo" + } + ] +} +``` + +### Sample revocation statement + +```json +{ + "db": "vault-db" +} +``` + +[mongodb-write-concern]: https://docs.mongodb.com/manual/reference/write-concern/ +[mgo-safe]: https://godoc.org/gopkg.in/mgo.v2#Safe diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mongodbatlas.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mongodbatlas.mdx new file mode 100644 index 0000000000..c895b92ce1 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mongodbatlas.mdx @@ -0,0 +1,109 @@ +--- +layout: 'api' +page_title: 'MongoDB Atlas - Database - Secrets Engines - HTTP API' +description: |- + The MongoDB Atlas plugin for Vault's Database Secrets Engine generates MongoDB Database User credentials for MongoDB Atlas. +--- + +# MongoDB atlas database plugin HTTP API + +The MongoDB Atlas plugin is one of the supported plugins for the Database +Secrets Engine. This plugin generates MongoDB Atlas Database User credentials dynamically based on +configured roles. + +## Configure connection + +In addition to the parameters defined by the [Database +Backend](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `public_key` `(string: )` – The Public Programmatic API Key used to authenticate with the MongoDB Atlas API. +- `private_key` `(string: )` - The Private Programmatic API Key used to connect with MongoDB Atlas API. +- `project_id` `(string: )` - The [Project ID](https://docs.atlas.mongodb.com/api/#project-id) the Database User should be created within. +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how + dynamic usernames are generated. + + +### Sample payload + +```json +{ + "plugin_name": "mongodbatlas-database-plugin", + "allowed_roles": "readonly", + "public_key": "aPublicKey", + "private_key": "aPrivateKey", + "project_id": "aProjectID" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/mongodbatlas +``` + +## Statements + +Statements are configured during Vault role creation and are used by the plugin to +determine what is sent to MongoDB Atlas upon user creation, renewal, and +revocation. For more information on configuring roles see the [Role API](/vault/api-docs/secret/databases#create-role) +in the Database Secrets Engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(string: )` – Specifies the database + statements executed to create and configure a user. Must be a + serialized JSON object, or a base64-encoded serialized JSON object. + The object can optionally contain a `database_name`, the name of + the authentication database to log into MongoDB. In Atlas deployments of + MongoDB, the options for the authentication database include admin (default) and $external database. + The object must also contain a `roles` array, and from Vault version 1.6.0 (plugin + version 0.2.0) may optionally contain a `scopes` array. The `roles` array + contains objects that hold a series of roles `roleName`, an optional + `databaseName` and `collectionName` value. The `scopes` array determines + which clusters and data lakes the user has access to, and defaults to all + scopes if omitted. For more information regarding the `roles` and `scopes` + fields, refer to [MongoDB Atlas documentation](https://docs.atlas.mongodb.com/reference/api/database-users-create-a-user/). +- `default_ttl` `(string/int): 0` - Specifies the TTL for the leases associated with this role. + Accepts time suffixed strings (`1h`) or an integer number of seconds. Defaults to system/engine default TTL time. +- `max_ttl` `(string/int): 0` - Specifies the maximum TTL for the leases associated with this role. Accepts time + suffixed strings (`1h`) or an integer number of seconds. Defaults to `sys/mounts` default TTL time; this value + is allowed to be less than the mount max TTL (or, if not set, the system max TTL), + but it is not allowed to be longer. See also [The TTL General Case](/vault/docs/concepts/tokens#the-general-case). + +### Sample creation statement + +```json +{ + "database_name": "admin", + "roles": [ + { + "databaseName": "admin", + "roleName": "atlasAdmin" + }, + { + "collectionName": "acollection", + "roleName": "read" + } + ], + "scopes": [ + { + "name": "a-cluster", + "type": "CLUSTER" + } + ] +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mssql.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mssql.mdx new file mode 100644 index 0000000000..3642b1dafa --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mssql.mdx @@ -0,0 +1,136 @@ +--- +layout: api +page_title: MSSQL - Database - Secrets Engines - HTTP API +description: >- + The MSSQL plugin for Vault's database secrets engine generates database + credentials to access MSSQL servers. +--- + +# MSSQL database plugin HTTP API + +The MSSQL database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the MSSQL database. + +## Configure connection + +In addition to the parameters defined by the [Database +Backend](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `connection_url` `(string: )` - Specifies the MSSQL DSN. This field + can be templated and supports passing the username and password + parameters in the following format {{field_name}}. A templated connection URL is + required when using root credential rotation. + +- `max_open_connections` `(int: 4)` - Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of + time a connection may be reused. If <= `0s` connections are reused forever. + +- `username` `(string: "")` - The root credential username used in the connection URL. + +- `password` `(string: "")` - The root credential password used in the connection URL. + +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how + dynamic usernames are generated. + +- `contained_db` `(bool: false)` - If set, specifies that the connection being configured is to a + [Contained Database](https://docs.microsoft.com/en-us/sql/relational-databases/databases/contained-databases?view=sql-server-ver15), + like AzureSQL. + +- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username + and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping) + for more information. Defaults to `false`. + +
+Default Username Template + +``` +{{ printf "v-%s-%s-%s-%s" (.DisplayName | truncate 20) (.RoleName | truncate 20) (random 20) (unix_time) | truncate 128 }} +``` + +
+ Example Usernames: + +| Example | | +| ------------- | ---------------------------------------------------- | +| `DisplayName` | `token` | +| `RoleName` | `myrolename` | +| Username | `v-token-myrolename-jNFRlKsZZMxJEx60o66i-1614294836` | + +| Example | | +| ------------- | ----------------------------------------------------------------------------- | +| `DisplayName` | `amuchlonger_dispname` | +| `RoleName` | `role-name-with-dashes` | +| Username | `v-amuchlonger_dispname-role-name-with-dashe-LUHU9xqm6YNisikA3iCQ-1614294836` | + +
+
+ +### Sample payload + +```json +{ + "plugin_name": "mssql-database-plugin", + "allowed_roles": "readonly", + "connection_url": "sqlserver://{{username}}:{{password}}@localhost:1433", + "max_open_connections": 5, + "max_connection_lifetime": "5s", + "username": "sa", + "password": "yourStrong(!)Password" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/mssql +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(list: )` – Specifies the database + statements executed to create and configure a user. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}` and `{{password}}` values will be substituted. + +- `revocation_statements` `(list: [])` – Specifies the database statements to + be executed to revoke a user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The `{{name}}` value will be + substituted. If not provided defaults to a generic drop user statement. + +- `rotation_statements` `(list: [])` – Specifies the database statements to be + executed to rotate the password for a given username. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}` and `{{password}}` values will be substituted. The + generated password will be a random alphanumeric 20 character string. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mysql-maria.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mysql-maria.mdx new file mode 100644 index 0000000000..bdce2662bd --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/mysql-maria.mdx @@ -0,0 +1,178 @@ +--- +layout: api +page_title: MySQL/MariaDB - Database - Secrets Engines - HTTP API +description: >- + The MySQL/MariaDB plugin for Vault's database secrets engine generates + database credentials to access MySQL and MariaDB servers. +--- + +# MySQL/MariaDB database plugin HTTP API + +@include 'x509-sha1-deprecation.mdx' + +The MySQL database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the MySQL database. + +## Configure connection + +In addition to the parameters defined by the [Database +Backend](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `connection_url` `(string: )` - Specifies the MySQL DSN. This field + can be templated and supports passing the username and password + parameters in the following format `{{field_name}}`. A templated connection URL is + required when using root credential rotation. + +- `max_open_connections` `(int: 4)` - Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of + time a connection may be reused. If ≤ 0s connections are reused forever. + +- `username` `(string: "")` - The root credential username used in the connection URL. + +- `password` `(string: "")` - The root credential password used in the connection URL. + +- `auth_type` `(string: "")` - If set to `gcp_iam`, will enable IAM authentication to a Google + CloudSQL instance. For more information on authenticating to CloudSQL via IAM, please refer to + Google's official documentation [here.](https://cloud.google.com/sql/docs/postgres/authentication). + +- `service_account_json` `(string: "")` - JSON encoded credentials for a GCP Service Account to use + for IAM authentication. Requires `auth_type` to be `gcp_iam`. + +- `tls_certificate_key` `(string: "")` - x509 certificate for connecting to the database. + This must be a PEM encoded version of the private key and the certificate combined. + +- `tls_ca` `(string: "")` - x509 CA file for validating the certificate presented by the + MySQL server. Must be PEM encoded. + +- `tls_server_name` `(string: "")` - Specifies the subject alternative name should be present in the + server's certificate. + +- `tls_skip_verify` `(boolean: false)` - When set to true, disables the server certificate verification. + Setting this to true is not recommended for production. + +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how + dynamic usernames are generated. + +- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username + and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping) + for more information. Defaults to `false`. + +**Default Username Templates:** + +
+mysql-database-plugin + +``` +{{ printf "v-%s-%s-%s-%s" (.DisplayName | truncate 10) (.RoleName | truncate 10) (random 20) (unix_time) | truncate 32 }} +``` + +
+Example Usernames: + +| Example | | +| ------------- | ---------------------------------- | +| `DisplayName` | `token` | +| `RoleName` | `myrolename` | +| Username | `v-token-myrolename-jNFRlKsZZMxJE` | + +| Example | | +| ------------- | ---------------------------------- | +| `DisplayName` | `amuchlonger_dispname` | +| `RoleName` | `role-name-with-dashes` | +| Username | `v-amuchlonge-role-name--LUHU9xqm` | + +
+
+ +

+ +
+ + mysql-aurora-database-plugin, mysql-rds-database-plugin, mysql-legacy-database-plugin + + +``` +{{ printf "v-%s-%s-%s" (.RoleName | truncate 4) (random 20) | truncate 16 }} +``` + +
+ Example Usernames: + +| Example | | +| ------------- | ------------------ | +| `DisplayName` | `token` | +| `RoleName` | `myrolename` | +| Username | `v-myro-jNFRlKsZZ` | + +| Example | | +| ------------- | ----------------------- | +| `DisplayName` | `amuchlonger_dispname` | +| `RoleName` | `role-name-with-dashes` | +| Username | `v-role-b9ODeKsfl` | + +
+
+ +### Sample payload + +```json +{ + "plugin_name": "mysql-database-plugin", + "allowed_roles": "readonly", + "connection_url": "{{username}}:{{password}}@tcp(127.0.0.1:3306)/", + "max_open_connections": 5, + "max_connection_lifetime": "5s", + "username": "root", + "password": "mysql" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/mysql +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(list: )` – Specifies the database + statements executed to create and configure a user. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}` and `{{password}}` values will be substituted. The + generated password will be a random alphanumeric 20 character string. + +- `revocation_statements` `(list: [])` – Specifies the database statements to + be executed to revoke a user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The `{{name}}` value will be + substituted. If not provided defaults to a generic drop user statement. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/oracle.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/oracle.mdx new file mode 100644 index 0000000000..4cc4cc1748 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/oracle.mdx @@ -0,0 +1,139 @@ +--- +layout: api +page_title: Oracle - Database - Secrets Engines - HTTP API +description: >- + The Oracle plugin for Vault's database secrets engine generates database + credentials to access Oracle servers. +--- + +# Oracle database plugin HTTP API + +The Oracle database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the Oracle database. + +## Configure connection + +In addition to the parameters defined by the [Database +Backend](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `connection_url` `(string: )` - Specifies the Oracle DSN. + +- `max_open_connections` `(int: 4)` - Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of + time a connection may be reused. If <= `0s` connections are reused forever. + +- `username` `(string: "")` - The root credential username used in the connection URL. + +- `password` `(string: "")` - The root credential password used in the connection URL. + +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how + dynamic usernames are generated. + +- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username + and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping) + for more information. Defaults to `false`. + +- `split_statements` `(boolean: true)` - Indicates that the provided statements + specified should be split on semi-colons. Set `split_statements` to true to + specify multiple SQL statements in a single string. Set `split_statements` to + `false` for complex queries such as stored or inline procedures. + +- `disconnect_sessions` `(boolean: true)` - Indicates the plugin should + disconnect any open sessions before running revocation statements. If + `disconnect_sessions` is `false`, the revocation statements **must** include + session disconnect logic. + +
+Default Username Template + +``` +{{ printf "V_%s_%s_%s_%s" (.DisplayName | truncate 8) (.RoleName | truncate 8) (random 20) (unix_time) | truncate 30 | uppercase | replace "-" "_" | replace "." "_" }} +``` + +
+Example Usernames: + +| Example | | +| ------------- | -------------------------------- | +| `DisplayName` | `token` | +| `RoleName` | `myrolename` | +| Username | `V_TOKEN_MYROLENA_JNFRLKSZZMXJE` | + +| Example | | +| ------------- | -------------------------------- | +| `DisplayName` | `amuchlonger_dispname` | +| `RoleName` | `role-name-with-dashes` | +| Username | `V_AMUCHLON_ROLE_NAM_LUHU9XQM6Y` | + +
+
+ +### Sample payload + +```json +{ + "plugin_name": "oracle-database-plugin", + "allowed_roles": "readonly", + "connection_url": "{{username}}/{{password}}@localhost:1521/OraDoc.localhost", + "max_open_connections": 5, + "max_connection_lifetime": "5s", + "username": "system", + "password": "Oracle" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/oracle +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(string: )` – Specifies the database + statements executed to create and configure a user. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}` and `{{password}}` values will be substituted. + +- `revocation_statements` `(string: "")` – Specifies the database statements to + be executed to revoke a user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The `{{name}}` value will be + substituted. If not provided defaults to a generic drop user statement. + +- `rotation_statements` `(list: [])` – Specifies the database statements to be + executed to rotate the password for a given username. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}` and `{{password}}` values will be substituted. The + generated password will be a random alphanumeric 20 character string. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/postgresql.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/postgresql.mdx new file mode 100644 index 0000000000..9ddfece16c --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/postgresql.mdx @@ -0,0 +1,222 @@ +--- +layout: api +page_title: PostgreSQL - Database - Secrets Engines - HTTP API +description: >- + The PostgreSQL plugin for Vault's database secrets engine generates database + credentials to access PostgreSQL servers. +--- + +# PostgreSQL database plugin HTTP API + +The PostgreSQL database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the PostgreSQL database. + +## Configure connection + +In addition to the parameters defined by the [Database +Backend](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `connection_url` `(string: )` - Specifies the PostgreSQL DSN. This field + can be templated and supports passing the username and password + parameters in the following format `{{field_name}}`. Certificate authentication + can be used by setting `?sslmode=` to be any of the applicable values as outlined in + the [Postgres SQL documentation](https://www.postgresql.org/docs/11/libpq-ssl.html#LIBPQ-SSL-PROTECTION) + and giving the SSL credentials in the `sslrootcert`, `sslcert` and `sslkey` credentials. + A templated connection URL is required when using root credential rotation. This field + supports both format string types, URI and keyword/value. Both formats support multiple + host connection strings. + Due to how `pgx` works, parameters such as `sslrootcert`, `sslcert`, `sslkey` are treated as paths + on the Vault server. + +- `max_open_connections` `(int: 4)` - Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of + time a connection may be reused. If <= `0s`, connections are reused forever. + +- `username` `(string: "")` - The root credential username used in the connection URL. + +- `password` `(string: "")` - The root credential password used in the connection URL. + +- `self_managed` `(boolean: "false")` - If + set, allows onboarding static roles with a rootless connection configuration. Mutually + exclusive with `username` and `password`. If set, will force `verify_connection` to be false. + +- `tls_ca` `(string: "")` - The x509 CA file for validating the certificate + presented by the PostgreSQL server. Must be PEM encoded. + +- `tls_certificate` `(string: "")` - The x509 client certificate for connecting + to the database. Must be PEM encoded. + +- `private_key` `(string: "")` - The secret key used for the x509 client + certificate. Must be PEM encoded. + +- `auth_type` `(string: "")` - If set to `gcp_iam`, will enable IAM authentication to a Google + CloudSQL instance. For more information on authenticating to CloudSQL via IAM, please refer to + Google's official documentation [here.](https://cloud.google.com/sql/docs/postgres/authentication). + +- `service_account_json` `(string: "")` - JSON encoded credentials for a GCP Service Account to use + for IAM authentication. Requires `auth_type` to be `gcp_iam`. + +- `use_private_ip` `(boolean: false)` - Enables the option to connect to CloudSQL Instances with Private IP. + Requires `auth_type` to be `gcp_iam`. + +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how + dynamic usernames are generated. + +- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username + and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping) + for more information. Defaults to `false`. + +- `password_authentication` `(string: "password")` - When set to "scram-sha-256", passwords will be hashed by Vault and stored as-is by PostgreSQL. + Using "scram-sha-256" requires a minimum version of PostgreSQL 10. Available options are "scram-sha-256" and "password". The default is "password". + When set to "password", passwords will be sent to PostgreSQL in plaintext format and may appear in PostgreSQL logs as-is. + For more information, please refer to the [PostgreSQL documentation](https://www.postgresql.org/docs/current/sql-createrole.html#password). + + +
+Default Username Template + +``` +{{ printf "v-%s-%s-%s-%s" (.DisplayName | truncate 8) (.RoleName | truncate 8) (random 20) (unix_time) | truncate 63 }} +``` + +
+Example Usernames: + +| Example | | +| ------------- | -------------------------------------------------- | +| `DisplayName` | `token` | +| `RoleName` | `myrolename` | +| Username | `v-token-myrolena-jNFRlKsZZMxJEx60o66i-1614294836` | + +| Example | | +| ------------- | ----------------------------------------------------- | +| `DisplayName` | `amuchlonger_dispname` | +| `RoleName` | `role-name-with-dashes` | +| Username | `v-amuchlon-role-nam-LUHU9xqm6YNisikA3iCQ-1614294836` | + +
+
+ +### Sample payload with URI-format connection string + +```json +{ + "plugin_name": "postgresql-database-plugin", + "allowed_roles": "readonly", + "connection_url": "postgresql://{{username}}:{{password}}@localhost:5432/postgres", + "max_open_connections": 5, + "max_connection_lifetime": "5s", + "username": "username", + "password": "password" +} +``` + +### Sample payload with Keyword/Value-format connection string + +```json +{ + "plugin_name": "postgresql-database-plugin", + "allowed_roles": "readonly", + "connection_url": "host=localhost port=5432 user={{username}} password={{password}}", + "max_open_connections": 5, + "max_connection_lifetime": "5s", + "username": "username", + "password": "password" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/postgresql +``` + +### Connection strings with multiple hosts + +Postgres supports multiple hosts in the connection string. An example use-case for this might be having +Postgres set up with Replication Manager. However, there are some formatting rules to consider when using +this feature. Please refer to the ["Specifying Multiple Hosts" section of the +official Postgres documentation](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) +for more information. Below are two small examples. + +#### URI-format Multi-Host string: + +```json +{ + "connection_url": "postgresql://{{username}}:{{password}}@hostone:5432,hosttwo:5432,hostthree:9999/postgres" +} +``` + +#### Keyword/Value-format Multi-Host string: + +```json +{ + "connection_url": "host=hostone,hosttwo,hostthree port=5432,5432,9999 user={{username}} password={{password}} dbname=postgres" +} +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(list: )` – Specifies the database + statements executed to create and configure a user. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}`, `{{password}}` and `{{expiration}}` values will be + substituted. The generated password will be a random alphanumeric 20 character + string. + +- `revocation_statements` `(list: [])` – Specifies the database statements to + be executed to revoke a user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The `{{name}}` value will be + substituted. If not provided defaults to a generic drop user statement. + +- `rollback_statements` `(list: [])` – Specifies the database statements to be + executed rollback a create operation in the event of an error. Not every + plugin type will support this functionality. Must be a semicolon-separated + string, a base64-encoded semicolon-separated string, a serialized JSON string + array, or a base64-encoded serialized JSON string array. The `{{name}}` value + will be substituted. + +- `renew_statements` `(list: [])` – Specifies the database statements to be + executed to renew a user. Not every plugin type will support this + functionality. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The `{{name}}` and + `{{expiration}}` values will be substituted. + +- `rotation_statements` `(list: [])` – Specifies the database statements to be + executed to rotate the password for a given username. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}` and `{{password}}` values will be substituted. The + generated password will be a random alphanumeric 20 character string. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/redis.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/redis.mdx new file mode 100644 index 0000000000..2f8c2980ae --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/redis.mdx @@ -0,0 +1,76 @@ +--- +layout: api +page_title: Redis - Database - Secrets Engines - HTTP API +description: >- + The Redis plugin for Vault's database secrets engine generates [ACL credentials](https://redis.io/docs/manual/security/acl/) + to access Redis servers. +--- + +# Redis database plugin HTTP API + +The Redis database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the Redis database. + +## Configure connection + +In addition to the parameters defined by the [Database +Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `host` `(string: )` – Specifies the host to connect to. + +- `port` `(int: )` – Specifies the port number of the connection. + +- `username` `(string: )` – Specifies the username for Vault to use. + +- `password` `(string: )` – Specifies the password corresponding to the given username. + +- `tls` `(bool: false)` – Specifies whether to use TLS when connecting to Redis. + +- `insecure_tls` `(bool: false)` – Specifies whether to skip verification of the +server certificate when using TLS. + +### Sample payload + +```json +{ + "plugin_name": "redis-database-plugin", + "host": "localhost://127.0.0.1", + "username": "user", + "password": "pass", + "allowed-roles": "my-*-role" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/redis +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(list: [])` – Specifies a JSON string containing +[Redis ACL rules](https://redis.io/commands/acl-cat) to assign to created users. If not provided, defaults to +a read-only user that can read any key. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/rediselasticache.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/rediselasticache.mdx new file mode 100644 index 0000000000..bc58dfae65 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/rediselasticache.mdx @@ -0,0 +1,64 @@ +--- +layout: api +page_title: Redis ElastiCache - Database - Secrets Engines - HTTP API +description: >- + The Redis ElastiCache plugin for Vault's database secrets engine generates new passwords for ElastiCache users. +--- + +# Redis ElastiCache database plugin HTTP API + +The Redis ElastiCache database plugin is one of the supported plugins for the database +secrets engine. This plugin generates static database credentials based on +configured roles for the Redis ElastiCache database. + +## Configure connection + +In addition to the parameters defined by the [Database +Secrets Engine](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `url` `(string: )` – Specifies the primary endpoint to connect to. + +- `access_key_id` `(string)` – Specifies the IAM `access_key_id` for Vault to use. If omitted, authentication falls back on +the AWS credentials provider chain and tries to infer authentication from the environment. + +- `secret_access_key` `(string)` – Specifies the IAM `secret_access_key` corresponding to the given `access_key_id`. +If omitted, authentication falls back on the AWS credentials provider chain and tries to infer authentication from the environment. + +- `region` `(string)` – Specifies the AWS region where to ElastiCache cluster is provisioned. If omitted, falls back on +the context from the environment. + +### Deprecated parameters + +- `username` `(string)` – Use `access_key_id` instead, it is strictly equivalent. + +- `password` `(string)` – Use `secret_access_key` instead, it is strictly equivalent. + +### Sample payload + +```json +{ + "plugin_name": "redis-elasticache-database-plugin", + "url": "primary-endpoint.my-cluster.xxx.yyy.cache.amazonaws.com:6379", + "access_key_id": "AKI***", + "secret_access_key": "ktriNYvULAWLzUmTGb***", + "region": "us-east-1", + "allowed-roles": "*" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/my-redis-cluster +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/redshift.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/redshift.mdx new file mode 100644 index 0000000000..4ad6de87a4 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/redshift.mdx @@ -0,0 +1,122 @@ +--- +layout: api +page_title: Redshift - Database - Secrets Engines - HTTP API +description: >- + The Redshift plugin for Vault's database secrets engine generates database + credentials to access the AWS Redshift service. +--- + +# Redshift database plugin HTTP API + +The Redshift database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the Redshift database. + +## Configure connection + +In addition to the parameters defined by the [Database +Backend](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `connection_url` `(string: )` - Specifies the Redshift DSN. This field + can be templated and supports passing the username and password + parameters in the following format `{{field_name}}`. A templated connection URL is + required when using root credential rotation. + +- `max_open_connections` `(int: 4)` - Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of + time a connection may be reused. If <= `0s` connections are reused forever. + +- `username` `(string: "")` - The root credential username used in the connection URL. + +- `password` `(string: "")` - The root credential password used in the connection URL. + +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how dynamic usernames are generated. + +- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username + and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping) + for more information. Defaults to `false`. + +### Sample payload + +```json +{ + "plugin_name": "redshift-database-plugin", + "allowed_roles": "readonly", + "connection_url": "postgresql://{{username}}:{{password}}@localhost:5432/dev", + "max_open_connections": 5, + "max_connection_lifetime": "5s", + "username": "username", + "password": "password" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/redshift +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(list: )` – Specifies the database + statements executed to create and configure a user. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}`, `{{password}}` and `{{expiration}}` values will be + substituted. The generated password will be a random alphanumeric 20 character + string. + +- `revocation_statements` `(list: [])` – Specifies the database statements to + be executed to revoke a user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The `{{name}}` value will be + substituted. If not provided defaults to a generic drop user statement. + +- `rollback_statements` `(list: [])` – Specifies the database statements to be + executed rollback a create operation in the event of an error. Not every + plugin type will support this functionality. Must be a semicolon-separated + string, a base64-encoded semicolon-separated string, a serialized JSON string + array, or a base64-encoded serialized JSON string array. The `{{name}}` value + will be substituted. + +- `renew_statements` `(list: [])` – Specifies the database statements to be + executed to renew a user. Not every plugin type will support this + functionality. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The `{{name}}` and + `{{expiration}}` values will be substituted. + +- `rotation_statements` `(list: [])` – Specifies the database statements to be + executed to rotate the password for a given username. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}` and `{{password}}` values will be substituted. The + generated password will be a random alphanumeric 20 character string. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/snowflake.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/snowflake.mdx new file mode 100644 index 0000000000..e5cc3732d4 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/databases/snowflake.mdx @@ -0,0 +1,157 @@ +--- +layout: api +page_title: Snowflake - Database - Secrets Engines - HTTP API +description: >- + The Snowflake plugin for Vault's database secrets engine generates database + credentials to access Snowflake servers. +--- + +# Snowflake database plugin HTTP API + + + + [Snowflake is disabling password authentication for all users](https://www.snowflake.com/en/blog/blocking-single-factor-password-authentification) in + November of 2025. HashiCorp has added support for key pair authentication in + place of passwords. + + Vault currently does not support rotate root for key pairs. To manually rotate + key pairs, users can: + + - update the root configuration in Vault with the new private key + - update the public key associated with the user in Snowflake + + For more information on rotating key pairs, please refer to the official + [Snowflake documentation](https://docs.snowflake.com/en/user-guide/key-pair-auth#configuring-key-pair-rotation). + + + +The Snowflake database plugin is one of the supported plugins for the database +secrets engine. This plugin generates database credentials dynamically based on +configured roles for the Snowflake database. + +## Configure connection + +In addition to the parameters defined by the [Database +Backend](/vault/api-docs/secret/databases#configure-connection), this plugin +has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/database/config/:name` | + +### Parameters + +- `connection_url` `(string: )` - Specifies the Snowflake DSN. This field + can be templated and supports passing the username and password + parameters in the format `{{field_name}}` when you use password authentication. + If you use root credential rotation for passwords, you must provide a templated + connection URL. Refer to the + [Snowflake secrets engine docs](/vault/docs/secrets/databases/snowflake#setup) + for more information on the connection URL format requirements for different + authentication methods. + +- `max_open_connections` `(int: 4)` - Specifies the maximum number of open + connections to the database. + +- `max_idle_connections` `(int: 0)` - Specifies the maximum number of idle + connections to the database. A zero uses the value of `max_open_connections` + and a negative value disables idle connections. If larger than + `max_open_connections` it will be reduced to be equal. + +- `max_connection_lifetime` `(string: "0s")` - Specifies the maximum amount of + time clients can reuse a connection. Set the lifetime to `0s` to make a + connection reusable forever. Snowflake uses a default session policy of 4 hours unless you [change the session policy definition](https://docs.snowflake.com/en/user-guide/session-policies#session-policies). + +- `username` `(string: "")` - The root credential username used in the connection URL. + +- `password` `(string: "")` - **Deprecated** The root credential password used in the connection URL. + +- `private_key` `(string: "")` - The root credential + [PEM-encoded private key](https://docs.snowflake.com/en/user-guide/key-pair-auth) + for the associated Snowflake user. + +- `username_template` `(string)` - [Template](/vault/docs/concepts/username-templating) describing how dynamic usernames are generated. + +- `disable_escaping` `(boolean: false)` - Turns off the escaping of special characters inside of the username + and password fields. See the [databases secrets engine docs](/vault/docs/secrets/databases#disable-character-escaping) + for more information. Defaults to `false`. + +### Sample payload + +```json +{ + "plugin_name": "snowflake-database-plugin", + "allowed_roles": "readonly", + "connection_url": "{{username}}:{{password}}@ecxxxx.west-us-1.azure/db_name", + "max_open_connections": 5, + "max_connection_lifetime": "5s", + "username": "username", + "private_key": "aPrivateKey" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/database/config/snowflake +``` + +## Statements + +Statements are configured during role creation and are used by the plugin to +determine what is sent to the database on user creation, renewing, and +revocation. For more information on configuring roles see the [Role +API](/vault/api-docs/secret/databases#create-role) in the database secrets engine docs. + +### Parameters + +The following are the statements used by this plugin. If not mentioned in this +list the plugin does not support that statement type. + +- `creation_statements` `(list: )` – Specifies the database + statements executed to create and configure a user. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}` and `{{expiration}}` values will be substituted. + + The following values will be substituted depending on the + [credential_type](/vault/api-docs/secret/databases#credential_type) of the role: + + - `{{password}}` is substituted for the `password` credential type + - `{{public_key}}` is substituted for the `rsa_private_key` credential type + +- `revocation_statements` `(list: [])` – Specifies the database statements to + be executed to revoke a user. Must be a semicolon-separated string, a + base64-encoded semicolon-separated string, a serialized JSON string array, or + a base64-encoded serialized JSON string array. The `{{name}}` value will be + substituted. If not provided defaults to a generic drop user statement. + +- `rollback_statements` `(list: [])` – Specifies the database statements to be + executed rollback a create operation in the event of an error. Not every + plugin type will support this functionality. Must be a semicolon-separated + string, a base64-encoded semicolon-separated string, a serialized JSON string + array, or a base64-encoded serialized JSON string array. The `{{name}}` value + will be substituted. + +- `renew_statements` `(list: [])` – Specifies the database statements to be + executed to renew a user. Not every plugin type will support this + functionality. Must be a semicolon-separated string, a base64-encoded + semicolon-separated string, a serialized JSON string array, or a + base64-encoded serialized JSON string array. The `{{name}}` and + `{{expiration}}` values will be substituted. + +- `rotation_statements` `(list: [])` – Specifies the database statements to be + executed to rotate the password for a given username. Must be a + semicolon-separated string, a base64-encoded semicolon-separated string, a + serialized JSON string array, or a base64-encoded serialized JSON string + array. The `{{name}}` value will be substituted. + + The following values will be substituted depending on the + [credential_type](/vault/api-docs/secret/databases#credential_type) of the role: + + - `{{password}}` is substituted for the `password` credential type + - `{{public_key}}` is substituted for the `rsa_private_key` credential type diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/gcp.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/gcp.mdx new file mode 100644 index 0000000000..376b5f832c --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/gcp.mdx @@ -0,0 +1,783 @@ +--- +layout: api +page_title: Google Cloud - Secrets Engines - HTTP API +description: This is the API documentation for the Vault Google Cloud secrets engine. +--- + +# Google Cloud secrets engine (API) + +This is the API documentation for the Vault Google Cloud Platform (GCP) +secrets engine. For general information about the usage and operation of +the GCP secrets engine, please see [these docs](/vault/docs/secrets/gcp). + +This documentation assumes the GCP secrets engine is enabled at the `/gcp` path +in Vault. Since it is possible to mount secrets engines at any path, please +update your API calls accordingly. + +## Write config + +Use the endpoint to configure shared information for the secrets engine. You can configure +credentials for a privileged service account either with Application Credentials or using +Plugin Workload Identity Federation (WIF). + +### IAM +Vault uses the official Google Cloud SDK to source credentials from environment +variables and shared files. + +From the highest precedence to lowest, you can pass root credentials to the Vault +server in the following ways: + +1. Provide static credentials to the API as a payload. + +1. Use [plugin workload identity federation](/vault/docs/secrets/gcp#plugin-workload-identity-federation-wif) +credentials. + +1. Set [application default credentials](https://cloud.google.com/docs/authentication/application-default-credentials) +as environment variables on the Vault server. + +1. Define credentials in shared credential files. + + + Passing Vault new root credential overwrites any preexisting root credentials. + + +| Method | Path | +| :----- | :------------ | +| `POST` | `/gcp/config` | + + +### Parameters + +- `credentials` (`string:""`) - JSON credentials (either file contents or '@path/to/file') + See docs for [alternative ways](/vault/docs/secrets/gcp#setup) + to pass in to this parameter, as well as the + [required permissions](/vault/docs/secrets/gcp#required-permissions). Mutually exclusive with `identity_token_audience`. + +@include 'rotationfields.mdx' + +- `service_account_email` `(string: "")` – Service Account +to impersonate for plugin workload identity federation. Required with `identity_token_audience`. + +- `identity_token_audience` `(string: "")` - The +audience claim value for plugin identity tokens. Must match an allowed audience configured +for the target [Workload Identity Pool](https://cloud.google.com/iam/docs/workload-identity-federation-with-other-providers#prepare). +Mutually exclusive with `credentials`. + +- `identity_token_ttl` `(string/int: 3600)` - The +TTL of generated tokens. Defaults to 1 hour. Uses [duration format strings](/vault/docs/concepts/duration-format). + +- `ttl` (`int: 0 || string:"0s"`) – Specifies default config TTL for long-lived credentials + (i.e. service account keys). Uses [duration format strings](/vault/docs/concepts/duration-format). + +- `max_ttl` (`int: 0 || string:"0s"`)– Specifies the maximum config TTL for long-lived credentials + (i.e. service account keys). Uses [duration format strings](/vault/docs/concepts/duration-format).\*\* + +### Sample payload + +```json +{ + "credentials": "", + "ttl": 3600, + "max_ttl": 14400 +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcp/config +``` + +## Rotate root credentials + +Request to rotate the GCP service account credentials used by Vault +for this mount. A new key will be generated for the service account, +replacing the internal value, and then a deletion of the old service +account key is scheduled. Note that this does not create a new service +account, only a new version of the service account key. + +This path is only valid if Vault has been configured to use GCP credentials via +the `config/` endpoint where "credentials" were specified. Additionally, the +provided service account must have permissions to create and delete service +account keys. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `/gcp/config/rotate-root` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://127.0.0.1:8200/v1/gcp/config/rotate-root +``` + +## Read config + +| Method | Path | +| :----- | :------------ | +| `GET` | `/gcp/config` | + +Credentials will be omitted from returned data. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/gcp/config +``` + +### Sample response + +```json +{ + "data": { + "ttl": "1h", + "max_ttl": "4h" + } +} +``` + +## Create/Update roleset + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/gcp/roleset/:name` | + +This method allows you to create a roleset or update an existing roleset. See [docs](/vault/docs/secrets/gcp#bindings) for the GCP secrets backend +to learn more about what happens when you create or update a roleset. + +**If you update a roleset's bindings, this will effectively revoke any secrets +generated under this roleset.** + +### Parameters + +- `name` (`string: `): Required. Name of the role. Cannot be updated. +- `secret_type` (`string: "access_token"`): Type of secret generated for this role set. Accepted values: `access_token`, `service_account_key`. Cannot be updated. +- `project` (`string: `): Name of the GCP project that this roleset's service account will belong to. Cannot be updated. +- `bindings` (`string: `): Bindings configuration string (expects HCL or JSON format in raw or base64-encoded string) +- `token_scopes` (`array: []`): List of OAuth scopes to assign to `access_token` secrets generated under this role set (`access_token` role sets only) + +### Sample payload + +```json +{ + "secret_type": "access_token", + "project": "mygcpproject", + "bindings": "...", + "token_scopes": [ + "https://www.googleapis.com/auth/cloud-platform", + "https://www.googleapis.com/auth/bigquery" + ] +} +``` + +#### Sample bindings: + +See [bindings format docs](/vault/docs/secrets/gcp#bindings) for more information. + +```hcl +resource "//cloudresourcemanager.googleapis.com/projects/mygcpproject" { + roles = [ + "roles/viewer" + ], +} + +resource "//bigquery.googleapis.com/projects/my-project/datasets/mydataset" { + roles = [ + "roles/bigquery.dataViewer" + ], +} + +resource "https://selflink/to/my/resource" { + roles = [ + "project/mygcpproject/roles/projcustomrole", + "organizations/myorg/roles/orgcustomrole" + ], +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset +``` + +## Rotate roleset account + +| Method | Path | | +| :----- | :-------------------------- | ------------------ | +| `POST` | `/gcp/roleset/:name/rotate` | `204 (empty body)` | + +This will rotate the service account this roleset uses to generate secrets. +(this also replaces the key `access_token` roleset). This can be used to invalidate +old secrets generated by the roleset or fix issues if a roleset's service account +(and/or keys) was changed outside of Vault (i.e. through GCP APIs/cloud console). + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset/rotate +``` + +## Rotate roleset account key (`access_token` roleset only) + +| Method | Path | | +| :----- | :------------------------------ | ------------------ | +| `POST` | `/gcp/roleset/:name/rotate-key` | `204 (empty body)` | + +This will rotate the service account key this roleset uses to generate +access tokens. This does not recreate the roleset service account. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset/rotate-key +``` + +## Read roleset + +| Method | Path | +| :----- | :------------------- | +| `GET` | `/gcp/roleset/:name` | + +### Parameters + +- `name` (`string:`): Name of the roleset to read. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset +``` + +### Sample response + +```json +{ + "data": { + "secret_type": "access_token", + "service_account_email": "vault-myroleset-XXXXXXXXXX@myproject.gserviceaccounts.com", + "service_account_project": "service-account-project", + "bindings": { + "project/mygcpproject": ["roles/viewer"], + "https://selflink/to/my/resource": [ + "project/mygcpproject/roles/projcustomrole", + "organizations/myorg/roles/orgcustomrole" + ] + }, + "token_scopes": ["https://www.googleapis.com/auth/cloud-platform"] + } +} +``` + +## List rolesets + +| Method | Path | +| :----- | :-------------- | +| `LIST` | `/gcp/rolesets` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/gcp/rolesets +``` + +### Sample response + +```json +{ + "data": { + "keys": ["my-token-roleset", "my-sakey-roleset"] + } +} +``` + +## Delete roleset + +This endpoint deletes an existing roleset by the given name. + +| Method | Path | +| :------- | :------------------- | +| `DELETE` | `/gcp/roleset/:name` | + +### Parameters + +- `name` (`string:`): Name of the roleset to delete. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset +``` + +## Create/Update static account + +| Method | Path | +| :----- | :-------------------------- | +| `POST` | `/gcp/static-account/:name` | + +This method allows you to create a static account or update an existing static account. See [docs](/vault/docs/secrets/gcp#bindings) for the GCP secrets backend +to learn more about what happens when you create or update a static account. + +**If you update a static account's bindings, this will effectively revoke any secrets +generated under this static account.** + +### Parameters + +- `name` (`string: `): Name of the static account. Cannot be updated. +- `secret_type` (`string: "access_token"`): Type of secret generated for this static account. Accepted values: `access_token`, `service_account_key`. Cannot be updated. +- `service_account_email` (`string: `): Email of the GCP service account to manage. Cannot be updated. +- `bindings` (`string`): Bindings configuration string (expects HCL or JSON format in raw or base64-encoded string). Optional. +- `token_scopes` (`array: []`): List of OAuth scopes to assign to `access_token` secrets generated under this static account (`access_token` static accounts only) + +### Sample payload + +```json +{ + "secret_type": "access_token", + "service_account_email": "example@mygcpproject.iam.gserviceaccount.com", + "bindings": "...", + "token_scopes": [ + "https://www.googleapis.com/auth/cloud-platform", + "https://www.googleapis.com/auth/bigquery" + ] +} +``` + +#### Sample bindings: + +See [bindings format docs](/vault/docs/secrets/gcp#bindings) for more information. + +```hcl +resource "//cloudresourcemanager.googleapis.com/projects/mygcpproject" { + roles = [ + "roles/viewer" + ], +} + +resource "//bigquery.googleapis.com/projects/my-project/datasets/mydataset" { + roles = [ + "roles/bigquery.dataViewer" + ], +} + +resource "https://selflink/to/my/resource" { + roles = [ + "project/mygcpproject/roles/projcustomrole", + "organizations/myorg/roles/orgcustomrole" + ], +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcp/static-account/my-token-account +``` + +## Rotate static account key (`access_token` static account only) + +| Method | Path | | +| :----- | :------------------------------ | ------------------------- | +| `POST` | `/gcp/static-account/:name/rotate-key` | `204 (empty body)` | + +This will rotate the service account key this static account uses to generate +access tokens. This does not recreate the service account. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://127.0.0.1:8200/v1/gcp/static-account/my-token-account/rotate-key +``` + +## Read static account + +| Method | Path | +| :----- | :-------------------------- | +| `GET` | `/gcp/static-account/:name` | + +### Parameters + +- `name` (`string:`): Name of the static account to read. + +This endpoint will only return bindings that are managed through the secrets engine. Bindings +manually managed outside of Vault will not be returned. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/gcp/static-account/my-token-account +``` + +### Sample response + +```json +{ + "data": { + "secret_type": "access_token", + "service_account_email": "example@mygcpproject.iam.gserviceaccount.com", + "service_account_project": "mygcpproject", + "bindings": { + "project/mygcpproject": ["roles/viewer"], + "https://selflink/to/my/resource": [ + "project/mygcpproject/roles/projcustomrole", + "organizations/myorg/roles/orgcustomrole" + ] + }, + "token_scopes": ["https://www.googleapis.com/auth/cloud-platform"] + } +} +``` + +## List static accounts + +| Method | Path | +| :----- | :--------------------- | +| `LIST` | `/gcp/static-accounts` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/gcp/static-accounts +``` + +### Sample response + +```json +{ + "data": { + "keys": ["my-token-account", "my-sakey-account"] + } +} +``` + +## Delete static account + +This endpoint deletes an existing static account by the given name. + +| Method | Path | +| :------- | :-------------------------- | +| `DELETE` | `/gcp/static-account/:name` | + +### Parameters + +- `name` (`string:`): Name of the static account to delete. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/gcp/static-account/my-token-account +``` + +## Create/Update impersonated account + +| Method | Path | +| :----- | :-------------------------------- | +| `POST` | `/gcp/impersonated-account/:name` | + +This method allows you to create an impersonated account or update an existing +impersonated account. + +### Parameters + +- `name` (`string: `): Name of the impersonated account. Cannot be updated. +- `service_account_email` (`string: `): Email of the GCP service account to + manage. Cannot be updated. +- `token_scopes` (`array: []`): List of OAuth scopes to assign to access tokens + generated under this impersonation account. +- `ttl` (`duration: ""`): Lifetime of the token generated. Defaults to 1 hour and + is limited to a maximum of 12 hours. Uses [duration format strings](/vault/docs/concepts/duration-format). + +### Sample payload + +```json +{ + "service_account_email": "projectOwner@my-project.iam.gserviceaccount.com", + "token_scopes": [ + "https://www.googleapis.com/auth/cloud-platform", + "https://www.googleapis.com/auth/bigquery" + ], + "ttl": "2h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcp/impersonated-account/my-token-impersonate +``` + +## Read impersonated account + +| Method | Path | +| :----- | :-------------------------------- | +| `GET` | `/gcp/impersonated-account/:name` | + +### Parameters + +- `name` (`string:`): Name of the impersonated account to read. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/gcp/impersonated-account/my-token-impersonate +``` + +### Sample response + +```json +{ + "data": { + "service_account_email": "projectOwner@my-project.iam.gserviceaccount.com", + "service_account_project": "my-project", + "token_scopes": [ + "https://www.googleapis.com/auth/cloud-platform", + "https://www.googleapis.com/auth/bigquery" + ], + "ttl": 7200 + }, +} +``` +## List impersonated accounts + +This endpoint lists the configured Vault roles for impersonated accounts. + +| Method | Path | +| :----- | :--------------------- | +| `LIST` | `/gcp/impersonated-accounts` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/gcp/impersonated-accounts +``` + +### Sample response + +```json +{ + "data": { + "keys": [ + "my-token-impersonate", + "secondary-role" + ] + } +} +``` + +## Delete impersonated account + +This endpoint deletes an existing impersonated account by the given name. + +| Method | Path | +| :------- | :-------------------------------- | +| `DELETE` | `/gcp/impersonated-account/:name` | + +### Parameters + +- `name` (`string:`): Name of the impersonated account to delete. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/gcp/impersonated-account/my-token-impersonate +``` + +## Generate secret (IAM service account creds): OAuth2 access token + +| Method | Path | +| :------------- | :------------------------------------------------------ | +| `GET` / `POST` | `/gcp/roleset/:roleset/token` | +| `GET` / `POST` | `/gcp/static-account/:static-account/token` | +| `GET` / `POST` | `/gcp/impersonated-account/:impersonated-account/token` | +| `GET` / `POST` | `/gcp/token/:roleset` (deprecated) | + +Generates an OAuth2 token with the scopes defined on the roleset, static +account, or impersonated account. This OAuth access token can +be used in GCP API calls, e.g. `curl -H "Authorization: Bearer $TOKEN" ...` + +Tokens are non-revocable and non-renewable and have a static TTL of an hour. The TTL configured +for the backend (either through the default system TTLs or through the `config/` endpoint) +do not apply. + +### Parameters + +- `roleset` (`string:`): Name of an roleset with secret type `access_token` to generate access_token under. +- `static-account` (`string:`): Name of the static account with secret type `access_token` to generate access_token under. +- `impersonated-account` (`string:`): Name of the impersonated account to + generate access_token_under. + +### Sample request + +**Roleset:** +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/gcp/roleset/my-token-roleset/token +``` + +**Static account:** +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/gcp/static-account/my-token-account/token +``` + +**Impersonated account:** +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/gcp/impersonated-account/my-token-impersonate/token +``` + +### Sample response + +```json +{ + "request_id": "", + "data": { + "token": "ya29.c.Elp5Be3ga87...", + "expires_at_seconds": 1537400046, + "token_ttl": 3599 + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Generate secret (IAM service account creds): service account key + +| Method | Path | +| :------------- | :---------------------------------------- | +| `GET` / `POST` | `/gcp/roleset/:roleset/key` | +| `GET` / `POST` | `/gcp/static-account/:static-account/key` | +| `GET` / `POST` | `/gcp/key/:roleset` (deprecated) | + + +If using `GET` ('read'), the optional parameters will be set to their defaults. Use `POST` if you +want to specify different values for these params. + +These keys are renewable and have TTL/max TTL as defined by either the backend config +or the system default if config was not defined. + +### Parameters + +- `roleset` (`string:`): Name of an roleset with secret type `service_account_key` to generate key under. +- `static-account` (`string:`): Name of an static account with secret type `service_account_key` to generate key under. +- `key_algorithm` (`string:"KEY_ALG_RSA_2048"`): Key algorithm used to generate key. Defaults to 2k RSA key + You probably should not choose other values (i.e. 1k), but accepted values are + `enum(`[`ServiceAccountKeyAlgorithm`](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts.keys#ServiceAccountKeyAlgorithm)`)` +- `key_type` (`string:"TYPE_GOOGLE_CREDENTIALS_FILE`): Private key type to generate. Defaults to JSON credentials file. + Accepted values are `enum(`[`ServiceAccountPrivateKeyType`](https://cloud.google.com/iam/reference/rest/v1/projects.serviceAccounts.keys#ServiceAccountPrivateKeyType)`)` +- `ttl` (`string: ""`): Specifies the Time To Live value provided using a [duration format string](/vault/docs/concepts/duration-format). If not set, uses the system default value. + +### Sample payload + +```json +{ + "key_algorithm": "KEY_ALG_RSA_2048", + "key_type": "TYPE_GOOGLE_CREDENTIALS_FILE" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/gcp/roleset/my-key-roleset/key +``` + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcp/roleset/my-key-roleset/key +``` + +### Sample response + +```json +{ + "request_id": "", + "lease_id": "gcp/roleset/my-key-roleset/key/", + "renewable": true, + "lease_duration": 3600, + "data": { + "private_key_data": "", + "key_algorithm": "TYPE_GOOGLE_CREDENTIALS_FILE", + "key_type": "KEY_ALG_RSA_2048" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Revoking/Renewing secrets + +See docs on how to [renew](/vault/api-docs/system/leases#renew-lease) and [revoke](/vault/api-docs/system/leases#revoke-lease) leases. +Note this only applies to service account keys. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/gcpkms.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/gcpkms.mdx new file mode 100644 index 0000000000..c2e172f5c1 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/gcpkms.mdx @@ -0,0 +1,878 @@ +--- +layout: api +page_title: Google Cloud KMS - Secrets Engines - HTTP API +description: This is the API documentation for the Vault Google Cloud KMS secrets engine. +--- + +# Google Cloud KMS secrets engine (API) + +This is the API documentation for the Vault Google Cloud KMS secrets engine. For +general information about the usage and operation of the Google Cloud KMS +secrets engine, please see the +[Google Cloud KMS documentation](/vault/docs/secrets/gcpkms). + +This documentation assumes the Google Cloud KMS secrets engine is enabled at the +`/gcpkms` path in Vault. Since it is possible to enable secrets engines at any +location, please update your API calls accordingly. + +## Configure credentials + +This endpoint configures the Google Cloud KMS secrets engine with credentials +and manages the requested scope(s) for authentication. + +| Method | Path | +| :----- | :-------------- | +| `POST` | `gcpkms/config` | + +### Example policy + +```hcl +path "gcpkms/config" { + capabilities = ["create", "update"] +} +``` + +### Parameters + +- `credentials` (`string: ""`) - + The credentials to use for authenticating to Google Cloud. Leave this blank to + use the Default Application Credentials or instance metadata authentication. + +- `scopes` (`array: []`) - + The list of full-URL scopes to request when authenticating. By default, this + requests https://www.googleapis.com/auth/cloudkms. + +### Sample payload + +```json +{ + "credentials": "< JSON credentials... >" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcpkms/config +``` + +## Read configuration + +This endpoint returns the configuration endpoint for the Google Cloud KMS +secrets engine. The credentials are not returned. + +| Method | Path | +| :----- | :-------------- | +| `GET` | `gcpkms/config` | + +### Example policy + +```hcl +path "gcpkms/config" { + capabilities = ["read"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/gcpkms/config +``` + +### Sample response + +```json +{ + "data": { + "scopes": ["https://www.googleapis.com/auth/cloudkms"] + } +} +``` + +## Delete configuration + +This endpoint deletes any configuration for the Google Cloud KMS secrets engine. +If there is no configuration, the endpoint still returns successfully. + +| Method | Path | +| :------- | :-------------- | +| `DELETE` | `gcpkms/config` | + +### Example policy + +```hcl +path "gcpkms/config" { + capabilities = ["delete"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/gcpkms/config +``` + +## Decrypt ciphertext + +This endpoint uses the named encryption key to decrypt the ciphertext string. For symmetric key types, the provided ciphertext must come from a previous invocation of the `/encrypt` endpoint. For asymmetric key types, the provided ciphertext must be from the encrypt operation against the corresponding key version's public key. + +| Method | Path | +| :----- | :-------------------- | +| `POST` | `gcpkms/decrypt/:key` | + +### Example policy + +```hcl +path "gcpkms/decrypt/my-key" { + capabilities = ["create", "update"] +} +``` + +### Parameters + +- `key` (`string: ""`) - + Name of the key in Vault to use for decryption. This key must already exist in + Vault and must map back to a Google Cloud KMS key. + This is specified as part of the URL. + +- `additional_authenticated_data` (`string: ""`) - + Optional data that was specified during encryption of this payload. + +- `ciphertext` (`string: ""`) - + Ciphertext to decrypt as previously returned from an encrypt operation. This + must be base64-encoded ciphertext as previously returned from an encrypt + operation. + +- `key_version` (`int: 0`) - + Integer version of the crypto key version to use for decryption. This is + required for asymmetric keys. For symmetric keys, Cloud KMS will choose the + correct version automatically. + +### Sample payload + +```json +{ + "ciphertext": "CiQAuMv0..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcpkms/decrypt/my-key +``` + +### Sample response + +```json +{ + "data": { + "plaintext": "hello world" + } +} +``` + +## Encrypt plaintext + +This endpoint uses the named encryption key to encrypt arbitrary plaintext +string data. The response will be base64-encoded encrypted ciphertext. + +| Method | Path | +| :----- | :-------------------- | +| `POST` | `gcpkms/encrypt/:key` | + +### Example policy + +```hcl +path "gcpkms/encrypt/my-key" { + capabilities = ["create", "update"] +} +``` + +### Parameters + +- `key` (`string: ""`) - + Name of the key in Vault to use for encryption. This key must already exist in + Vault and must map back to a Google Cloud KMS key. + This is specified as part of the URL. + +- `additional_authenticated_data` (`string: ""`) - + Optional base64-encoded data that, if specified, must also be provided to + decrypt this payload. + +- `key_version` (`int: 0`) - + Integer version of the crypto key version to use for encryption. If unspecified, + this defaults to the latest active crypto key version. + +- `plaintext` (`string: ""`) - + Plaintext value to be encrypted. This can be a string or binary, but the size + is limited. See the Google Cloud KMS documentation for information on size + limitations by key types. + +### Sample payload + +```json +{ + "plaintext": "hello world" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcpkms/encrypt/my-key +``` + +### Sample response + +```json +{ + "data": { + "ciphertext": "CiQAuMv0...", + "key_version": "1" + } +} +``` + +## Re-Encrypt existing ciphertext + +This endpoint uses the named encryption key to re-encrypt the underlying +cryptokey to the latest version for this ciphertext without disclosing the +original plaintext value to the requestor. This is similar to "rewrapping" in +Vault's transit secrets engine. + +| Method | Path | +| :----- | :---------------------- | +| `POST` | `gcpkms/reencrypt/:key` | + +### Example policy + +```hcl +path "gcpkms/reencrypt/my-key" { + capabilities = ["create", "update"] +} +``` + +### Parameters + +- `key` (`string: ""`) - + Name of the key to use for encryption. This key must already exist in Vault and + Google Cloud KMS. + This is specified as part of the URL. + +- `additional_authenticated_data` (`string: ""`) - + Optional data that, if specified, must also be provided during decryption. + +- `ciphertext` (`string: ""`) - + Ciphertext to be re-encrypted to the latest key version. This must be ciphertext + that Vault previously generated for this named key. + +- `key_version` (`int: 0`) - + Integer version of the crypto key version to use for re-encryption. If unspecified, + this defaults to the latest active crypto key version. + +### Sample payload + +```json +{ + "ciphertext": "CiQAuMv0..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcpkms/reencrypt/my-key +``` + +### Sample response + +```json +{ + "data": { + "ciphertext": "0lX848IG...", + "key_version": "3" + } +} +``` + +## Sign digest + +This endpoint uses the named encryption key to sign digest string data. The +response will include the base64-encoded signature. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `gcpkms/sign/:key` | + +### Example policy + +```hcl +path "gcpkms/sign/my-key" { + capabilities = ["create", "update"] +} +``` + +### Parameters + +- `key` (`string: ""`) - + Name of the key in Vault to use for signing. This key must already exist in + Vault and must map back to a Google Cloud KMS key. + This is specified as part of the URL. + +- `key_version` (`int: `) - + Integer version of the crypto key version to use for signing. + +- `digest` (`string: `) - + Digest to sign. This digest is the base64 encoded binary value, and must match + the signing algorithm digest of the Cloud KMS key, for example: + + ```text + $ openssl dgst -sha256 -binary /my/file | base64 + ``` + +### Sample payload + +```json +{ + "key_version": "1", + "digest": "LoM6lxd8YS+hUynZwrlCG20ViUUqqbNNNmh7HCtOkSc=" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcpkms/sign/my-key +``` + +### Sample response + +```json +{ + "data": { + "signature": "MGYCMQCOfWMc21jBevoRRo4zGjYsCXer8s..." + } +} +``` + +## Verify digest + +This endpoint uses the named encryption key to verify a signature and digest +string data. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `gcpkms/verify/:key` | + +### Example policy + +```hcl +path "gcpkms/verify/my-key" { + capabilities = ["create", "update"] +} +``` + +### Parameters + +- `key` (`string: ""`) - + Name of the key in Vault to use for verifying. This key must already exist in + Vault and must map back to a Google Cloud KMS key. + This is specified as part of the URL. + +- `key_version` (`int: `) - + Integer version of the crypto key version to use for verifying. + +- `digest` (`string: `) - + Digest that was signed. This digest is the base64 encoded binary value, and must match + the signing algorithm digest of the Cloud KMS key. For example: + + ```text + $ openssl dgst -sha256 -binary /my/file | base64 + ``` + +- `signature` (`string: `) - + Signature of the digest as returned from a signing operation. + +### Sample payload + +```json +{ + "key_version": "1", + "digest": "LoM6lxd8YS+hUynZwrlCG20ViUUqqbNNNmh7HCtOkSc=", + "signature": "MGQCMEN2rgg6sj2vUEC3IcKDD+UprtMnxDoB3..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcpkms/verify/my-key +``` + +### Sample response + +```json +{ + "data": { + "valid": true + } +} +``` + +## List keys + +This endpoint lists the named keys available for use in Vault. It does not list +all Google Cloud KMS keys. + +| Method | Path | +| :----- | :------------ | +| `LIST` | `gcpkms/keys` | + +### Example policy + +```hcl +path "gcpkms/keys" { + capabilities = ["list"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/gcpkms/keys +``` + +### Sample response + +```json +{ + "data": { + "keys": ["my-key"] + } +} +``` + +## Create/Update Google Cloud KMS key + +This endpoint is used to create or update a Google Cloud KMS key. In addition to +registering the key in Vault, this endpoint will also create the corresponding +Google Cloud KMS key with the given configuration options. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `gcpkms/keys/:key` | + +### Example policy + +```hcl +path "gcpkms/keys/my-key" { + capabilities = ["create", "update"] +} +``` + +### Parameters + +- `key` (`string: ""`) - + Name of the key in Vault. + This is specified as part of the URL. + +- `crypto_key` (`string: ""`) - + Name of the crypto key to use. If the given crypto key does not exist, Vault + will try to create it. This defaults to the name of the key given to Vault as + the parameter if unspecified. + +- `key_ring` (`string: ""`) - + Full Google Cloud resource ID of the key ring with the project and location + (e.g. projects/my-project/locations/global/keyRings/my-keyring). If the given + key ring does not exist, Vault will try to create it during a create operation. + +- `labels` (`mapstring: nil`) - + Arbitrary key=value labels to apply to the crypto key. To specify multiple + labels, specify this argument multiple times (e.g. labels="a=b" labels="c=d"). + +- `rotation_period` (`string: ""`) - + Amount of time between crypto key version rotations. This is specified as a + time duration value like 72h (72 hours). The smallest possible value is 24h. + +- `protection_level` (`string: "software"`) - + Level of protection to use for the key management. Valid values are `software` + and `hsm`. The default value is `software`. The value cannot be changed after + creation. + +- `purpose` (`string: "encrypt_decrypt"`) - + Purpose of the key. Valid options are `asymmetric_decrypt`, `asymmetric_sign`, + and `encrypt_decrypt`. The default value is `encrypt_decrypt`. The value cannot + be changed after creation. + +- `algorithm` (`string: "symmetric_encryption"`) - + Algorithm to use for encryption, decryption, or signing. The value depends on + the key purpose. The value cannot be changed after creation. See table below + for the supported algorithms of each purpose. + + | Purpose | Supported Algorithms | + | :------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `encrypt_decrypt` | `symmetric_encryption` | + | `asymmetric_decrypt` | `rsa_decrypt_oaep_2048_sha256`
`rsa_decrypt_oaep_3072_sha256`
`rsa_decrypt_oaep_4096_sha256` | + | `asymmetric_sign` | `rsa_sign_pss_2048_sha256`
`rsa_sign_pss_3072_sha256`
`rsa_sign_pss_4096_sha256`
`rsa_sign_pkcs1_2048_sha256`
`rsa_sign_pkcs1_3072_sha256`
`rsa_sign_pkcs1_4096_sha256`
`ec_sign_p256_sha256`
`ec_sign_p384_sha384` | + +### Sample payload + +```json +{ + "key_ring": "projects/my-project/locations/my-location/keyRings/my-keyring", + "labels": { + "foo": "bar" + }, + "rotation_period": "72h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcpkms/keys/my-key +``` + +## Delete Google Cloud KMS key + +This endpoint deletes a key from both Vault and Google Cloud KMS. This will +disable all crypto key versions for this crypto key in Google Cloud KMS and +delete Vault's reference to the crypto key. + +| Method | Path | +| :------- | :----------------- | +| `DELETE` | `gcpkms/keys/:key` | + +### Example policy + +```hcl +path "gcpkms/keys/my-key" { + capabilities = ["delete"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/gcpkms/keys/my-key +``` + +## Read Google Cloud KMS key + +This endpoint reads data about a Google Cloud KMS crypto key, including the key +status and current primary key version. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `gcpkms/keys/:key` | + +### Example policy + +```hcl +path "gcpkms/keys/my-key" { + capabilities = ["read"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/gcpkms/keys/my-key +``` + +### Sample response + +```json +{ + "data": { + "id": "projects/my-project/locations/my-location/keyRings/my-keyring/cryptoKeys/my-crypto-key", + "labels": { + "foo": "bar" + }, + "next_rotation_time_seconds": 1536613424, + "primary_version": "3", + "purpose": "encrypt_decrypt", + "rotation_schedule_seconds": 259200, + "state": "enabled" + } +} +``` + +## Read Vault key configuration + +This endpoint reads data about a Vault's configuration of the key. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `gcpkms/keys/config/:key` | + +### Example policy + +```hcl +path "gcpkms/keys/config/my-key" { + capabilities = ["read"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/gcpkms/keys/config/my-key +``` + +### Sample response + +```json +{ + "data": { + "name": "my-key", + "crypto_key": "projects/my-project/locations/my-location/keyRings/my-keyring/cryptoKeys/my-crypto-key", + "min_version": 10 + } +} +``` + +## Update Vault key configuration + +This endpoint is used to update Vault's information about an existing key. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `gcpkms/keys/config/:key` | + +### Example policy + +```hcl +path "gcpkms/keys/my-key" { + capabilities = ["create", "update"] +} +``` + +### Parameters + +- `key` (`string: ""`) - + Name of the key in Vault. + This is specified as part of the URL. + +- `min_version` (`int: 0`) - + Minimum allowed crypto key version. If set to a positive value, key versions + less than the given value are not permitted to be used. If set to 0 or a + negative value, there is no minimum key version. + +- `max_version` (`int: 0`) - + Maximum allowed crypto key version. If set to a positive value, key versions + greater than the given value are not permitted to be used. If set to 0 or a + negative value, there is no maximum key version. + +### Sample payload + +```json +{ + "min_version": 10 +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcpkms/keys/config/my-key +``` + +## Deregister crypto key + +This endpoint deregisters an existing reference Vault has to a crypto key in +Google Cloud KMS. The underlying Google Cloud KMS key remains unchanged. + +| Method | Path | +| :----- | :---------------------------- | +| `POST` | `gcpkms/keys/deregister/:key` | + +### Example policy + +```hcl +path "gcpkms/keys/deregister/my-key" { + capabilities = ["create", "update"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://127.0.0.1:8200/v1/gcpkms/keys/deregister/my-key +``` + +## Register crypto key + +This endpoint registers an existing crypto key in Google Cloud KMS and makes it +available for encryption and decryption in Vault. + +| Method | Path | +| :----- | :-------------------------- | +| `POST` | `gcpkms/keys/register/:key` | + +### Example policy + +```hcl +path "gcpkms/keys/register/my-key" { + capabilities = ["create", "update"] +} +``` + +### Parameters + +- `key` (`string: ""`) - + Name of the key to register in Vault. This will be the named used to refer to + the underlying crypto key when encrypting or decrypting data. + This is specified as part of the URL. + +- `crypto_key` (`string: ""`) - + Full resource ID of the crypto key including the project, location, key ring, + and crypto key like "projects/%s/locations/%s/keyRings/%s/cryptoKeys/%s". This + crypto key must already exist in Google Cloud KMS unless verify is set to + "false". + +- `verify` (`bool: true`) - + Verify that the given Google Cloud KMS crypto key exists and is accessible + before creating the storage entry in Vault. Set this to "false" if the key will + not exist at creation time. + +### Sample payload + +```json +{ + "crypto_key": "projects/my-project/locations/my-location/keyRings/my-keyring/cryptoKeys/my-crypto-key", + "verify": true +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/gcpkms/keys/register/my-key +``` + +## Rotate crypto key + +This endpoint rotates a crypto key by creating a new crypto key version for the +corresponding Google Cloud KMS key and updates the new crypto key to be the +primary key for future encryptions. + +**It can take up to 2 hours for a new crypto key version to become the primary, +so be sure to issue a read operation if you require new data to be encrypted +with this key.** + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `gcpkms/keys/rotate/:key` | + +### Example policy + +```hcl +path "gcpkms/keys/rotate/my-key" { + capabilities = ["create", "update"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://127.0.0.1:8200/v1/gcpkms/keys/rotate/my-key +``` + +### Sample response + +```json +{ + "data": { + "key_version": "3" + } +} +``` + +## Trim KMS key versions + +This endpoint deletes old crypto key versions that are older than the key's specified `min_version`. + +**Data encrypted with older key versions will be irrecoverable!** + +| Method | Path | +| :----- | :---------------------- | +| `POST` | `gcpkms/keys/trim/:key` | + +### Example policy + +```hcl +path "gcpkms/keys/trim/my-key" { + capabilities = ["create", "update"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://127.0.0.1:8200/v1/gcpkms/keys/trim/my-key +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/entity-alias.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/entity-alias.mdx new file mode 100644 index 0000000000..13d71355e4 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/entity-alias.mdx @@ -0,0 +1,255 @@ +--- +layout: api +page_title: 'Identity Secret Backend: Entity Alias - HTTP API' +description: >- + This is the API documentation for managing entity aliases in the identity + store. +--- + +~> **NOTE:** Be careful in granting permissions to non-readonly identity endpoints. +If a user can modify an entity, they can grant it additional privileges through +policies. If a user can modify an alias they can login with, they can bind it to +an entity with higher privileges. + +## Create an entity alias + +~> **IMPORTANT NOTE:** Prior to creating any alias it is important to consider the cardinality of the alias' name, +since there are potential security issues to be aware of. The main one revolves around alias reuse. It is possible +for multiple authenticated entities to be bound to the same alias, and therefore gain access to all of its privileges. +It is recommended, whenever possible, to create a unique alias for each entity. This is especially true in the case +of machine generated entities. + +This endpoint creates a new alias for an entity. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/identity/entity-alias` | + +### Parameters + +- `name` `(string: )` - Name of the alias. Name should be the identifier + of the client in the authentication source. For example, if the alias belongs + to userpass backend, the name should be a valid username within userpass + auth method. If the alias belongs to GitHub, it should be the GitHub username. If the alias + belongs to an approle auth method, the name should be a valid RoleID. + +- `id` `(string: )` - ID of the entity alias. If set, updates the + corresponding entity alias. + +- `canonical_id` `(string: )` - Entity ID to which this alias belongs to. + +- `mount_accessor` `(string: )` - Accessor of the mount to which the + alias should belong to. + +- `custom_metadata` `(map: )` - A map of arbitrary string to string valued + user-provided metadata meant to describe the alias. + +### Sample payload + +```json +{ + "name": "testuser", + "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3", + "mount_accessor": "auth_userpass_e50b1a44", + "custom_metadata": { + "contact_email": "james_updated@example.com" + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/entity-alias +``` + +### Sample response + +```json +{ + "data": { + "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3", + "id": "34982d3d-e3ce-5d8b-6e5f-b9bb34246c31" + } +} +``` + +## Read entity alias by ID + +This endpoint queries the entity alias by its identifier. + +| Method | Path | +| :----- | :------------------------------ | +| `GET` | `/identity/entity-alias/id/:id` | + +### Parameters + +- `id` `(string: )` – Identifier of entity alias. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/identity/entity-alias/id/34982d3d-e3ce-5d8b-6e5f-b9bb34246c31 +``` + +### Sample response + +```json +{ + "data": { + "creation_time": "2017-07-25T21:41:09.820717636Z", + "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3", + "custom_metadata": { + "contact_email":"james@example.com" + }, + "id": "34982d3d-e3ce-5d8b-6e5f-b9bb34246c31", + "last_update_time": "2017-07-25T21:41:09.820717636Z", + "local": false, + "metadata": { + "group": "san_francisco", + "region": "west" + }, + "mount_accessor": "auth_userpass_e50b1a44", + "mount_path": "userpass/", + "mount_type": "userpass", + "name": "testuser" + } +} +``` + +## Update entity alias by ID + +This endpoint is used to update an existing entity alias. + +| Method | Path | +| :----- | :------------------------------ | +| `POST` | `/identity/entity-alias/id/:id` | + +### Parameters + +- `id` `(string: )` – Identifier of the entity alias. + +- `name` `(string: "")` - Name of the alias. Name should be the identifier + of the client in the authentication source. For example, if the alias belongs + to userpass backend, the name should be a valid username within userpass + backend. If alias belongs to GitHub, it should be the GitHub username. + +- `canonical_id` `(string: "")` - Entity ID to which this alias belongs to. + +- `mount_accessor` `(string: "")` - Accessor of the mount to which the + alias should belong to. + +- `custom_metadata` `(map: )` - A map of arbitrary string to string valued + user-provided metadata meant to describe the alias. + +### Sample payload + +```json +{ + "name": "testuser", + "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3", + "mount_accessor": "auth_userpass_e50b1a44" + "custom_metadata": { + "contact_email": "james@example.com" + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/entity-alias/id/34982d3d-e3ce-5d8b-6e5f-b9bb34246c31 +``` + +### Sample response + +```json +{ + "data": { + "canonical_id": "404e57bc-a0b1-a80f-0a73-b6e92e8a52d3", + "id": "34982d3d-e3ce-5d8b-6e5f-b9bb34246c31" + } +} +``` + +## Delete entity alias by ID + +This endpoint deletes an alias from its corresponding entity. + +| Method | Path | +| :------- | :------------------------------ | +| `DELETE` | `/identity/entity-alias/id/:id` | + +### Parameters + +- `id` `(string: )` – Identifier of the entity alias. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/entity-alias/id/34982d3d-e3ce-5d8b-6e5f-b9bb34246c31 +``` + +## List entity aliases by ID + +The list by ID endpoint returns the available entity aliases and key data by their identifiers. + +| Method | Path | +| :----- | :------------------------------------ | +| `LIST` | `/identity/entity-alias/id` | +| `GET` | `/identity/entity-alias/id?list=true` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/entity-alias/id +``` + +### Sample response + +```json +{ + "data": { + "key_info": { + "35405f3c-884a-a3ff-4176-bac57f220811": { + "canonical_id": "0c34f097-6313-9597-3b22-91e34072ad28", + "custom_metadata": null, + "local": false, + "mount_accessor": "auth_jwt_e47c5220", + "mount_path": "auth/tfc_jwt/", + "mount_type": "jwt", + "name": "app-alias-1" + }, + "4065d8c7-4fa6-db9d-e190-f9644c09638a": { + "canonical_id": "21c6f2bf-b9b0-db44-242f-18bf76cb9ff0", + "custom_metadata": null, + "local": false, + "mount_accessor": "auth_ns_token_79c4d932", + "mount_path": "auth/token/", + "mount_type": "ns_token", + "name": "app-alias-2" + } + }, + "keys": [ + "35405f3c-884a-a3ff-4176-bac57f220811", + "4065d8c7-4fa6-db9d-e190-f9644c09638a" + ] + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/entity.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/entity.mdx new file mode 100644 index 0000000000..4ecec6855e --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/entity.mdx @@ -0,0 +1,453 @@ +--- +layout: api +page_title: 'Identity Secret Backend: Entity - HTTP API' +description: This is the API documentation for managing entities in the identity store. +--- + +## Create an entity + +This endpoint creates or updates an Entity. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/identity/entity` | + +### Parameters + +- `name` `(string: entity-)` – Name of the entity. + +- `id` `(string: )` - ID of the entity. If set, updates the + corresponding existing entity. + +- `metadata` `(key-value-map: {})` – Metadata to be associated with the + entity. + +- `policies` `(list of strings: [])` – Policies to be tied to the entity. + +- `disabled` `(bool: false)` – Whether the entity is disabled. Disabled + entities' associated tokens cannot be used, but are not revoked. + +### Sample payload + +```json +{ + "metadata": { + "organization": "hashicorp", + "team": "vault" + }, + "policies": ["eng-dev", "infra-dev"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/entity +``` + +### Sample response + +```json +{ + "data": { + "id": "8d6a45e5-572f-8f13-d226-cd0d1ec57297", + "aliases": null + } +} +``` + +## Read entity by ID + +This endpoint queries the entity by its identifier. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/identity/entity/id/:id` | + +### Parameters + +- `id` `(string: )` – Identifier of the entity. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/identity/entity/id/8d6a45e5-572f-8f13-d226-cd0d1ec57297 +``` + +### Sample response + +```json +{ + "data": { + "bucket_key_hash": "177553e4c58987f4cc5d7e530136c642", + "creation_time": "2017-07-25T20:29:22.614756844Z", + "disabled": false, + "id": "8d6a45e5-572f-8f13-d226-cd0d1ec57297", + "last_update_time": "2017-07-25T20:29:22.614756844Z", + "metadata": { + "organization": "hashicorp", + "team": "vault" + }, + "name": "entity-c323de27-2ad2-5ded-dbf3-0c7ef98bc613", + "aliases": [], + "policies": ["eng-dev", "infra-dev"] + } +} +``` + +## Update entity by ID + +This endpoint is used to update an existing entity. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `/identity/entity/id/:id` | + +### Parameters + +- `id` `(string: )` – Identifier of the entity. +- `name` `(string: entity-)` – Name of the entity. +- `metadata` `(key-value-map: {})` – Metadata to be associated with the entity. +- `policies` `(list of strings: [])` – Policies to be tied to the entity. +- `disabled` `(bool: false)` – Whether the entity is disabled. Disabled + entities' associated tokens cannot be used, but are not revoked. + +### Sample payload + +```json +{ + "name": "updatedEntityName", + "metadata": { + "organization": "hashicorp", + "team": "nomad" + }, + "policies": ["eng-developers", "infra-developers"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/entity/id/8d6a45e5-572f-8f13-d226-cd0d1ec57297 +``` + +### Sample response + +```json +{ + "data": { + "id": "8d6a45e5-572f-8f13-d226-cd0d1ec57297", + "aliases": null + } +} +``` + +## Delete entity by ID + +This endpoint deletes an entity and all its associated aliases. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `/identity/entity/id/:id` | + +### Parameters + +- `id` `(string: )` – Identifier of the entity. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/entity/id/8d6a45e5-572f-8f13-d226-cd0d1ec57297 +``` + +## Batch delete entities + +This endpoint deletes all entities provided. + +| Method | Path | +| :----- | :------------------------------ | +| `POST` | `/identity/entity/batch-delete` | + +### Parameters + +- `entity_ids` `([]string: )` – List of entity identifiers to delete. + +### Sample payload + +```json +{ + "entity_ids": [ + "02fe5a88-912b-6794-62ed-db873ef86a95", + "3bf81bc9-44df-8138-57f9-724a9ae36d04", + "627fba68-98c9-c012-71ba-bfb349585ce1", + "6c4c805b-b384-3d0e-4d51-44d349887b96", + "70a72feb-35d1-c775-0813-8efaa8b4b9b5", + "f1092a67-ce34-48fd-161d-c13a367bc1cd", + "faedd89a-0d82-c197-c8f9-93a3e6cf0cd0" + ] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/entity/batch-delete +``` + +## List entities by ID + +This endpoint returns a list of available entities by their identifiers. + +| Method | Path | +| :----- | :------------------------------ | +| `LIST` | `/identity/entity/id` | +| `GET` | `/identity/entity/id?list=true` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/entity/id +``` + +### Sample response + +```json +{ + "data": { + "keys": [ + "02fe5a88-912b-6794-62ed-db873ef86a95", + "3bf81bc9-44df-8138-57f9-724a9ae36d04", + "627fba68-98c9-c012-71ba-bfb349585ce1", + "6c4c805b-b384-3d0e-4d51-44d349887b96", + "70a72feb-35d1-c775-0813-8efaa8b4b9b5", + "f1092a67-ce34-48fd-161d-c13a367bc1cd", + "faedd89a-0d82-c197-c8f9-93a3e6cf0cd0" + ] + } +} +``` + +## Create/Update entity by name + +This endpoint is used to create or update an entity by a given name. + +| Method | Path | +| :----- | :---------------------------- | +| `POST` | `/identity/entity/name/:name` | + +### Parameters + +- `name` `(string: entity-)` – Name of the entity. + +- `metadata` `(key-value-map: {})` – Metadata to be associated with the entity. + +- `policies` `(list of strings: [])` – Policies to be tied to the entity. + +- `disabled` `(bool: false)` – Whether the entity is disabled. Disabled + entities' associated tokens cannot be used, but are not revoked. + +### Sample payload + +```json +{ + "metadata": { + "organization": "hashicorp", + "team": "nomad" + }, + "policies": ["eng-developers", "infra-developers"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/entity/name/testentityname +``` + +### Sample response + +```json +{ + "data": { + "aliases": null, + "id": "0826be06-577c-a076-3942-2f92da0310ce" + } +} +``` + +## Read entity by name + +This endpoint queries the entity by its name. + +| Method | Path | +| :----- | :---------------------------- | +| `GET` | `/identity/entity/name/:name` | + +### Parameters + +- `name` `(string: )` – Name of the entity. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/identity/entity/name/testentityname +``` + +### Sample response + +```json +{ + "data": { + "aliases": [], + "creation_time": "2018-09-19T17:20:27.705389973Z", + "direct_group_ids": [], + "disabled": false, + "group_ids": [], + "id": "0826be06-577c-a076-3942-2f92da0310ce", + "inherited_group_ids": [], + "last_update_time": "2018-09-19T17:20:27.705389973Z", + "merged_entity_ids": null, + "metadata": { + "organization": "hashicorp", + "team": "nomad" + }, + "name": "testentityname", + "policies": ["eng-developers", "infra-developers"] + } +} +``` + +## Delete entity by name + +This endpoint deletes an entity and all its associated aliases, given the +entity name. + +| Method | Path | +| :------- | :---------------------------- | +| `DELETE` | `/identity/entity/name/:name` | + +### Parameters + +- `name` `(string: )` – Name of the entity. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/entity/name/testentityname +``` + +## List entities by name + +This endpoint returns a list of available entities by their names. + +| Method | Path | +| :----- | :-------------------------------- | +| `LIST` | `/identity/entity/name` | +| `GET` | `/identity/entity/name?list=true` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/entity/name +``` + +### Sample response + +```json +{ + "data": { + "keys": ["testentityname"] + } +} +``` + +## Merge entities + +This endpoint merges many entities into one entity. Additionally, all groups associated with `from_entity_ids` are merged with those of `to_entity_id`. +Note that if these entities contain aliases sharing the same mount accessor, the merge will fail unless `conflicting_alias_ids_to_keep` is present, and +entities must be merged one at a time. This is because each entity can only have one alias with each mount accessor - for more +information, see the [identity concepts page](/vault/docs/concepts/identity). + + + +We recommended limiting merging to the leader node of your primary cluster. + + + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/identity/entity/merge` | + +### Parameters + +- `from_entity_ids` `(list of strings: )` - Entity IDs which need to get + merged. + +- `to_entity_id` `(string: )` - Entity ID into which all the other + entities need to get merged. + +- `force` `(bool: false)` - Setting this will follow the 'mine' strategy for + merging MFA secrets. If there are secrets of the same type both in entities + that are merged from and in entity into which all others are getting merged, + secrets in the destination will be unaltered. If not set, this API will throw + an error containing all the conflicts. + +- `conflicting_alias_ids_to_keep` `(list of strings: [])` - A list of entity + aliases to keep in the case where the to-Entity and from-Entity have aliases + with the same mount accessor. In the case where alias share mount accessors, + the alias ID given in this list will be kept or merged, and the other alias will be deleted. + Note that merges requiring this parameter must have only one from-Entity. + +### Sample payload + +```json +{ + "to_entity_id": "f2cdefbe-f510-a226-77fa-989a48ba6abc", + "from_entity_ids": [ + "1ade80ec-ba5c-8eed-91e2-b9dcd41d6fff", + "270976d0-9bab-14a5-4b92-3861805ef73d" + ] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/entity/merge +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/group-alias.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/group-alias.mdx new file mode 100644 index 0000000000..db5d500f79 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/group-alias.mdx @@ -0,0 +1,196 @@ +--- +layout: api +page_title: 'Identity Secret Backend: Group Alias - HTTP API' +description: >- + This is the API documentation for managing the group aliases in the identity + store. +--- + +## Create a group alias + +This endpoint creates or updates a group alias. + +| Method | Path | +| :----- | :---------------------- | +| `POST` | `/identity/group-alias` | + +### Parameters + +- `name` `(string: entity-)` – Name of the group alias. + +- `id` `(string: )` - ID of the group alias. If set, updates the + corresponding existing group alias. + +- `mount_accessor` `(string: "")` – Mount accessor which this alias belongs + to. + +- `canonical_id` `(string: "")` - ID of the group to which this is an alias. + +### Sample payload + +```json +{ + "canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b", + "mount_accessor": "auth_github_232a90dc", + "name": "dev-team" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/group-alias +``` + +### Sample response + +```json +{ + "data": { + "canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b", + "id": "ca726050-d8ac-6f1f-4210-3b5c5b613824" + } +} +``` + +## Update group alias by ID + +This endpoint is used to update an existing group alias. + +| Method | Path | +| :----- | :----------------------------- | +| `POST` | `/identity/group-alias/id/:id` | + +### Parameters + +- `id` `(string: )` - ID of the group alias. + +- `name` `(string: entity-)` – Name of the group alias. + +- `mount_accessor` `(string: "")` – Mount accessor which this alias belongs + to. + +- `canonical_id` `(string: "")` - ID of the group to which this is an alias. + +### Sample payload + +```json +{ + "canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b", + "mount_accessor": "auth_github_232a90dc", + "name": "dev-team" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/group-alias/id/ca726050-d8ac-6f1f-4210-3b5c5b613824 +``` + +### Sample response + +```json +{ + "data": { + "canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b", + "id": "ca726050-d8ac-6f1f-4210-3b5c5b613824" + } +} +``` + +## Read group alias by ID + +This endpoint queries the group alias by its identifier. + +| Method | Path | +| :----- | :----------------------------- | +| `GET` | `/identity/group-alias/id/:id` | + +### Parameters + +- `id` `(string: )` – ID of the group alias. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/identity/group-alias/id/ca726050-d8ac-6f1f-4210-3b5c5b613824 +``` + +### Sample response + +```json +{ + "data": { + "canonical_id": "b86920ea-2831-00ff-15c5-a3f923f1ee3b", + "creation_time": "2017-11-13T20:09:41.661694Z", + "id": "ca726050-d8ac-6f1f-4210-3b5c5b613824", + "last_update_time": "2017-11-13T20:09:41.661694Z", + "merged_from_canonical_ids": null, + "metadata": null, + "mount_accessor": "auth_github_232a90dc", + "mount_path": "", + "mount_type": "github", + "name": "dev-team" + } +} +``` + +## Delete group alias by ID + +This endpoint deletes a group alias. + +| Method | Path | +| :------- | :----------------------------- | +| `DELETE` | `/identity/group-alias/id/:id` | + +### Parameters + +- `id` `(string: )` – ID of the group alias. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/group-alias/id/ca726050-d8ac-6f1f-4210-3b5c5b613824 +``` + +## List group alias by ID + +This endpoint returns a list of available group aliases by their identifiers. + +| Method | Path | +| :----- | :----------------------------------- | +| `LIST` | `/identity/group-alias/id` | +| `GET` | `/identity/group-alias/id?list=true` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/group-alias/id +``` + +### Sample response + +```json +{ + "data": { + "keys": ["ca726050-d8ac-6f1f-4210-3b5c5b613824"] + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/group.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/group.mdx new file mode 100644 index 0000000000..0e6230f863 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/group.mdx @@ -0,0 +1,385 @@ +--- +layout: api +page_title: 'Identity Secret Backend: Group - HTTP API' +description: This is the API documentation for managing groups in the identity store. +--- + +~> **NOTE:** Be careful in granting permissions to non-readonly identity group +endpoints. If a user can modify group membership, they can add their entity to +a group with higher privileges. + +## Create a group + +This endpoint creates or updates a Group. + +| Method | Path | +| :----- | :---------------- | +| `POST` | `/identity/group` | + +### Parameters + +- `name` `(string: entity-)` – Name of the group. If set (and + ID is not set), updates the corresponding existing group. + +- `id` `(string: )` - ID of the group. If set, updates the + corresponding existing group. + +- `type` `(string: "internal")` - Type of the group, `internal` or `external`. + Defaults to `internal`. + +- `metadata` `(key-value-map: {})` – Metadata to be associated with the + group. + +- `policies` `(list of strings: [])` – Policies to be tied to the group. + +- `member_group_ids` `(list of strings: [])` - Group IDs to be assigned as + group members. + +- `member_entity_ids` `(list of strings: [])` - Entity IDs to be assigned as + group members. + +### Sample payload + +```json +{ + "metadata": { + "hello": "world" + }, + "policies": ["grouppolicy1", "grouppolicy2"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/group +``` + +### Sample response + +```json +{ + "data": { + "id": "363926d8-dd8b-c9f0-21f8-7b248be80ce1", + "name": "group_ab813d63" + } +} +``` + +## Read group by ID + +This endpoint queries the group by its identifier. + +| Method | Path | +| :----- | :----------------------- | +| `GET` | `/identity/group/id/:id` | + +### Parameters + +- `id` `(string: )` – Identifier of the group. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1 +``` + +### Sample response + +```json +{ + "data": { + "alias": {}, + "creation_time": "2017-11-13T19:36:47.102945Z", + "id": "363926d8-dd8b-c9f0-21f8-7b248be80ce1", + "last_update_time": "2017-11-13T19:36:47.102945Z", + "member_entity_ids": [], + "member_group_ids": null, + "metadata": { + "hello": "world" + }, + "modify_index": 1, + "name": "group_ab813d63", + "policies": ["grouppolicy1", "grouppolicy2"], + "type": "internal" + } +} +``` + +## Update group by ID + +This endpoint is used to update an existing group. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/identity/group/id/:id` | + +### Parameters + +- `id` `(string: )` – Identifier of the entity. + +- `name` `(string: entity-)` – Name of the group. + +- `type` `(string: "internal")` - Type of the group, `internal` or `external`. + Defaults to `internal`. + +- `metadata` `(key-value-map: {})` – Metadata to be associated with the + group. + +- `policies` `(list of strings: [])` – Policies to be tied to the group. + +- `member_group_ids` `(list of strings: [])` - Group IDs to be assigned as + group members. + +- `member_entity_ids` `(list of strings: [])` - Entity IDs to be assigned as + group members. + +### Sample payload + +```json +{ + "name": "testgroupname", + "metadata": { + "hello": "everyone" + }, + "policies": ["grouppolicy2", "grouppolicy3"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1 +``` + +### Sample response + +```json +{ + "data": { + "id": "363926d8-dd8b-c9f0-21f8-7b248be80ce1", + "name": "testgroupname" + } +} +``` + +## Delete group by ID + +This endpoint deletes a group. + +| Method | Path | +| :------- | :----------------------- | +| `DELETE` | `/identity/group/id/:id` | + +### Parameters + +- `id` `(string: )` – Identifier of the group. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/group/id/363926d8-dd8b-c9f0-21f8-7b248be80ce1 +``` + +## List groups by ID + +This endpoint returns a list of available groups by their identifiers. + +| Method | Path | +| :----- | :----------------------------- | +| `LIST` | `/identity/group/id` | +| `GET` | `/identity/group/id?list=true` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/group/id +``` + +### Sample response + +```json +{ + "data": { + "keys": [ + "052567cf-1580-6f20-50c8-d38bc46dae6e", + "26da8035-6691-b89e-67ac-ebf9ea7f9893", + "363926d8-dd8b-c9f0-21f8-7b248be80ce1", + "5c4a5720-7408-c113-1dcc-9ede725d0ac8", + "d55e0f34-5c16-38ae-87af-324c9b656c43", + "e4e56e04-0dec-9b68-9b20-a450975d898e" + ] + } +} +``` + +## Create/Update group by name + +This endpoint is used to create or update a group by its name. + +| Method | Path | +| :----- | :--------------------------- | +| `POST` | `/identity/group/name/:name` | + +### Parameters + +- `name` `(string: entity-)` – Name of the group. + +- `type` `(string: "internal")` - Type of the group, `internal` or `external`. + Defaults to `internal`. + +- `metadata` `(key-value-map: {})` – Metadata to be associated with the + group. + +- `policies` `(list of strings: [])` – Policies to be tied to the group. + +- `member_group_ids` `(list of strings: [])` - Group IDs to be assigned as + group members. + +- `member_entity_ids` `(list of strings: [])` - Entity IDs to be assigned as + group members. + +### Sample payload + +```json +{ + "metadata": { + "hello": "everyone" + }, + "policies": ["grouppolicy2", "grouppolicy3"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/group/name/testgroupname +``` + +### Sample response + +```json +{ + "request_id": "b98b4a3d-a9f1-e151-11e1-ad91cfb08351", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "id": "5a3a04a0-0c3a-a4c3-74e8-26b1adbeaece", + "name": "testgroupname" + }, + "warnings": null +} +``` + +## Read group by name + +This endpoint queries the group by its name. + +| Method | Path | +| :----- | :--------------------------- | +| `GET` | `/identity/group/name/:name` | + +### Parameters + +- `name` `(string: )` – Name of the group. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/identity/group/name/testgroupname +``` + +### Sample response + +```json +{ + "data": { + "alias": {}, + "creation_time": "2018-09-19T22:02:04.395128091Z", + "id": "5a3a04a0-0c3a-a4c3-74e8-26b1adbeaece", + "last_update_time": "2018-09-19T22:02:04.395128091Z", + "member_entity_ids": [], + "member_group_ids": null, + "metadata": { + "foo": "bar" + }, + "modify_index": 1, + "name": "testgroupname", + "parent_group_ids": null, + "policies": ["grouppolicy1", "grouppolicy2"], + "type": "internal" + } +} +``` + +## Delete group by name + +This endpoint deletes a group, given its name. + +| Method | Path | +| :------- | :--------------------------- | +| `DELETE` | `/identity/group/name/:name` | + +### Parameters + +- `name` `(string: )` – Name of the group. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/group/name/testgroupname +``` + +## List groups by name + +This endpoint returns a list of available groups by their names. + +| Method | Path | +| :----- | :------------------------------- | +| `LIST` | `/identity/group/name` | +| `GET` | `/identity/group/name?list=true` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/group/name +``` + +### Sample response + +```json +{ + "data": { + "keys": ["testgroupname"] + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/index.mdx new file mode 100644 index 0000000000..e649db30ee --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/index.mdx @@ -0,0 +1,22 @@ +--- +layout: api +page_title: Identity - Secrets Engines - HTTP API +description: This is the API documentation for the Vault Identity secrets engine. +--- + +# Identity secrets engine (API) + +This is the API documentation for the Vault Identity secrets engine. For general +information about the usage and operation of the Identity secrets engine, please +see the [Vault Identity documentation](/vault/docs/secrets/identity). + +## API sections + +- [Entity](/vault/api-docs/secret/identity/entity) +- [Entity Alias](/vault/api-docs/secret/identity/entity-alias) +- [Group](/vault/api-docs/secret/identity/group) +- [Group Alias](/vault/api-docs/secret/identity/group-alias) +- [Identity Tokens](/vault/api-docs/secret/identity/tokens) +- [Lookup](/vault/api-docs/secret/identity/lookup) +- [OIDC Provider](/vault/api-docs/secret/identity/oidc-provider) +- [MFA](/vault/api-docs/secret/identity/mfa) diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/lookup.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/lookup.mdx new file mode 100644 index 0000000000..5bcb00efe8 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/lookup.mdx @@ -0,0 +1,131 @@ +--- +layout: api +page_title: 'Identity Secret Backend: Lookup - HTTP API' +description: |- + This is the API documentation for entity and group lookups from identity + store. +--- + +## Lookup an entity + +This endpoint looks up an entity based on the given criteria. The criteria can +be `name`, `id`, `alias_id`, or a combination of `alias_name` and +`alias_mount_accessor`. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `/identity/lookup/entity` | + +### Parameters + +- `name` `(string: "")` – Name of the entity. + +- `id` `(string: "")` - ID of the entity. + +- `alias_id` `(string: "")` - ID of the alias. + +- `alias_name` `(string: "")` - Name of the alias. This should be supplied in + conjunction with `alias_mount_accessor`. + +- `alias_mount_accessor` `(string: "")` - Accessor of the mount to which the + alias belongs to. This should be supplied in conjunction with `alias_name`. + +### Sample payload + +```json +{ + "id": "043fedec-967d-b2c9-d3af-0c467b04e1fd" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/lookup/entity +``` + +### Sample response + +```json +{ + "data": { + "aliases": [], + "creation_time": "2017-11-13T21:01:33.543497Z", + "direct_group_ids": [], + "group_ids": [], + "id": "043fedec-967d-b2c9-d3af-0c467b04e1fd", + "inherited_group_ids": [], + "last_update_time": "2017-11-13T21:01:33.543497Z", + "merged_entity_ids": null, + "metadata": null, + "name": "entity_43cc451b", + "policies": null + } +} +``` + +## Lookup a group + +This endpoint looks up a group based on the given criteria. The criteria can +be `name`, `id`, `alias_id`, or a combination of `alias_name` and +`alias_mount_accessor`. + +| Method | Path | +| :----- | :----------------------- | +| `POST` | `/identity/lookup/group` | + +### Parameters + +- `name` `(string: "")` – Name of the group. + +- `id` `(string: "")` - ID of the group. + +- `alias_id` `(string: "")` - ID of the alias. + +- `alias_name` `(string: "")` - Name of the alias. This should be supplied in + conjunction with `alias_mount_accessor`. + +- `alias_mount_accessor` `(string: "")` - Accessor of the mount to which the + alias belongs to. This should be supplied in conjunction with `alias_name`. + +### Sample payload + +```json +{ + "id": "70a4bdef-9da3-4460-b524-bb08542eef25" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/lookup/group +``` + +### Sample response + +```json +{ + "data": { + "alias": {}, + "creation_time": "2017-11-13T21:06:44.475587Z", + "id": "70a4bdef-9da3-4460-b524-bb08542eef25", + "last_update_time": "2017-11-13T21:06:44.475587Z", + "member_entity_ids": [], + "member_group_ids": null, + "metadata": null, + "modify_index": 1, + "name": "group_eaf2aab1", + "policies": null, + "type": "internal" + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/duo.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/duo.mdx new file mode 100644 index 0000000000..831c2eea60 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/duo.mdx @@ -0,0 +1,180 @@ +--- +layout: api +page_title: /identity/mfa/method/duo - HTTP API +description: >- + The '/identity/mfa/method/duo' endpoint focuses on managing Duo MFA behaviors in Vault. +--- + +## Create Duo MFA method + +This endpoint creates a new MFA method of type Duo. + +| Method | Path | +|:-------|:---------------------------| +| `POST` | `/identity/mfa/method/duo` | + +### Parameters + +- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0. + +- `username_format` `(string)` - A template string for mapping Identity names to MFA methods. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}"`. If blank, the Entity's Name field is used as-is. + +- `secret_key` `(string: )` - Secret key for Duo. + +- `integration_key` `(string: )` - Integration key for Duo. + +- `api_hostname` `(string: )` - API hostname for Duo. + +- `push_info` `(string)` - Push information for Duo. + +- `use_passcode` `(bool: false)` - If true, the user is reminded to use the passcode upon MFA validation. + +### Sample payload + +```json +{ + "username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}", + "secret_key": "BIACEUEAXI20BNWTEYXT", + "integration_key": "8C7THtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz", + "api_hostname": "api-2b5c39f5.duosecurity.com", + "method_name": "ns1_duo" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/duo +``` + +### Sample response + +```json +{ + "data": { + "method_id": "0888fd69-4ea2-91d7-415e-c4bba548529b" + } +} +``` + +## Update Duo MFA method + +This endpoint updates the configuration of an MFA method of type Duo. + +| Method | Path | +|:-------|:--------------------------------------| +| `POST` | `/identity/mfa/method/duo/:method_id` | + +### Parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +- and all of the parameters documented under the preceding "Create" endpoint. + +### Sample payload + +Identical to the preceding "Create" endpoint. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d +``` + +## Read Duo MFA method + +This endpoint queries the MFA configuration of Duo type for a given method +ID. + +| Method | Path | +|:-------|:--------------------------------------| +| `GET` | `/identity/mfa/method/duo/:method_id` | + +### Parameters + +- `id` `(string: )` – UUID of the MFA method. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d +``` + +### Sample response + +```json +{ + "data": { + "api_hostname": "api-2b5c39f5.duosecurity.com", + "id": "4194659f-139b-400b-b5dd-86bfb726759d", + "integration_key": "BIACEUEAXI20BNWTEYXT", + "pushinfo": "", + "secret_key": "8C7THtrIigh2rPZQMbguugt8IUftWhMRCOBzbuyz", + "type": "duo", + "username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}", + "use_passcode": false + } +} +``` + +## Delete Duo MFA method + +This endpoint deletes a Duo MFA method. MFA methods can only be deleted if they're not currently in use +by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement). + +| Method | Path | +|:---------|:--------------------------------------| +| `DELETE` | `/identity/mfa/method/duo/:method_id` | + +### Parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/mfa/method/duo/4194659f-139b-400b-b5dd-86bfb726759d +``` + +## List Duo MFA methods + +This endpoint lists Duo MFA methods that are visible in the current namespace or in parent namespaces. + +| Method | Path | +|:-------|:---------------------------| +| `LIST` | `/identity/mfa/method/duo` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/mfa/method/duo +``` + +### Sample response + +```json +{ + "data": { + "keys": [ + "4194659f-139b-400b-b5dd-86bfb726759d" + ] + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/index.mdx new file mode 100644 index 0000000000..39923c3e19 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/index.mdx @@ -0,0 +1,27 @@ +--- +layout: api +page_title: /identity/mfa - HTTP API +description: >- + The '/identity/mfa' endpoint focuses on managing login MFA behaviors in Vault. +--- + +# `/identity/mfa` + +## Supported MFA types. + +- [TOTP](/vault/api-docs/secret/identity/mfa/totp) + +- [Okta](/vault/api-docs/secret/identity/mfa/okta) + +- [Duo](/vault/api-docs/secret/identity/mfa/duo) + +- [PingID](/vault/api-docs/secret/identity/mfa/pingid) + +## Other + +- [Login Enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement) +- [MFA Validate](/vault/api-docs/system/mfa/validate) + +While the above endpoints are available in all editions of Vault, +they are namespace aware. MFA methods and login enforcements created in one namespace are separate from other +namespaces. In the community version of Vault, everything operates in the root namespace. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/login-enforcement.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/login-enforcement.mdx new file mode 100644 index 0000000000..a122403666 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/login-enforcement.mdx @@ -0,0 +1,153 @@ +--- +layout: api +page_title: /identity/mfa/login-enforcement - HTTP API +description: >- + The '/identity/mfa/login-enforcement' endpoint focuses on specifying which MFA methods should be used + when logging in. +--- + +## Create a login enforcement + +This endpoint creates or updates a login enforcement that specifies which MFA methods should be used when logging into +Vault. If there are multiple login enforcements, each one needs to be satisfied before a login attempt succeeds. + +| Method | Path | +| :----- |:----------------------------------------| +| `POST` | `/identity/mfa/login-enforcement/:name` | + +### Parameters + +- `name` `(string: )` - Name for this login enforcement configuration. + +- `mfa_method_ids` `([]string: )` - Array of MFA method UUIDs to use. These will be ORed together, meaning +if several IDs are specified, any one of them is sufficient to login. + +- `auth_method_accessors` `([]string: [])` - Array of auth mount accessor IDs. If present, only auth methods +corresponding to the given accessors are checked during login. + +- `auth_method_types` `([]string: [])` - Array of auth method types. If present, only auth methods +corresponding to the given types are checked during login. + +- `identity_group_ids` `([]string: [])` - Array of identity group IDs. If present, only entities belonging +to one of the given groups are checked during login. Note that these IDs can be from the current namespace or +a child namespace. + +- `identity_entity_ids` `([]string: [])` - Array of identity entity IDs. If present, only entities with the given +IDs are checked during login. Note that these IDs can be from the current namespace or a child namespace. + +Note that while none of `auth_method_accessors`, `auth_method_types`, `identity_group_ids`, or `identity_entity_ids` is +individually required, at least one of those four fields must be present to create a login enforcement. + +### Sample payload + +```json +{ + "mfa_method_ids": ["134f7ce9-feae-4c6c-9ed7-ab3e413dbfce"], + "auth_method_accessors": ["auth_userpass_337fdb6a"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/login-enforcement/foo +``` + +## Read login enforcement + +This endpoint reads the login enforcement configuration for a given name. + +| Method | Path | +| :----- |:----------------------------------------| +| `GET` | `/identity/mfa/login-enforcement/:name` | + +### Parameters + +- `name` `(string: )` – Name of the login enforcement. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/mfa/login-enforcement/foo + +``` + +### Sample response + +```json +{ + "data": { + "auth_method_accessors": [ + "auth_userpass_337fdb6a" + ], + "auth_method_types": [], + "id": "24167a6c-759a-c596-6d48-391c89c4befc", + "identity_entity_ids": [], + "identity_group_ids": [], + "mfa_method_ids": [ + "c1372abf-bf64-1f26-c2a4-cbcfa135b775" + ], + "name": "foo", + "namespace_id": "root" + } +} +``` + +## Delete login enforcement + +This endpoint deletes a login enforcement configuration by the given name. + +| Method | Path | +| :------- |:----------------------------------------| +| `DELETE` | `/identity/mfa/login-enforcement/:name` | + +### Parameters + +- `name` `(string: )` - Name of the login enforcement. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/mfa/login-enforcement/foo + +``` + +## List login enforcements + +This endpoint lists login enforcements that are visible in the current namespace or in parent namespaces. + +| Method | Path | +|:-------|:----------------------------------| +| `LIST` | `/identity/mfa/login-enforcement` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/mfa/login-enforcement + +``` + +### Sample response + +```json +{ + "data": { + "keys": [ + "foo" + ] + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/okta.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/okta.mdx new file mode 100644 index 0000000000..7aac74a25a --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/okta.mdx @@ -0,0 +1,174 @@ +--- +layout: api +page_title: /identity/mfa/method/okta - HTTP API +description: >- + The '/identity/mfa/method/okta' endpoint focuses on managing Okta MFA behaviors in Vault. +--- + +## Create okta MFA method + +This endpoint creates a new MFA method of type Okta. + +| Method | Path | +|:-------|:----------------------------| +| `POST` | `/identity/mfa/method/okta` | + +### Parameters + +- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0. + +- `username_format` `(string)` - A format string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}@example.com"`. If blank, the Entity's Name field is used as-is. + +- `org_name` `(string: )` - Name of the organization to be used in the Okta API. + +- `api_token` `(string: )` - Okta API key. + +- `base_url` `(string)` - If set, will be used as the base domain for API requests. Examples are okta.com, oktapreview.com, and okta-emea.com. + +- `primary_email` `(bool: false)` - If set, the username will only match the primary email for the account. + +### Sample payload + +```json +{ + "username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}", + "org_name": "dev-262778", + "api_token": "0081u7KrReNkzmABZJAP2oDyIXccveqx9vIOEyCZDC" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/okta +``` + +### Sample response + +```json +{ + "data": { + "method_id": "0888fd69-4ea2-91d7-415e-c4bba548529b" + } +} +``` + +## Update okta MFA method + +This endpoint updates the configuration of an MFA method of type Okta. + +| Method | Path | +|:-------|:---------------------------------------| +| `POST` | `/identity/mfa/method/okta/:method_id` | + +### Parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +- and all of the parameters documented under the preceding "Create" endpoint. + +### Sample payload + +Identical to the preceding "Create" endpoint. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc +``` + +## Read okta MFA method + +This endpoint queries the MFA configuration of Okta type for a given method +name. + +| Method | Path | +|:-------|:---------------------------------------| +| `GET` | `/identity/mfa/method/okta/:method_id` | + +### Parameters + +- `method_id` `(string: )` – UUID of the MFA method. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc +``` + +### Sample response + +```json +{ + "data": { + "api_token": "0081u7KrReNkzmABZJAP2oDyIXccveqx9vIOEyCZDC", + "id": "1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc", + "name": "my_okta", + "org_name": "dev-262778", + "type": "okta", + "username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}" + } +} +``` + +## Delete okta MFA method + +This endpoint deletes a Okta MFA method. The MFA methods can only be deleted if they're not currently in use +by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement). + +| Method | Path | +|:---------|:---------------------------------------| +| `DELETE` | `/identity/mfa/method/okta/:method_id` | + +### Parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/mfa/method/okta/1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc +``` + +## List okta MFA methods + +This endpoint lists Okta MFA methods that are visible in the current namespace or in parent namespaces. + +| Method | Path | +|:-------|:----------------------------| +| `LIST` | `/identity/mfa/method/okta` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/mfa/method/okta +``` + +### Sample response + +```json +{ + "data": { + "keys": [ + "1db034b5-81f1-4a2b-8c2b-0f51ed0bd9fc" + ] + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/pingid.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/pingid.mdx new file mode 100644 index 0000000000..18b2061328 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/pingid.mdx @@ -0,0 +1,158 @@ +--- +layout: api +page_title: /identity/mfa/method/pingid - HTTP API +description: >- + The '/identity/mfa/method/pingid' endpoint focuses on managing PingID MFA behaviors in Vault. +--- + +## Create PingID MFA method + +This endpoint creates an MFA method of type PingID. + +| Method | Path | +|:-------|:------------------------------| +| `POST` | `/identity/mfa/method/pingid` | + +### Parameters + +- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0. + +- `username_format` `(string)` - A template string for mapping Identity names to MFA method names. Values to substitute should be placed in `{{}}`. For example, `"{{identity.entity.name}}@example.com"`. If blank, the Entity's Name field is used as-is. + +- `settings_file_base64` `(string: )` - A base64-encoded third-party settings file retrieved from PingID's configuration page. + +### Sample payload + +```json +{ + "username_format": "{{identity.entity.aliases.auth_userpass_1793464a.name}}", + "settings_file_base64": "AA8owj3..." +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/pingid +``` + +## Update PingID MFA method + +This endpoint updates the configuration of an MFA method of type PingID. + +| Method | Path | +|:-------|:-----------------------------------------| +| `POST` | `/identity/mfa/method/pingid/:method_id` | + +### Parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +- and all of the parameters documented under the preceding "Create" endpoint. + +### Sample payload + +Identical to the preceding "Create" endpoint. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233 +``` + +## Read PingID MFA method + +This endpoint queries the MFA configuration of PingID type for a given method +name. + +| Method | Path | +|:-------|:----------------------------------| +| `GET` | `/identity/mfa/method/pingid/:id` | + +### Parameters + +- `id` `(string: )` – UUID of the MFA method. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233 +``` + +### Sample response + +```json +{ + "data": { + "use_signature": true, + "idp_url": "https://idpxnyl3m.pingidentity.com/pingid", + "admin_url": "https://idpxnyl3m.pingidentity.com/pingid", + "authenticator_url": "https://authenticator.pingone.com/pingid/ppm", + "id": "f8381105-67f0-4105-8662-4b07ae5c1233", + "org_alias": "181459b0-9fb1-4938-8c86...", + "type": "pingid", + } +} +``` + +## Delete PingID MFA method + +This endpoint deletes a PingID MFA method. MFA methods can only be deleted if they're not currently in use +by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement). + +| Method | Path | +|:---------|:----------------------------------| +| `DELETE` | `/identity/mfa/method/pingid/:id` | + +### Parameters + +- `id` `(string: )` - UUID of the MFA method. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/mfa/method/pingid/f8381105-67f0-4105-8662-4b07ae5c1233 +``` + +## List PingID MFA methods + +This endpoint lists PingID MFA methods that are visible in the current namespace or in parent namespaces. + +| Method | Path | +|:-------|:------------------------------| +| `LIST` | `/identity/mfa/method/pingid` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/mfa/method/pingid +``` + +### Sample response + +```json +{ + "data": { + "keys": [ + "f8381105-67f0-4105-8662-4b07ae5c1233" + ] + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/totp.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/totp.mdx new file mode 100644 index 0000000000..244c620dbc --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/mfa/totp.mdx @@ -0,0 +1,355 @@ +--- +layout: api +page_title: /identity/mfa/method/totp - HTTP API +description: >- + The '/identity/mfa/method/totp' endpoint focuses on managing TOTP MFA behaviors in Vault. +--- + +## Create TOTP MFA method + +This endpoint creates an MFA method of type TOTP. + +| Method | Path | +|:-------|:----------------------------| +| `POST` | `/identity/mfa/method/totp` | + +### Request parameters + +- `method_name` `(string)` - The unique name identifier for this MFA method. Supported from Vault 1.13.0. + +- `issuer` `(string: )` - The name of the key's issuing organization. + +- `period` `(int or duration format string: 30)` - The length of time used to generate a counter for the TOTP token calculation. + +- `key_size` `(int: 20)` – Specifies the size in bytes of the generated key. + +- `qr_size` `(int: 200)` - The pixel size of the generated square QR code. + +- `algorithm` `(string: "SHA1")` – Specifies the hashing algorithm used to generate the TOTP code. Options include "SHA1", "SHA256" and "SHA512". + +- `digits` `(int: 6)` - The number of digits in the generated TOTP token. This value can either be 6 or 8. + +- `skew` `(int: 1)` - The number of delay periods that are allowed when validating a TOTP token. This value can either be 0 or 1. + +- `max_validation_attempts` `(int: 5)` - The maximum number of consecutive failed validation attempts. + +- `enable_self_enrollment` `(bool: false)` - When enabled, allows users to setup TOTP for their account by generating + a TOTP secret (QR code) during login if they do not already have one. + +### Sample payload + +```json +{ + "issuer": "vault" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/totp +``` + +## Update TOTP MFA method + +This endpoint updates the configuration of an MFA method of type TOTP. + +| Method | Path | +|:-------|:---------------------------------------| +| `POST` | `/identity/mfa/method/totp/:method_id` | + +### Path parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +### Request parameters + +All of the parameters documented under the preceding ["Create"](#create-totp-mfa-method) endpoint. + +### Sample payload + +Identical to the preceding "Create" endpoint. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/totp/1f36d4cf-52c9-475d-a5cd-49c573c54e55 +``` + +## Read TOTP MFA method + +This endpoint queries the MFA configuration of TOTP type for a given method +ID. + +| Method | Path | +|:-------|:---------------------------------------| +| `GET` | `/identity/mfa/method/totp/:method_id` | + +### Path parameters + +- `method_id` `(string: )` – UUID of the MFA method. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be +``` + +### Sample response + +```json +{ + "data": { + "algorithm": "SHA1", + "digits": 6, + "id": "4c6b1968-b385-4c46-ac5e-9b74e7b206be", + "issuer": "vault", + "key_size": 20, + "period": 30, + "qr_size": 200, + "skew": 1, + "type": "totp", + "namespace": "" + } +} +``` + +## Delete TOTP MFA method + +This endpoint deletes a TOTP MFA method. MFA methods can only be deleted if they're not currently in use +by a [login enforcement](/vault/api-docs/secret/identity/mfa/login-enforcement). + +| Method | Path | +|:---------|:---------------------------------------| +| `DELETE` | `/identity/mfa/method/totp/:method_id` | + +### Path parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/mfa/method/totp/4c6b1968-b385-4c46-ac5e-9b74e7b206be +``` + +## List TOTP MFA methods + +This endpoint lists TOTP MFA methods that are visible in the current namespace or in parent namespaces. + +| Method | Path | +|:-------|:----------------------------| +| `LIST` | `/identity/mfa/method/totp` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/mfa/method/totp +``` + +### Sample response + +```json +{ + "data": { + "keys": [ + "1f36d4cf-52c9-475d-a5cd-49c573c54e55", + "4c6b1968-b385-4c46-ac5e-9b74e7b206be" + ] + } +} +``` + +## Generate a TOTP MFA secret + +This endpoint generates an MFA secret in the entity of the calling token, if it +doesn't exist already, using the configuration stored under the given MFA +method ID. + +| Method | Path | +|:-------|:-------------------------------------| +| `POST` | `/identity/mfa/method/totp/generate` | + +### Request parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +### Sample payload + +```json +{ + "method_id": "1f36d4cf-52c9-475d-a5cd-49c573c54e55" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/totp/generate +``` + +### Sample response + +```json +{ + "data": { + "barcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGc0lEQVR4nOyd244bOQxEZxbz/7+cRQI4sLWiyCLlTU1wzkMAu1uXTIGSxUv3148fH2DEP396AvDK189/Pj97jR/W9Wi/fs7uz/pZya5H92dk40fzjeY1+XtiIWYgiBkIYsbX84dba7O6B0z3hmgPqO5Z6/WsH3VvynjuDwsxA0HMQBAzvnZfZueI6Pvs93r2+z6ax7qWZ+2zPSP7PutfPW8of08sxAwEMQNBzNjuISqRLyc7X6jnkex8UPVBqXtJxk2PORZiBoKYgSBmXNlDsriIeq6J+umeG1RfVjav7L4JWIgZCGIGgpix3UO6a6MaU4/OD9Fnda2P2qnxl2ge1fbKOFiIGQhiBoKY8bKHdH052V5Q3VPUz9n42XhR++zzStWXVgELMQNBzEAQM37tIbd9MtX4Qvc8EI13q32210Sfb8wHCzEDQcxAEDM+f6532e/86nmiPYk31X2sZP1Pz0PVGP+pPRZiBoKYgSBmbPeQ/9xUvP6geg7p9leNj3RrH7v1K+reRm7vNwBBzEAQM471IVmt3oN31V9E93Xr3KNx1BrD7t+jMl8sxAwEMQNBzDjm9lZj5d04gZoLHPX3rjjFu3J5T/8/LMQMBDEDQcyQ6kPUHNsH1TU+Gi/qr+rLmo6zfq6eTzr9YiFmIIgZCGLG5/M69y5fzfr9Ol613bQ/NaYe9bui5gKczmNYiBkIYgaCmHF85mK01t2KO2Q1h9l43dzgbhxG7b+zZ2EhZiCIGQhiRuvZ77dygNVY+3q9es5Qv1+vT2sIlb0OCzEDQcxAEDMkX1bXN7S2z8brxl2q40b3rXR9bxn4sr4RCGIGgpjxUh8S0a2feFdNYrd/Ndad9Xsrpv/cHgsxA0HMQBAzPk/reXdN7fqA3ln/PZnndE9SxsFCzEAQMxDEjJd4iJqrqtYiPlBr9qZE81znk7V/F8TUjUEQMxDEjO1ze9U1PqtFzO5X87VW1H6i+XXqyneQl/UXgSBmIIgZpdzebgxdPWdMfVnr/dHn23XsWb18VpP4DBZiBoKYgSBmbPOyukzr2Lvnlu781FzkaF7deezAQsxAEDMQxIxjTP33TcN8JpXqOOp9qg8tm586n8qehYWYgSBmIIgZrfcYZvGPW2tztZ0aj8nGzb7Prnfr5z+wED8QxAwEMaP0PvVpzV63zru6pld//6t7SvRZzXmO5rPrBwsxA0HMQBAzpGeddH08WT/VNTv6vZ/NJxp/Wh8S9ZvN5/T/x0LMQBAzEMSMY0y9mpdV3YPU+pNsnGm+1v9dyxhBjaExCGIGgpixPYdUzwUdf/8JNV+qu3dE/aj9Z/Un0XzWcTiHGIMgZiCIGaX3qf+++fLe0f0dP83FVfO0VNS9jXOIMQhiBoKY8esc0vUBqb4ttY49Q13js/uzPKsuSr4XFmIGgpiBIGaM8rKmz0bJxo36nZ5Xov6zcbvnFqWWEQsxA0HMQBAzSs9cXKneH8ULpnUV0/lle0Y3DqOOv2uPhZiBIGYgiBnbOvVunfdKNyf2to9L9UV1Y/Tr/ep5iXiIIQhiBoKYcczLys4P1b2lGwNf23dr99Q8rqnvrOvr+sBC/EAQMxDEjG1M/UHXFxWhxAUq31evd5nmjWU+MvKyvgEIYgaCmLF9F+7Ul7TSrbdQzw/qeOv9K7f+v0o7LMQMBDEDQcw4vj8kYlpf3vUFZe2jeVbbVX1Y1fE6eyAWYgaCmIEgZmyfdVL9XT7NAb5F9xyh7n3Tc1IlToKFmIEgZiCIGaV3UHXrv6P23fyubj1K1l80zwg17yq6vhsfCzE DQcxAEDOOz+2troUZaq1hNP40lr/eP61TicbP5nO6joWYgSBmIIgZx7ysiNu+ruj6dB5q7D4ii5Oo82EP+UYgiBkIYob0/pCV2/Uda7/TunX1PJHNq9qvGvN/HgcLMQNBzEAQM1p5WdM6kI mv5zReNo9uvtet+WTz+sBC/EAQMxDEjO0zF99dA9it+6jOM7qe+dKqde7V/qP5nP5eWIgZCGIGgpix3UNUbsXkq/Xd2Thd35zqE5v66Hb9YCFmIIgZCGLGlT3kwS1fUbcGsVq3HvUXnY/U+ ExEZW/DQsxAEDMQxIzS+0Mybq3REd1c3ur5qBs7z/a4zjNWsBAzEMQMBDHjZQ+Z+oAeqGv42o9aq5j1m5HN51ZdfWX+WIgZCGIGgpixfX8I/DmwEDP+DQAA//9kwGH4xZewMgAAAABJRU5E rkJggg==", + "url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&period=30&secret=XVE7TOZWJVEWQOATOD7 U53IEAJG72Z2I" + } +} +``` + +## Administratively generate a TOTP MFA secret + +This endpoint can be used to generate a TOTP MFA secret. Unlike the `generate` +API which stores the generated secret on the entity ID of the calling token, +the `admin-generate` API stores the generated secret on the given entity ID. + +| Method | Path | +|:-------|:-------------------------------------------| +| `POST` | `/identity/mfa/method/totp/admin-generate` | + +### Request parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +- `entity_id` `(string: )` - Entity ID on which the generated secret + needs to get stored. + +### Sample payload + +```json +{ + "method_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4", + "entity_id": "9189f7fd-e3f5-436b-a835-cb14864b1e01" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json + http://127.0.0.1:8200/v1/identity/mfa/method/totp/admin-generate +``` + +### Sample response + +```json +{ + "data": { + "barcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGZElEQVR4nOyd7W4jNwxFkyLv/8pbpMAAHnUo8pJyc1Oc82OB2KOP9QVFSyTlrz9/PsCIv356AnDn6/ufz89e48i6ov6u59f319ezfqtWnf2/snHX19XnVL7bYyFmIIgZCGLG5/e61V2b37WWXkRr9+lxonEvqv1XfeHK6/NYiBkIYgaCmPH19GK2j4ieX9/P9h0R2T6l+pzqYzKfmM0zQvk8sRAzEMQMBDHj0YdMqa6Z1TOvyDdF/VTPnqLnVzIfePLEHAsxA0HMQBAz3uJDqvuVbO1Vv/934yzReNV4ykmwEDMQxAwEMePRh5xeG6fxjNXnVM+Y1HHVM7Tq56R8nliIGQhiBoKYcfMhp2LT6hp7UY2hV8dTY/KZT1N9SufzxELMQBAzEMSMf3zI6X2HembUXbuz8dT9g+qLIiafJxZiBoKYgSBm3OpDunlMartTubrdeEUWI1dzAqa5wK9gIWYgiBkIYsaReIi6P1jbqd/7qznDqm9SfcKJs6sVLMQMBDEDQcz43K3z3fqLaf336fiFymQf8dRe8aVYiBkIYgaCmHHzIdW8pGo8QT1rOuULTvkc9a6TqD+lTgULMQNBzEAQMx7jIRdqjV7ULvpbrReJxl/nodYodseLxu/GWz6wED8QxAwEMeN2X9ZK9/4neRLDNfrUc919yPp8t/8PLMQPBDEDQcyQ6tTVO0JWqvGT6PWu75jub6L+T/kg4iHGIIgZCGLGKB5yKn5SpVuDWKXrI0/4jgssxAwEMQNBzNieZWV0v/erZ0Knxp3OYxoXqoyPhZiBIGYgiBmPub1q7m7G6fiB2n+3niSbZwT7kP8RCGIGgpjxeF9W5iPU8/+ofUY1r6q6ZkfzmtbJV2skozw04iHGIIgZCGKGlJeVvZ61V+MX07OiqJ9oftE41fGm9TD4EEMQxAwEMaN010lW1zGNoVfX+OrZl/rcfx0P2c0XCzEDQcxAEDMe87K68YBubH7tdxonmcb0q+2qZ2DK/gkLMQNBzEAQM2516lXUs6GIbA3v+qruPinrX/Ud0Xx288JCzEAQMxDEjG2NYXf/odztsXuuEoOu9BO93933RONm86n0h4WYgSBmIIgZt9+gqtaDq7m3K2rObnc+UT/Z36f2MZ28MCzEDAQxA0HMaJ1lTevBo/5OxRsysv1O9Fx1nO4Z3QcW4geCmIEgZki/H1Klu+Z369PVeVXHexfEQ34RCGIGgpjxWGN40c1VXdtXaxW79SLTOvqonVpDqdavkNv7C0AQMxDEjNK9vdP4gFq3ntV1Z+NEf099ZEZ1vrv+sBAzEMQMBDFjW2PYjT9U4xqqT1D7/ak4j5rn9QoWYgaCmIEgZpTu7e2u5Vk/4aQO3XFSHUc9s1rnNfVdr/1hIWYgiBkIYsZtH6LGA9Z20d8Z3fuq1HyqUznC1fZVX0c8xBgEMQNBzNje2xvxrlzYan1K1H82fjXOUfU12XzW5yufBxZiBoKYgSBmSL+FezE9s1lR9yHq2VvUT7fefOpjd58fFmIGgpiBIGZId52sr6u5u9M7RtTn1Hmr8ZzqnSvK2R4WYgaCmIEgZmzjIdHr3Rzfi278I3pdvStFrWVUfU52d8quPRZiBoKYgSBmbOvU//Xwobr1U7FpNV8qatetm4+onvU9jYuFmIEgZiCIGbf7srLv1d01vLsWqzmzapymeyaWfQ5qXtsrWIgZCGIGgphR+g2q9f0V9Y6SartsXtP8qOmZWDTe5AwMCzEDQcxAEDMeY+rVfUj0fLddN9Y+3feodfPd+pnKvLAQMxDEDAQxY1unPo11q+2i8adxCXV+an/qfHbzwELMQBAzEMQMKaYediL6FDVmruaBTWsU1bMwdT67/zcWYgaCmIEgZrR+g+piPata18Tu9/Zurq5aTxLNV833qs6nMg8sxAwEMQNBzHisD8lQ6y3W/qt3kpyuS8/ez3xiNL/qfMjL+oUgiBkIYkYppn7R9THd56s5tBGn60myfcSJ3GMsxAwEMQNBzGjdlxXRja1068mj9tla3c3DysaLxon+fgILMQNBzEAQM476kG5c5aJ7BnS6bqX6+jS/jLysXwCCmIEgZmx/x7DK6btCurF31WdMawPfkXOMhZiBIGYgiBmPvx+iUo2RV/vp3llSpZuXpfqgbNwnsBAzEMQMBDHjSH0InAMLMePvAAAA//8x2VnbmmL6HQAAAABJRU5ErkJggg==", + "url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&period=30&secret=6HQ4RZ7GM6MMLRKVDCI23LXNZF7UDZ2U" + } +} +``` + +### Administratively destroy TOTP MFA secret + +This endpoint deletes a TOTP MFA secret from the given entity ID. + +To overwrite a secret on the entity, +explicitly deleting the secret first is required. This API can be used to delete the secret +and the `generate` or `admin-generate` APIs should be used to regenerate a new +secret. + +| Method | Path | +|:-------|:------------------------------------------| +| `POST` | `/identity/mfa/method/totp/admin-destroy` | + +### Request parameters + +- `method_id` `(string: )` - UUID of the MFA method. + +- `entity_id` `(string: )` - Entity ID from which the MFA secret + should be removed. + +### Sample payload + +```json +{ + "method_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4", + "entity_id": "9189f7fd-e3f5-436b-a835-cb14864b1e01" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/totp/admin-destroy +``` + +## Self-enroll in TOTP MFA + +The self-enroll endpoint lets users setup TOTP MFA by generating a TOTP +secret (QR code) during login if they do not already have one. To use +self-enrollment you must set [`enable_self_enrollment`](./totp#enable_self_enrollment) to `true` for the TOTP MFA +method. + +| Method | Path | +|:-------|:----------------------------------------| +| `POST` | `/identity/mfa/method/totp/self-enroll` | + +### Request parameters + +- `mfa_request_id` `(string: )` - The unique identifier of an MFA + requirement in the authentication response of a login request. + +- `mfa_method_id` `(string: )` - UUID of the MFA method. + +### Sample payload + +```json +{ + "mfa_request_id": "5879c74a-1418-1948-7be9-97b209d693a7", + "mfa_method_id": "4746fb81-028c-cd4e-026b-7dd18fe4c2f4" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/mfa/method/totp/self-enroll +``` + +### Sample response + +```json +{ + "data": { + "barcode": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADIEAAAAADYoy0BAAAGZElEQVR4nOyd7W4jNwxFkyLv/8pbpMAAHnUo8pJyc1Oc82OB2KOP9QVFSyTlrz9/PsCIv356AnDn6/ufz89e48i6ov6u59f319ezfqtWnf2/snHX19XnVL7bYyFmIIgZCGLG5/e61V2b37WWXkRr9+lxonEvqv1XfeHK6/NYiBkIYgaCmPH19GK2j4ieX9/P9h0R2T6l+pzqYzKfmM0zQvk8sRAzEMQMBDHj0YdMqa6Z1TOvyDdF/VTPnqLnVzIfePLEHAsxA0HMQBAz3uJDqvuVbO1Vv/934yzReNV4ykmwEDMQxAwEMePRh5xeG6fxjNXnVM+Y1HHVM7Tq56R8nliIGQhiBoKYcfMhp2LT6hp7UY2hV8dTY/KZT1N9SufzxELMQBAzEMSMf3zI6X2HembUXbuz8dT9g+qLIiafJxZiBoKYgSBm3OpDunlMartTubrdeEUWI1dzAqa5wK9gIWYgiBkIYsaReIi6P1jbqd/7qznDqm9SfcKJs6sVLMQMBDEDQcz43K3z3fqLaf336fiFymQf8dRe8aVYiBkIYgaCmHHzIdW8pGo8QT1rOuULTvkc9a6TqD+lTgULMQNBzEAQMx7jIRdqjV7ULvpbrReJxl/nodYodseLxu/GWz6wED8QxAwEMeN2X9ZK9/4neRLDNfrUc919yPp8t/8PLMQPBDEDQcyQ6tTVO0JWqvGT6PWu75jub6L+T/kg4iHGIIgZCGLGKB5yKn5SpVuDWKXrI0/4jgssxAwEMQNBzNieZWV0v/erZ0Knxp3OYxoXqoyPhZiBIGYgiBmPub1q7m7G6fiB2n+3niSbZwT7kP8RCGIGgpjxeF9W5iPU8/+ofUY1r6q6ZkfzmtbJV2skozw04iHGIIgZCGKGlJeVvZ61V+MX07OiqJ9oftE41fGm9TD4EEMQxAwEMaN010lW1zGNoVfX+OrZl/rcfx0P2c0XCzEDQcxAEDMe87K68YBubH7tdxonmcb0q+2qZ2DK/gkLMQNBzEAQM2516lXUs6GIbA3v+qruPinrX/Ud0Xx288JCzEAQMxDEjG2NYXf/odztsXuuEoOu9BO93933RONm86n0h4WYgSBmIIgZt9+gqtaDq7m3K2rObnc+UT/Z36f2MZ28MCzEDAQxA0HMaJ1lTevBo/5OxRsysv1O9Fx1nO4Z3QcW4geCmIEgZki/H1Klu+Z369PVeVXHexfEQ34RCGIGgpjxWGN40c1VXdtXaxW79SLTOvqonVpDqdavkNv7C0AQMxDEjNK9vdP4gFq3ntV1Z+NEf099ZEZ1vrv+sBAzEMQMBDFjW2PYjT9U4xqqT1D7/ak4j5rn9QoWYgaCmIEgZpTu7e2u5Vk/4aQO3XFSHUc9s1rnNfVdr/1hIWYgiBkIYsZtH6LGA9Z20d8Z3fuq1HyqUznC1fZVX0c8xBgEMQNBzNje2xvxrlzYan1K1H82fjXOUfU12XzW5yufBxZiBoKYgSBmSL+FezE9s1lR9yHq2VvUT7fefOpjd58fFmIGgpiBIGZId52sr6u5u9M7RtTn1Hmr8ZzqnSvK2R4WYgaCmIEgZmzjIdHr3Rzfi278I3pdvStFrWVUfU52d8quPRZiBoKYgSBmbOvU//Xwobr1U7FpNV8qatetm4+onvU9jYuFmIEgZiCIGbf7srLv1d01vLsWqzmzapymeyaWfQ5qXtsrWIgZCGIGgphR+g2q9f0V9Y6SartsXtP8qOmZWDTe5AwMCzEDQcxAEDMeY+rVfUj0fLddN9Y+3feodfPd+pnKvLAQMxDEDAQxY1unPo11q+2i8adxCXV+an/qfHbzwELMQBAzEMQMKaYediL6FDVmruaBTWsU1bMwdT67/zcWYgaCmIEgZrR+g+piPata18Tu9/Zurq5aTxLNV833qs6nMg8sxAwEMQNBzHisD8lQ6y3W/qt3kpyuS8/ez3xiNL/qfMjL+oUgiBkIYkYppn7R9THd56s5tBGn60myfcSJ3GMsxAwEMQNBzGjdlxXRja1068mj9tla3c3DysaLxon+fgILMQNBzEAQM476kG5c5aJ7BnS6bqX6+jS/jLysXwCCmIEgZmx/x7DK6btCurF31WdMawPfkXOMhZiBIGYgiBmPvx+iUo2RV/vp3llSpZuXpfqgbNwnsBAzEMQMBDHjSH0InAMLMePvAAAA//8x2VnbmmL6HQAAAABJRU5ErkJggg==", + "url": "otpauth://totp/vault:4746fb81-028c-cd4e-026b-7dd18fe4c2f4?algorithm=SHA1&digits=6&issuer=vault&period=30&secret=6HQ4RZ7GM6MMLRKVDCI23LXNZF7UDZ2U" + } +} +``` \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/oidc-provider.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/oidc-provider.mdx new file mode 100644 index 0000000000..db46867d96 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/oidc-provider.mdx @@ -0,0 +1,834 @@ +--- +layout: api +page_title: 'OIDC Identity Provider' +description: >- + This is the API documentation for configuring and managing OIDC providers with Vault. +--- + +## Create or update a provider + +This endpoint creates or updates a Provider. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `identity/oidc/provider/:name` | + +### Parameters + +- `name` `(string: )` – The name of the provider. This parameter is specified as part of the URL. + +- `issuer` `(string: )` - Specifies what will be used as the `scheme://host:port` component for the `iss` claim of ID tokens. This defaults to a URL with + Vault's `api_addr` as the `scheme://host:port` component and `/v1/:namespace/identity/oidc/provider/:name` as the path + component. If provided explicitly, it must point to a Vault instance that is network reachable by clients for ID token validation. + +- `allowed_client_ids` `([]string: )` – The client IDs that are permitted to use the provider. If empty, no clients are allowed. If `"*"` is provided, all clients are allowed. + +- `scopes_supported` `([]string: )` – The scopes available for requesting on the provider. + +### Sample payload + +```json +{ + "allowed_client_ids": ["*"], + "scopes_supported": ["test-scope"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider +``` + +## Read provider by name + +This endpoint queries the OIDC provider by its name. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/identity/oidc/provider/:name` | + +### Parameters + +- `name` `(string: )` – The name of the provider. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider +``` + +### Sample response + +```json +{ + "data": { + "allowed_client_ids":["*"], + "issuer":"", + "scopes_supported":["test-scope"] + } +} +``` + +## List providers + +This endpoint returns a list of all OIDC providers. + +| Method | Path | +| :----- | :------------------------------ | +| `LIST` | `/identity/oidc/provider` | + +### Query parameters + +- `allowed_client_id` `(string: )` – Filters the list of OIDC providers to those + that allow the given client ID in their set of [allowed_client_ids](/vault/api-docs/secret/identity/oidc-provider#allowed_client_ids). + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/oidc/provider +``` + +### Sample response + +```json +{ + "data": { + "key_info": { + "default": { + "allowed_client_ids": [ + "*" + ], + "issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/default", + "scopes_supported": [] + } + }, + "keys": [ + "default" + ] + } +} +``` + +## Delete provider by name + +This endpoint deletes an OIDC provider. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `/identity/oidc/provider/:name` | + +### Parameters + +- `name` `(string: )` – The name of the provider. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider +``` + +## Create or update a scope + +This endpoint creates or updates a scope. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `identity/oidc/scope/:name` | + +### Parameters + +- `name` `(string: )` – The name of the scope. This parameter is specified as part of the URL. The `openid` scope name is reserved. + +- `template` `(string: )` - The [JSON template](/vault/docs/concepts/oidc-provider#scopes) + string for the scope. This may be provided as escaped JSON or base64 encoded JSON. + +- `description` `(string: )` – A description of the scope. + +### Sample payload + +```json +{ + "template":"{ \"groups\": {{identity.entity.groups.names}} }", + "description":"A simple scope example." +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope +``` + +## Read scope by name + +This endpoint queries a scope by its name. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/identity/oidc/scope/:name` | + +### Parameters + +- `name` `(string: )` – The name of the scope. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope +``` + +### Sample response + +```json +{ + "data": { + "description":"A simple scope example.", + "template":"{ \"groups\": {{identity.entity.groups.names}} }" + } +} +``` + +## List scopes + +This endpoint returns a list of all configured scopes. + +| Method | Path | +| :----- | :------------------------------ | +| `LIST` | `/identity/oidc/scope` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/oidc/scope +``` + +### Sample response + +```json +{ + "data": { + "keys":[ + "test-scope" + ] + } +} +``` + +## Delete scope by name + +This endpoint deletes a scope. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `/identity/oidc/scope/:name` | + +### Parameters + +- `name` `(string: )` – The name of the scope. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/oidc/scope/test-scope +``` + +## Create or update a client + +This endpoint creates or updates a client. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `identity/oidc/client/:name` | + +### Parameters + +- `name` `(string: )` – The name of the client. This parameter is specified as part of the URL. + +- `key` `(string: "default")` – A reference to a [named key](/vault/api-docs/secret/identity/tokens#create-a-named-key) + resource. This key will be used to sign ID tokens for the client. This cannot be modified + after creation. If not supplied, defaults to the built-in [default key](/vault/docs/concepts/oidc-provider#keys). + +- `redirect_uris` `([]string: )` - Redirection URI values used by the client. One of these values + must exactly match the `redirect_uri` parameter value used in each [authentication request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest). + +- `assignments` `([]string: )` – A list of assignment resources associated with + the client. Client assignments limit the Vault entities and groups that are allowed to + authenticate through the client. By default, no Vault entities are allowed. To allow all + Vault entities to authenticate through the client, supply the built-in + [allow_all](/vault/docs/concepts/oidc-provider#assignments) assignment. + +- `client_type` `(string: "confidential")` – The [client type](https://datatracker.ietf.org/doc/html/rfc6749#section-2.1) + based on its ability to maintain confidentiality of credentials. This cannot be modified + after creation. The following list details the differences between confidential and public + clients in Vault: + - `confidential` + - Capable of maintaining the confidentiality of its credentials + - Has a client secret + - Uses the `client_secret_basic` or `client_secret_post` [client authentication method](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) + - May use Proof Key for Code Exchange ([PKCE](https://datatracker.ietf.org/doc/html/rfc7636)) + for the authorization code flow + - `public` + - Not capable of maintaining the confidentiality of its credentials + - Does not have a client secret + - Uses the `none` [client authentication method](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) + - Must use Proof Key for Code Exchange ([PKCE](https://datatracker.ietf.org/doc/html/rfc7636)) + for the authorization code flow + +- `id_token_ttl` `(int or duration: "24h")` – The time-to-live for ID tokens obtained by the client. + Accepts [duration format strings](/vault/docs/concepts/duration-format). The value should be less than the `verification_ttl` + on the key. + +- `access_token_ttl` `(int or duration: "24h")` – The time-to-live for access tokens obtained by the client. + Accepts [duration format strings](/vault/docs/concepts/duration-format). + +### Sample payload + +```json +{ + "key":"test-key", + "access_token_ttl":"30m", + "id_token_ttl":"1h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/client/test-client +``` + +## Read client by name + +This endpoint queries a client by its name. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/identity/oidc/client/:name` | + +### Parameters + +- `name` `(string: )` – The name of the client. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/identity/oidc/client/test-client +``` + +### Sample response + +```json +{ + "data":{ + "access_token_ttl":1800, + "assignments":[], + "client_id":"014zXvcvbvIZWwD5NfD1Uzmv7c5JBRMb", + "client_secret":"hvo_secret_bZtgQPBZaJXK7F5vOI7JlvEuLOfOUS7DmwynFjE3xKcsen7TyowqPFfYFXG2tbWM", + "client_type": "confidential", + "id_token_ttl":3600, + "key":"test-key", + "redirect_uris":[] + } +} +``` + +## List clients + +This endpoint returns a list of all configured clients. + +| Method | Path | +| :----- | :------------------------------ | +| `LIST` | `/identity/oidc/client` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/oidc/client +``` + +### Sample response + +```json +{ + "data": { + "key_info": { + "my-app": { + "access_token_ttl": 86400, + "assignments": [ + "allow_all" + ], + "client_id": "wGr981oYLJbcr4zrUriYxjxSc80JL7HW", + "client_type": "confidential", + "id_token_ttl": 86400, + "key": "default", + "redirect_uris": [ + "http://localhost:5555/callback" + ] + } + }, + "keys": [ + "my-app" + ] + } +} +``` + +## Delete client by name + +This endpoint deletes a client. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `/identity/oidc/client/:name` | + +### Parameters + +- `name` `(string: )` – The name of the client. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/oidc/client/test-client +``` + +## Create or update an assignment + +This endpoint creates or updates an assignment. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `identity/oidc/assignment/:name` | + +### Parameters + +- `name` `(string: )` – The name of the assignment. This parameter is specified as part of the URL. + +- `entity_ids` `([]string: )` - A list of Vault [entity](/vault/docs/secrets/identity#entities-and-aliases) IDs. + +- `group_ids` `([]string: )` – A list of Vault [group](/vault/docs/secrets/identity#identity-groups) IDs. + +### Sample payload + +```json +{ + "group_ids":["262ca5b9-7b69-0a84-446a-303dc7d778af"], + "entity_ids":["b6094ac6-baf4-6520-b05a-2bd9f07c66da"] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment +``` + +## Read assignment by name + +This endpoint queries an assignment by its name. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/identity/oidc/assignment/:name` | + +### Parameters + +- `name` `(string: )` – The name of the assignment. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment +``` + +### Sample response + +```json +{ + "data":{ + "entity_ids":[ + "b6094ac6-baf4-6520-b05a-2bd9f07c66da" + ], + "group_ids":[ + "262ca5b9-7b69-0a84-446a-303dc7d778af" + ] + } +} +``` + +## List assignments + +This endpoint returns a list of all configured assignments. + +| Method | Path | +| :----- | :------------------------------ | +| `LIST` | `/identity/oidc/assignment` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/oidc/assignment +``` + +### Sample response + +```json +{ + "data": { + "keys":[ + "test-assignment" + ] + } +} +``` + +## Delete assignment by name + +This endpoint deletes an assignment. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `/identity/oidc/assignment/:name` | + +### Parameters + +- `name` `(string: )` – The name of the assignment. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/oidc/assignment/test-assignment +``` + +## Read provider OpenID configuration + +Returns OpenID Connect Metadata for a named OIDC provider. The response is a +compliant [OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse). + +| Method | Path | +| :----- | :--------------------------------------------------------------- | +| `GET` | `/identity/oidc/provider/:name/.well-known/openid-configuration` | + +### Parameters + +- `name` `(string: )` – The name of the provider. This parameter is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/openid-configuration +``` + +### Sample response + +```json +{ + "issuer": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider", + "jwks_uri": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/keys", + "authorization_endpoint": "http://127.0.0.1:8200/ui/vault/identity/oidc/provider/test-provider/authorize", + "token_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/token", + "userinfo_endpoint": "http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/userinfo", + "request_parameter_supported": false, + "request_uri_parameter_supported": false, + "id_token_signing_alg_values_supported": [ + "RS256", + "RS384", + "RS512", + "ES256", + "ES384", + "ES512", + "EdDSA" + ], + "response_types_supported": [ + "code" + ], + "scopes_supported": [ + "openid" + ], + "subject_types_supported": [ + "public" + ], + "grant_types_supported": [ + "authorization_code" + ], + "token_endpoint_auth_methods_supported": [ + "client_secret_basic", + "client_secret_post", + "none" + ], + "code_challenge_methods_supported": [ + "plain", + "S256" + ] +} +``` + +## Read provider public keys + +Query this path to retrieve the public portion of keys for an OIDC provider. +Clients can use them to validate the authenticity of an identity token. + +| Method | Path | +| :----- | :----------------------------------------------- | +| `GET` | `/identity/oidc/provider/:name/.well-known/keys` | + +### Parameters + +- `name` `(string: )` – The name of the provider. This parameter is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/.well-known/keys +``` + +### Sample response + +```json +{ + "keys": [ + { + "use": "sig", + "kty": "RSA", + "kid": "ee7c0920-fdb9-5c1a-9c69-6dab710d1a09", + "alg": "RS256", + "n": "zdFjUV9lBw5nQPvTtwH-gzKgRG7iepvYbFoc2hNB0-inJL25oh-mvNW3GS8jPY5XHLsiWa_1TKKE99JrKQgane2C96soFeOvR7SozbCeH8_FpZelH1Pym1NV038j05Vp87uB9FeKPsy1PNOLPTs_Fp42JIAenly7ojYwPp1s61p9V0U9rOhtldY7GkXHLN9s8v3aJjxqrTS3Puhs9MFS7EgRrEDAc69uiLXCoYXKygjXddvJi6j446XxnO2eTRMGl1f2t04s_vDgVnFQgjQSKYWPbOMhf2slkeR47fqE3qqUDzINxauqMbkW-PlLP9IN0crR2uC07cG2os4RxN4YHw", + "e": "AQAB" + }, + { + "use": "sig", + "kty": "RSA", + "kid": "6e468221-b7c2-9d2d-744d-33b7ae0357cb", + "alg": "RS256", + "n": "rMaucILJKiFg_lkCE8ZEV_8jiYdaVDjKkc-8XPBW8S34wIRl1EbsgCYfMHtJnIJ_3eUgOVorW5KVeN9C8W16LR3lhqRWS9y4qlt0AcWpOvsmxr5q5dS_QqgCjeftCKwJzUsMi5bMW8wKjRZdd-qLz6X1rVSZWX82G0So8nRBg9d3MNJbKcdIJrRbrxWkm8U9xMqRouzbyQ2Hsp2rRVgGh7yjEA6daI5Ao8UsPdBmlCM9oKZ1_Kje5JTfZKeHlT-58vn_ylCjMVlapLuUsDN6He2kPVyOzGbie297VOfjmB7QX0ah1f7Ni1UJFJYHrVK9wMfCLTltSFZBcQ9--FlVdQ", + "e": "AQAB" + } + ]} +``` + +## Authorization endpoint + +Provides the [Authorization Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#AuthorizationEndpoint) +for an OIDC provider. This allows OIDC clients to request an authorization code +to be used for the [Authorization Code Flow](https://openid.net/specs/openid-connect-core-1_0.html#CodeFlowAuth). + +| Method | Path | +| :---------- | :---------------------------------------- | +| `GET/POST` | `/identity/oidc/provider/:name/authorize` | + +### Parameters + +- `name` `(string: )` - The name of the provider. This parameter is specified as part of the URL. + +- `scope` `(string: )` - A space-delimited list of scopes to be requested. The `openid` scope is required. + +- `response_type` `(string: )` - The OIDC authentication flow to be used. The following response types are supported: `code`. + +- `client_id` `(string: )` - The ID of the requesting client. + +- `redirect_uri` `(string: )` - The redirection URI to which the response will be sent. + +- `state` `(string: )` - A value used to maintain state between the authentication request and client. + +- `nonce` `(string: )` - A value that is returned in the ID token nonce claim. It is used to mitigate replay attacks, so we *strongly encourage* providing this optional parameter. + +- `max_age` `(integer: )` - The allowable elapsed time in seconds since the last + time the end-user was actively authenticated. + +- `code_challenge` `(string: )` - The [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) + code challenge derived from the client's code verifier. Optional for `confidential` clients. + Required for `public` clients. + +- `code_challenge_method` `(string: "plain")` - The method that was used to derive the + [PKCE](https://datatracker.ietf.org/doc/html/rfc7636) code challenge. The following + methods are supported: `S256`, `plain`. + +### Sample request + +```shell-session +$ curl \ + --request GET \ + --header "X-Vault-Token: ..." \ + -G \ + -d "response_type=code" \ + -d "client_id=$CLIENT_ID" \ + -d "state=af0ifjsldkj" \ + -d "nonce=abcdefghijk" \ + --data-urlencode "scope=openid" \ + --data-urlencode "redirect_uri=http://127.0.0.1:8251/callback" \ + http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/authorize +``` + +### Sample response + +```json +{ + "code": "BDSc9kVYljxND93YpveBuJtSvguM3AWe", + "state": "af0ifjsldkj" +} +``` + +## Token endpoint + +Provides the [Token Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#TokenEndpoint) +for an OIDC provider. + +| Method | Path | +| :------ | :------------------------------------ | +| `POST` | `/identity/oidc/provider/:name/token` | + +### Parameters + +- `name` `(string: )` - The name of the provider. This parameter is + specified as part of the URL. + +- `code` `(string: )` - The authorization code received from the + provider's authorization endpoint. + +- `grant_type` `(string: )` - The authorization grant type. The + following grant types are supported: `authorization_code`. + +- `redirect_uri` `(string: )` - The callback location where the + authorization request was sent. This must match the `redirect_uri` used when the + original authorization code was generated. + +- `client_id` `(string: )` - The ID of the requesting client. This parameter + is required for `public` clients which do not have a client secret or `confidential` + clients using the `client_secret_post` client authentication method. + +- `client_secret` `(string: )` - The secret of the requesting client. This + parameter is required for `confidential` clients using the `client_secret_post` client + authentication method. + +- `code_verifier` `(string: )` - The code verifier associated with the given + `code`. Required for authorization codes that were granted using [PKCE](https://datatracker.ietf.org/doc/html/rfc7636). + Required for `public` clients. + +### Headers + +- `Authorization: Basic` `(string: )` - An HTTP Basic authentication scheme header + including the `client_id` and `client_secret` as described in the [client_secret_basic](https://openid.net/specs/openid-connect-core-1_0.html#ClientAuthentication) + authentication method. This header is only required for `confidential` clients using + the `client_secret_basic` client authentication method. + +### Sample request + +```shell-session +$ BASIC_AUTH_CREDS=$(printf "%s:%s" "$CLIENT_ID" "$CLIENT_SECRET" | base64) +$ curl \ + --request POST \ + --header "Authorization: Basic $BASIC_AUTH_CREDS" \ + -H 'Content-Type: application/x-www-form-urlencoded' \ + -d "code=4RL50r78p8HsNJY0GVUNGfjLHnpkRf3N" \ + -d "grant_type=authorization_code" \ + -d "redirect_uri=http://127.0.0.1:8251/callback" \ + http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/token +``` + +### Sample response + +```json +{ + "access_token": "b.AAAAAQJEH5VXjfjUESCwySTKk2MS1MGVNc9oU-N2EyoLKVo9SYa-NnOWAXloYfrlO45UWC3R1PC5ZShl3JdmRJ0264julNnlBduSNXJkYjgCQsFQwXTKHcjhqdNsmJNMWiPaHPn5NLSpNQVtzAxfHADt4r9rmX-UEG5seOWbmK_Z5WwS_4a8-wcVPB7FpOGzfBydP7yMxHu-3H1TWyQvYVr28XUfYxcBbdlzxhJn0yqkWItgmZ25xEOp7SW7Pg4tYB7AXfk", + "expires_in": 3600, + "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImEzMjk5ZWVmLTllNDEtOGNiYS1kNWExLTZmZWM2NjIyODRjYyJ9.eyJhdF9oYXNoIjoiMUdlQlEzUFdtUjJ2ajZVU2swSW42USIsImF1ZCI6InpTSktMVmk0R1BYS1o3TTZzUUEwY3FNc05VaHNPYkVTIiwiY19oYXNoIjoiN09SOUszNmhNdllENzJkUkFLUHhNdyIsImNvbnRhY3QiOnsiZW1haWwiOiJ2YXVsdEBoYXNoaWNvcnAuY29tIiwicGhvbmVfbnVtYmVyIjoiMTIzLTQ1Ni03ODkwIn0sImV4cCI6MTYzMzEwNjI5NCwiZ3JvdXBzIjpbImVuZ2luZWVyaW5nIl0sImlhdCI6MTYzMzEwNDQ5NCwiaXNzIjoiaHR0cDovLzEyNy4wLjAuMTo4MjAwL3YxL2lkZW50aXR5L29pZGMvcHJvdmlkZXIvbXktcHJvdmlkZXIiLCJuYW1lc3BhY2UiOiJyb290Iiwibm9uY2UiOiJhYmNkZWZnaGlqayIsInN1YiI6IjUwMDA3OTZlLTM2ZGYtMGQ4Yy02NDYwLTgxODUzZDliMjY2NyIsInVzZXJuYW1lIjoiZW5kLXVzZXIifQ.ehdLj6jnrJvltar1kkVSyNK48w2M5vkh5DTFJFZDqatnDWhQbbKGLZnVgd3wD6KPboXRaUwhGe4jDiTIiSoJaovOhsia77NKukym_ROLvGZw-LG7xaYkzJLnmEfeQhelLxWe0DHPROB7VXcFqBx8vX5hkuoVyqrB87vwiobK42pDPZ9MRsmbM2yzBC3wrnT7RQFtT4q2Bbyt9YIAHUaq9rU0PwJRoNISw6of1uQHo3_UzLdpwth7PEOEcI47OBGFA5vR_Gw3ocREfSrUWfCWOInAKCT43cImvg4Bts6qiZYfv9n-iNBq4AihGqq_VEF-hB1Hrprn7VgnEZ1VjUHaQQ", + "token_type": "Bearer" +} +``` + +## UserInfo endpoint + +Provides the [UserInfo Endpoint](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) +for an OIDC provider. The UserInfo Endpoint is an OAuth 2.0 Protected +Resource that returns Claims about the authenticated End-User. + +| Method | Path | +| :------ | :--------------------------------------- | +| `POST` | `/identity/oidc/provider/:name/userinfo` | + +### Parameters + +- `name` `(string: )` - The name of the provider. This parameter is +specified as part of the URL. + +### Headers + +- Access Token `(string: )` - The access token provided by the +`Authorization: Bearer ` HTTP header acquired from the authorization +endpoint. + +### Sample request + +```shell-session +$ curl \ + -X GET \ + --header "Authorization: Bearer $ACCESS_TOKEN" \ + http://127.0.0.1:8200/v1/identity/oidc/provider/test-provider/userinfo +``` + +### Sample response + +```json +{ + "contact": { + "email": "vault@hashicorp.com", + "phone_number": "123-456-7890" + }, + "groups": [ + "engineering" + ], + "sub": "5000796e-36df-0d8c-6460-81853d9b2667", + "username": "end-user"} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/tokens.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/tokens.mdx new file mode 100644 index 0000000000..1e80ded7cd --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/identity/tokens.mdx @@ -0,0 +1,564 @@ +--- +layout: api +page_title: 'Identity Secret Backend: Identity Tokens - HTTP API' +description: >- + This is the API documentation for configuring, acquiring, and validating vault + issued identity tokens. +--- + +## Configure the identity tokens backend + +This endpoint updates configurations for OIDC-compliant identity tokens issued by Vault. + +| Method | Path | +| :----- | :--------------------- | +| `POST` | `identity/oidc/config` | + +### Parameters + +- `issuer` `(string: "")` – Issuer URL to be used in the iss claim of the token. If not set, Vault's api_addr will be used. The issuer is a case sensitive URL using the https scheme that contains scheme, host, and an optional port number. + +### Sample payload + +```json +{ + "issuer": "https://example.com:1234" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/config +``` + +### Sample response + +```json +{ + "data": null, + "warnings": [ + "If \"issuer\" is set explicitly, all tokens must be validated against that address, including those issued by secondary clusters. Setting issuer to \"\" will restore the default behavior of using the cluster's api_addr as the issuer." + ] +} +``` + +## Read configurations for the identity tokens backend + +This endpoint queries vault identity tokens configurations. + +| Method | Path | +| :----- | :--------------------- | +| `GET` | `identity/oidc/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/config +``` + +### Sample response + +```json +{ + "data": { + "issuer": "https://example.com:1234" + } +} +``` + +## Create a named key + +This endpoint creates or updates a named key which is used by a role to sign tokens. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `identity/oidc/key/:name` | + +### Parameters + +- `name` `(string)` – Name of the named key. + +- `rotation_period` `(int or time string: "24h")` - How often to generate a new signing key. Uses [duration format strings](/vault/docs/concepts/duration-format). + +- `verification_ttl` `(int or time string: "24h")` - Controls how long the public portion of a signing key will be available for verification after being rotated. Uses [duration format strings](/vault/docs/concepts/duration-format). + +- `allowed_client_ids` `(list: [])` - Array of role client ids allowed to use this key for signing. If empty, no roles are allowed. If "\*", all roles are allowed. + +- `algorithm` `(string: "RS256")` - Signing algorithm to use. Allowed values are: RS256 (default), RS384, RS512, ES256, ES384, ES512, EdDSA. + +### Sample payload + +```json +{ + "rotation_period": "12h", + "verification_ttl": 43200 +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 +``` + +## Read a named key + +This endpoint queries a named key and returns its configurations. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `identity/oidc/key/:name` | + +### Parameters + +- `name` `(string)` – Name of the key. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 +``` + +### Sample response + +```json +{ + "data": { + "algorithm": "RS256", + "rotation_period": 43200, + "verification_ttl": 43200 + } +} +``` + +## Delete a named key + +This endpoint deletes a named key. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `identity/oidc/key/:name` | + +### Parameters + +- `name` `(string)` – Name of the key. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001 +``` + +## List named keys + +This endpoint will List all named keys. + +| Method | Path | +| :----- | :------------------ | +| `LIST` | `identity/oidc/key` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/oidc/key +``` + +### Sample response + +```json +{ + "data": { + "keys": ["named-key-001", "named-key-002"] + } +} +``` + +## Rotate a named key + +This endpoint rotates a named key. + +| Method | Path | +| :----- | :------------------------------- | +| `POST` | `identity/oidc/key/:name/rotate` | + +### Parameters + +- `name` `(string)` – Name of the key to be rotated. + +- `verification_ttl` `(string: )` - Controls how long the public portion of the key will be available for verification after being rotated. Setting verification_ttl here will override the verification_ttl set on the key. + +### Sample payload + +```json +{ + "verification_ttl": 0 +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/key/named-key-001/rotate +``` + +## Create or update a role + +Create or update a role. ID tokens are generated against a role and signed against a named key. + +| Method | Path | +| :----- | :------------------------- | +| `POST` | `identity/oidc/role/:name` | + +### Parameters + +- `name` `(string)` – Name of the role. + +- `key` `(string)` – A configured named key, the key must already exist. + +- `template` `(string: )` - The template string to use for generating tokens. This may be in string-ified JSON or base64 format. + +- `client_id` `(string: )` - Optional client ID. A random ID will be generated if left unset. + +- `ttl` `(int or time string: "24h")` - TTL of the tokens generated against the role. Uses [duration format strings](/vault/docs/concepts/duration-format). + +### Sample payload + +```json +{ + "key": "named-key-001", + "ttl": "12h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/role/role-001 +``` + +## Read a role + +This endpoint queries a role and returs its configuration. + +| Method | Path | +| :----- | :------------------------- | +| `GET` | `identity/oidc/role/:name` | + +### Parameters + +- `name` `(string)` – Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/role/role-001 +``` + +### Sample response + +```json +{ + "data": { + "client_id": "PGE8tf4RmJkDwvjI1FgARkXEmH", + "key": "named-key-001", + "template": "", + "ttl": 43200 + } +} +``` + +## Delete a role + +This endpoint deletes a role. + +| Method | Path | +| :------- | :------------------------- | +| `DELETE` | `identity/oidc/role/:name` | + +### Parameters + +- `name` `(string)` – Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/identity/oidc/role/role-001 +``` + +## List roles + +This endpoint will list all signing keys. + +| Method | Path | +| :----- | :------------------- | +| `LIST` | `identity/oidc/role` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/identity/oidc/role +``` + +### Sample response + +```json +{ + "data": { + "keys": ["role-001", "role-002", "testrole"] + } +} +``` + +## Generate a signed ID token + +Use this endpoint to generate a signed ID (OIDC) token. + +| Method | Path | +| :----- | :-------------------------- | +| `GET` | `identity/oidc/token/:name` | + +### Parameters + +- `name` `(string: "")` – The name of the role against which to generate a signed ID token + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/token/role-001 +``` + +### Sample response + +```json +{ + "data": { + "client_id": "P6CfCzyHsQY4pMcA6kWAOCItA7", + "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjJkMGI4YjlkLWYwNGQtNzFlYy1iNjc0LWM3MzU4NDMyYmM1YiJ9.eyJhdWQiOiJQNkNmQ3p5SHNRWTRwTWNBNmtXQU9DSXRBNyIsImV4cCI6MTU2MTQ4ODQxMiwiaWF0IjoxNTYxNDAyMDEyLCJpc3MiOiJodHRwczovL2V4YW1wbGUuY29tOjEyMzQiLCJzdWIiOiI2YzY1ZWFmNy1kNGY0LTEzMzMtMDJiYy0xYzc1MjE5YzMxMDIifQ.IcbWTmks7P5eVtwmIBl5rL1B88MI55a9JJuYVLIlwE9aP_ilXpX5fE38CDm5PixDDVJb8TI2Q_FO4GMMH0ymHDO25ZvA917WcyHCSBGaQlgcS-WUL2fYTqFjSh-pezszaYBgPuGvH7hJjlTZO6g0LPCyUWat3zcRIjIQdXZum-OyhWAelQlveEL8sOG_ldyZ8v7fy7GXDxfJOK1kpw5AX9DXJKylbwZTBS8tLb-7edq8uZ0lNQyWy9VPEW_EEIZvGWy0AHua-Loa2l59GRRP8mPxuMYxH_c88x1lsSw0vH9E3rU8AXLyF3n4d40PASXEjZ-7dnIf4w4hf2P4L0xs_g", + "ttl": 86400 + } +} +``` + +## Introspect a signed ID token + +This endpoint can verify the authenticity and active state of a signed ID token. + +| Method | Path | +| :----- | :------------------------- | +| `POST` | `identity/oidc/introspect` | + +### Parameters + +- `token` `(string)` – A signed OIDC compliant ID token + +- `client_id` `(string: )` - Specifying the client ID additionally requires the token to contain a matching `aud` claim + +### Sample payload + +```json +{ + "token": "eyJhbGciOiJSUzI1NiIsImtpZCI6ImE4NDQ4YmVkLTk4ZTMtMDNhMC01ODY4LTdmOWYyZDc5NWY2NSJ9.eyJhdWQiOiJpUDdyV1A4dmhDVFFpOTAydGhaR0hUazJMbyIsImV4cCI6MTU2MTQ4OTE0OSwiaWF0IjoxNTYxNDAyNzQ5LCJpc3MiOiJodHRwOi8vMTI3LjAuMC4xOjgyMDAvdjEvaWRlbnRpdHkvb2lkYyIsInN1YiI6IjQ1NDQxZTg3LWMyMWQtYzY5NS0wNGM3LWU0YmU4MGU1M2Y0ZiJ9.IYZx1bBofBgwphLZggugFUE7V3ZLFDNr0UYv3hhc4RlIu5WgFZPRjpKVXPdORozYJJB_37aJW6qm5j8nNSz4WrWUmMcrVxoZi2VBExu-GcHHniEPRryR9t_45rqP2MycLBz0dICOjFDWvfkp6ddyCsQfkRnplPGCaN67MUEdgYQf5QNyxaG-yabRPiATY_OtXSjiNsMhJe6ZloYTZZc9gTTfKcKQf4mfy5yRY6471qkqeTuYNhKjwdkEnCSaEjHmCdZOYC5DAet16eQ7ankcwBno17_zs7vbPmkXNttALOrjSQgGe1td1SCfZeg5UOs7_IPk0qqdwOdyQ8wsrDmSyg" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/identity/oidc/introspect +``` + +### Sample response + +```json +{ + "active": true +} +``` + +## Read the OpenID configuration from an identity token issuer + +Use the `.well-known` endpoint to retrieve an +[OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse) +with a set of claims about the identity token issuer. + +| Method | Path | +| :----- | :----------------------------------------------- | +| `GET` | `identity/oidc/.well-known/openid-configuration` | + +### Sample request + +```shell-session +$ curl \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/.well-known/openid-configuration +``` + +### Sample response + +```json +{ + "issuer": "https://example.com/v1/identity/oidc", + "jwks_uri": "https://example.com/v1/identity/oidc/.well-known/keys", + "response_types_supported": [ + "id_token" + ], + "subject_types_supported": [ + "public" + ], + "id_token_signing_alg_values_supported": [ + "RS256", + "RS384", + "RS512", + "ES256", + "ES384", + "ES512", + "EdDSA" + ] +} +``` + +## Read identity token issuer's public JWKS + +Query `identity/oidc/.well-known/keys` to retrieve the public portion of named keys. Clients can use this to validate the authenticity of an identity token. + +### Sample request + +```shell-session +$ curl \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/.well-known/keys +``` + +### Sample response + +```json +{ + "keys": [ + { + "use": "sig", + "kty": "RSA", + "kid": "94178020-55b5-e18d-b32b-1010ba5a35b4", + "alg": "RS256", + "n": "1bt-V8T7g0zr7koNbdppFrUM5YrnybPDOt-cK3MKmL1FcN3aOltCw9tCYStHgm8mIz_DJ1HgIjA-DcK_O9gacEGFCidUuudV8O4TixToHEVyRe1yXu-Q98hwkm9JtFF9PvMzDXhn4s3bLanOZzO15JAdVCo0JnwSIT9Ay3LxPLbWHYbPj7ROScuvic99OyvWz87qBK-AoXmxo9lRNY39LtieMr1D2iq0HvtjHkfiarr34CSTcuksknOsY49BU5ktrs_YJSEVpeRQ8RywY1sWrq8w_UmGsNFfPr--crXQw0ekJCXzmotsRHE5jwMuhjuucVlnyQFBYEdfDB_iPbC7Hw", + "e": "AQAB" + } + ] +} +``` + +## Read plugin identity token issuer's OpenID configuration + +Use the `.well-known` endpoint to retrieve an +[OpenID Provider Configuration Response](https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse) +with a set of claims about the plugin identity token issuer. + +| Method | Path | +| :----- | :----------------------------------------------- | +| `GET` | `identity/oidc/plugins/.well-known/openid-configuration` | + +### Sample request + +```shell-session +$ curl \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/plugins/.well-known/openid-configuration +``` + +### Sample response + +```json +{ + "issuer": "https://example.com/v1/identity/oidc/plugins", + "jwks_uri": "https://example.com/v1/identity/oidc/plugins/.well-known/keys", + "response_types_supported": [ + "id_token" + ], + "subject_types_supported": [ + "public" + ], + "id_token_signing_alg_values_supported": [ + "RS256", + "RS384", + "RS512", + "ES256", + "ES384", + "ES512", + "EdDSA" + ] +} +``` + +## Read the public JWKS from a plugin identity token issuer + +Query this path to retrieve the public portion of named keys. Clients can use this to validate the authenticity of an identity token. + +### Sample request + +```shell-session +$ curl \ + --request GET \ + http://127.0.0.1:8200/v1/identity/oidc/.well-known/keys +``` + +### Sample response + +```json +{ + "keys": [ + { + "use": "sig", + "kty": "RSA", + "kid": "94178020-55b5-e18d-b32b-1010ba5a35b4", + "alg": "RS256", + "n": "1bt-V8T7g0zr7koNbdppFrUM5YrnybPDOt-cK3MKmL1FcN3aOltCw9tCYStHgm8mIz_DJ1HgIjA-DcK_O9gacEGFCidUuudV8O4TixToHEVyRe1yXu-Q98hwkm9JtFF9PvMzDXhn4s3bLanOZzO15JAdVCo0JnwSIT9Ay3LxPLbWHYbPj7ROScuvic99OyvWz87qBK-AoXmxo9lRNY39LtieMr1D2iq0HvtjHkfiarr34CSTcuksknOsY49BU5ktrs_YJSEVpeRQ8RywY1sWrq8w_UmGsNFfPr--crXQw0ekJCXzmotsRHE5jwMuhjuucVlnyQFBYEdfDB_iPbC7Hw", + "e": "AQAB" + } + ] +} +``` \ No newline at end of file diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/index.mdx new file mode 100644 index 0000000000..efe63dc780 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/index.mdx @@ -0,0 +1,17 @@ +--- +layout: api +page_title: Secrets Engines - HTTP API +description: |- + Each secrets engine publishes its own set of API paths and methods. These + endpoints are documented in this section. +--- + +# Secrets engines + +Each secrets engine publishes its own set of API paths and methods. These +endpoints are documented in this section. secrets engines are enabled at a path, +but the documentation will assume the default paths for simplicity. If you are +enabled at a different path, you should adjust your API calls accordingly. + +For the API documentation for a specific secrets engine, please choose a secrets +engine from the navigation. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/awskms.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/awskms.mdx new file mode 100644 index 0000000000..37699d421b --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/awskms.mdx @@ -0,0 +1,51 @@ +--- +layout: api +page_title: AWS KMS - Key Management - Secrets Engines - HTTP API +description: The AWS KMS API documentation for the Key Management secrets engine. +--- + +# AWS KMS (API) + +The Key Management secrets engine supports lifecycle management of keys in [AWS KMS](https://aws.amazon.com/kms/) +regions. This is accomplished by configuring a KMS provider resource with the `awskms` provider and +other provider-specific parameter values. + +The following sections provide API documentation that is specific to AWS KMS. + +## Create/Update KMS provider + +This endpoint creates or updates a KMS provider. If a KMS provider with the given `name` +does not exist, it will be created. If the KMS provider exists, it will be updated with +the given parameter values. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/keymgmt/kms/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the KMS provider to create or update. + This is provided as part of the request URL. + +- `provider` `(string: )` – Specifies the name of a KMS provider that's external to + Vault. Must be set to `awskms`. Cannot be changed after creation. + +- `key_collection` `(string: )` – Refers to the name of an AWS + [region](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/?p=ngi&loc=2). + Cannot be changed after creation. + +- `credentials` `(map: nil)` – The credentials to use for authentication with + AWS KMS. Supplying values for this parameter is optional, as credentials may also be specified + as environment variables. Credentials provided to this parameter will take precedence over + credentials provided via environment variables. + + - `access_key` `(string: )` - The AWS access key ID. May also be specified + by the `AWS_ACCESS_KEY_ID` environment variable. + - `secret_key` `(string: )` - The AWS secret access key. May also be specified + by the `AWS_SECRET_ACCESS_KEY` environment variable. + - `session_token` `(string: )` - The AWS session token. May also be specified + by the `AWS_SESSION_TOKEN` environment variable. + - `endpoint` `(string: )` - The KMS API endpoint to be used to make AWS KMS + requests. May also be specified by the `AWS_KMS_ENDPOINT` environment variable. This + is useful when connecting to KMS over a [VPC Endpoint](https://docs.aws.amazon.com/kms/latest/developerguide/kms-vpc-endpoint.html). + If not set, the secrets engine will use the default API endpoint for the region. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/azurekeyvault.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/azurekeyvault.mdx new file mode 100644 index 0000000000..b6a649c88d --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/azurekeyvault.mdx @@ -0,0 +1,49 @@ +--- +layout: api +page_title: Azure Key Vault - Key Management - Secrets Engines - HTTP API +description: The Azure Key Vault API documentation for the Key Management secrets engine. +--- + +# Azure key Vault (API) + +The Key Management secrets engine supports lifecycle management of keys in named +[Azure Key Vault](https://docs.microsoft.com/en-us/azure/key-vault/) instances. +This is accomplished by configuring a KMS provider resource with the `azurekeyvault` +provider and other provider-specific parameter values. + +The following sections provide API documentation that is specific to Azure Key Vault. + +## Create/Update KMS provider + +This endpoint creates or updates a KMS provider. If a KMS provider with the given `name` +does not exist, it will be created. If the KMS provider exists, it will be updated with +the given parameter values. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/keymgmt/kms/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the KMS provider to create or update. + This is provided as part of the request URL. + +- `provider` `(string: )` – Specifies the name of a KMS provider that's external to + Vault. Must be set to `azurekeyvault`. Cannot be changed after creation. + +- `key_collection` `(string: )` – Refers to the name of an existing Azure Key Vault + instance. Cannot be changed after creation. + +- `credentials` `(map: nil)` – The credentials to use for authentication with + Azure Key Vault. Supplying values for this parameter is optional, as credentials may also + be specified as environment variables. Environment variables will take precedence over + credentials provided via this parameter. + + - `tenant_id` `(string: )` - The tenant ID for the Azure Active Directory + organization. May also be specified by the `AZURE_TENANT_ID` environment variable. + - `client_id` `(string: )` - The client ID for credentials to invoke the + Azure APIs. May also be specified by the `AZURE_CLIENT_ID` environment variable. + - `client_secret` `(string: )` - The client secret for credentials to invoke + the Azure APIs. May also be specified by the `AZURE_CLIENT_SECRET` environment variable. + - `environment` `(string: "AzurePublicCloud")` - The Azure Cloud environment API endpoints to + use. May also be specified by the `AZURE_ENVIRONMENT` environment variable. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/gcpkms.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/gcpkms.mdx new file mode 100644 index 0000000000..b491c09f45 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/gcpkms.mdx @@ -0,0 +1,47 @@ +--- +layout: api +page_title: GCP Cloud KMS - Key Management - Secrets Engines - HTTP API +description: The GCP Cloud KMS API documentation for the Key Management secrets engine. +--- + +# GCP Cloud KMS (API) + +The Key Management secrets engine supports lifecycle management of keys in [GCP Cloud KMS](https://cloud.google.com/security-key-management) +[key rings](https://cloud.google.com/kms/docs/resource-hierarchy#key_rings). This is accomplished by +configuring a KMS provider resource with the `gcpckms` provider and other provider-specific parameter +values. + +The following sections provide API documentation that is specific to GCP Cloud KMS. + +## Create/Update KMS provider + +This endpoint creates or updates a KMS provider. If a KMS provider with the given `name` +does not exist, it will be created. If the KMS provider exists, it will be updated with +the given parameter values. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/keymgmt/kms/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the KMS provider to create or update. + This is provided as part of the request URL. + +- `provider` `(string: )` – Specifies the name of a KMS provider that's external to + Vault. Must be set to `gcpckms`. Cannot be changed after creation. + +- `key_collection` `(string: )` – Refers to the + [resource ID](https://cloud.google.com/kms/docs/resource-hierarchy#retrieve_resource_id) + of an existing GCP Cloud KMS [key ring](https://cloud.google.com/kms/docs/resource-hierarchy#key_rings). + Cannot be changed after creation. + +- `credentials` `(map: nil)` – The credentials to use for authentication with GCP + Cloud KMS. Supplying values for this parameter is optional, as credentials may also be specified + as environment variables. See the [authentication](/vault/docs/secrets/key-management/gcpkms#authentication) + section for details on precedence. + + - `service_account_file` `(string: )` - The path to a Google service account key file. The + key file must be readable on the host that Vault server is running on. May also be provided by the + `GOOGLE_CREDENTIALS` environment variable or by + [application default credentials](https://cloud.google.com/docs/authentication/production). diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/index.mdx new file mode 100644 index 0000000000..223fe95989 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/key-management/index.mdx @@ -0,0 +1,552 @@ +--- +layout: api +page_title: Key Management - Secrets Engines - HTTP API +description: The API documentation for the Key Management secrets engine. +--- + +# Key management secrets engine (API) + +This is the API documentation for the Key Management secrets engine. For general +information about the usage and operation of the secrets engine, please see the +[Key Management secrets engine documentation](/vault/docs/secrets/key-management). + +This documentation assumes the Key Management secrets engine is enabled at the +`/keymgmt` path in Vault. Since it is possible to enable secrets engines at any +location, please update your API calls accordingly. + +## Create key + +This endpoint creates a named cryptographic key of a specified type. These parameters +set cannot be changed after key creation. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/keymgmt/key/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the key to create. + This is provided as part of the request URL. + +- `type` `(string: "rsa-2048")` – Specifies the type of cryptographic key to create. The + following key types are supported: + + - `aes256-gcm96` - AES-GCM with a 256-bit AES key and a 96-bit nonce (symmetric) + - `rsa-2048` - RSA with bit size of 2048 (asymmetric) + - `rsa-3072` - RSA with bit size of 3072 (asymmetric) + - `rsa-4096` - RSA with bit size of 4096 (asymmetric) + - `ecdsa-p256` - ECDSA using the P-256 elliptic curve (asymmetric) + - `ecdsa-p384` - ECDSA using the P-384 elliptic curve (asymmetric) + - `ecdsa-p521` - ECDSA using the P-521 elliptic curve (asymmetric) + +### Sample payload + +```json +{ + "type": "rsa-2048" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/keymgmt/key/example-key +``` + +## Read key + +This endpoint returns information about a named key. The `keys` object will hold information +regarding each key version. Different information will be returned depending on the key type. +For example, an asymmetric key will return its public key in a PEM encoding. + +| Method | Path | +| :----- | :------------------- | +| `GET` | `/keymgmt/key/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the key to read. + This is provided as part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/keymgmt/key/example-key +``` + +### Sample response + +```json +{ + "data": { + "deletion_allowed": false, + "keys": { + "1": { + "creation_time": "2020-11-02T15:54:58.768473-08:00", + "public_key": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----" + }, + "2": { + "creation_time": "2020-11-04T16:58:47.591718-08:00", + "public_key": "-----BEGIN PUBLIC KEY----- ... -----END PUBLIC KEY-----" + } + }, + "latest_version": 2, + "min_enabled_version": 1, + "name": "example-key", + "type": "rsa-2048" + } +} +``` + +## List keys + +This endpoint returns a list of all existing keys. + +| Method | Path | +| :----- | :------------- | +| `LIST` | `/keymgmt/key` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/keymgmt/key +``` + +### Sample response + +```json +{ + "data": { + "keys": ["example-key"] + } +} +``` + +## Update key + +This endpoint updates a named key. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/keymgmt/key/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the key to update. + This is provided as part of the request URL. + +- `min_enabled_version` `(int: 0)` – Specifies the minimum enabled version of the key. All + versions of the key less than the specified version will be disabled for cryptographic + operations in the KMS provider that the key has been distributed to. Setting this value to + `0` means that all versions will be enabled. + +- `deletion_allowed` `(bool: false)` – Specifies if the key is allowed to be deleted. + +### Sample payload + +```json +{ + "min_enabled_version": 0, + "deletion_allowed": true +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/keymgmt/key/example-key +``` + +## Rotate key + +This endpoint rotates the version of a named key. + +| Method | Path | +| :----- | :-------------------------- | +| `POST` | `/keymgmt/key/:name/rotate` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the key to rotate. + This is provided as part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/keymgmt/key/example-key/rotate +``` + +## Delete key + +This endpoint deletes a named key. The key must be removed from all KMS providers that it's +been distributed to and have `deletion_allowed` set to `true` in order to be deleted. + +| Method | Path | +| :------- | :------------------- | +| `DELETE` | `/keymgmt/key/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the key to delete. + This is provided as part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/keymgmt/key/example-key +``` + +## List KMS providers of key + +This endpoint returns a list of all KMS providers that the named key has been distributed to. +Currently, a key can only be distributed to a single KMS provider. + +| Method | Path | +| :----- | :----------------------- | +| `LIST` | `/keymgmt/key/:name/kms` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the key. + This is provided as part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/keymgmt/key/example-key/kms +``` + +### Sample response + +```json +{ + "data": { + "keys": ["example-kms"] + } +} +``` + +## Create/Update KMS provider + +This endpoint creates or updates a KMS provider. If a KMS provider with the given `name` +does not exist, it will be created. If the KMS provider exists, it will be updated with +the given parameter values. + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/keymgmt/kms/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the KMS provider to create or update. + This is provided as part of the request URL. + +- `provider` `(string: )` – Specifies the name of a KMS provider that's external to + Vault. Cannot be changed after creation. For more information about each provider, refer to + the [KMS Providers](/vault/docs/secrets/key-management#kms-providers) section. The following values + are supported: + + - `azurekeyvault` + - `awskms` + - `gcpckms` + +### Common parameters + +There are common parameters that expect different values depending on the specified `provider`. +Please reference the API documentation for individual KMS providers to determine which values to +set for each of the parameters listed below. + +- `key_collection` `(string: )` – Refers to a location to store keys in the specified + `provider`. Cannot be changed after creation. The expected value for this parameter will differ + depending on the specified `provider`. + +- `credentials` `(map: nil)` – The credentials to use for authentication with + the specified `provider`. Supplying values for this parameter is optional, as credentials may + also be specified as environment variables. The expected keys and values for this parameter + will differ depending on the specified `provider`. + +### Sample payload + +```json +{ + "credentials": [ + "client_id=example-client-id", + "client_secret=example-client-secret", + "tenant_id=example-tenant-id" + ], + "key_collection": "example-keyvault-name", + "provider": "azurekeyvault" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/keymgmt/kms/example-kms +``` + +## Read KMS provider + +This endpoint returns information about a KMS provider. + +| Method | Path | +| :----- | :------------------- | +| `GET` | `/keymgmt/kms/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the KMS provider to read. + This is provided as part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/keymgmt/kms/example-kms +``` + +### Sample response + +```json +{ + "data": { + "key_collection": "example-keyvault-name", + "provider": "azurekeyvault" + } +} +``` + +## List KMS providers + +This endpoint returns a list of all existing KMS providers. + +| Method | Path | +| :----- | :------------- | +| `LIST` | `/keymgmt/kms` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/keymgmt/kms +``` + +### Sample response + +```json +{ + "data": { + "keys": ["example-kms"] + } +} +``` + +## Delete KMS provider + +This endpoint deletes a KMS provider. A KMS provider cannot be deleted until all keys +that have been distributed to it are removed. + +| Method | Path | +| :------- | :------------------- | +| `DELETE` | `/keymgmt/kms/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the KMS provider to delete. + This is provided as part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/keymgmt/kms/example-kms +``` + +## Distribute key to KMS provider + +This endpoint distributes a named key to the KMS provider. The key will be securely delivered +(i.e., wrapped for protection in transit) following the key import specification of the KMS +provider. The parameters set cannot be changed after the key has been distributed. + +| Method | Path | +| :----- | :--------------------------------- | +| `POST` | `/keymgmt/kms/:name/key/:key_name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the KMS provider to distribute the given key + to. This is provided as part of the request URL. + +- `key_name` `(string: )` – Specifies the name of the key to distribute to the given KMS + provider. This is provided as part of the request URL. + +- `purpose` `([]string: )` – Specifies the purpose of the key. The purpose defines a set + of cryptographic capabilities that the key will have in the KMS provider. A key must have at + least one of the supported purposes. The following values are supported: + + - `encrypt` + - `decrypt` + - `sign` + - `verify` + - `wrap` + - `unwrap` + +- `protection` `(string: "hsm")` – Specifies the protection of the key. The protection defines + where cryptographic operations are performed with the key in the KMS provider. The following + values are supported: + + - `hsm` + - `software` + +### Sample payload + +```json +{ + "protection": "hsm", + "purpose": "encrypt,decrypt" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key +``` + +## Read key in KMS provider + +This endpoint returns information about a key that's been distributed to a KMS provider. + +| Method | Path | +| :----- | :--------------------------------- | +| `GET` | `/keymgmt/kms/:name/key/:key_name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the KMS provider. This is provided as + part of the request URL. + +- `key_name` `(string: )` – Specifies the name of the key. This is provided as part + of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key +``` + +### Sample response + +```json +{ + "data": { + "name": "example-key-", + "protection": "hsm", + "purpose": "encrypt,decrypt", + "versions": { + "1": "c96a8956194f4632bc3837b64a1b45b1", + "2": "01ce657d33f64eb38f9432be543f3f52" + } + } +} +``` + +## List keys in KMS provider + +This endpoint returns a list of all keys that have been distributed to the given KMS +provider. Many keys can be distributed to a single KMS provider. + +| Method | Path | +| :----- | :----------------------- | +| `LIST` | `/keymgmt/kms/:name/key` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the KMS provider. + This is provided as part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key +``` + +### Sample response + +```json +{ + "data": { + "keys": ["example-key"] + } +} +``` + +## Remove key from KMS provider + +This endpoint removes a named key from the KMS provider. This will only delete the key from +the KMS provider. The key will still exist in the secrets engine and can be redistributed to +a KMS provider at a later time. To permanently delete the key from the secrets engine, the +[Delete Key](#delete-key) API must be invoked. + +| Method | Path | +| :------- | :--------------------------------- | +| `DELETE` | `/keymgmt/kms/:name/key/:key_name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the KMS provider. This is provided as + part of the request URL. + +- `key_name` `(string: )` – Specifies the name of the key. This is provided as part + of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/keymgmt/kms/example-kms/key/example-key +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/kmip.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/kmip.mdx new file mode 100644 index 0000000000..5f9442aee7 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/kmip.mdx @@ -0,0 +1,609 @@ +--- +layout: api +page_title: KMIP - Secrets Engines - HTTP API +description: This is the API documentation for the Vault KMIP secrets engine. +--- + +# KMIP secrets engine (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault KMIP secrets engine. For general +information about the usage and operation of +the KMIP secrets engine, please see [these docs](/vault/docs/secrets/kmip). + +This documentation assumes the KMIP secrets engine is enabled at the `/kmip` path +in Vault. Since it is possible to mount secrets engines at any path, please +update your API calls accordingly. + +## Write config + +| Method | Path | +| :----- | :------------- | +| `POST` | `/kmip/config` | + +This endpoint configures shared information for the secrets engine. After writing +to it the KMIP engine will generate a CA and start listening for KMIP requests. +If the server was already running and any non-client settings are changed, the +server will be restarted using the new settings. All generated CAs will use +entropy augmentation to generate their certificates if entropy augmentation +is enabled. + +### Parameters + +- `listen_addrs` (`list: ["127.0.0.1:5696"] || string`) - Address and port the + KMIP server should listen on. Can be given as a JSON list or a + comma-separated string list. If multiple values are given, all will be + listened on. +- `connection_timeout` (`int: 1 || string:"1s"`) - Duration in either an integer + number of seconds (10) or an integer time unit (10s) within which connections + must become ready. + +- `server_hostnames` (`list: ["localhost"] || string`) - Hostnames to include in + the server's TLS certificate as SAN DNS names. The first will be used as the + common name (CN). + +- `server_ips` (`list: [] || string`) - IPs to include in the server's TLS + certificate as SAN IP addresses. Localhost (IPv4 and IPv6) will be automatically + included. +- `tls_ca_key_type` (`string: "ec"`) - CA key type, `rsa` or `ec`. + +- `tls_ca_key_bits` (`int: 521`) - CA key bits, valid values depend on key type. + +- `tls_min_version` (`string: "tls12"`) - Minimum TLS version to accept. + +- `default_tls_client_key_type` (`string: "ec"`): - Client certificate key type, + `rsa` or `ec`. + +- `default_tls_client_key_bits` (`int: 521`): - Client certificate key bits, valid + values depend on key type. + +- `default_tls_client_ttl` (`int: 86400 || string:"24h"`) – Client certificate + TTL in either an integer number of seconds (10) or an integer time unit (10s). + +### Sample payload + +```json +{ + "listen_addrs": "127.0.0.1:5696,192.168.1.2:9000", + "connection_timeout": "1s", + "server_hostnames": "myhostname1,myhostname2", + "server_ips": "192.168.1.2", + "tls_ca_key_type": "ec", + "tls_ca_key_bits": 521, + "tls_min_version": "tls11", + "default_tls_client_key_type": "ec", + "default_tls_client_key_bits": 224, + "default_tls_client_ttl": 86400 +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/kmip/config +``` + +## Read config + +| Method | Path | +| :----- | :------------- | +| `GET` | `/kmip/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/kmip/config +``` + +### Sample response + +```json +{ + "data": { + "listen_addrs": ["127.0.0.1:5696", "192.168.1.2:9000"], + "connection_timeout": "1s", + "server_hostnames": ["myhostname1", "myhostname2"], + "server_ips": ["192.168.1.2"], + "tls_ca_key_type": "ec", + "tls_ca_key_bits": 521, + "tls_min_version": "tls11", + "default_tls_client_key_type": "ec", + "default_tls_client_key_bits": 224, + "default_tls_client_ttl": 86400 + } +} +``` + +## Read CA + +| Method | Path | +| :----- | :--------- | +| `GET` | `/kmip/ca` | + +Returns the CA certificates in PEM format. Returns an error if config has never +been written. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/kmip/ca +``` + +### Sample response + +```json +{ + "data": { + "ca_pem": "-----BEGIN CERTIFICATE-----\nMIICNzCCAZigAwIBAgIUApNsRil/dzQy3XT+yjZQEpcA49kwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4MzIzM1oX\nDTI5MDYyMTE4MzMwM1owKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWlu\ndGVybWVkaWF0ZTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEAGWJGwPjGGoXivBv\nLJwR+fIG3z6Ei06bhZgTaRW/U3eA5oivxubxOVZPe1BJGWCsIVNjxMZAN4Pswki7\nAHme9bdJAUbQw33tC1iAb0wjzIpoPv1+pdSk6wYZTCKzOYWCbsTb3SOIetpk7sQw\niM17agwIRK9qGvX3Q4PBfEKEpstAjoaJo2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD\nVR0TAQH/BAgwBgEB/wIBCTAdBgNVHQ4EFgQUKMwPpRxU2Uzydv21bc8ePfUpGFEw\nHwYDVR0jBBgwFoAUwrPrJc9EsU6kTWJ5hXkJV4PEq9swCgYIKoZIzj0EAwIDgYwA\nMIGIAkIBRCarRMer42Ni/fKQBTi+uFk+2sPyCxCYDWTfMFAusC51dC2F91mUL77R\nkHxauSkh5gcZVAch/dg/L0ewP0AZUBUCQgE1VqoBN9klFky7LHfl62p6PgprH7d1\nYCvYVbWdBNnEdrL2P9aKsuCewdqycZVJLmM36cHnOAEGg1yea8soQL0Ylw==\n-----END CERTIFICATE-----\n-----BEGIN CERTIFICATE-----\nMIICKTCCAYugAwIBAgIUOBgW1GCH+n5gC6m8Ff5jq+5DmO8wCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4MzIzM1oX\nDTI5MDYyMTE4MzMwM1owHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MIGb\nMBAGByqGSM49AgEGBSuBBAAjA4GGAAQA7vkbmKJR+SVBTJjAFnma0ynTIi64doZA\n5oOXIAExvOyyI2KBNfqXxgzt/51u9vvixQf3VX/1Jph+0fkIcIYUEmIBFAH7Th1X\n0EOOdmMHfN0YkXDEUUdKIZyQxgA7o3DF+JAVg1cdBV7S8jZyXik7pL+IFnlYdfvN\nUZcArUkMfKo1cZajZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/\nAgEKMB0GA1UdDgQWBBTCs+slz0SxTqRNYnmFeQlXg8Sr2zAfBgNVHSMEGDAWgBTC\ns+slz0SxTqRNYnmFeQlXg8Sr2zAKBggqhkjOPQQDAgOBiwAwgYcCQgGjKAC371/5\npxgYdLVBmVC6Aa+oOvwGfnich2YLSLbThySED7+fXl1BY43VU703ad6M34fStf6z\nwFZvVZVK188DCQJBJcSZ7YA3PjOre+epJHtAba+1CkAdbSAeGhBDgHdIEP1/FDvx\n+U2QYeVZ7kAVnkzPxa17V0yqjxDtQDTiOw/ZV5c=\n-----END CERTIFICATE-----" + } +} +``` + +## Write scope + +| Method | Path | +| :----- | :------------------- | +| `POST` | `/kmip/scope/:scope` | + +Creates a new scope with the given name. + +### Parameters + +- `scope` (`string: `) - Name of scope. This is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://127.0.0.1:8200/v1/kmip/scope/myscope +``` + +## List scopes + +| Method | Path | +| :----- | :------------ | +| `LIST` | `/kmip/scope` | + +List existing scopes. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/kmip/scope +``` + +### Sample response + +```json +{ + "data": { + "keys": ["myscope"] + } +} +``` + +## Delete scope + +| Method | Path | +| :------- | :------------------- | +| `DELETE` | `/kmip/scope/:scope` | + +Delete a scope by name. + +### Parameters + +- `scope` (`string: `) - Name of scope. This is part of the request URL. +- `force` (`bool: false`) - Force scope deletion. If KMIP managed objects have + been created within the scope this param must be provided or the deletion will + fail. This value should be supplied as a query parameter, or as an argument in + the CLI. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/kmip/scope/myscope?force=false +``` + +## Write role + +| Method | Path | +| :----- | :------------------------------ | +| `POST` | `/kmip/scope/:scope/role/:role` | + +Creates or updates a role. + +### Parameters + +- `scope` (`string: `) - Name of scope. This is part of the request URL. +- `role` (`string: `) - Name of role. This is part of the request URL. +- `tls_client_key_type` (`string`): - Client certificate key type, + `rsa` or `ec`. Overrides engine-wide default managed in `config` endpoint. +- `tls_client_key_bits` (`int`): - Client certificate key bits, valid + values depend on key type. Overrides engine-wide default managed in `config` + endpoint. +- `tls_client_ttl` (`int or string`) – Client certificate + TTL in either an integer number of seconds (10) or an integer time unit (10s). + Overrides engine-wide default managed in `config` endpoint. +- `operation_none` (`bool: false`) - Remove all permissions + from this role. May not be specified with any other + `operation_` params. +- `operation_all` (`bool: false`) - Grant all permissions + to this role. May not be specified with any other + `operation_` params. +- `operation_activate` (`bool: false`) - Grant permission to use the KMIP + `Activate` operation. +- `operation_add_attribute` (`bool: false`) - Grant permission to use the KMIP + `Add Attribute` operation. +- `operation_create` (`bool: false`) - Grant permission to use the KMIP + `Create` operation. +- `operation_decrypt` (`bool: false`) - Grant permission to use the KMIP + `Decrypt` operation. +- `operation_destroy` (`bool: false`) - Grant permission to use the KMIP + `Destroy` operation. +- `operation_discover_versions` (`bool: false`) - Grant permission to use the KMIP + `Discover Versions` operation. +- `operation_encrypt` (`bool: false`) - Grant permission to use the KMIP + `Encrypt` operation. +- `operation_get` (`bool: false`) - Grant permission to use the KMIP + `Get` operation. +- `operation_get_attribute_list` (`bool: false`) - Grant permission to use the KMIP + `Get Attribute List` operation. +- `operation_get_attributes` (`bool: false`) - Grant permission to use the KMIP + `Get Attributes` operation. +- `operation_import` (`bool: false`) - Grant permission to use the KMIP + `Import` operation. +- `operation_locate` (`bool: false`) - Grant permission to use the KMIP + `Locate` operation. +- `operation_query` (`bool: false`) - Grant permission to use the KMIP + `Query` operation. +- `operation_register` (`bool: false`) - Grant permission to use the KMIP + `Register` operation. +- `operation_rekey` (`bool: false`) - Grant permission to use the KMIP + `Rekey` operation. +- `operation_revoke` (`bool: false`) - Grant permission to use the KMIP + `Revoke` operation. + +### Sample payload + +```json +{ + "operation_activate": true, + "operation_add_attribute": true, + "operation_create": true, + "operation_decrypt": true, + "operation_destroy": true, + "operation_discover_versions": true, + "operation_encrypt": true, + "operation_get": true, + "operation_get_attribute_list": true, + "operation_get_attributes": true, + "operation_import": true, + "operation_locate": true, + "operation_query": true, + "operation_register": true, + "operation_rekey": true, + "operation_revoke": true +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole +``` + +## Read role + +| Method | Path | +| :----- | :------------------------------ | +| `GET` | `/kmip/scope/:scope/role/:role` | + +Read a role. + +### Parameters + +- `scope` (`string: `) - Name of scope. This is part of the request URL. +- `role` (`string: `) - Name of role. This is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole +``` + +### Sample response + +```json +{ + "data": { + "operation_activate": true, + "operation_add_attribute": true, + "operation_create": true, + "operation_decrypt": true, + "operation_destroy": true, + "operation_discover_versions": true, + "operation_encrypt": true, + "operation_get": true, + "operation_get_attribute_list": true, + "operation_get_attributes": true, + "operation_import": true, + "operation_locate": true, + "operation_query": true, + "operation_register": true, + "operation_rekey": true, + "operation_revoke": true + } +} +``` + +## List roles + +| Method | Path | +| :----- | :------------------------ | +| `LIST` | `/kmip/scope/:scope/role` | + +List roles with a scope. + +### Parameters + +- `scope` (`string: `) - Name of scope. This is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/kmip/scope/myscope/role +``` + +### Sample response + +```json +{ + "data": { + "keys": ["myrole"] + } +} +``` + +## Delete role + +| Method | Path | +| :------- | :------------------------------ | +| `DELETE` | `/kmip/scope/:scope/role/:role` | + +Delete a role by name. + +### Parameters + +- `scope` (`string: `) - Name of scope. This is part of the request URL. +- `role` (`string: `) - Name of role. This is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole +``` + +## Generate credential + +| Method | Path | +| :----- | :-------------------------------------------------- | +| `POST` | `/kmip/scope/:scope/role/:role/credential/generate` | + +Create a new client certificate tied to the given role and scope. +This endpoint uses entropy augmentation to generate the client certificate +if entropy augmentation is enabled. + +### Parameters + +- `scope` (`string: `) - Name of scope. This is part of the request URL. +- `role` (`string: `) - Name of role. This is part of the request URL. +- `format` (`string: "pem"`) - Format to return the certificate, private key, + and CA chain in. One of `pem`, `pem_bundle`, or `der`. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole/credential/generate +``` + +### Sample response + +```json +{ + "data": { + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIICNzCCAZigAwIBAgIUKOGtsdXdMjjGni52EsaMQ7ozhCEwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4NTgyMVoX\nDTI5MDYyMTE4NTg1MVowKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWlu\ndGVybWVkaWF0ZTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEATHNhNvU0GMtzl6A\nPbNaCoF0jV3z09RCfLKEqMl/MXv/AlPcfiqCQeOWBwWHv76epPWkCCo+IlNq8ldQ\neVe52p6mABMvRjE6BZ/eLea27zImI6waK7nZ2hqx0npb8ivdbwmrgp0NQnv0sJ+o\nPeLa2vh9wDK1NJebmOv0yRAbCw2CH7Rbo2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD\nVR0TAQH/BAgwBgEB/wIBCTAdBgNVHQ4EFgQU2naFRym+xfFvZm2TNRBXNf3MJSsw\nHwYDVR0jBBgwFoAUFrA/R807R0BnIt395KzaXdP4n00wCgYIKoZIzj0EAwIDgYwA\nMIGIAkIAkb8EdHCXgPpQsKYedMz4X2j5CFSVdZTWsPVw1XuSXIsIsc6018V4z9Kp\nkPacsHZTBR636y2toqRPDG4y9MLqFFkCQgCV1jEkiNhhKc+ZWuDjerdqNvLnCbe+\n7t4fiG9zQgWwh6IxL11cNyGVz9gS9af32DtuYf0xwFLOwLgn1RadC9Pd7Q==\n-----END CERTIFICATE-----", + "-----BEGIN CERTIFICATE-----\nMIICKTCCAYugAwIBAgIUOcs4pXlp+UgGiUKfKlcxIE/woPEwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4NTgyMVoX\nDTI5MDYyMTE4NTg1MVowHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MIGb\nMBAGByqGSM49AgEGBSuBBAAjA4GGAAQAcst7uNwu77WtLDkbz4ILYDiQ3BgS++qU\nOoNKcKyvNe8YX6PtrdQWPTaxT4MZNHZvTv+BAQTQqGLKrstpkjXPh+sBn7V4trkT\nMCtxUjIGneURUXS4IC/KJEA60P7ep7MrGnJfG/N4m+Q/a6BuxKhdEavXtepniCMz\npHw4DCpW/9m2t16jZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/\nAgEKMB0GA1UdDgQWBBQWsD9HzTtHQGci3f3krNpd0/ifTTAfBgNVHSMEGDAWgBQW\nsD9HzTtHQGci3f3krNpd0/ifTTAKBggqhkjOPQQDAgOBiwAwgYcCQR7iNoA4nBV3\ndSn8nfafklFvHZxoKR1j3nn+56z4JHD6TNr//GNqQiqnM3P//Tce+E4KzEax4xRg\nhaLURgPLNBjOAkIAqW+1/+v9D0vXOU1WPc+/oFvhSjYnr5qqcTL7by5fsmMXzAIe\nLODXiODxdppXXnMZPCPZh6MGgUwEGYeCnaXopWc=\n-----END CERTIFICATE-----" + ], + "certificate": "-----BEGIN CERTIFICATE-----\nMIICOzCCAZygAwIBAgIUeOkn0HAdoh31nGkVKdafpCNuhFEwCgYIKoZIzj0EAwIw\nKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWludGVybWVkaWF0ZTAeFw0x\nOTA2MjQxOTAwMDlaFw0xOTA2MjUxOTAwMzlaMCAxDjAMBgNVBAsTBWlsVjYzMQ4w\nDAYDVQQDEwUyRnlWTjCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEAA0rIy0h2DL3\nzmTXVj2v22Kz0N1EUUATlRgBj1XBsBA1Pdd7CSZoefmh/u6Z8TjtRX9Z1aj9Bb/d\nJxS3zB4mguULAF4k7bLH1gKXMVC6NYjjk3mfxH5jG4QY8S8n6uyqzNgI5KRJ2Hyj\nm8549Nvq3rvs8yOVXPSOGzkJ5KdUmSvXicMQo2cwZTAOBgNVHQ8BAf8EBAMCA6gw\nEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0OBBYEFEuzruLILCil5Fp32ZjE4AhD\nU268MB8GA1UdIwQYMBaAFNp2hUcpvsXxb2ZtkzUQVzX9zCUrMAoGCCqGSM49BAMC\nA4GMADCBiAJCAeeuaIsgO9ro7opzZ9y9hSHkKB5WA5Qc7ePoSiKHNNbVvIJMkjRQ\nC9YtUMQNnQ8wE6D/9xvR+9OBIi7t16iHGPGbAkIA6WIG6HHRNUXnHPIiW8iy/04O\nfVqZgJHJEeyGQbwdaehs+Z5xOz6TA4Z3uZOAMnPcb+KDwchnQ8CJnmT/KnnT5D8=\n-----END CERTIFICATE-----", + "private_key": "-----BEGIN EC PRIVATE KEY-----\nMIHcAgEBBEIBB4xDj9SUtb6Z466lVQIf3ucy21q5S2Fp9bzTQ0Ch5Vg2+DhUZUa1\nDjKvDdICY6hLPBFAwcOUFdDXr4kH/i8wuRWgBwYFK4EEACOhgYkDgYYABAANKyMt\nIdgy985k11Y9r9tis9DdRFFAE5UYAY9VwbAQNT3XewkmaHn5of7umfE47UV/WdWo\n/QW/3ScUt8weJoLlCwBeJO2yx9YClzFQujWI45N5n8R+YxuEGPEvJ+rsqszYCOSk\nSdh8o5vOePTb6t677PMjlVz0jhs5CeSnVJkr14nDEA==\n-----END EC PRIVATE KEY-----", + "serial_number": "728181095563584845125173905844944137943705466376" + } +} +``` + +## Sign CSR + +| Method | Path | +| :----- | :---------------------------------------------- | +| `POST` | `/kmip/scope/:scope/role/:role/credential/sign` | + +Create a new client certificate tied to the given role and scope, +based on a Certificate Signing Request (CSR) provided as input. +The key type and key bits used in the CSR must match those of the role. + +### Parameters + +- `scope` (`string: `) - Name of scope. This is part of the request URL. +- `role` (`string: `) - Name of role. This is part of the request URL. +- `format` (`string: "pem"`) - Format to return the certificate, private key, + and CA chain in. One of `pem`, `pem_bundle`, or `der`. +- `csr` (`string`) - CSR in PEM format. + +### Sample request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data '{"csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIC5DCCAcwCAQIwaTEMMAoGA1UEAwwDRUtNMQ8wDQYDVQQKDAZOZXRBcHAxEjAQ\nBgNVBAsMCVNvbGlkRmlyZTESMBAGA1UEBwwJU3Vubnl2YWxlMRMwEQYDVQQIDApD\nYWxpZm9ybmlhMQswCQYDVQQGEwJVUzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCC\nAQoCggEBALFjeR5ZeKlTSLNKLr0Gl4DEH1oICDZj3oMYAEGMO/uW/4YleFmYSkPc\nxqqT/i6nlys+ZvLMtFdTr4lZBVsVD/AhjDVVBKuxaHIbolZFBjVxY3J2MuCWS2hB\nN2pRmGgnlpPwiu0VpA1bNJ/Shw3Zol9OnYliZAzc6U/hMxDUP7yQHSU5Q9T3vHV2\n3xR38PmeXKqdG+S68/cuhEHtUPa1mTagntkYU5BDOKpcmPenEam7itR+Tp1yZupp\n5sdfI/5trO4YI6jtUmMsA5PaNlKMDqzwjkiI8+kd+aDgIJa5c9VeEXC/PkjXRJ9G\nC/mSQOhM84EaYAU6zDw9B78j5ca2izsCAwEAAaA2MDQGCSqGSIb3DQEJDjEnMCUw\nDgYDVR0PAQH/BAQDAgWgMBMGA1UdJQQMMAoGCCsGAQUFBwMCMA0GCSqGSIb3DQEB\nCwUAA4IBAQBXW2nA4EsNYDLo8gzBqsM3AFYTdYTO+Q2wu0fUZp3cX3AOIYFstW6/\nrCpdU3/z5ICS9i4ZHfJOAeKtBeOE+VCt7xI/+ZH1D7I9mNWZ7wp+ZXWImzRtEmBZ\nSj6wVa2Igmtiqr2UQegWnp5MG5Ds37DvmBoFDvcGMKy3tVJamSXFhqtdY2QSzYMM\nCjuqNUjll4RUUurjKmET8ZVHjLXGI3MxGVVg6aC3TtYuK12DFEFSy8LlfVn6kXS4\nPTe4Y6ffW5JykdW85xMq5RM6rpwsrVaKvVFOwn9O7lGZLeq4HFPcjY2SXZxAT+bi\nb/t+UQOjhlb0X2YdjPGHjFd+spZQ6u0a\n-----END CERTIFICATE REQUEST-----"}' + https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole/credential/sign +``` + +### Sample response + +```json +{ + "data": { + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIICNzCCAZigAwIBAgIUKOGtsdXdMjjGni52EsaMQ7ozhCEwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4NTgyMVoX\nDTI5MDYyMTE4NTg1MVowKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWlu\ndGVybWVkaWF0ZTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEATHNhNvU0GMtzl6A\nPbNaCoF0jV3z09RCfLKEqMl/MXv/AlPcfiqCQeOWBwWHv76epPWkCCo+IlNq8ldQ\neVe52p6mABMvRjE6BZ/eLea27zImI6waK7nZ2hqx0npb8ivdbwmrgp0NQnv0sJ+o\nPeLa2vh9wDK1NJebmOv0yRAbCw2CH7Rbo2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD\nVR0TAQH/BAgwBgEB/wIBCTAdBgNVHQ4EFgQU2naFRym+xfFvZm2TNRBXNf3MJSsw\nHwYDVR0jBBgwFoAUFrA/R807R0BnIt395KzaXdP4n00wCgYIKoZIzj0EAwIDgYwA\nMIGIAkIAkb8EdHCXgPpQsKYedMz4X2j5CFSVdZTWsPVw1XuSXIsIsc6018V4z9Kp\nkPacsHZTBR636y2toqRPDG4y9MLqFFkCQgCV1jEkiNhhKc+ZWuDjerdqNvLnCbe+\n7t4fiG9zQgWwh6IxL11cNyGVz9gS9af32DtuYf0xwFLOwLgn1RadC9Pd7Q==\n-----END CERTIFICATE-----", + "-----BEGIN CERTIFICATE-----\nMIICKTCCAYugAwIBAgIUOcs4pXlp+UgGiUKfKlcxIE/woPEwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE4NTgyMVoX\nDTI5MDYyMTE4NTg1MVowHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MIGb\nMBAGByqGSM49AgEGBSuBBAAjA4GGAAQAcst7uNwu77WtLDkbz4ILYDiQ3BgS++qU\nOoNKcKyvNe8YX6PtrdQWPTaxT4MZNHZvTv+BAQTQqGLKrstpkjXPh+sBn7V4trkT\nMCtxUjIGneURUXS4IC/KJEA60P7ep7MrGnJfG/N4m+Q/a6BuxKhdEavXtepniCMz\npHw4DCpW/9m2t16jZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/\nAgEKMB0GA1UdDgQWBBQWsD9HzTtHQGci3f3krNpd0/ifTTAfBgNVHSMEGDAWgBQW\nsD9HzTtHQGci3f3krNpd0/ifTTAKBggqhkjOPQQDAgOBiwAwgYcCQR7iNoA4nBV3\ndSn8nfafklFvHZxoKR1j3nn+56z4JHD6TNr//GNqQiqnM3P//Tce+E4KzEax4xRg\nhaLURgPLNBjOAkIAqW+1/+v9D0vXOU1WPc+/oFvhSjYnr5qqcTL7by5fsmMXzAIe\nLODXiODxdppXXnMZPCPZh6MGgUwEGYeCnaXopWc=\n-----END CERTIFICATE-----" + ], + "certificate": "-----BEGIN CERTIFICATE-----\nMIICOzCCAZygAwIBAgIUeOkn0HAdoh31nGkVKdafpCNuhFEwCgYIKoZIzj0EAwIw\nKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWludGVybWVkaWF0ZTAeFw0x\nOTA2MjQxOTAwMDlaFw0xOTA2MjUxOTAwMzlaMCAxDjAMBgNVBAsTBWlsVjYzMQ4w\nDAYDVQQDEwUyRnlWTjCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEAA0rIy0h2DL3\nzmTXVj2v22Kz0N1EUUATlRgBj1XBsBA1Pdd7CSZoefmh/u6Z8TjtRX9Z1aj9Bb/d\nJxS3zB4mguULAF4k7bLH1gKXMVC6NYjjk3mfxH5jG4QY8S8n6uyqzNgI5KRJ2Hyj\nm8549Nvq3rvs8yOVXPSOGzkJ5KdUmSvXicMQo2cwZTAOBgNVHQ8BAf8EBAMCA6gw\nEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0OBBYEFEuzruLILCil5Fp32ZjE4AhD\nU268MB8GA1UdIwQYMBaAFNp2hUcpvsXxb2ZtkzUQVzX9zCUrMAoGCCqGSM49BAMC\nA4GMADCBiAJCAeeuaIsgO9ro7opzZ9y9hSHkKB5WA5Qc7ePoSiKHNNbVvIJMkjRQ\nC9YtUMQNnQ8wE6D/9xvR+9OBIi7t16iHGPGbAkIA6WIG6HHRNUXnHPIiW8iy/04O\nfVqZgJHJEeyGQbwdaehs+Z5xOz6TA4Z3uZOAMnPcb+KDwchnQ8CJnmT/KnnT5D8=\n-----END CERTIFICATE-----", + "serial_number": "728181095563584845125173905844944137943705466376" + } +} +``` + +## Lookup credential + +| Method | Path | +| :----- | :------------------------------------------------ | +| `GET` | `/kmip/scope/:scope/role/:role/credential/lookup` | + +Read a certificate by serial number. The private key cannot be obtained except +at generation time. + +### Parameters + +- `scope` (`string: `) - Name of scope. This is part of the request URL. +- `role` (`string: `) - Name of role. This is part of the request URL. +- `serial_number` (`string: `) - Serial number of certificate to revoke. +- `format` (`string: "pem"`) - Format to return the certificate, private key, + and CA chain in. One of `pem`, `pem_bundle`, or `der`. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole/credential/lookup?serial_number=728181095563584845125173905844944137943705466376 +``` + +### Sample response + +```json +{ + "data": { + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIICNzCCAZigAwIBAgIUGptwpwpVvxlx3sBniJ7TRGD9gCkwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE5MDY0N1oX\nDTI5MDYyMTE5MDcxN1owKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWlu\ndGVybWVkaWF0ZTCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEADO48mMu5V2PTbcg\nq0JPB5ReWwnUHhfFh/+XLP8ZM112JpOFutlcUYYZ23jAlvrlYZ+m1E0ASr0592ZM\n9CwIXy3zAJChPrV3tiofhINR5PPqCF42FcfNj4l7VN/XeYMN6dslX+O4dPn/DsbH\nZi7kWr5KSOR939ULFaRMYe3l2MxaYZ2do2YwZDAOBgNVHQ8BAf8EBAMCAQYwEgYD\nVR0TAQH/BAgwBgEB/wIBCTAdBgNVHQ4EFgQUPP7VJOGk3qR0qKqx3TLN1R8JDiQw\nHwYDVR0jBBgwFoAUBHr+hhaorPU2jIF35DTBDhL7uWowCgYIKoZIzj0EAwIDgYwA\nMIGIAkIA7G82rqLYb6bKrQZzhpNwvVIFOSocEJrUbP0E0D8dEeOmKs43C70P5e0s\nTrrpNAMEsK6vXWtM+QcrZZp+yyM6k3QCQgG8cxFIl8tgoMKWe0+cDeOoHtczopRy\nSk+Tt7DNNP9sfYK11g7w8xzbtW4ZuZKKoYRbxN+eQHn5c+8akMSt4h71Dg==\n-----END CERTIFICATE-----", + "-----BEGIN CERTIFICATE-----\nMIICKDCCAYugAwIBAgIUWv6jrjNbsvdX43l4s10HaJkSxOMwCgYIKoZIzj0EAwIw\nHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MB4XDTE5MDYyNDE5MDY0N1oX\nDTI5MDYyMTE5MDcxN1owHTEbMBkGA1UEAxMSdmF1bHQta21pcC1kZWZhdWx0MIGb\nMBAGByqGSM49AgEGBSuBBAAjA4GGAAQAP6C8d9ZUalKBM1NdALtEMlv+dwFnK88F\n8bp7i6hV55vER45FtKKciQwWoA91FjfWTrDYPHb1X4OPZvcjQGnIJ1AAj+BSzEWr\neJXNo46RxLLl+cndiVDqlbJlhE9qVn9ueLHhPIPNSFZneY9cTj5+EOPyKiBCo4xB\ndTtVr29lLu/JwM2jZjBkMA4GA1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/\nAgEKMB0GA1UdDgQWBBQEev6GFqis9TaMgXfkNMEOEvu5ajAfBgNVHSMEGDAWgBQE\nev6GFqis9TaMgXfkNMEOEvu5ajAKBggqhkjOPQQDAgOBigAwgYYCQUlJqNoWCz4H\npjMNphxD4A8lfWtIrajGUhSxE9+JWRzoPpEJSwVobvryU2SO5u0sfqxtcmX/sBjY\n12N5QVFfqpB3AkErsjg8eMkh+OMalmWxRYtTuZt+i4DPm1CKEVIkUT8ZBXYTIl9V\nG3TG8lmby/8e+YUwJEKVvOy6tVI8ExEoVslwKw==\n-----END CERTIFICATE-----" + ], + "certificate": "-----BEGIN CERTIFICATE-----\nMIICOjCCAZygAwIBAgIUf4zFBobFJMkSIvM7CfceSVfYNggwCgYIKoZIzj0EAwIw\nKjEoMCYGA1UEAxMfdmF1bHQta21pcC1kZWZhdWx0LWludGVybWVkaWF0ZTAeFw0x\nOTA2MjQxOTA3MTBaFw0xOTA2MjUxOTA3NDBaMCAxDjAMBgNVBAsTBW5BcUswMQ4w\nDAYDVQQDEwU0Qjd2STCBmzAQBgcqhkjOPQIBBgUrgQQAIwOBhgAEAdxHrbr/EXUz\nzWCd9HMUDus6r/3QF1Y3u9dPD2UwM76J3aICmykkm7xoYpoyg4chBEDxBWh2YkGT\na4WFMoXBa+k1AZhdvlj8tjOUlYZrTCLB9FBPCGz3JB4f5cmbG5JVsQ8qnBPiyV3e\nU21cWM6mWlhZKHWIdBU2pj+eXW78K5LMu2sWo2cwZTAOBgNVHQ8BAf8EBAMCA6gw\nEwYDVR0lBAwwCgYIKwYBBQUHAwIwHQYDVR0OBBYEFAT0QZOpZCTMCz7F8+BvF2xs\nZSfkMB8GA1UdIwQYMBaAFDz+1SThpN6kdKiqsd0yzdUfCQ4kMAoGCCqGSM49BAMC\nA4GLADCBhwJBPxBV4DgPi5zihRnxu7zTNeqe/xlvrEt1uTff8QtW3JsigbBDHV+A\nxBe7vc8mL8VQPG7BFKvvxuQvOAeeQ+AR8ZoCQgDtbaWgLtfbzKvwlY48e6dLeBpK\nDu1DaZq+79EON2lhWQ+ULHblJc5cK0F6Ff5OC89aDnV1TWQDHeR91mZdYiWZZQ==\n-----END CERTIFICATE-----", + "serial_number": "728181095563584845125173905844944137943705466376" + } +} +``` + +## List credential serial numbers + +| Method | Path | +| :----- | :----------------------------------------- | +| `LIST` | `/kmip/scope/:scope/role/:role/credential` | + +List the serial numbers of all certificates within a role. + +### Parameters + +- `scope` (`string: `) - Name of scope. This is part of the request URL. +- `role` (`string: `) - Name of role. This is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole/credential +``` + +### Sample response + +```json +{ + "data": { + "keys": ["728181095563584845125173905844944137943705466376"] + } +} +``` + +## Revoke credential + +| Method | Path | +| :----- | :------------------------------------------------ | +| `POST` | `/kmip/scope/:scope/role/:role/credential/revoke` | + +Delete a certificate, thereby revoking it. + +### Parameters + +- `scope` (`string: `) - Name of scope. This is part of the request URL. +- `role` (`string: `) - Name of role. This is part of the request URL. +- `serial_number` (`string: ""`) - Serial number of certificate to revoke. + Exactly one of `serial_number` or `certificate` must be provided. +- `certificate` (`string: """`) - Certificate to revoke, in PEM format. + Exactly one of `serial_number` or `certificate` must be provided. + +### Sample payload + +```json +{ + "serial_number": "728181095563584845125173905844944137943705466376" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/kmip/scope/myscope/role/myrole/credential/revoke +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/kubernetes.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/kubernetes.mdx new file mode 100644 index 0000000000..ef7851ebe4 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/kubernetes.mdx @@ -0,0 +1,437 @@ +--- +layout: api +page_title: Kubernetes - Secrets Engines - HTTP API +description: This is the API documentation for the Vault Kubernetes secrets engine. +--- + +# Kubernetes secrets engine (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault Kubernetes secrets engine. To +learn more about the usage and operation, see the +[Kubernetes secrets engine documentation](/vault/docs/secrets/kubernetes). + +This documentation assumes the Kubernetes secrets engine is mounted at the +`/kubernetes` path in Vault. Since it is possible to enable secrets engines at +any location, please update your API calls accordingly. + +## Write configuration + +This endpoint configures the plugin with the necessary information to reach the +Kubernetes API and authenticate with it. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `/kubernetes/config` | + +### Parameters + +- `kubernetes_host` `(string: "https://$KUBERNETES_SERVICE_HOST:KUBERNETES_SERVICE_PORT_HTTPS")` - + Kubernetes API URL to connect to. Must be specified if the standard pod environment + variables `KUBERNETES_SERVICE_HOST` or `KUBERNETES_SERVICE_PORT_HTTPS` are not set. +- `kubernetes_ca_cert` `(string: "")` - PEM encoded CA certificate to verify the + Kubernetes API server certificate. Defaults to the local pod's CA certificate + at `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt` if found, or + otherwise the host's root CA set. +- `service_account_jwt` `(string: "")` - The JSON web token of the service account + used by the secrets engine to manage Kubernetes credentials. Defaults to the local pod's + JWT at `/var/run/secrets/kubernetes.io/serviceaccount/token` if found. +- `disable_local_ca_jwt` `(bool: false)` - Disable defaulting to the local CA + certificate and service account JWT when running in a Kubernetes pod. + +### Sample payload + +```json +{ + "kubernetes_host": "https://192.168.99.100:8443", + "kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----\n.....\n-----END CERTIFICATE-----" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/kubernetes/config +``` + +## Read configuration + +Returns the config previously set, excluding credentials. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/kubernetes/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/kubernetes/config +``` + +### Sample response + +```json +{ + "data":{ + "kubernetes_host": "https://192.168.99.100:8443", + "kubernetes_ca_cert": "-----BEGIN CERTIFICATE-----.....-----END CERTIFICATE-----", + "disable_local_ca_jwt": false + } +} +``` + +## Delete configuration + +Deletes the config previously set. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `/kubernetes/config` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE + http://127.0.0.1:8200/v1/kubernetes/config +``` + +## Create role + +A role configures what service account tokens can be generated, and what +permissions will be attached to them. The permissions attached to a service +account token depend on the Kubernetes roles applied to its service account. + +Each Kubernetes secrets engine role can operate in one of 3 modes. Each successive +mode generates more Kubernetes objects, and therefore requires more permissions +for Vault's own Kubernetes service account. + +* Generate a service account token for a pre-existing service account - set `service_account_name`. +* Generate a service account _and_ a token, and bind a pre-existing Kubernetes role - set `kubernetes_role_name`. +* Generate a Kubernetes role, role binding, service account and token - set `generated_role_rules`. + +Only one of `service_account_name`, `kubernetes_role_name` or +`generated_role_rules` can be set. + +| Method | Path | +| :----- | :---------------------------- | +| `POST` | `/kubernetes/roles/:name` | + +### Parameters + +- `name` `(string: )` - The name of the role. Included in the path. +- `allowed_kubernetes_namespaces` `(array: [])` - The list of Kubernetes + namespaces this role can generate credentials for. If set to `"*"` all + namespaces are allowed. If set with `allowed_kubernetes_namespace_selector`, the conditions are + `OR`ed. +- `allowed_kubernetes_namespace_selector` `(string: "")` - A label selector for Kubernetes + namespaces in which credentials can be generated. Accepts either a JSON or YAML object. The value + should be of type + [LabelSelector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.24/#labelselector-v1-meta) + as illustrated in [Sample Payload 4](/vault/api-docs/secret/kubernetes#sample-payload-4) and + [Sample Payload 5](/vault/api-docs/secret/kubernetes#sample-payload-5) below. + If set with `allowed_kubernetes_namespaces`, the conditions are `OR`ed. +- `token_max_ttl` `(string: "")` - The maximum TTL for generated Kubernetes + tokens, specified in seconds or as a Go duration format string, e.g. `"1h"`. + If not set or set to 0, the [system default](/vault/docs/configuration#max_lease_ttl) will be used. +- `token_default_ttl` `(string: "")` - The default TTL for generated Kubernetes + tokens, specified in seconds or as a Go duration format string, e.g. `"1h"`. + If not set or set to 0, the [system default](/vault/docs/configuration#default_lease_ttl) will be used. +- `token_default_audiences` `(string: "")` - The default intended audiences for generated Kubernetes + tokens, specified by a comma separated string. e.g `"custom-audience-0,custom-audience-1"`. + If not set or set to `""`, the Kubernetes cluster default for audiences of service account tokens will be used. +- `service_account_name` `(string: "")` - The pre-existing service account to + generate tokens for. Mutually exclusive with all role parameters. If set, only + a Kubernetes token will be created when credentials are requested. See the + [Kubernetes service account documentation](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/) + for more details on service accounts. +- `kubernetes_role_name` `(string: "")` - The pre-existing Role or ClusterRole + to bind a generated service account to. If set, Kubernetes token, service + account, and role binding objects will be created when credentials are requested. + See the [Kubernetes roles documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#role-and-clusterrole) + for more details on Kubernetes roles. +- `kubernetes_role_type` `(string: "Role")` - Specifies whether the Kubernetes + role is a `Role` or `ClusterRole`. +- `kubernetes_role_ref_type` `(string: "")` - Optional value indicating whether + the Kubernetes role referenced in the final RoleBinding is a Role or + ClusterRole. When left blank, Vault uses the value from `kubernetes_role_type`. +- `generated_role_rules` `(string: "")` - The Role or ClusterRole rules to use + when generating a role. Accepts either JSON or YAML formatted rules. If set, the + entire chain of Kubernetes objects will be generated when credentials are + requested. The value should be a `rules` key with an array of + [PolicyRule](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.23/#policyrule-v1-rbac-authorization-k8s-io) + objects, as illustrated in the + [Kubernetes RBAC documentation](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) + and [Sample Payload 3](/vault/api-docs/secret/kubernetes#sample-payload-3) below. +- `name_template` `(string: "")` - The name template to use when generating + service accounts, roles and role bindings. If unset, a default template is + used. See [username templating](/vault/docs/concepts/username-templating) + for details on how to write a custom template. +- `extra_annotations` `(map: nil)` - Additional annotations to + apply to all generated Kubernetes objects. See the + [Kubernetes annotations documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) + for more details on annotations. +- `extra_labels` `(map: nil)` - Additional labels to apply to + all generated Kubernetes objects. See the + [Kubernetes labels documentation](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/) + for more details on labels. + +### Sample payload 1 + +To generate tokens for a pre-existing service account: + +```json +{ + "allowed_kubernetes_namespaces": "*", + "service_account_name": "default", + "token_max_ttl": "24h" +} +``` + +### Sample payload 2 + +To generate tokens for a pre-existing ClusterRole: + +```json +{ + "allowed_kubernetes_namespaces": "*", + "kubernetes_role_type": "ClusterRole", + "kubernetes_role_name": "vault-k8s-secrets-role" +} +``` + +Or to define a secrets role of type `Role` but use a `ClusterRole` as reference + +```json +{ + "allowed_kubernetes_namespaces": "default", + "kubernetes_role_type": "Role", + "kubernetes_role_ref_type": "ClusterRole", + "kubernetes_role_name": "vault-k8s-secrets-role" +} +``` + +### Sample payload 3 + +To generate tokens for a defined set of Kubernetes role rules: + +```json +{ + "allowed_kubernetes_namespaces": "*", + "generated_role_rules": "rules:\n- apiGroups: [\"\"]\n resources: [\"pods\"]\n verbs: [\"list\"]\n", +} +``` + +Or to define the same rules as JSON: + +```json +{ + "allowed_kubernetes_namespaces": "*", + "generated_role_rules": "'rules': [{'apiGroups': [''],'resources': ['pods'],'verbs': ['list']}]" +} +``` + +### Sample payload 4 + +To generate tokens in namespaces based on a label selector for the namespaces: + +```json +{ + "allowed_kubernetes_namespace_selector": "matchLabels:\n stage: prod\n sa-generator: vault", + "service_account_name": "default", +} +``` + +Or to define the same selector as JSON: + +```json +{ + "allowed_kubernetes_namespace_selector": "'{'matchLabels':{'stage':'prod','sa-generator':'vault'}}", + "service_account_name": "default", +} +``` + +### Sample payload 5 + +To generate tokens in namespaces based on a label selector for the namespaces and via a normal +namespace array: + +```json +{ + "allowed_kubernetes_namespaces": "vault-system,testing", + "allowed_kubernetes_namespace_selector": "'{'matchLabels':{'stage':'prod','sa-generator':'vault'}}", + "service_account_name": "default", +} +``` + +In the payload above, the token can be generated for any namespace that either contains the labels +defined in the selector, or is named `vault-system` or `testing`. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/kubernetes/roles/default-role +``` + +## Read role + +Returns the previously configured role. + +| Method | Path | +| :----- | :---------------------------- | +| `GET` | `/kubernetes/roles/:name` | + +### Parameters + +- `name` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/kubernetes/role/default-role +``` + +### Sample response + +```json +{ + "data": { + "additional_metadata": {}, + "allowed_kubernetes_namespaces": [ + "*" + ], + "generated_role_rules": "", + "kubernetes_role_name": "", + "kubernetes_role_type": "Role", + "kubernetes_role_ref_type": "Role", + "name": "default-role", + "name_template": "", + "service_account_name": "default", + "token_default_ttl": 0, + "token_max_ttl": 86400 + } +} +``` + +## List roles + +Lists all the roles that are configured. + +| Method | Path | +| :----- | :-------------------------------- | +| `LIST` | `/kubernetes/roles` | +| `GET` | `/kubernetes/roles?list=true` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/kubernetes/roles +``` + +### Sample response + +```json +{ + "data": { + "keys": ["default-role", "prod-role"] + } +} +``` + +## Delete role + +Deletes the previously configured role. + +| Method | Path | +| :------- | :---------------------------- | +| `DELETE` | `/kubernetes/roles/:role` | + +### Parameters + +- `role` `(string: )` - Name of the role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/kubernetes/role/default-role +``` + +## Generate credentials + +Generate a service account token. + +| Method | Path | +| :----- | :------------------------ | +| `POST` | `/kubernetes/creds/:role` | + +### Parameters + +- `role` `(string: )` - Name of the role to generate credentials for. +- `kubernetes_namespace` `(string)` - The name of the Kubernetes + namespace in which to generate the credentials. Optional if the Vault role is configured + with a single namespace that is not `"*"`; required otherwise. +- `cluster_role_binding` `(bool: false)` - If true, generate a ClusterRoleBinding + to grant permissions across the whole cluster instead of within a namespace. + Requires the Vault role to have `kubernetes_role_type` set to ClusterRole. +- `ttl` `(string: "")` - The TTL of the generated Kubernetes service account token, + specified in seconds or as a Go duration format string, e.g. `"1h"`. The TTL + returned may be different from the TTL specified due to limits specified in + Kubernetes, Vault system-wide controls, or role-specific controls. +- `audiences` `(string: "")` - A comma separated string containing the intended audiences + of the generated Kubernetes service account the token, e.g. `"custom-audience-0,custom-audience-1"`. + If not set or set to `""`, + the [token_default_audiences](/vault/api-docs/secret/kubernetes#token_default_audiences) will be used. + +### Sample payload + +```json +{ + "kubernetes_namespace": "default", + "ttl": "1h" +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/kubernetes/creds/default-role +``` + +### Sample response + +```json +{ + "request_id": "58fefc6c-5195-c17a-94f2-8f889f3df57c", + "lease_id": "kubernetes/creds/default-role/aWczfcfJ7NKUdiirJrPXIs38", + "renewable": false, + "lease_duration": 3600, + "data": { + "service_account_name": "default", + "service_account_namespace": "default", + "service_account_token": "eyJhbG..." + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/index.mdx new file mode 100644 index 0000000000..6abdfbaa7d --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/index.mdx @@ -0,0 +1,15 @@ +--- +layout: api +page_title: KV - Secrets Engines - HTTP API +description: This is the API documentation for the Vault KV secrets engine. +--- + +# KV secrets engine (API) + +This backend can be run in one of two versions. Each of which have a distinct API. +Choose the version below you are running. For more information on the KV secrets +engine see the [Vault kv documentation](/vault/docs/secrets/kv). + +- [KV Version 1 API](/vault/api-docs/secret/kv/kv-v1) + +- [KV Version 2 API](/vault/api-docs/secret/kv/kv-v2) diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v1.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v1.mdx new file mode 100644 index 0000000000..d450be840c --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v1.mdx @@ -0,0 +1,215 @@ +--- +layout: api +page_title: KV - Secrets Engines - HTTP API +description: This is the API documentation for the Vault KV secrets engine, version 1. +--- + +# KV secrets engine - version 1 (API) + +This is the API documentation for the Vault KV secrets engine. For general +information about the usage and operation of the version 1 KV secrets engine, please +see the [Vault KV documentation](/vault/docs/secrets/kv/kv-v1). For information +about the differences between KV version 1 and version 2, please [see the KV overview +documentation](/vault/docs/secrets/kv). + +~> Note: This documentation assumes the kv secrets engine is enabled at the +`/secret` path in Vault. Since it is possible to enable secrets engines at any +location, please update your API calls accordingly. + +## Read secret + +This endpoint retrieves the secret at the specified location. + +| Method | Path | +| :----- | :-------------- | +| `GET` | `/secret/:path` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to read. + This is specified as part of the URL. +- `read_snapshot_id` `(string: "")` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path. + +### Sample requests + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/secret/my-secret +``` + +To read the secret from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`: + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/secret/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a +``` + +### Sample response + +```json +{ + "auth": null, + "data": { + "foo": "bar", + "ttl": "1h" + }, + "lease_duration": 3600, + "lease_id": "", + "renewable": false +} +``` + +_Note_: the `lease_duration` field, which will be populated if a "ttl" field +was included in the data, is advisory. No lease is created. This is a way for +writers to indicate how often a given value should be re-read by the client. +See the [Vault KV secrets engine documentation](/vault/docs/secrets/kv/kv-v1#ttls) +for more details. + +## List secrets + +This endpoint returns a list of key names at the specified location. Folders are +suffixed with `/`. The input must be a folder; list on a file will not return a +value. Note that no policy-based filtering is performed on keys; do not encode +sensitive information in key names. The values themselves are not accessible via +this API. + +| Method | Path | +| :----- | :-------------- | +| `LIST` | `/secret/:path` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to list. + This is specified as part of the URL. +- `read_snapshot_id` `(string: "")` - Query parameter specifying the ID of a snapshot previously loaded into Vault that contains secrets at the provided path. + +### Sample requests + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/secret/my-secret +``` + +To list the secrets from a loaded snapshot with ID `2403d301-94f2-46a1-a39d-02be83e2831a`: + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://127.0.0.1:8200/v1/secret/my-secret?read_snapshot_id=2403d301-94f2-46a1-a39d-02be83e2831a" +``` + + +### Sample response + +The example below shows output for a query path of `secret/` when there are +secrets at `secret/foo` and `secret/foo/bar`; note the difference in the two +entries. + +```json +{ + "auth": null, + "data": { + "keys": ["foo", "foo/"] + }, + "lease_duration": 2764800, + "lease_id": "", + "renewable": false +} +``` + +## Create/Update secret + +This endpoint stores a secret at the specified location. If the value does not +yet exist, the calling token must have an ACL policy granting the `create` +capability. If the value already exists, the calling token must have an ACL +policy granting the `update` capability. + +| Method | Path | +| :----- | :-------------- | +| `POST` | `/secret/:path` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secrets to + create/update. This is specified as part of the URL. + +- `:key` `(string: "")` – Specifies a key in the payload, paired with an associated value, to + be held at the given location. Multiple key/value pairs can be specified, and + all will be returned on a read operation. A key called `ttl` will trigger + some special behavior. See the [Vault KV secrets engine + documentation](/vault/docs/secrets/kv/kv-v1#ttls) for details. + +### Sample payload + +```json +{ + "foo": "bar", + "zip": "zap" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/secret/my-secret +``` + +## Recover secret + +[Recover](/vault/docs/sysadmin/snapshots/recover-a-secret) a secret at the +specified location from the given loaded snapshot. + +| Method | Path | +|:----------|:----------------| +| `RECOVER` | `/secret/:path` | + +### Query parameters + +- `path` `(string: )` – The target path of the secrets you want to recover. + +### Headers + +- `X-Vault-Recover-Snapshot-Id` `(string: )` - The ID of a snapshot previously loaded into Vault that contains secrets at the provided path. +- `X-Vault-Recover-Source-Path` `(string: "")` - Optional header specifying the original path of the data in the snapshot, if recovering to a different path than the original path. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request RECOVER \ + --header "X-Vault-Recover-Snapshot-Id: 2403d301-94f2-46a1-a39d-02be83e2831a" \ + --header "X-Vault-Recover-Source-Path: secret/my-old-secret" \ + https://127.0.0.1:8200/v1/secret/my-secret +``` + +## Delete secret + +This endpoint deletes the secret at the specified location. + +| Method | Path | +| :------- | :-------------- | +| `DELETE` | `/secret/:path` | + +### Parameters + +- `path` `(string: )` – Specifies the path of the secret to delete. + This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/secret/my-secret +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v2.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v2.mdx new file mode 100644 index 0000000000..6cde70b3c3 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/kv/kv-v2.mdx @@ -0,0 +1,778 @@ +--- +layout: api +page_title: KV - Secrets Engines - HTTP API +description: This is the API documentation for the Vault KV secrets engine, version 2. +--- + +# KV secrets engine - version 2 (API) + +This is the API documentation for the Vault KV secrets engine while running in +versioned mode. For general information about the usage and operation of the version 2 +KV secrets engine, please see the [Vault KV documentation](/vault/docs/secrets/kv/kv-v2). +For information about the differences between KV version 1 and version 2, please [see the KV overview +documentation](/vault/docs/secrets/kv). + +## Configure the KV engine + +This path configures backend level settings that are applied to every key in the +key-value store. + +| Method | Path | +|:-------|:-----------------------------| +| `POST` | `/:secret-mount-path/config` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount to config, + such as `secret`. This is specified as part of the URL. + +- `max_versions` `(int: 0)` – The number of versions to keep per key. This value + applies to all keys, but a key's metadata setting can overwrite this value. + Once a key has more than the configured allowed versions, the oldest version + will be permanently deleted. When 0 is used or the value is unset, Vault + will keep 10 versions. + +- `cas_required` `(bool: false)` – If true all keys will require the cas + parameter to be set on all write requests. + +- `delete_version_after` `(string:"0s")` – If set, specifies the length + of time before a version is deleted. + Accepts [duration format strings](/vault/docs/concepts/duration-format). + +### Sample payload + +```json +{ + "max_versions": 5, + "cas_required": false, + "delete_version_after": "3h25m19s" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/secret/config +``` + +## Read KV engine configuration + +This path retrieves the current configuration for the secrets backend at the +given path. + +| Method | Path | +|:-------|:-----------------------------| +| `GET` | `/:secret-mount-path/config` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount to read the config, + of, such as `secret`. This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/secret/config +``` + +### Sample response + +```json +{ + "data": { + "cas_required": false, + "delete_version_after": "3h25m19s", + "max_versions": 0 + } +} +``` + +## Read secret version + +This endpoint retrieves the secret at the specified location. The metadata +fields `created_time`, `deletion_time`, `destroyed`, and `version` are version +specific. The `custom_metadata` field is part of the secret's key metadata and +is included in the response whether or not the calling token has `read` access to +the associated [metadata endpoint](/vault/api-docs/secret/kv/kv-v2#read-secret-metadata). + +| Method | Path | +|:-------|:---------------------------------------------------------| +| `GET` | `/:secret-mount-path/data/:path?version=:version-number` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to read, such as `secret`. This is specified as part of the URL. +- `path` `(string: )` – Specifies the path of the secret to read. + This is specified as part of the URL. +- `version` `(int: 0)` - Specifies the version to return. If not set the latest + version is returned. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/secret/data/my-secret?version=2 +``` + +### Sample response + +```json +{ + "data": { + "data": { + "foo": "bar" + }, + "metadata": { + "created_time": "2018-03-22T02:24:06.945319214Z", + "custom_metadata": { + "owner": "jdoe", + "mission_critical": "false" + }, + "deletion_time": "", + "destroyed": false, + "version": 2 + } + } +} +``` + +## Create/Update secret + +This endpoint creates a new version of a secret at the specified location. If +the value does not yet exist, the calling token must have an ACL policy granting +the `create` capability. If the value already exists, the calling token must +have an ACL policy granting the `update` capability. + +| Method | Path | +|:-------|:---------------------------------| +| `POST` | `/:secret-mount-path/data/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to update, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to update. + This is specified as part of the URL. + +- `options` `(Map: )` – An object that holds option settings. + + - `cas` `(int: )` - This flag is required if `cas_required` is set + to true on either the secret or the engine's config. If not set the write + will be allowed. In order for a write to be successful, `cas` must be set to + the current version of the secret. If set to 0 a write will only be allowed if + the key doesn't exist as unset keys do not have any version information. Also + remember that soft deletes do not remove any underlying version data from storage. + In order to write to a soft deleted key, the cas parameter must match the key's + current version. + +- `data` `(Map: )` – The contents of the data map will be stored and + returned on read. + +### Sample payload + +```json +{ + "options": { + "cas": 0 + }, + "data": { + "foo": "bar", + "zip": "zap" + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/secret/data/my-secret +``` + +### Sample response + +```json +{ + "data": { + "created_time": "2018-03-22T02:36:43.986212308Z", + "custom_metadata": { + "owner": "jdoe", + "mission_critical": "false" + }, + "deletion_time": "", + "destroyed": false, + "version": 1 + } +} +``` + +## Patch secret + +This endpoint provides the ability to patch an _existing_ secret at the specified +location. The secret must neither be deleted nor destroyed. The calling token must +have an ACL policy granting the `patch` capability. Currently, only +[JSON merge patch](https://datatracker.ietf.org/doc/html/draft-ietf-appsawg-json-merge-patch-07) +is supported and must be specified using a `Content-Type` header value of +`application/merge-patch+json`. A new version will be created upon successfully +applying a patch with the provided data. + +| Method | Path | +|:--------|:---------------------------------| +| `PATCH` | `/:secret-mount-path/data/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to patch, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to patch. + This is specified as part of the URL. + +- `options` `(Map: )` – An object that holds option settings. + + - `cas` `(int: )` - This flag is required if `cas_required` is set to true on either + the secret or the engine's config. In order for a write to be successful, `cas` must be set + to the current version of the secret. A patch operation must be attempted on an existing + key, thus the provided `cas` value must be greater than 0. + +- `data` `(Map: )` – The contents of the data map will be applied as a partial + update to the existing entry via a JSON merge patch to the existing entry. + +### Sample payload + +```json +{ + "options": { + "cas": 1 + }, + "data": { + "foo": "a", + "bar": { + "baz": "b" + } + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --header "Content-Type: application/merge-patch+json" + --request PATCH \ + --data @payload.json \ + https://127.0.0.1:8200/v1/secret/data/my-secret +``` + +### Sample response + +```json +{ + "data": { + "created_time": "2021-09-10T15:26:08.684999Z", + "custom_metadata": { + "owner": "jdoe", + "mission_critical": "false" + }, + "deletion_time": "", + "destroyed": false, + "version": 2 + } +} +``` + +## Read secret subkeys + +This endpoint provides the subkeys within a secret entry that exists +at the requested path. The secret entry at this path will be retrieved +and stripped of all data by replacing underlying values of leaf keys +(i.e. non-map keys or map keys with no underlying subkeys) with `null`. + +| Method | Path | +|:-------|:------------------------------------| +| `GET` | `/:secret-mount-path/subkeys/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to read, such as `secret`. This is specified as part of the URL. +- `path` `(string: )` – Specifies the path of the secret to read. + This is specified as part of the URL. +- `version` `(int: 0)` - Specifies the version to return. If not set the latest + version is returned. +- `depth` `(int: 0)` - Specifies the deepest nesting level to provide in the output. + The default value 0 will not impose any limit. If non-zero, keys that reside at the + specified `depth` value will be artificially treated as leaves and will thus be `null` + even if further underlying subkeys exist. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/secret/subkeys/my-secret?version=1 +``` + +### Sample secret data + +```json +{ + "foo": "abc", + "bar": { + "baz": "def" + }, + "quux": {} +} +``` + +### Sample response + +```json +{ + "subkeys": { + "foo": null, + "bar": { + "baz": null + }, + "quux": null + }, + "metadata": { + "created_time": "2021-12-14T20:28:00.773477Z", + "custom_metadata": null, + "deletion_time": "", + "destroyed": false, + "version": 1 + } +} +``` + +## Delete latest version of secret + +This endpoint issues a soft delete of the secret's latest version at the +specified location. This marks the version as deleted and will stop it from +being returned from reads, but the underlying data will not be removed. A +delete can be undone using the `undelete` path. + +| Method | Path | +| :------- | :------------------- | +| `DELETE` | `/:secret-mount-path/data/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to delete, such as `secret`. This is specified as part of the URL. +- `path` `(string: )` – Specifies the path of the secret to delete. + This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/secret/data/my-secret +``` + +## Delete secret versions + +This endpoint issues a soft delete of the specified versions of the secret. This +marks the versions as deleted and will stop them from being returned from reads, +but the underlying data will not be removed. A delete can be undone using the +`undelete` path. + +| Method | Path | +|:-------|:-----------------------------------| +| `POST` | `/:secret-mount-path/delete/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to delete, such as `secret`. This is specified as part of the URL. +- `path` `(string: )` – Specifies the path of the secret to delete. + This is specified as part of the URL. +- `versions` `([]int: )` - The versions to be deleted. The versioned + data will not be deleted, but it will no longer be returned in normal get + requests. + +### Sample payload + +```json +{ + "versions": [1, 2] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/secret/delete/my-secret +``` + +## Undelete secret versions + +Undeletes the data for the provided version and path in the key-value store. +This restores the data, allowing it to be returned on get requests. + +| Method | Path | +|:-------|:-------------------------------------| +| `POST` | `/:secret-mount-path/undelete/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to undelete, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to undelete. + This is specified as part of the URL. + +- `versions` `([]int: )` - The versions to undelete. The versions will + be restored and their data will be returned on normal get requests. + +### Sample payload + +```json +{ + "versions": [1, 2] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/secret/undelete/my-secret +``` + +## Destroy secret versions + +Permanently removes the specified version data for the provided key and version +numbers from the key-value store. + +| Method | Path | +|:-------|:------------------------------------| +| `PUT` | `/:secret-mount-path/destroy/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to destroy, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to destroy. + This is specified as part of the URL. + +- `versions` `([]int: )` - The versions to destroy. Their data will be + permanently deleted. + +### Sample payload + +```json +{ + "versions": [1, 2] +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request PUT \ + --data @payload.json \ + https://127.0.0.1:8200/v1/secret/destroy/my-secret +``` + +## List secrets + +This endpoint returns a list of key names at the specified location. Folders are +suffixed with `/`. The input must be a folder; list on a file will not return a +value. Note that no policy-based filtering is performed on keys; do not encode +sensitive information in key names. The values themselves are not accessible via +this command. + +To list secrets for KV v2, a user must have a policy granting them the list capability on this `/metadata/` path - even if all the rest of their interactions with the KV v2 are via the `/data/` APIs. Access to at least list the `/metadata/` path should typically also be granted. + +| Method | Path | +|:-------|:-------------------------------------| +| `LIST` | `/:secret-mount-path/metadata/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing +the secret to list, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secrets to list. + This is specified as part of the URL. + +- `exclude_deleted` `(bool: false)` – Only return non-deleted entries. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + https://${VAULT_ADDR}/v1/secret/metadata/my-secret?exclude_deleted=false +``` + +### Sample response + +The example below shows output for a query path of `secret/` when there are +secrets at `secret/foo` and `secret/foo/bar`; note the difference in the two +entries. + +```json +{ + "data": { + "keys": ["foo", "foo/"] + } +} +``` + +## Read secret metadata + +This endpoint retrieves the metadata and versions for the secret at the +specified path. Metadata is version-agnostic. + +| Method | Path | +|:-------|:-------------------------------------| +| `GET` | `/:secret-mount-path/metadata/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to read, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to read. + This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + https://127.0.0.1:8200/v1/secret/metadata/my-secret +``` + +### Sample response + +```json +{ + "data": { + "cas_required": false, + "created_time": "2018-03-22T02:24:06.945319214Z", + "current_version": 3, + "delete_version_after": "3h25m19s", + "max_versions": 0, + "oldest_version": 0, + "updated_time": "2018-03-22T02:36:43.986212308Z", + "custom_metadata": { + "foo": "abc", + "bar": "123", + "baz": "5c07d823-3810-48f6-a147-4c06b5219e84" + }, + "versions": { + "1": { + "created_time": "2018-03-22T02:24:06.945319214Z", + "created_by": { + "actor": "userpass-myuser", + "operation": "create", + "entity_id": "12345678-1234-1234-1234-123456789012", + "client_id": "12345678-1234-1234-1234-123456789012", + }, + "deletion_time": "", + "destroyed": false + }, + "2": { + "created_time": "2018-03-22T02:36:33.954880664Z", + "created_by": { + "actor": "userpass-myuser", + "operation": "update", + "entity_id": "12345678-1234-1234-1234-123456789012", + "client_id": "12345678-1234-1234-1234-123456789012", + }, + "deletion_time": "", + "destroyed": false + }, + "3": { + "created_time": "2018-03-22T02:36:43.986212308Z", + "created_by": { + "actor": "userpass-myuser", + "operation": "update", + "entity_id": "12345678-1234-1234-1234-123456789012", + "client_id": "12345678-1234-1234-1234-123456789012", + }, + "deletion_time": "", + "destroyed": false + } + } + } +} +``` + +## Create/Update metadata + +This endpoint creates or updates the metadata of a secret at the specified location. +It does not create a new version. + +| Method | Path | +|:-------|:-------------------------------------| +| `POST` | `/:secret-mount-path/metadata/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to update, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to update. + This is specified as part of the URL. + +- `max_versions` `(int: 0)` – The number of versions to keep per key. If not + set, the backend’s configured max version is used. Once a key has more than + the configured allowed versions, the oldest version will be permanently + deleted. + +- `cas_required` `(bool: false)` – If true, the key will require the `cas` + parameter to be set on all write requests. If false, the backend’s + configuration will be used. + +- `delete_version_after` `(string:"0s")` – Set the `delete_version_after` value + to a duration to specify the `deletion_time` for all new versions + written to this key. If not set, the backend's `delete_version_after` will be + used. If the value is greater than the backend's `delete_version_after`, the + backend's `delete_version_after` will be used. Accepts [duration format + strings](/vault/docs/concepts/duration-format). + +- `custom_metadata` `(map: nil)` - A map of arbitrary string to string valued user-provided metadata meant + to describe the secret. + +### Sample payload + +```json +{ + "max_versions": 5, + "cas_required": false, + "delete_version_after": "3h25m19s", + "custom_metadata": { + "foo": "abc", + "bar": "123", + "baz": "5c07d823-3810-48f6-a147-4c06b5219e84" + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + https://127.0.0.1:8200/v1/secret/metadata/my-secret +``` + +## Patch metadata + +This endpoint patches an existing metadata entry of a secret at the specified +location. The calling token must have an ACL policy granting the `patch` +capability. Currently, only JSON merge patch is supported and must be specified +using a `Content-Type` header value of `application/merge-patch+json`. It does +not create a new version. + +| Method | Path | +|:--------|:-------------------------------------| +| `PATCH` | `/:secret-mount-path/metadata/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to patch, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to patch. + This is specified as part of the URL. + +- `max_versions` `(int: 0)` – The number of versions to keep per key. If not + set, the backend’s configured max version is used. Once a key has more than + the configured allowed versions, the oldest version will be permanently + deleted. + +- `cas_required` `(bool: false)` – If true, the key will require the `cas` + parameter to be set on all write requests. If false, the backend’s + configuration will be used. + +- `delete_version_after` `(string:"0s")` – Set the `delete_version_after` value + to a duration to specify the `deletion_time` for all new versions + written to this key. If not set, the backend's `delete_version_after` will be + used. If the value is greater than the backend's `delete_version_after`, the + backend's `delete_version_after` will be used. Accepts [duration format + strings](/vault/docs/concepts/duration-format). + +- `custom_metadata` `(map: nil)` - A map of arbitrary string to string valued user-provided metadata meant + to describe the secret. + +### Sample payload + +```json +{ + "max_versions": 5, + "custom_metadata": { + "bar": "123" + } +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --header "Content-Type: application/merge-patch+json" + --request PATCH \ + --data @payload.json \ + https://127.0.0.1:8200/v1/secret/metadata/my-secret +``` + +## Delete metadata and all versions + +This endpoint permanently deletes the key metadata and all version data for the +specified key. All version history will be removed. + +| Method | Path | +|:---------|:-------------------------| +| `DELETE` | `/:secret-mount-path/metadata/:path` | + +### Parameters + +- `secret-mount-path` `(string: )` - The path to the KV mount containing + the secret to delete, such as `secret`. This is specified as part of the URL. + +- `path` `(string: )` – Specifies the path of the secret to delete. + This is specified as part of the URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + https://127.0.0.1:8200/v1/secret/metadata/my-secret +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/ldap.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/ldap.mdx new file mode 100644 index 0000000000..d4d643cb15 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/ldap.mdx @@ -0,0 +1,874 @@ +--- +layout: api +page_title: LDAP - Secrets Engines - HTTP API +description: This is the API documentation for the Vault LDAP secrets engine. +--- + +# LDAP secrets engine (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault LDAP secrets engine. For general +information about the usage and operation of the LDAP secrets engine, +please see the [LDAP secrets engine docs](/vault/docs/secrets/ldap). + +This documentation assumes the LDAP secrets engine is enabled at the `/ldap` path +in Vault. Since it is possible to mount secrets engines at any path, please +update your API calls accordingly. + +## Configuration management + +This endpoint configures the LDAP secret engine to manage user entries. + +| Method | Path | +| :------- | :----------------- | +| `POST` | `/ldap/config` | +| `GET` | `/ldap/config` | +| `DELETE` | `/ldap/config` | + +-> **Note**: The LDAP entry used by `config` should have the necessary privileges +to search and change entry passwords in LDAP. + +### Parameters + +- `binddn` `(string: )` - Distinguished name (DN) of object to bind for managing user entries. + For example, `cn=vault,ou=Users,dc=hashicorp,dc=com`. +- `bindpass` `(string: )` - Password to use along with `binddn` for managing user entries. +- `url` `(string: "ldap://127.0.0.1")` - The LDAP server to connect to. Examples: `ldaps://ldap.myorg.com`, + `ldaps://ldap.myorg.com:636`. This can also be a comma-delineated list of URLs, e.g. + `ldaps://ldap.myorg.com, ldaps://ldap.myorg.com:636`, in which case the servers will be tried in-order if + there are errors during the connection process.`. +- `password_policy` `(string: )` - The name of the [password policy](/vault/docs/concepts/password-policies) + to use to generate passwords. Note that this accepts the name of the policy, not the policy itself. +- `schema` `(string: "openldap")` - The LDAP schema to use when storing entry passwords. + Valid schemas include `openldap`, `ad`, and `racf`. +- `credential_type` `(string: "password")` - The type of password to generate. Valid values include `password` and `phrase`. + When set to `phrase`, the secrets engine will modify the RACF schema for all static roles to manage password phrases instead of passwords. +- `userdn` `(string: )` - The base DN under which to perform user search in + [library management](/vault/api-docs/secret/ldap#library-management) and [static roles](/vault/api-docs/secret/ldap#static-roles). + For example, `ou=Users,dc=hashicorp,dc=com`. +- `userattr` `(string: )` – The attribute field name used to perform user search + in [library management](/vault/api-docs/secret/ldap#library-management) and [static roles](/vault/api-docs/secret/ldap#static-roles). + Defaults to `cn` for the `openldap` schema, `userPrincipalName` for the `ad` schema, and + `racfid` for the `racf` schema. +- `upndomain` (string: `optional`) - The domain (userPrincipalDomain) used to construct a UPN + string for authentication. The constructed UPN will appear as `[binddn]@[upndomain]`. For + example, if `upndomain=example.com` and `binddn=admin`, the UPN string `admin@example.com` + will be used to log in to Active Directory. +- `request_timeout` `(integer: 90, string: "90s" )` - Timeout, in seconds, for the connection when + making requests against the server before returning back an error. +- `starttls` `(bool: )` - If true, issues a `StartTLS` command after establishing an unencrypted connection. +- `insecure_tls` `(bool: )` - 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. +- `client_tls_cert` `(string: )` - Client certificate to provide to the LDAP server, must be x509 + PEM encoded. +- `client_tls_key` `(string: )` - Client key to provide to the LDAP server, must be x509 PEM encoded. +- `skip_static_role_import_rotation` `(bool: false)` - The default value to use for `skip_import_rotation` when + creating static roles. This field can be overridden on an individual role level during [role creation](#static-roles). + See the [static roles section](#static-roles) for more detailed information and caveats. + +@include 'rotationfields.mdx' + +**Deprecated Parameters**: + +- `length` `(int: 64)` - The length of generated password strings. Note: some schemas may require shorter + password lengths (such as `racf`). Mutually exclusive with `password_policy` +- `connection_timeout` `(integer: 30 or string: "30s")` - Timeout, in + seconds, before trying the next URL in your Vault configuration when + attempting to connect to your LDAP server. When both + `connection_timeout` and `request_timeout` are set, Vault uses the + smaller of the two values for connection **and** request timeouts. + +**Note about password generation**: + +`length` and `password_policy` cannot both be set in the configuration. The `POST` endpoint will reject the +configuration if both are specified. + +- If neither are set, this will default to a reasonable default password generation algorithm (the same algorithm as + prior to the introduction of password policies). +- If `length` is set, the same algorithm is used, but with the length specified instead of the default length. +- If `password_policy` is set, the password will be generated from the associated + [password policy](/vault/docs/concepts/password-policies). The policy is not exercised prior to saving the configuration. + The policy will need to exist prior to passwords needing to be generated by this engine, but does not need to exist + prior to saving the configuration. + +See [LDAP secrets engine docs](/vault/docs/secrets/ldap) for additional information. + +### Sample payload + +```json +{ + "binddn": "cn=vault,ou=Users,dc=hashicorp,dc=com", + "bindpass": "pa$$w0rd", + "url": "ldaps://127.0.0.11" +} +``` + +### Sample POST request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/ldap/config +``` + +### Sample GET request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + https://127.0.0.1:8200/v1/ldap/config +``` + +### Sample response + +```json +{ + "data": { + "binddn": "cn=admin,dc=hashicorp,dc=com", + "case_sensitive_names": false, + "certificate": "", + "insecure_tls": false, + "length": 64, + "schema": "openldap", + "starttls": false, + "tls_max_version": "tls12", + "tls_min_version": "tls12", + "url": "ldap://127.0.0.1" + } +} +``` + +## Rotate root password + +The `rotate-root` endpoint offers password rotation for the `binddn` entry used to manage LDAP. +This generated password will only be known to Vault and will not be retrievable once rotated. + +| Method | Path | +| :----- | :---------------------- | +| `POST` | `/ldap/rotate-root` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/ldap/rotate-root +``` + +## Static roles + +The `static-role` endpoint configures Vault to manage the passwords of existing individual LDAP entries. + +| Method | Path | +| :------- | :--------------------------------- | +| `GET` | `/ldap/static-role` | +| `GET` | `/ldap/static-role/:role_name` | +| `LIST` | `/ldap/static-role/:role_name` | +| `POST` | `/ldap/static-role/:role_name` | +| `DELETE` | `/ldap/static-role/:role_name` | + + + + Windows Servers hosting Active Directory include a + `lifetime period of an old password` configuration setting that lets clients + authenticate with old passwords for a specified amount of time. + + For more information, refer to the + [NTLM network authentication behavior](https://learn.microsoft.com/en-us/troubleshoot/windows-server/windows-security/new-setting-modifies-ntlm-network-authentication) + guide by Microsoft. + + + +### Parameters + +- `role_name` `(string: )` – URL parameter specifying the name of the + role. Role name can contain an arbitrary number of forward slashes to define a + [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths). +- `username` `(string: )` - The username of the existing LDAP entry to manage + password rotation for. LDAP search for the username will be rooted at the [userdn](/vault/api-docs/secret/ldap#userdn) + configuration value. The attribute to use when searching for the user can be configured + with the [userattr](/vault/api-docs/secret/ldap#userattr) configuration value. This is useful + when `dn` isn't used for login purposes (such as SSH). Cannot be modified after creation.
+ **Example:** `"bob"` +- `dn` `(string: )` - Distinguished name (DN) of the existing LDAP entry to manage + password rotation for. If given, it will take precedence over `username` for the LDAP + search performed during password rotation. Cannot be modified after creation.
+ **Example:** `cn=bob,ou=Users,dc=hashicorp,dc=com` +- `rotation_period` `(string: )` - How often Vault should rotate the password of the user entry. Accepts + [duration format strings](/vault/docs/concepts/duration-format). The minimum rotation period is 5 seconds.
+ **Example:** `"3600", "5s", "1h"` +- `skip_import_rotation` `(boolean: false)` - When set on a role creation request, Vault will not rotate the + pre-existing password of the associated LDAP entry. Note: This means that Vault will not be able to supply the + password to `GET` requests until the password is rotated (either automatically or manually by `rotate-role`). This + field overrides `skip_static_role_import_rotation` from the ldap config if both are set. + +### Sample payload + +```json +{ + "dn": "cn=hashicorp,ou=Users,dc=hashicorp,dc=com", + "rotation_period": "24h", + "username": "hashicorp" +} +``` + +### Sample POST request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/ldap/static-role/hashicorp +``` + +### Sample GET request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/ldap/static-role/hashicorp +``` + +### Sample GET response + +```json +{ + "data": { + "dn": "uid=hashicorp,ou=Users,dc=hashicorp,dc=com", + "last_vault_rotation": "2020-02-19T11:31:53.7812-05:00", + "rotation_period": 86400, + "username": "hashicorp" + } +} +``` + +### Sample LIST response + +```json +["hashicorp", "bob"] +``` + +## Static role passwords + +The `static-cred` endpoint offers the credential information for a given static-role. + +| Method | Path | +| :----- | :--------------------------------- | +| `GET` | `/ldap/static-cred/:role_name` | + +### Parameters + +- `role_name` `(string: )` – URL parameter specifying the name of the + role. + +#### Sample GET request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/ldap/static-cred/hashicorp +``` + +#### Sample GET response + +```json +{ + "dn": "uid=hashicorp,ou=Users,dc=hashicorp,dc=com", + "last_vault_rotation": "2020-02-19T11:31:53.7812-05:00", + "password": "LTNfyn7pS7XEZIxEYQ2sEAWic02PEP7zSvIs0xMqIjaU0ORzLhKOKVmYLxL1Xkyv", + "last_password": "?@09AZSen9TzUwK7ZhafS7B0GuWGraQjfWEna5SwnmF/tVaKFqjXhhGV/Z0v/pBJ", + "rotation_period": 86400, + "ttl": 86072, + "username": "hashicorp" +} +``` + +## Manually rotate static role password + +The `rotate-role` endpoint rotates the password of an existing static role. + +| Method | Path | +| :----- | :--------------------------------- | +| `POST` | `/ldap/rotate-role/:role_name` | + +### Parameters + +- `role_name` `(string: )` – URL parameter specifying the name of the + role. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/ldap/rotate-role/:role_name +``` + +## Dynamic roles + +Create or update a dynamic role configuration. This provides instructions to Vault on how to create an +LDAP domain user account. + +### Create/Delete dynamic role configuration + +Creates, updates, or deletes a dynamic role. + +| Method | Path | +| :------- | :-------------------------- | +| `GET` | `/ldap/role/:role_name` | +| `POST` | `/ldap/role/:role_name` | +| `DELETE` | `/ldap/role/:role_name` | + +The `POST` endpoint allows for partial updates of existing roles. If a role exists and a `POST` request is made +against it, only the keys specified in the request will be updated. To delete a value, specify the key with an +empty string as the value. Example: `vault write ldap/role/myrole default_ttl=""` + +#### Parameters + +- `role_name` `(string: )` – URL parameter specifying the name of the + role. Role name can contain an arbitrary number of forward slashes to define a + [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths). +- `creation_ldif` `(string, required)` - A templatized LDIF string used to create a user account. This may contain + multiple LDIF entries. The `creation_ldif` can also be used to add the user account to an **_existing_** group. + All LDIF entries are performed in order. If Vault encounters an error while executing the `creation_ldif` it will + stop at the first error and not execute any remaining LDIF entries. If an error occurs and `rollback_ldif` is + specified, the LDIF entries in `rollback_ldif` will be executed. See `rollback_ldif` for more details. This field + may optionally be provided as a base64 encoded string. +- `deletion_ldif` `(string, required)` - A templatized LDIF string used to delete the user account once its TTL has + expired. This may contain multiple LDIF entries. All LDIF entries are performed in order. If Vault encounters an + error while executing an entry in the `deletion_ldif` it will attempt to continue executing any remaining entries. + This field may optionally be provided as a base64 encoded string. +- `rollback_ldif` `(string, not required but recommended)` - A templatized LDIF string used to attempt to rollback + any changes in the event that execution of the `creation_ldif` results in an error. This may contain multiple LDIF + entries. All LDIF entries are performed in order. If Vault encounters an error while executing an entry in the + `rollback_ldif` it will attempt to continue executing any remaining entries. This field may optionally be provided + as a base64 encoded string. +- `username_template` `(string)` - A template used to generate a dynamic username. This will be used to fill in the + `.Username` field within the `creation_ldif` string. + +
+Default Username Template + +``` +v_{{.DisplayName}}_{{.RoleName}}_{{random 10}}_{{unix_time}} +``` + +
+Example Usernames: + +| Example | | +| ------------- | ------------------------------------------ | +| `DisplayName` | `token` | +| `RoleName` | `myrolename` | +| Username | `v_token_myrolename_uszt1n4cyh_1614294836` | + +| Example | | +| ------------- | -------------------------------------------------------------------- | +| `DisplayName` | `amuchlonger_dispname` | +| `RoleName` | `role-name-with-dashes` | +| Username | `v_amuchlonger_dispname_role-name-with-dashes_s0t9xb0jsa_1614294836` | + +
+
+ +- `default_ttl` `(string/int)` - Specifies the TTL for the leases associated with this role. Accepts + [duration format strings](/vault/docs/concepts/duration-format). Defaults to system/engine default TTL time. +- `max_ttl` `(string/int)` - Specifies the maximum TTL for the leases associated with this role. Accepts + [duration format strings](/vault/docs/concepts/duration-format). Defaults to system/mount default TTL time; + this value is allowed to be less than the mount max TTL (or, if not set, the system max TTL), + but it is not allowed to be longer. + +The `creation_ldif`, `deletion_ldif`, `rollback_ldif`, and `username_template` fields are all templated fields. See +[Username Templating](/vault/docs/concepts/username-templating) for details on how to use templating. Also see +[Templates](#templates) for specifics on what data is available for each template. + +#### Sample payload + +Sample LDIF files: + +`creation.ldif`: + +``` +dn: cn={{.Username}},ou=users,dc=learn,dc=example +objectClass: person +objectClass: top +cn: learn +sn: {{.Password | utf16le | base64}} +memberOf: cn=dev,ou=groups,dc=learn,dc=example +userPassword: {{.Password}} +``` + +`deletion.ldif` & `rollback.ldif`: + +``` +dn: cn={{.Username}},ou=users,dc=learn,dc=example +changetype: delete +``` + +Full Payload: + +```json +{ + "creation_ldif": "...", + "deletion_ldif": "...", + "rollback_ldif": "...", + "username_template": "...", + "default_ttl": "1h", + "max_ttl": "24h" +} +``` + +-> Note: The LDIF statements may optionally be base64 encoded. If they are base64 encoded when creating/updating the +role configuration, the decoded version will be returned from the `GET` endpoint. + +#### Sample POST request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/ldap/role/dynamic-role +``` + +### Templates + +LDIF and username templates use the [Go template syntax](https://golang.org/pkg/text/template/) to construct the +LDIF/username that will be executed against the server. This is done because certain values (such as the username +and password within an LDIF statement) are not known at configuration time. Additionally, the template gives a +lot of flexibility to the operator to construct the LDIF and username. + +Templated fields are delimited by `{{` and `}}`. To reference a field (such as the generated `Username`), a period is +placed in front of the field name. Example: `{{.Username}}`. Spaces can be included between `{{` and `}}`. For instance: +`{{.Username|lowercase}}` is the same as `{{ .Username | lowercase }}`. + +If a field needs to be modified (such as SHA256 hashing, base64 encoding, etc.) the value can be sent to one of the +[built-in functions](#template-functions). This uses a "pipe" syntax: `{{.Username | base64}}`. Values may be "piped" +to multiple functions: `{{.Username | lowercase | base64}}` + +#### LDIF template fields + +The following parameters are available within the LDIF templates: + +`.Username` - The name of the generated user (optionally from `username_template`).
+**Default pattern:** `v___<10 random chars>_` + +`.Password` - The generated password (optionally from +[password policies](/vault/docs/concepts/password-policies)) + +`.RoleName` - The name of the role that credentials are being generated for. + +`.DisplayName` - The display name associated with the authentication token used to make the credentials request. + +`.IssueTime` - The time that the lease was created. This time may be slightly earlier than the associated lease due to +where this value is calculated compared with where Vault calculates details of the lease.
+**Format:** 2006-01-02T15:04:05Z07:00 ([RFC3339](https://golang.org/pkg/time/#pkg-constants)) + +`.IssueTimeSeconds` - The [unix time](https://en.wikipedia.org/wiki/Unix_time) the lease was created. This time may +be slightly earlier than the associated lease due to where this value is calculated compared with where Vault +calculates details of the lease.
+**Format:** Integer indicating the number of seconds elapsed since January 1, 1970. + +`.ExpirationTime` - The time that the lease is set to expire. This time may be slightly earlier than the associated +lease due to where this value is calculated compared with where Vault calculates details of the lease.
+**Format:** 2006-01-02T15:04:05Z07:00 ([RFC3339](https://golang.org/pkg/time/#pkg-constants)) + +`.ExpirationTimeSeconds` - The [unix time](https://en.wikipedia.org/wiki/Unix_time) the lease is set to expire. This +time may be slightly earlier than the associated lease due to where this value is calculated compared with where Vault +calculates details of the lease.
+**Format:** Integer indicating the number of seconds elapsed since January 1, 1970. + +#### Username template fields + +The following parameters are available within the username template: + +**Important note:** If any of the following fields include dashes or underscores, they will not be removed/changed +unless explicitly done so within the username template. For instance: + +If `RoleName` is `test-role` and the `username_template` is `v_{{.RoleName}}_{{unix_time}}`, the result of this template +may be: `v_test-role_1234567890`. Note the `-` (dash) in the `test-role`. If the LDAP system Vault is managing +restricts usernames/DNs to not allow for dashes (or other characters), the template must explicitly modify/remove those +characters. In this example, the template can be changed to `v_{{.RoleName | replace "-" "_"}}` to replace +the dashes with underscores. See [Template Functions](#template-functions) for more functions available. + +`.RoleName` - The name of the role the credentials are being generated from. + +`.DisplayName` - The display name associated with the user making the request against Value. + +#### Template functions + +Both the LDIF templates and the username template use the [Go template language](https://golang.org/pkg/text/template) +so all [functions](https://golang.org/pkg/text/template/#hdr-Functions) and capabilities from that language are +supported including functions such as `printf`. + +In addition to the functions available through the template language, the following custom functions are also available: + +`random` - Generates a random string from lowercase letters, uppercase letters, and numbers. Must include a +number indicating how many characters to generate.
+**Example:** `{{random 20}}` generates 20 random characters + +`truncate` - truncates the previous value to the provided number of characters.
+**Example:** `{{.FieldName | truncate 10}}` + +`truncate_sha256` - Truncates the previous value to the provided number of characters. The last 8 characters of the +truncated value will be the first 8 characters of the SHA256 hash of the truncated characters. + +This can aid in identifying values (such as the role & display names) if they need to be truncated to a particular +length, particularly if the value has common prefixes. An example of this is having many roles with a common prefix in +the name of the role, but the role name is truncated such that only the prefix is shown. This function will keep the +non-prefix part of the role name in the username which will aid in identification while also keeping uniqueness. + +**Example:**
+`v_{{.RoleName | truncate_sha256 15}}_{{unix_time}}`.
+If two roles exist for this template, `myreallylongprefix-foobar` and `myreallylongprefix-bazqux`, the username for the first role +would be `v_myrealle6da86ec_1234567890` and the username for the second role would be `v_myrealld0420a55_1234567890`. + +`uppercase` - Uppercases the provided value.
+**Example:** `{{.FieldName | uppercase}}` + +`lowercase` - Lowercases the provided value.
+**Example:** `{{.FieldName | lowercase}}` + +`replace` - Find/replace on the provided value.
+**Example:** `{{.FieldName | replace "-" "_"}}` + +`sha256` - SHA256 hashes the provided value.
+**Example:** `{{.FieldName | sha256}}` + +`base64` - Base64 encodes the provided value.
+**Example:** `{{.FieldName | base64}}` + +`unix_time` - The current unix timestamp (number of seconds since Jan 1 1970).
+**Example:** `{{unix_time}}` + +`unix_time_millis` - The current unix timestamp in milliseconds.
+**Example:** `{{unix_time_millis}}` + +`timestamp` - The current time. Must provide a formatting string based on Go’s time package.
+**Example:** `{{timestamp "2006-01-02T15:04:05Z"}}` + +`uuid` - Generates a random UUID.
+**Example:** `{{uuid}}` + +##### LDIF template functions + +Additionally, the LDIF templates include an additional function to facilitate Active Directory password handling. +The username template cannot use this function. + +`utf16le` - Encodes the provided value into UTF16-LE.
+**Example:** `{{.FieldName | utf16le}}` + +## Dynamic role passwords + +The `creds` endpoint offers the credential information for a given dynamic role. + +| Method | Path | +| :----- | :--------------------------------- | +| `GET` | `/ldap/creds/:role_name` | + +### Parameters + +- `role_name` `(string: )` – URL parameter specifying the name of the + role. + +#### Sample GET request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/ldap/creds/dynamic-role +``` + +#### Sample GET response + +```json +{ + "distinguished_names": [ + "cn=v_token-dispname_testrole_jmZMnjS42a_1680580467,ou=users,dc=hashicorp,dc=com" + ], + "password": "OWexB3OzYYLFiotWxUS2EheGpriwR20fa2yA7JGTsnBREcxyqpwf73htofMihxcC", + "username": "v_token-dispname_testrole_jmZMnjS42a_1680580467" +} +``` + +## Library set management + +The `library` endpoint configures the sets of service accounts that Vault will offer for check-out. + +| Method | Path | +| :------- | :---------------------- | +| `LIST` | `/ldap/library` | +| `LIST` | `/ldap/library/:set_name` | +| `POST` | `/ldap/library/:set_name` | +| `GET` | `/ldap/library/:set_name` | +| `DELETE` | `/ldap/library/:set_name` | + +When adding a service account to the library, Vault verifies it already exists in the LDAP directory. + +### Parameters + +- `set_name` `(string: )` – URL parameter specifying the name of the + set. +- `service_account_names` `(string: "", or list: [] required)` - The names of all the service accounts that can be + checked out from this set. These service accounts must only be used by Vault, and may only be in one set. These + service accounts must already exist in the LDAP directory. +- `ttl` `(duration: "24h", optional)` - The maximum amount of time a single check-out lasts before Vault + automatically checks it back in. Defaults to 24 hours. Setting it to zero reflects an unlimited lending period. + Uses [duration format strings](/vault/docs/concepts/duration-format). +- `max_ttl` `(duration: "24h", optional)` - The maximum amount of time a check-out last with renewal before Vault + automatically checks it back in. Defaults to 24 hours. Setting it to zero reflects an unlimited lending period. + Uses [duration format strings](/vault/docs/concepts/duration-format). +- `disable_check_in_enforcement` `(bool: false, optional)` - Disable enforcing that service accounts must be + checked in by the entity or client token that checked them out. Defaults to false. + +### Sample POST request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/ldap/library/accounting-team +``` + +### Sample POST payload + +```json +{ + "service_account_names": ["fizz@example.com", "buzz@example.com"], + "ttl": "10h", + "max_ttl": "20h", + "disable_check_in_enforcement": false +} +``` + +### Sample GET response + +```json +{ + "service_account_names": ["fizz@example.com", "buzz@example.com"], + "ttl": "10h", + "max_ttl": "20h", + "disable_check_in_enforcement": false +} +``` + +### Sample LIST request + +Use the `/ldap/library` endpoint to list the top-level set names of service +accounts in Vault. Refer to the LDAP secrets engine +[hierarchical paths](/vault/docs/secrets/ldap#hierarchical-paths) documentation +for more information on path-based names. + +For example: + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/ldap/library +``` + +#### Sample LIST response + +```json +["accounting-team", "dev/"] +``` + +### Sample LIST request + +Use the `/ldap/library` endpoint to list the top-level set names of service +accounts in Vault at the given path. Refer to the LDAP secrets engine +[hierarchical paths](/vault/docs/secrets/ldap#hierarchical-paths) documentation +for more information on path-based names. + +For example: + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/ldap/library/dev +``` + +#### Sample LIST response + +```json +["backend", "frontend"] +``` + +## Library set status check + +This endpoint provides the check-out status of service accounts in a library set. + +| Method | Path | +| :----- | :----------------------------- | +| `GET` | `/ldap/library/:set_name/status` | + +### Parameters + +- `set_name` `(string: "", required)` - URL parameter specifying the set name of + the requested service accounts. The set name can contain an arbitrary number of + forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths). + +### Sample GET request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/ldap/library/accounting-team/status +``` + +### Sample GET response + +```json +{ + "request_id": "9e44c8b5-d142-5867-2a11-49f3ba71215a", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "buzz@example.com": { + "available": true + }, + "fizz@example.com": { + "available": false, + "borrower_client_token": "4c653e473bf7e27c6759fccc3def20c44d776279", + "borrower_entity_id": "631256b1-8523-9838-5501-d0a1e2cdad9c" + } + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Check-Out management + +This endpoint provides service account check out for a library set. + +| Method | Path | +| :----- | :-------------------------------- | +| `POST` | `/ldap/library/:set_name/check-out` | + +Returns a `200` if a credential is available, and a `400` if no credential is available. + +### Parameters + +- `set_name` `(string: "", required)` - URL parameter specifying the set name of + the requested service accounts. The set name can contain an arbitrary number of + forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths). +- `ttl` `(duration: "", optional)` - The maximum amount of time a check-out lasts before Vault + automatically checks it back in. Setting it to zero reflects an unlimited lending period. + Defaults to the set's `ttl`. If the requested `ttl` is higher than the set's, the set's will be used. + Uses [duration format strings](/vault/docs/concepts/duration-format). + +### Sample POST request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/ldap/library/accounting-team/check-out +``` + +### Sample POST payload + +```json +{ + "ttl": "1h" +} +``` + +### Sample POST response + +```json +{ + "request_id": "364a17d4-e5ab-998b-ceee-b49929229e0c", + "lease_id": "ad/library/accounting-team/check-out/aoBsaBEI4PK96VnukubvYDlZ", + "renewable": true, + "lease_duration": 36000, + "data": { + "password": "?@09QW0KZ8DSBu3deIu7XLY1NZqzwhozmMAZ6v0IcZJGOjs5GvpVMvOeW7/duls2", + "service_account_name": "fizz@example.com" + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` + +## Check-In management + +By default, check-in must be called by the same entity or client token used for check-out. +To disable this behavior, use the `disable_check_in_enforcement` toggle on the library set. Or, use +the `ad/library/manage/:set_name/check-in` behavior to force check-in of the account. Access to the +"manage" endpoint should only be granted to highly privileged Vault users, like Vault operators. + +If a caller attempts to check in a service account they're not authorized to check in, they will +receive an error response. If they attempt to check in a service account they _are_ authorized to +check in, but it's _already_ checked in, they will receive a successful response but the account +will not be included in the `check_ins` listed. `check_ins` shows which service accounts were checked +in _by this particular call_. + +| Method | Path | +| :----- | :-------------------------------------- | +| `POST` | `/ldap/library/:set_name/check-in` | +| `POST` | `/ldap/library/manage/:set_name/check-in` | + +### Parameters + +- `set_name` `(string: "", required)` - URL parameter specifying the set name of + the requested service accounts. The set name can contain an arbitrary number of + forward slashes to define a [hierarchical path](/vault/docs/secrets/ldap#hierarchical-paths). +- `service_account_names` `(string: "", or list: [] optional)` - The names of all the service accounts to be + checked in. May be omitted if only one is checked out. + +### Sample POST request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/ldap/library/accounting-team/check-in +``` + +### Sample POST payload + +```json +{ + "service_account_names": ["fizz@example.com"] +} +``` + +### Sample POST response + +```json +{ + "request_id": "db45c714-3f68-b748-95bc-8f7467637a52", + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "check_ins": ["fizz@example.com"] + }, + "wrap_info": null, + "warnings": null, + "auth": null +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/mongodbatlas.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/mongodbatlas.mdx new file mode 100644 index 0000000000..1c3d756478 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/mongodbatlas.mdx @@ -0,0 +1,254 @@ +--- +layout: api +page_title: MongoDB Atlas - Secrets Engines - HTTP API +description: |- + The MongoDB Atlas Secrets Engine for Vault generates MongoDB Atlas Programmatic API Keys dynamically. +--- + +# MongoDB atlas secrets engine + +The MongoDB Atlas Secrets Engine generates Programmatic API keys for MongoDB Atlas. This allows one to manage the lifecycle of these MongoDB Atlas secrets through Vault. The created MongoDB Atlas secrets are +time-based and are automatically revoked when the Vault lease expires, unless renewed. Vault will create a Programmatic API key for each lease scoped to the MongoDB Atlas project or organization denoted with the included role(s). An IP Whitelist may also be configured for the Programmatic API key with desired IPs and/or CIDR blocks. + +The MongoDB Atlas Programmatic API Key Public and +Private Key is returned to the caller. To learn more about Programmatic API Keys visit the [Programmatic API Keys Doc](https://docs.atlas.mongodb.com/reference/api/apiKeys/). + +## Configure connection + +In addition to the parameters defined by the Secrets Engines Backend, this plugin has a number of parameters to further configure a connection. + +| Method | Path | +| :----- | :--------------------- | +| `POST` | `/mongodbatlas/config` | + +### Parameters + +- `public_key` `(string: )` – The Public Programmatic API Key used to authenticate with the MongoDB Atlas API. +- `private_key` `(string: )` - The Private Programmatic API Key used to connect with MongoDB Atlas API. + +### Sample payload + +```json +{ + "public_key": "yhltsvan", + "private_key": "2c130c23-e6b6-4da8-a93f-a8bf33218830" +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/mongodbatlas/config +``` + +## Create/Update programmatic API key role + +Programmatic API Key credential types create a Vault role to generate a Programmatic API Key at +either the MongoDB Atlas Organization or Project level with the designated role(s) for programmatic access. If a role with the name does not exist, it will be created. If the role exists, it will be updated with the new attributes. + +| Method | Path | +| :----- | :------------- | +| `POST` | `/roles/:name` | + +### Parameters + +- `name` `(string )` - Unique identifier name of the role name +- `organization_id` `(string )` - Unique identifier for the organization to which + the target API Key belongs. Use the [orgs endpoint](https://www.mongodb.com/docs/atlas/reference/api/organization-get-all/) + to retrieve all organizations to which the authenticated user has access. Required if + `project_id` is not set. +- `project_id` `(string )` - Unique identifier for the project to which the target + API Key belongs. Use the [projects endpoint](https://www.mongodb.com/docs/atlas/reference/api/project-get-all/) + to retrieve all organizations to which the authenticated user has access. Required if + `organization_id` is not set. +- `roles` `(list [string] )` - List of roles that the API Key needs to have. If the roles array is provided: + + -> **IMPORTANT:** Provide at least one role. Make sure all roles must be valid for the Organization or Project. + + -> **NOTE:** Include all roles that you want this API Key to have. Any roles not in this array are removed. + + - The Organization roles are: + + - `ORG_OWNER` + - `ORG_MEMBER` + - `ORG_GROUP_CREATOR` + - `ORG_BILLING_ADMIN` + - `ORG_READ_ONLY` + + - The Project roles are: + - `GROUP_CHARTS_ADMIN` + - `GROUP_CLUSTER_MANAGER` + - `GROUP_DATA_ACCESS_ADMIN` + - `GROUP_DATA_ACCESS_READ_ONLY` + - `GROUP_DATA_ACCESS_READ_WRITE` + - `GROUP_OWNER` + - `GROUP_READ_ONLY` + +* `ip_addresses` `(list [string] )` - IP address to be added to the whitelist for the API key. This field is mutually exclusive with the cidrBlock field. +* `cidr_blocks` `(list [string] )` - Whitelist entry in CIDR notation to be added for the API key. This field is mutually exclusive with the ipAddress field. +* `project_roles` `(list [string] )` - Roles assigned when an Organization API key is assigned to a Projects API key. +* `ttl` `(string )` - Duration in seconds after which the issued credential should expire. Defaults to 0, in which case the value will fallback to the system/mount defaults. +* `max_ttl` `(string )` - The maximum allowed lifetime of credentials issued using this role. + + +### Sample payload + +```json +{ + "project_id": "5cf5a45a9ccf6400e60981b6", + "roles": ["GROUP_CLUSTER_MANAGER"], + "cidr_blocks": ["192.168.1.3/32"], + "ip_addresses": ["192.168.1.3", "192.168.1.4"] +} +``` + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/mongodbatlas/roles/test-programmatic-key +``` + +### Sample response + +```json +{ + "project_id": "5cf5a45a9ccf6400e60981b6", + "roles": ["GROUP_CLUSTER_MANAGER"], + "cidr_blocks": ["192.168.1.3/32"], + "ip_addresses": ["192.168.1.3", "192.168.1.4"], + "organization_id": "7cf5a45a9ccf6400e60981b7", + "ttl": "30m", + "max_ttl": "1h" +} +``` + +## Read programmatic API key role + +| Method | Path | +| :----- | :------------- | +| `GET` | `/roles/:name` | + +### Parameters + +- `name` `(string )` - Unique identifier name of the role name + +### Sample payload + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + --data @payload.json \ + http://127.0.0.1:8200/mongodbatlas/roles/test-programmatic-key +``` + +### Sample response + +```json +{ + "project_id": "5cf5a45a9ccf6400e60981b6", + "roles": ["GROUP_CLUSTER_MANAGER"], + "cidr_blocks": ["192.168.1.3/32"], + "ip_addresses": ["192.168.1.3", "192.168.1.4"], + "organization_id": "7cf5a45a9ccf6400e60981b7", + "ttl": "30m", + "max_ttl": "1h" +} +``` + +## List programmatic API key role + +| Method | Path | +| :----- | :------- | +| `GET` | `/roles` | + +### Sample payload + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + --data @payload.json \ + http://127.0.0.1:8200/mongodbatlas/roles +``` + +### Sample response + +```json +[ + { + "project_id": "5cf5a45a9ccf6400e60981b6", + "roles": ["GROUP_CLUSTER_MANAGER"], + "cidr_blocks": ["192.168.1.3/32"], + "ip_addresses": ["192.168.1.3", "192.168.1.4"], + "organization_id": "7cf5a45a9ccf6400e60981b7", + "ttl": "30m", + "max_ttl": "1h" + }, + { + "project_id": "5cf5a45a9ccf6400e60981b6", + "roles": ["READ"], + "cidr_blocks": ["192.168.1.3/35"], + "ip_addresses": ["192.168.1.5", "192.168.1.6"], + "organization_id": "7cf5a45a9ccf6400e60981b7", + "ttl": "30m", + "max_ttl": "1h" + } +] +``` + +## Delete programmatic API key role + +| Method | Path | +| :------- | :------------- | +| `DELETE` | `/roles/:name` | + +### Parameters + +- `name` `(string )` - Unique identifier name of the role name + +### Sample payload + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + --data @payload.json \ + http://127.0.0.1:8200/mongodbatlas/roles/test-programmatic-key +``` + +## Read credential + +| Method | Path | +| :----- | :------------- | +| `GET` | `/creds/:name` | + +### Parameters + +- `name` `(string )` - Unique identifier name of the credential + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/mongodbatlas/creds/0fLBv1c2YDzPlJB1PwsRRKHR +``` + +### Sample response + +```json +{ + "lease_duration": "20s", + "lease_renewable": true, + "description": "vault-test-1563980947-1318", + "private_key": "905ae89e-6ee8-40rd-ab12-613t8e3fe836", + "public_key": "klpruxce" +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/nomad.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/nomad.mdx new file mode 100644 index 0000000000..1f31511736 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/nomad.mdx @@ -0,0 +1,332 @@ +--- +layout: api +page_title: Nomad Secrets Engine- HTTP API +description: This is the API documentation for the Vault Nomad secrets engine. +--- + +# Nomad secrets engine (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault Nomad secrets engine. For general +information about the usage and operation of the Nomad secrets engine, please see the +[Vault Nomad secrets engine documentation](/vault/docs/secrets/nomad). + +This documentation assumes the Nomad secrets engine is mounted at the `/nomad` path +in Vault. Since it is possible to mount secrets engines at any location, please +update your API calls accordingly. + +## Configure access + +This endpoint configures the access information for Nomad. This access +information is used so that Vault can communicate with Nomad and generate +Nomad tokens. + +| Method | Path | +| :----- | :--------------------- | +| `POST` | `/nomad/config/access` | + +### Parameters + +- `address` `(string: "")` – Specifies the address of the Nomad + instance, provided as `"protocol://host:port"` like `"http://127.0.0.1:4646"`. + This value can also be provided on individual calls with the NOMAD_ADDR + environment variable. + +- `token` `(string: "")` – Specifies the Nomad Management token to use. + This value can also be provided on individual calls with the NOMAD_TOKEN + environment variable. + +- `max_token_name_length` `(int: )` – Specifies the maximum length to + use for the name of the Nomad token generated with [Generate + Credential](#generate-credential). If omitted, `0` is used and ignored, + defaulting to the max value allowed by the Nomad version. For Nomad versions + 0.8.3 and earlier, the default is `64`. For Nomad version 0.8.4 and later, the default is + `256`. + +- `ca_cert` `(string: "")` - CA certificate to use when verifying Nomad server certificate, + must be x509 PEM encoded. + +- `client_cert` `(string: "")` - Client certificate used for Nomad's TLS communication, + must be x509 PEM encoded and if this is set you need to also set client_key. + +- `client_key` `(string: "")` - Client key used for Nomad's TLS communication, + must be x509 PEM encoded and if this is set you need to also set client_cert. + +### Sample payload + +```json +{ + "address": "http://127.0.0.1:4646", + "token": "adha...", + "max_token_name_length": 256 +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ..." \ + --data @payload.json \ + http://127.0.0.1:8200/v1/nomad/config/access +``` + +## Read access configuration + +This endpoint queries for information about the Nomad connection. + +| Method | Path | +| :----- | :--------------------- | +| `GET` | `/nomad/config/access` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/nomad/config/access +``` + +### Sample response + +```json + "data": { + "address": "http://localhost:4646/" + } +``` + +## Configure lease + +This endpoint configures the lease settings for generated tokens. + +| Method | Path | +| :----- | :-------------------- | +| `POST` | `/nomad/config/lease` | + +### Parameters + +- `ttl` `(string: "")` – Specifies the ttl for the lease. Uses [duration format strings](/vault/docs/concepts/duration-format). + +- `max_ttl` `(string: "")` – Specifies the max ttl for the lease. Uses [duration format strings](/vault/docs/concepts/duration-format). + +### Sample payload + +```json +{ + "ttl": 1800, + "max_ttl": 3600 +} +``` + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/nomad/config/lease +``` + +## Read lease configuration + +This endpoint queries for information about the Lease TTL for the specified mount. + +| Method | Path | +| :----- | :-------------------- | +| `GET` | `/nomad/config/lease` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/nomad/config/lease +``` + +### Sample response + +```json + "data": { + "max_ttl": 86400, + "ttl": 86400 + } +``` + +## Delete lease configuration + +This endpoint deletes the lease configuration. + +| Method | Path | +| :------- | :-------------------- | +| `DELETE` | `/nomad/config/lease` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/nomad/config/lease +``` + +## Create/Update role + +This endpoint creates or updates the Nomad role definition in Vault. If the role does not exist, it will be created. If the role already exists, it will receive +updated attributes. + +| Method | Path | +| :----- | :------------------ | +| `POST` | `/nomad/role/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of an existing role against + which to create this Nomad tokens. This is part of the request URL. + +- `policies` `(string: "")` – Comma separated list of Nomad policies the token is going to be created against. These need to be created beforehand in Nomad. + +- `global` `(bool: "false")` – Specifies if the token should be global, as defined in the [Nomad Documentation](/nomad/tutorials/access-control#acl-tokens). + +- `type` `(string: "client")` - Specifies the type of token to create when + using this role. Valid values are `"client"` or `"management"`. + +### Sample payload + +To create a client token with a custom policy: + +```json +{ + "policies": "readonly" +} +``` + +### Sample request + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ..." \ + --data @payload.json \ + http://127.0.0.1:8200/v1/nomad/role/monitoring +``` + +## Read role + +This endpoint queries for information about a Nomad role with the given name. +If no role exists with that name, a 404 is returned. + +| Method | Path | +| :----- | :------------------ | +| `GET` | `/nomad/role/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to query. This + is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/nomad/role/monitoring +``` + +### Sample response + +```json +{ + "data": { + "lease": "0s", + "policies": ["example"], + "token_type": "client" + } +} +``` + +## List roles + +This endpoint lists all existing roles in the secrets engine. + +| Method | Path | +| :----- | :---------------------- | +| `LIST` | `/nomad/role` | +| `GET` | `/nomad/role?list=true` | + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/nomad/role +``` + +### Sample response + +```json +{ + "data": { + "keys": ["example"] + } +} +``` + +## Delete role + +This endpoint deletes a Nomad role with the given name. Even if the role does +not exist, this endpoint will still return a successful response. + +| Method | Path | +| :------- | :------------------ | +| `DELETE` | `/nomad/role/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of the role to delete. This + is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --request DELETE \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/nomad/role/example-role +``` + +## Generate credential + +This endpoint generates a dynamic Nomad token based on the given role +definition. + +| Method | Path | +| :----- | :------------------- | +| `GET` | `/nomad/creds/:name` | + +### Parameters + +- `name` `(string: )` – Specifies the name of an existing role against + which to create this Nomad token. This is part of the request URL. + +### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/nomad/creds/example +``` + +### Sample response + +```json +{ + "data": { + "accessor_id": "c834ba40-8d84-b0c1-c084-3a31d3383c03", + "secret_id": "65af6f07-7f57-bb24-cdae-a27f86a894ce" + } +} +``` diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/index.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/index.mdx new file mode 100644 index 0000000000..71489a1623 --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/index.mdx @@ -0,0 +1,4870 @@ +--- +layout: api +page_title: PKI - Secrets Engines - HTTP API +description: This is the API documentation for the Vault PKI secrets engine. +--- + +# PKI secrets engine (API) + +@include 'x509-sha1-deprecation.mdx' + +This is the API documentation for the Vault PKI secrets engine. For general +information about the usage and operation of the PKI secrets engine, please see +the [PKI documentation](/vault/docs/secrets/pki). + +This documentation assumes the PKI secrets engine is enabled at the `/pki` path +in Vault. Since it is possible to enable secrets engines at any location, please +update your API calls accordingly. + +## Table of contents + +- [Notice About New Multi-Issuer Functionality](#notice-about-new-multi-issuer-functionality) +- [Issuing Certificates](#issuing-certificates) + - [List Roles](#list-roles) + - [Read Role](#read-role) + - [Generate Certificate and Key](#generate-certificate-and-key) + - [Generate Certificate and Key with External Policy ](#generate-certificate-and-key-with-external-policy) + - [Sign Certificate](#sign-certificate) + - [Sign Certificate with External Policy ](#sign-certificate-with-external-policy) + - [Sign Intermediate](#sign-intermediate) + - [Sign Intermediate with External Policy ](#sign-intermediate-with-external-policy) + - [Sign Self-Issued](#sign-self-issued) + - [Sign Verbatim](#sign-verbatim) + - [Revoke Certificate](#revoke-certificate) + - [Revoke Certificate with Private Key](#revoke-certificate-with-private-key) + - [List Revoked Certificates](#list-revoked-certificates) + - [List Revocation Requests](#list-revocation-requests) + - [List Cross-Cluster Revocations](#list-cross-cluster-revocations) +- [Accessing Authority Information](#accessing-authority-information) + - [List Issuers](#list-issuers) + - [Read Issuer Certificate](#read-issuer-certificate) + - [Read Default Issuer Certificate Chain](#read-default-issuer-certificate-chain) + - [Read Issuer CRL](#read-issuer-crl) + - [OCSP Request](#ocsp-request) + - [List Certificates](#list-certificates) + - [Read Certificate](#read-certificate) + - [Read Batch Certificate](#read-batch-certificate) + - [Read Certificate Metadata ](#read-certificate-metadata) +- [Managing Keys and Issuers](#managing-keys-and-issuers) + - [List Issuers](#list-issuers) + - [List Keys](#list-keys) + - [Generate Key](#generate-key) + - [Generate Root](#generate-root) + - [Generate Intermediate CSR](#generate-intermediate-csr) + - [Import CA Certificates and Keys](#import-ca-certificates-and-keys) + - [Read Issuer](#read-issuer) + - [Update Issuer](#update-issuer) + - [Revoke Issuer](#revoke-issuer) + - [Delete Issuer](#delete-issuer) + - [Import Key](#import-key) + - [Read Key](#read-key) + - [Update Key](#update-key) + - [Delete Key](#delete-key) + - [Delete All Issuers and Keys](#delete-all-issuers-and-keys) +- [Managing Authority Information](#managing-authority-information) + - [List Roles](#list-roles) + - [Create/Update Role](#create-update-role) + - [Read Role](#read-role) + - [Delete Role](#delete-role) + - [Read Certificate Issuance External Policy Service (CIEPS) Configuration ](#read-certificate-issuance-external-policy-service-cieps-configuration) + - [Set Certificate Issuance External Policy Service (CIEPS) Configuration ](#set-certificate-issuance-external-policy-service-cieps-configuration) + - [Read URLs](#read-urls) + - [Set URLs](#set-urls) + - [Read Issuers Configuration](#read-issuers-configuration) + - [Set Issuers Configuration](#set-issuers-configuration) + - [Read Keys Configuration](#read-keys-configuration) + - [Set Keys Configuration](#set-keys-configuration) + - [Read Cluster Configuration](#read-cluster-configuration) + - [Set Cluster Configuration](#set-cluster-configuration) + - [Read CRL Configuration](#read-crl-configuration) + - [Set CRL Configuration](#set-crl-configuration) + - [Rotate CRLs](#rotate-crls) + - [Rotate Delta CRLs](#rotate-delta-crls) + - [Combining CRLs from the Same Issuer](#combine-crls-from-the-same-issuer) + - [Sign Revocation List](#sign-revocation-list) + - [Tidy](#tidy) + - [Read Automatic Tidy Configuration](#read-automatic-tidy-configuration) + - [Set Automatic Tidy Configuration](#set-automatic-tidy-configuration) + - [Tidy Status](#tidy-status) + - [Cancel Tidy](#cancel-tidy) +- [Certificate Issuance Protocols](/vault/api-docs/secret/pki/issuance) + - [ACME - Automatic Certificate Management Environment](/vault/api-docs/secret/pki/issuance#acme-certificate-issuance) + - [EST - Enrollment over Secure Transport ](/vault/api-docs/secret/pki/issuance#est-certificate-issuance) + - [CMPv2 - Certificate Management Protocol (v2) ](/vault/api-docs/secret/pki/issuance#cmpv2-certificate-issuance) + - [SCEP - Simple Certificate Enrollment Protocol ](/vault/api-docs/secret/pki/issuance#scep-certificate-issuance) +- [Cluster Scalability](#cluster-scalability) +- [Managed Key](#managed-keys) (Enterprise Only) +- [Vault CLI with DER/PEM responses](#vault-cli-with-der-pem-responses) + +## Notice about new Multi-Issuer functionality + +Vault since 1.11.0 allows a single PKI mount to have multiple Certificate +Authority (CA) certificates ("issuers") in a single mount, for the purpose +of facilitating rotation. All issuers within a single mount are treated as a +single Authority, meaning that: + + 1. Certificate Revocation List (CRL) configuration is common to all issuers, + 2. All authority access URLs are common to all issuers, + 3. Issued certificates' serial numbers will be unique across all issuers. + +However, since each issuer may have a distinct subject and keys, different +issuers may have different CRLs. + +It is _strongly_ encouraged to limit the scope of CAs within a mount and not +to mix different types of CAs (roots and intermediates). + +~> **Note**: Some functionality will not work if a default issuer is not + configured. Vault automatically selects the default issuer from the + current issuing certificate on migration from an older Vault version + (Vault < 1.11.0). + +## Issuing certificates + +The following API endpoints allow users or operators to request certificates +and are all authenticated. + +In general, for self-serve use, the `/pki/sign/:name` and `/pki/issue/:name` +are sufficient to allow most users to access for ACL purposes. The per-issuer +variants (`/pki/issuer/:issuer_ref/sign/:name` and +`/pki/issuer/:issuer_ref/issue/:name`) allow the requester to override the +role's chosen issuer, potentially allowing users to request certificates +issued by the wrong parent authority. + +Some API endpoints included here are privileged and should only be accessed +by trusted users or operators; these include the various `sign-verbatim`, +`sign-self-signed` and `sign-intermediate` endpoints. + +If an issued certificate has been compromised, it should be revoked. The +Vault PKI secrets engine presently only allows revocation by serial number; +because this could allow users to deny access to other users, it should be +restricted to operators. + +### List roles + +This endpoint returns a list of available roles. Only the role names are +returned, not any values. It is useful to both operators and users. + +| Method | Path | +| :----- | :----------- | +| `LIST` | `/pki/roles` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/pki/roles +``` + +#### Sample response + +```json +{ + "auth": null, + "data": { + "keys": ["dev", "prod"] + }, + "lease_duration": 0, + "lease_id": "", + "renewable": false +} +``` + +### Read role + +This endpoint queries the role definition. It is useful to both operators and +users. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/pki/roles/:name` | + +#### Parameters + +- `name` `(string: )` - Specifies the name of the role to read. This + is part of the request URL. + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/roles/my-role +``` + +#### Sample response + +```json +{ + "data": { + "allow_any_name": false, + "allow_ip_sans": true, + "allow_localhost": true, + "allow_subdomains": false, + "allowed_domains": ["example.com", "foobar.com"], + "allowed_uri_sans": ["example.com", "spiffe://*"], + "allowed_other_sans": [ + "1.3.6.1.4.1.311.20.2.3;utf8:devops@example.com", + "1.3.6.1.4.1.311.20.2.4;UTF-8:*" + ], + "client_flag": true, + "code_signing_flag": false, + "key_bits": 2048, + "key_type": "rsa", + "ttl": "6h", + "max_ttl": "12h", + "server_flag": true, + ... additional fields elided ... + } +} +``` + + + +### Generate certificate and key + +This endpoint generates a new set of credentials (private key and certificate) +based on the role named in the endpoint. The issuing CA certificate and full CA +chain is returned as well, so that only the root CA need be in a client's trust +store. Choice of issuing CA is determined first by the role (when using the +`/pki/issue/:name` path) and then by the path (when using the +`/pki/issuer/:issuer_ref/issue/name` path). + +It is suggested to limit access to the path-overridden issue endpoint (on +`/pki/issuer/:issuer_ref/issue/:name`). + +~> **Note**: The private key is _not_ stored. If you do not save the private + key from the response, you will need to request a new certificate. + +| Method | Path | Issuer | +| :----- | :------------------------------------ | :------------ | +| `POST` | `/pki/issue/:name` | Role selected | +| `POST` | `/pki/issuer/:issuer_ref/issue/:name` | Path selected | + +#### Parameters + +- `name` `(string: )` - Specifies the name of the role to create the + certificate against. This is part of the request URL. + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +~> Note: This parameter is not present on the `/pki/issue/:name` path and + takes its value from the role's `issuer_ref` field. + +- `common_name` `(string: "")` - Specifies the requested CN for the + certificate. If the CN is allowed by role policy, it will be issued. If more + than one `common_name` is desired, specify the alternative names in the + `alt_names` list. + +~> Note: A value for `common_name` is required when [require_cn](#require_cn) is set to `true` + +- `alt_names` `(string: "")` - Specifies requested Subject Alternative Names, in + a comma-delimited list. These can be host names or email addresses; they will + be parsed into their respective fields. If any requested names do not match + role policy, the entire request will be denied. + +- `ip_sans` `(string: "")` - Specifies requested IP Subject Alternative Names, + in a comma-delimited list. Only valid if the role allows IP SANs (which is the + default). + +- `uri_sans` `(string: "")` - Specifies the requested URI Subject Alternative + Names, in a comma-delimited list. If any requested URIs do not match role policy, + the entire request will be denied. + +- `other_sans` `(string: "")` - Specifies custom OID/UTF8-string SANs. These + must match values specified on the role in `allowed_other_sans` (see role + creation for allowed_other_sans globbing rules). + The format is the same as OpenSSL: `;:` where the + only current valid type is `UTF8`. This can be a comma-delimited list or a + JSON string slice. + +- `ttl` `(string: "")` - Specifies requested Time To Live. Cannot be greater + than the role's `max_ttl` value. If not provided, the role's `ttl` value will + be used. Note that the role values default to system values if not explicitly + set. See `not_after` as an alternative for setting an absolute end date + (rather than a relative one). + +- `format` `(string: "pem")` - Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`; defaults to `pem`. If `der`, the output is + base64 encoded. If `pem_bundle`, the `certificate` field will contain the + private key and certificate, concatenated; if the issuing CA is not a + Vault-derived self-signed root, this will be included as well. + +- `private_key_format` `(string: "der")` - Specifies the format for marshaling + the private key within the private_key response field. Defaults to `der` which will + return either base64-encoded DER or PEM-encoded DER, depending on the value of + `format`. The other option is `pkcs8` which will return the key marshalled as + PEM-encoded PKCS8. + +~> **Note** that this does not apply to the private key within the certificate + field if `format=pem_bundle` parameter is specified. + +- `exclude_cn_from_sans` `(bool: false)` - If true, the given `common_name` will + not be included in DNS or Email Subject Alternate Names (as appropriate). + Useful if the CN is not a hostname or email address, but is instead some + human-readable identifier. + +- `not_after` `(string)` - Set the Not After field of the certificate with + specified date value. The value format should be given in UTC format + `YYYY-MM-ddTHH:MM:SSZ`. Supports the Y10K end date for IEEE 802.1AR-2018 + standard devices, `9999-12-31T23:59:59Z`. + +- `remove_roots_from_chain` `(bool: false)` - If true, the returned `ca_chain` + field will not include any self-signed CA certificates. Useful if end-users + already have the root CA in their trust store. + +- `user_ids` `(string: "")` - Specifies the comma-separated list of requested + User ID (OID 0.9.2342.19200300.100.1.1) Subject values to be placed on the + signed certificate. This field is validated against `allowed_user_ids` on + the role. + +- `cert_metadata` `(string: "")` - A base 64 + encoded value or an empty string to associate with the certificate's serial + number. The role's no_store_metadata must be set to false, otherwise an + error is returned when specified. To retrieve metadata see: + [Read Certificate Metadata](#read-certificate-metadata) + +#### Sample payload + +```json +{ + "common_name": "www.example.com" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/issue/my-role +``` + +#### Sample response + +```json +{ + "lease_id": "pki/issue/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "expiration": "1654105687", + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n" + ], + "private_key": "-----BEGIN RSA PRIVATE KEY-----\nMIIEowIBAAKCAQEAnVHfwoKsUG1GDVyWB1AFroaKl2ImMBO8EnvGLRrmobIkQvh+\n...\nQN351pgTphi6nlCkGPzkDuwvtxSxiCWXQcaxrHAL7MiJpPzkIBq1\n-----END RSA PRIVATE KEY-----\n", + "private_key_type": "rsa", + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "warnings": "", + "auth": null +} +``` + +### Generate certificate and key with external policy + +Similar to the [generate certificate and key](#generate-certificate-and-key) +endpoint, this endpoint generate key material and certificate via an external +policy engine. The private key material stays local to Vault, with the external +service getting only an empty CSR. Any parameters passed to this endpoint are +passed verbatim to the Certificate Issuance External +Policy Service (CIEPS). The +response format is the same between both endpoints. + +It is suggested to limit access to the path-overridden issue endpoint (on +`/pki/issuer/:issuer_ref/external-policy/issue/:policy`) and let the CIEPS +engine override the issuer as necessary. + +| Method | Path | Issuer | +| :----- |:----------------------------------------------------------| :-------------------------- | +| `POST` | `/pki/external-policy/issue(/:policy)` | `default` or CIEPS-selected | +| `POST` | `/pki/issuer/:issuer_ref/external-policy/issue(/:policy)` | Path or CIEPS selected | + +#### Parameters + +- `policy` `(string: )` - Specifies the name of the policy to create + the certificate against. This is part of the request URL and is passed to the + external CIEPS engine. + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +~> Note: This parameter is not present on the `/pki/external-policy/sign/:policy` + path and takes its value from the CIEPS engine response's `issuer_ref` + field, which can override the user-requested issuer. + +- `format` `(string: "pem")` - Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`; defaults to `pem`. If `der`, the output is + base64 encoded. If `pem_bundle`, the `certificate` field will contain the + private key and certificate, concatenated; if the issuing CA is not a + Vault-derived self-signed root, this will be included as well. + +- `key_type` `(string: "rsa")` - Specifies the desired key type; must be `rsa`, `ed25519` + or `ec`. + +- `key_bits` `(int: 0)` - Specifies the number of bits to use for the + generated keys. Allowed values are 0 (universal default); with + `key_type=rsa`, allowed values are: 2048 (default), 3072, 4096 or 8192; + with `key_type=ec`, allowed values are: 224, 256 (default), + 384, or 521; ignored with `key_type=ed25519`. + +- `private_key_format` `(string: "der")` - Specifies the format for marshaling + the private key within the private_key response field. Defaults to `der` which will + return either base64-encoded DER or PEM-encoded DER, depending on the value of + `format`. The other option is `pkcs8` which will return the key marshalled as + PEM-encoded PKCS8. + +~> **Note** that this does not apply to the private key within the certificate + field if `format=pem_bundle` parameter is specified. + + +- `remove_roots_from_chain` `(bool: false)` - If true, the returned `ca_chain` + field will not include any self-signed CA certificates. Useful if end-users + already have the root CA in their trust store. + +Other parameters may be specified and will not be parsed by Vault but may be +recognized based on external CIEPS engine definition. + +#### Sample payload + +```json +{ + "common_name": "example.com", + "key_type": "rsa", + "key_bits": 2048 +} +``` + +#### Sample response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "expiration": "1654105687", + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n" + ], + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:52" + }, + "auth": null +} +``` + +### Sign certificate + +This endpoint signs a new certificate based upon the provided CSR and the +supplied parameters, subject to the restrictions contained in the role named in +the endpoint. The issuing CA certificate and the full CA chain is returned as +well, so that only the root CA need be in a client's trust store. + +It is suggested to limit access to the path-overridden sign endpoint (on +`/pki/issuer/:issuer_ref/sign/:name`). + +| Method | Path | Issuer | +| :----- | :----------------------------------- | :------------ | +| `POST` | `/pki/sign/:name` | Role selected | +| `POST` | `/pki/issuer/:issuer_ref/sign/:name` | Path selected | + +#### Parameters + +- `name` `(string: )` - Specifies the name of the role to create the + certificate against. This is part of the request URL. + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +~> Note: This parameter is not present on the `/pki/sign/:name` path and + takes its value from the role's `issuer_ref` field. + +- `csr` `(string: )` - Specifies the PEM-encoded CSR. + +- `common_name` `(string: )` - Specifies the requested CN for the + certificate. If the CN is allowed by role policy, it will be issued. If + more than one `common_name` is desired, specify the alternative names in + the `alt_names` list. + +- `alt_names` `(string: "")` - Specifies the requested Subject Alternative + Names, in a comma-delimited list. These can be host names or email addresses; + they will be parsed into their respective fields. If any requested names do + not match role policy, the entire request will be denied. + +- `other_sans` `(string: "")` - Specifies custom OID/UTF8-string SANs. These + must match values specified on the role in `allowed_other_sans` (see role + creation for allowed_other_sans globbing rules). + The format is the same as OpenSSL: `;:` where the + only current valid type is `UTF8`. This can be a comma-delimited list or a + JSON string slice. + +- `ip_sans` `(string: "")` - Specifies the requested IP Subject Alternative + Names, in a comma-delimited list. Only valid if the role allows IP SANs (which + is the default). + +- `uri_sans` `(string: "")` - Specifies the requested URI Subject Alternative + Names, in a comma-delimited list. If any requested URIs do not match role policy, + the entire request will be denied. + +- `ttl` `(string: "")` - Specifies the requested Time To Live. Cannot be greater + than the role's `max_ttl` value. If not provided, the role's `ttl` value will + be used. Note that the role values default to system values if not explicitly + set. See `not_after` as an alternative for setting an absolute end date + (rather than a relative one). + +- `format` `(string: "pem")` - Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, if the + issuing CA is not a Vault-derived self-signed root, it will be concatenated + with the certificate. + +- `exclude_cn_from_sans` `(bool: false)` - If true, the given `common_name` will + not be included in DNS or Email Subject Alternate Names (as appropriate). + Useful if the CN is not a hostname or email address, but is instead some + human-readable identifier. + +- `not_after` `(string)` - Set the Not After field of the certificate with + specified date value. The value format should be given in UTC format + `YYYY-MM-ddTHH:MM:SSZ`. Supports the Y10K end date for IEEE 802.1AR-2018 + standard devices, `9999-12-31T23:59:59Z`. + +- `remove_roots_from_chain` `(bool: false)` - If true, the returned `ca_chain` + field will not include any self-signed CA certificates. Useful if end-users + already have the root CA in their trust store. + +- `user_ids` `(string: "")` - Specifies the comma-separated list of requested + User ID (OID 0.9.2342.19200300.100.1.1) Subject values to be placed on the + signed certificate. This field is validated against `allowed_user_ids` on + the role. + +- `cert_metadata` `(string: "")` - A base 64 + encoded value or an empty string to associate with the certificate's serial + number. The role's no_store_metadata must be set to false, otherwise an + error is returned when specified. To retrieve metadata see: + [Read Certificate Metadata](#read-certificate-metadata) + +#### Sample payload + +```json +{ + "csr": "...", + "common_name": "example.com" +} +``` + +#### Sample response + +```json +{ + "lease_id": "pki/sign/test/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "expiration": "1654105687", + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n" + ], + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null +} +``` + +### Sign certificate with external policy + +Similar to the [sign certificate](#sign-certificate) endpoint, this endpoint +signs the specified leaf CSR via an external policy engine. Any parameters +passed to this endpoint are passed verbatim to the Certificate Issuance External +Policy Service (CIEPS). The response format is the same +between both endpoints. + +It is suggested to limit access to the path-overridden sign endpoint (on +`/pki/issuer/:issuer_ref/external-policy/sign/:policy`) and let the CIEPS +engine override the issuer as necessary. + +| Method | Path | Issuer | +| :----- |:---------------------------------------------------------| :-------------------------- | +| `POST` | `/pki/external-policy/sign(/:policy)` | `default` or CIEPS-selected | +| `POST` | `/pki/issuer/:issuer_ref/external-policy/sign(/:policy)` | Path or CIEPS selected | + +#### Parameters + +- `policy` `(string: )` - Specifies the name of the policy to create + the certificate against. This is part of the request URL and is passed to the + external CIEPS engine. + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +~> Note: This parameter is not present on the `/pki/external-policy/sign/:policy` + path and takes its value from the CIEPS engine response's `issuer_ref` + field, which can override the user-requested issuer. + +- `csr` `(string: )` - Specifies the PEM-encoded CSR. + +- `format` `(string: "pem")` - Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`; defaults to `pem`. If `der`, the output is + base64 encoded. If `pem_bundle`, the `certificate` field will contain the + private key and certificate, concatenated; if the issuing CA is not a + Vault-derived self-signed root, this will be included as well. + +- `private_key_format` `(string: "der")` - Specifies the format for marshaling + the private key within the private_key response field. Defaults to `der` which will + return either base64-encoded DER or PEM-encoded DER, depending on the value of + `format`. The other option is `pkcs8` which will return the key marshalled as + PEM-encoded PKCS8. + +~> **Note** that this does not apply to the private key within the certificate + field if `format=pem_bundle` parameter is specified. + +- `remove_roots_from_chain` `(bool: false)` - If true, the returned `ca_chain` + field will not include any self-signed CA certificates. Useful if end-users + already have the root CA in their trust store. + +Other parameters may be specified and will not be parsed by Vault but may be +recognized based on external CIEPS engine definition. + +#### Sample payload + +```json +{ + "csr": "...", + "common_name": "example.com", + "key_attestation": "..." +} +``` + +#### Sample response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "expiration": "1654105687", + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n" + ], + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:52" + }, + "auth": null +} +``` + +### Sign intermediate + +This endpoint uses the configured CA certificate to issue a certificate with +appropriate values for acting as an intermediate CA. Distribution points use the +values set via `config/urls`. Values set in the CSR are ignored unless +`use_csr_values` is set to true, in which case the values from the CSR are used +verbatim. + +This endpoint can be used both when signing a Vault-backed intermediate or +when signing an externally-owned intermediate. + +~> **Note**: This is a privileged endpoint, as callers are granted a new + intermediate certificate, with which they can issue for arbitrary names. + Access to this endpoint should be restricted by policy to only trusted + operators. + +By default, Vault truncates the `notAfter` field of the signed intermediary +to use the `notAfter` field of the signing issuer, it the computed field for the +intermediary goes beyond the prescribed length. + +| Method | Path | Issuer | +| :----- | :------------------------------------------ | :------- | +| `POST` | `/pki/root/sign-intermediate` | `default` | +| `POST` | `/pki/issuer/:issuer_ref/sign-intermediate` | Selected | + +#### Parameters + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +~> Note: This parameter is not present on the `/pki/root/sign-intermediate` + path and takes the value `default`. + +- `csr` `(string: )` - Specifies the PEM-encoded CSR to be signed. + +- `common_name` `(string: )` - Specifies the requested CN for the + certificate. If more than one `common_name` is desired, specify the + alternative names in the `alt_names` list. + +- `alt_names` `(string: "")` - Specifies the requested Subject Alternative + Names, in a comma-delimited list. These can be host names or email addresses; + they will be parsed into their respective fields. + +- `ip_sans` `(string: "")` - Specifies the requested IP Subject Alternative + Names, in a comma-delimited list. + +- `uri_sans` `(string: "")` - Specifies the requested URI Subject Alternative + Names, in a comma-delimited list. + +- `other_sans` `(string: "")` - Specifies custom OID/UTF8-string SANs. These + must match values specified on the role in `allowed_other_sans` (see role + creation for allowed_other_sans globbing rules). + The format is the same as OpenSSL: `;:` where the + only current valid type is `UTF8`. This can be a comma-delimited list or a + JSON string slice. + +- `ttl` `(string: "")` - Specifies the requested Time To Live (after which the + certificate will be expired). This cannot be larger than the engine's max (or, + if not set, the system max). However, this can be after the expiration of the + signing CA. See `not_after` as an alternative for setting an absolute end date + (rather than a relative one). + +- `format` `(string: "pem")` - Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, if the + issuing CA is not a Vault-derived self-signed root, it will be concatenated + with the certificate. + +- `max_path_length` `(int: -1)` - Specifies the maximum path length to encode in + the generated certificate. `-1`, means no limit, unless the signing + certificate has a maximum path length set, in which case the path length is + set to one less than that of the signing certificate. A limit of `0` means a + literal path length of zero. + +- `key_usage` `([]string: CRL,CertSign)` - This list of key usages will be added + to the existing set of key usages, CRL,CertSign, on the generated certificate. + Per the CAB Forum requirements, Vault ignores values other than `DigitalSignature`. + To get a certificate with additional `key_usage` values, add the desired values to + the CSR, then call this function with `use_csr_values` set to `true`. + +- `exclude_cn_from_sans` `(bool: false)` - If true, the given `common_name` will + not be included in DNS or Email Subject Alternate Names (as appropriate). + Useful if the CN is not a hostname or email address, but is instead some + human-readable identifier. + +- `use_csr_values` `(bool: false)` - If set to `true`, then: 1) Subject + information, including names and alternate names, will be preserved from the + CSR rather than using the values provided in the other parameters to this + path; 2) Any key usages (for instance, non-repudiation) requested in the CSR + will be added to the basic set of key usages used for CA certs signed by this + path; 3) Extensions requested in the CSR will be copied into the issued + certificate. + +- `permitted_dns_domains` `(string: "")` - A comma separated string (or, string + array) containing DNS domains for which certificates are allowed to be issued + or signed by this CA certificate. Supports subdomains via a `.` in front of + the domain, as per [RFC 5280 Section 4.2.1.10 - Name + Constraints](https://tools.ietf.org/html/rfc5280#section-4.2.1.10) + +- `excluded_dns_domains` `(string: "")` - A comma separated string (or, string + array) containing DNS domains for which certificates are not allowed to be issued + or signed by this CA certificate. Supports subdomains via a `.` in front of + the domain, as per [RFC 5280 Section 4.2.1.10 - Name + Constraints](https://tools.ietf.org/html/rfc5280#section-4.2.1.10) + +- `permitted_ip_ranges` `(string: "")` - A comma separated string (or, string + array) containing IP ranges for which certificates are allowed to be issued or + signed by this CA certificate. IP ranges must be in the CIDR notation of IP + address and prefix length like "192.0.2.0/24" or "2001:db8::/32", as defined + in RFC 4632 and RFC 4291. + +- `excluded_ip_ranges` `(string: "")` - A comma separated string (or, string + array) containing IP ranges for which certificates are not allowed to be + issued or signed by this CA certificate. IP ranges must be in the CIDR + notation of IP address and prefix length like "192.0.2.0/24" or + "2001:db8::/32", as defined in RFC 4632 and RFC 4291. + +- `permitted_email_addresses` `(string: "")` - A comma separated string (or, string + array) containing email addresses for which certificates are allowed to be issued or + signed by this CA certificate. + +- `excluded_email_addresses` `(string: "")` - A comma separated string (or, + string array) containing email addresses for which certificates are not + allowed to be issued or signed by this CA certificate. + +- `permitted_uri_domains` `(string: "")` - A comma separated string (or, string + array) containing fully qualified domain names for which certificates are + allowed to be issued or signed by this CA certificate. Supports subdomains via + a `.` in front of the domain, as per [RFC 5280 Section 4.2.1.10 - Name + Constraints](https://tools.ietf.org/html/rfc5280#section-4.2.1.10) + +- `excluded_uri_domains` `(string: "")` - A comma separated string (or, string + array) containing fully qualified domain names for which certificates are not + allowed to be issued or signed by this CA certificate. Supports subdomains via + a `.` in front of the domain, as per [RFC 5280 Section 4.2.1.10 - Name + Constraints](https://tools.ietf.org/html/rfc5280#section-4.2.1.10) + +- `ou` `(string: "")` - Specifies the OU (OrganizationalUnit) values in the + subject field of the resulting certificate. This is a comma-separated string + or JSON array. + +- `organization` `(string: "")` - Specifies the O (Organization) values in the + subject field of the resulting certificate. This is a comma-separated string + or JSON array. + +- `country` `(string: "")` - Specifies the C (Country) values in the subject + field of the resulting certificate. This is a comma-separated string or JSON + array. + +- `locality` `(string: "")` - Specifies the L (Locality) values in the subject + field of the resulting certificate. This is a comma-separated string or JSON + array. + +- `province` `(string: "")` - Specifies the ST (Province) values in the subject + field of the resulting certificate. This is a comma-separated string or JSON + array. + +- `street_address` `(string: "")` - Specifies the Street Address values in the + subject field of the resulting certificate. This is a comma-separated string + or JSON array. + +- `postal_code` `(string: "")` - Specifies the Postal Code values in the + subject field of the resulting certificate. This is a comma-separated string + or JSON array. + +- `serial_number` `(string: "")` - - Specifies the requested Subject's named + [Serial Number](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31) + value, if any. If you want more than one, specify alternative names in the + `alt_names` map using OID 2.5.4.5. Note that this has no impact on the + Certificate's serial number field, which Vault randomly generates. + +- `not_before_duration` `(duration: "30s")` - Specifies the duration by which to + backdate the NotBefore property. This value has no impact in the validity period + of the requested certificate, specified in the `ttl` field. + Uses [duration format strings](/vault/docs/concepts/duration-format). + +- `not_after` `(string)` - Set the Not After field of the certificate with + specified date value. The value format should be given in UTC format + `YYYY-MM-ddTHH:MM:SSZ`. Supports the Y10K end date for IEEE 802.1AR-2018 + standard devices, `9999-12-31T23:59:59Z`. + +- `signature_bits` `(int: 0)` - Specifies the number of bits to use in + the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, + and 512 for SHA-2-512. Defaults to 0 to automatically detect based + on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size + for NIST P-Curves). + +~> **Note**: ECDSA and Ed25519 issuers do not follow configuration of the + `signature_bits` value; only RSA issuers will change signature types + based on this parameter. + +- `skid` `(string: "")` - Value for the Subject Key Identifier field + (RFC 5280 Section 4.2.1.2). Specified as a string in hex format. Default + is empty, allowing Vault to automatically calculate the SKID according + to method one in the above RFC section. + +~> **Note**: This value should ONLY be used when cross-signing to mimic + the existing certificate's SKID value; this is necessary to allow + certain TLS implementations (such as OpenSSL) which use SKID/AKID + matches in chain building to restrict possible valid chains. + +- `use_pss` `(bool: false)` - Specifies whether or not to use PSS signatures + over PKCS#1v1.5 signatures when a RSA-type issuer is used. Ignored for + ECDSA/Ed25519 issuers. + +#### Sample payload + +```json +{ + "csr": "...", + "common_name": "example.com" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/root/sign-intermediate +``` + +#### Sample response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "expiration": "1654105687", + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n" + ], + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null +} +``` + +### Sign Intermediate with External Policy + +Similar to [sign intermediate](#sign-intermediate), this endpoint accepts a +CSR and returns a certificate with appropriate values for acting as an +intermediate CA via an external policy engine. Any parameters passed to this +endpoint are passed verbatim to the Certificate Issuance External Policy Service +(CIEPS). +The response format is the same between both endpoints. + +It is suggested to limit access to the path-overridden issue endpoint +(on /pki/issuer/:issuer_ref/external-policy/issue/:policy) and let the CIEPS +engine override the issuer as necessary. + +| Method | Path | Issuer | +|--------|---------------------------------------------------------------------|---------------------------| +| POST | /pki/external-policy/sign-intermediate(/:policy) | default or CIEPS-selected | +| POST | /pki/issuer/:issuer_ref/external-policy/sign-intermediate(/:policy) | Path or CIEPS selected | + +#### Parameters + +- `policy` `(string: )` - Specifies the name of the policy to create + the certificate against. This is part of the request URL and is passed to the + external CIEPS engine. + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +~> Note: This parameter is not present on the `/pki/external-policy/sign-intermediate` +path and takes its value from the CIEPS engine response's `issuer_ref` +field, which can override the user-requested issuer. + +- `csr` `(string: )` - Specifies the PEM-encoded CSR. + +- `format` `(string: "pem")` - Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`; defaults to `pem`. If `der`, the output is + base64 encoded. If `pem_bundle`, the `certificate` field will contain the + private key and certificate, concatenated; if the issuing CA is not a + Vault-derived self-signed root, this will be included as well. + +- `private_key_format` `(string: "pem")` - Specifies the format for marshaling + the private key within the private_key response field. Defaults to `der` which will + return either base64-encoded DER or PEM-encoded DER, depending on the value of + `format`. The other option is `pkcs8` which will return the key marshalled as + PEM-encoded PKCS8. + +~> **Note** that this does not apply to the private key within the certificate +field if `format=pem_bundle` parameter is specified. + +Other parameters may be specified and will not be parsed by Vault but may be +recognized based on external CIEPS engine definition. + +#### Sample payload + +```json +{ + "csr": "..." +} +``` + +#### Sample response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "expiration": "1654105687", + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n" + ], + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null +} +``` + +### Sign Self-Issued + +This endpoint uses the configured CA certificate to sign a self-issued +certificate (which will usually be a self-signed certificate as well). + +~> **_This is an extremely privileged endpoint_**. The given certificate will be + signed as-is with only minimal validation performed (is it a CA cert, and is it + actually self-issued). The only values that will be changed will be the + authority key ID, the issuer DN, and, if set, any distribution points.

+ It is recommended to limit this endpoint to only trusted operators. + +This is generally only needed for root certificate rolling in cases where you +don't want/can't get access to a CSR (such as if it's a root stored in Vault +where the key is not exposed). If you don't know whether you need this +endpoint, you most likely should be using a different endpoint (such as +`sign-intermediate`). + +| Method | Path | Issuer | Requires `sudo` capability | +| :----- | :----------------------------------------- | :-------- | :------------------------- | +| `POST` | `/pki/root/sign-self-issued` | `default` | yes | +| `POST` | `/pki/issuer/:issuer_ref/sign-self-issued` | Selected | no | + +#### Parameters + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +~> Note: This parameter is not present on the `/pki/root/sign-self-issued` + path and takes the value `default`. + +- `certificate` `(string: )` - Specifies the PEM-encoded self-issued certificate. + +- `require_matching_certificate_algorithms` `(bool: false)` - If true, requires +that the public key algorithm of the CA match that of the submitted certificate. + +#### Sample payload + +```json +{ + "certificate": "..." +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/root/sign-self-issued +``` + +#### Sample response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n" + }, + "auth": null +} +``` + +### Sign verbatim + +This endpoint signs a new certificate based upon the provided CSR. Values are +taken verbatim from the CSR; the _only_ restriction is that this endpoint will +refuse to issue an intermediate CA certificate (see the +`/pki/root/sign-intermediate` endpoint for that functionality.) + +**This is a potentially dangerous endpoint and only highly trusted users should +have access.** + +| Method | Path | Issuer | +| :----- | :---------------------------------------------- | :-------- | +| `POST` | `/pki/sign-verbatim(/:name)` | `default` | +| `POST` | `/pki/issuer/:issuer_ref/sign-verbatim(/:name)` | Selected | + +#### Parameters + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +~> Note: This parameter is not present on the `/pki/root/sign-self-issued` + path and takes the value `default`. + +- `name` `(string: "")` - Specifies a role. If set, the following parameters + from the role will have effect: `ttl`, `max_ttl`, `issuer`, `generate_lease`, + `no_store`, `no_store_metadata` and `not_before_duration`. + +- `csr` `(string: )` - Specifies the PEM-encoded CSR. + +- `key_usage` `(list: ["DigitalSignature", "KeyAgreement", "KeyEncipherment"])` - + Specifies the default key usage constraint on the issued certificate. Valid + values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage - simply + drop the `KeyUsage` part of the value. Values are not case-sensitive. To + specify no default key usage constraints, set this to an empty list. + +~> Note: previous versions of this document incorrectly called this a constraint; + this value is only used as a default when the `KeyUsage` extension is missing + from the CSR. + +- `ext_key_usage` `(list: [])` - + Specifies the default extended key usage constraint on the issued certificate. Valid + values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage - simply + drop the `ExtKeyUsage` part of the value. Values are not case-sensitive. To + specify no key default usage constraints, set this to an empty list. + +~> Note: previous versions of this document incorrectly called this a constraint; + this value is only used as a default when the `ExtendedKeyUsage` extension is + missing from the CSR. + +- `ext_key_usage_oids` `(string: "")` - A comma-separated string or list of extended key usage oids. + +~> Note: This value is only used as a default when the `ExtendedKeyUsage` + extension is missing from the CSR. + +- `enforce_leaf_not_after_behavior` `(bool: false)` - If true, do not apply the default truncate + behavior to the issued CA certificate, instead defer to the issuer's configured `leaf_not_after_behavior`. + If an issuer's `leaf_not_after_behavior` is set to `always_enforce_err`, this flag is not required if + the desired behavior is to error out on requests who's TTL extends beyond the issuer's NotAfter. + +- `ttl` `(string: "")` - Specifies the requested Time To Live. Cannot be greater + than the engine's `max_ttl` value. If not provided, the engine's `ttl` value + will be used, which defaults to system values if not explicitly set. See + `not_after` as an alternative for setting an absolute end date (rather than + a relative one). + +- `format` `(string: "pem")` - Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the certificate and, if the + issuing CA is not a Vault-derived self-signed root, it will be concatenated + with the certificate. + +- `not_after` `(string)` - Set the Not After field of the certificate with + specified date value. The value format should be given in UTC format + `YYYY-MM-ddTHH:MM:SSZ`. Supports the Y10K end date for IEEE 802.1AR-2018 + standard devices, `9999-12-31T23:59:59Z`. + +- `signature_bits` `(int: 0)` - Specifies the number of bits to use in + the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, + and 512 for SHA-2-512. Defaults to 0 to automatically detect based + on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size + for NIST P-Curves). + +~> **Note**: ECDSA and Ed25519 issuers do not follow configuration of the + `signature_bits` value; only RSA issuers will change signature types + based on this parameter. + +- `use_pss` `(bool: false)` - Specifies whether or not to use PSS signatures + over PKCS#1v1.5 signatures when a RSA-type issuer is used. Ignored for + ECDSA/Ed25519 issuers. + +- `remove_roots_from_chain` `(bool: false)` - If true, the returned `ca_chain` + field will not include any self-signed CA certificates. Useful if end-users + already have the root CA in their trust store. + +- `user_ids` `(string: "")` - Specifies the comma-separated list of requested + User ID (OID 0.9.2342.19200300.100.1.1) Subject values to be placed on the + signed certificate. No validation on names is performed using this endpoint. + +- `cert_metadata` `(string: "")` - A base 64 + encoded value or an empty string to associate with the certificate's serial + number. A role must be passed to sign-verbatim, and that role's + no_store_metadata must be set to false, otherwise an error is returned when + specified. To retrieve metadata see: + [Read Certificate Metadata](#read-certificate-metadata) + +#### Sample payload + +```json +{ + "csr": "..." +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/sign-verbatim +``` + +#### Sample response + +```json +{ + "lease_id": "pki/sign-verbatim/7ad6cfa5-f04f-c62a-d477-f33210475d05", + "renewable": false, + "lease_duration": 21600, + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n", + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIIDUTCCAjmgAwIBAgIJAKM+z4MSfw2mMA0GCSqGSIb3DQEBCwUAMBsxGTAXBgNV\n...\nG/7g4koczXLoUM3OQXd5Aq2cs4SS1vODrYmgbioFsQ3eDHd1fg==\n-----END CERTIFICATE-----\n" + ], + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58" + }, + "auth": null +} +``` + +### Revoke certificate + +This endpoint revokes a certificate using its serial number. This is an +alternative option to the standard method of revoking using Vault lease IDs. A +successful revocation rotates the CRL unless `auto_rebuild` is set to `true` + in [the CRL configuration](#set-revocation-configuration). + +~> **Note**: This operation is privileged as it allows revocation of arbitrary + certificates based purely on their serial number. It does not validate that + the requesting user issued the certificate or has possession of the private + key.

+ It is not possible to revoke issuers using this path. + +| Method | Path | +| :----- | :------------ | +| `POST` | `/pki/revoke` | + +#### Parameters + +~> Note: either `serial_number` or `certificate` (but not both) must be + specified on requests to this endpoint. + +- `serial_number` `(string: )` - Specifies the serial number of the + certificate to revoke, in hyphen-separated or colon-separated hexadecimal. + +- `certificate` `(string: )` - Specifies the certificate to revoke, + in PEM format. This certificate must have been signed by one of the issuers + in this mount in order to be accepted for revocation. + +#### Sample payload + +```json +{ + "serial_number": "39:dd:2e..." +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/revoke +``` + +#### Sample response + +```json +{ + "data": { + "revocation_time": 1433269787 + } +} +``` + +### Revoke certificate with private key + +This endpoint revokes a certificate using its private key as proof that the +request is authorized by an appropriate individual (Proof of Possession). + +This is an alternative option to the standard method of revoking using Vault +lease IDs or revocation via serial number. A successful revocation will +rotate the CRL unless `auto_rebuild` is set to true +in [the CRL configuration](#set-revocation-configuration). + +It is not possible to revoke issuers using this path. + +~> **Note**: This operation is **NOT** privileged, as it validates revocation + has a private key corresponding to a certificate signed by Vault. However, + to avoid third parties performing a denial-of-service (DOS) against Vault, + we've made this endpoint authenticated. Thus it is strongly encouraged to + generally allow all access to this path via ACLs. + +| Method | Path | +| :----- | :--------------------- | +| `POST` | `/pki/revoke-with-key` | + +#### Parameters + +~> Note: either `serial_number` or `certificate` (but not both) must be + specified on requests to this endpoint. + +- `serial_number` `(string: )` - Specifies the serial number of the + certificate to revoke, in hyphen-separated or colon-separated hexadecimal. + +- `certificate` `(string: )` - Specifies the certificate to revoke, + in PEM format. This certificate must have been signed by one of the issuers + in this mount in order to be accepted for revocation. + +- `private_key` `(string: )` - Specifies the private key (in PEM + format) corresponding to the certificate issued by Vault that is attempted + to be revoked. This endpoint must be called several times (with each unique + certificate/serial number) if this private key is used in multiple + certificates as Vault does not maintain such a mapping. + +#### Sample payload + +```json +{ + "serial_number": "39:dd:2e...", + "private_key": "-----BEGIN PRIVATE KEY-----\n..." +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/revoke-with-key +``` + +#### Sample response + +```json +{ + "data": { + "revocation_time": 1433269787 + } +} +``` + + +### List revoked certificates + +This endpoint returns a list of serial numbers that have been revoked on the local cluster. + +| Method | Path | +|:-------|:------------------| +| `LIST` | `/certs/revoked` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/pki/certs/revoked +``` + +#### Sample response + +```json +{ + "data": { + "keys": [ + "3d:80:91:c3:c2:34:3b:81:69:3d:92:a3:80:69:db:53:04:26:ab:b4" + ] + } +} +``` + +### List revocation requests + +This endpoint returns a list of serial numbers that have been requested to +be revoked on any cluster, along with information about the request's state +and which cluster it originated on. + +| Method | Path | +| :----- | :------------------------ | +| `LIST` | `/certs/revocation-queue` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/pki/certs/revocation-queue +``` + +#### Sample response + +```json +{ + "data": { + "key_info": { + "3d:80:91:c3:c2:34:3b:81:69:3d:92:a3:80:69:db:53:04:26:ab:b4": { + "requesting_cluster": "48327b28-8325-6d79-6a0b-4cbaa6f27b4a" + } + }, + "keys": [ + "3d:80:91:c3:c2:34:3b:81:69:3d:92:a3:80:69:db:53:04:26:ab:b4" + ] + } +} +``` + +### List Cross-Cluster revocations + +This endpoint returns a list of serial numbers that have been revoked on any +cluster, along with the clusters that have a copy of that revoked certificate. + +| Method | Path | +| :----- | :----------------------- | +| `LIST` | `/certs/unified-revoked` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/pki/certs/unified-revoked +``` + +#### Sample response + +```json +{ + "data": { + "key_info": { + "7f:fd:12:5b:16:29:bb:28:ea:24:bc:a1:80:f7:4e:6e:a0:69:b9:95": { + "revoking_clusters": [ + "48327b28-8325-6d79-6a0b-4cbaa6f27b4a" + ] + } + }, + "keys": [ + "7f:fd:12:5b:16:29:bb:28:ea:24:bc:a1:80:f7:4e:6e:a0:69:b9:95" + ] + } +} +``` + +--- + +## Accessing authority information + +All consumers of the PKI Secrets Engine mount point will have access to the +following unauthenticated APIs, useful for reading information about the +certificate authority in this mount point. + +This includes information about [CA certificates](#read-issuer-certificate), +[their chains](#read-default-issuer-certificate-chain), and [their signed +CRLs](#read-issuer-crl), containing an encoded list of revoked certificates +previously issued by this authority. Individual issued [certificates can +also be read](#read-certificate), assuming their serial number is known. +Finally, the list of issuing certificates is public information in this +mount. + +### List issuers + +This endpoint returns a list of issuers currently provisioned in this mount. +The response includes both the issuer's identifier as well as the name chosen +by the operators; either can be used to refer to the issuer later. + +This endpoint is unauthenticated. + +| Method | Path | +| :----- | :------------- | +| `LIST` | `/pki/issuers` | + +#### Sample request + +```shell-session +$ curl \ + --request LIST \ + http://127.0.0.1:8200/v1/pki/issuers +``` + +#### Sample response + +```json +{ + "data": { + "key_info": { + "1ae8ce9d-2f70-0761-a465-8c9840a247a2": { + "issuer_name": "imported-root" + }, + "3dc79a5a-7a6c-70e2-1123-94b88557ba12": { + "issuer_name": "root-x1" + } + }, + "keys": [ + "1ae8ce9d-2f70-0761-a465-8c9840a247a2", + "3dc79a5a-7a6c-70e2-1123-94b88557ba12" + ] + } +} +``` + + + +### Read issuer certificate + +This endpoint retrieves the specified issuer's certificate. + +Note that the response differs between the older `/pki/cert/ca` +path and the newer `/pki/issuer/:issuer_ref/json` path; the latter +includes the full `ca_chain` of the issuer, removing the need for a separate +endpoint. + +These are unauthenticated endpoints. + +~> Note: this endpoint accepts the `If-Modified-Since` header, to respond with + 304 Not Modified when the requested resource has not changed. This header + needs to be allowed on the PKI mount by tuning the `passthrough_request_headers` + option. In order for clients to know the last modified time, the response + header `Last-Modified` needs to be added to the mount tunable + `allowed_response_headers`. + +| Method | Path | Issuer | Format | +| :----- | :----------------------------- | :-------- |:----------------------------------------------------------------------------------| +| `GET` | `/pki/cert/ca` | `default` | JSON | +| `GET` | `/pki/ca` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | +| `GET` | `/pki/ca/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | +| `GET` | `/pki/issuer/:issuer_ref/json` | Selected | JSON | +| `GET` | `/pki/issuer/:issuer_ref/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | +| `GET` | `/pki/issuer/:issuer_ref/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | + +#### Parameters + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +~> Note: This parameter is not present on the `/pki/cert/ca` and + `/pki/ca(/pem)?` paths and takes the implicit value `default`. + +#### Sample request + +```shell-session +$ curl \ + http://127.0.0.1:8200/v1/pki/issuer/root-x1/json +``` + +#### Sample response + +```text +{ + "data": { + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...", + "-----BEGIN CERTIFICATE-----\nMIIDFTCCAf2gAwIBAgIUUo/qwLm5AyqUWqFHw1MlgwUtS/kwDQYJKoZIhvcNAQEL\n..." + ], + "certificate": "-----BEGIN CERTIFICATE-----\nnMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL...", + "revocation_time": 0 + } +} +``` + + + +### Read default issuer certificate chain + +This endpoint retrieves the default issuer's CA certificate chain, including +the default issuer. + +To read [other issuers' chains](#read-issuer-certificate), use the +`/pki/issuer/:issuer_ref/json` endpoint instead. + +These are unauthenticated endpoints. + +| Method | Path | Issuer | Format | +| :----- | :------------------- | :-------- |:----------------------------------------------------------------------------------| +| `GET` | `/pki/ca_chain` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | +| `GET` | `/pki/cert/ca_chain` | `default` | JSON | + +~> **Note**: As of Vault 1.11.0, these endpoints now return the full chain + (including the default issuer's certificate and all parent issuers known + to Vault) in these responses. + +#### Sample request + +```shell-session +$ curl \ + http://127.0.0.1:8200/v1/pki/ca_chain +``` + +#### Sample response + +```text + +``` + + + +### Read issuer CRL + +This endpoint retrieves the specified issuer's CRL. + +Note that the response differs between the older `/pki/cert/crl` path and +the newer `/pki/issuer/:issuer_ref/crl` path; the latter correctly places the +PEM-encoded CRL in the `crl` field whereas the former incorrectly places it +in the `certificate` field. + +Endpoints with type `complete` are full CRLs containing all revoked +certificates (as of the time of generation. Endpoints with type `delta` +contain incremental CRLs on top of the last complete CRL, with any new +certificates that have been revoked. See the [revocation configuration +section](#set-crl-configuration) for more information about these options. +The delta CRL clears when the next complete CRL is rebuilt. Consumers of +delta CRLs will need to update their client to support fetching the +corresponding full CRL when it has been regenerated; otherwise, some serial +numbers may not appear in the local copy of the full CRL if the remote +complete and delta CRLs has been regenerated. + +Endpoints with source `local` only include cluster-local revocations. When +the `unified_crl` parameters is enabled in the [CRL +configuration](#set-crl-configuration), endpoints with source `unified` +will have revocations from all clusters. Generally use of the `unified` +source is more consistent with expectations of external apps, but see +the [PKI Considerations](/vault/docs/secrets/pki/considerations) page +for a discussion on cluster size and unified CRLs/OCSP. + + + Unified CRLs require a Vault Enterprise license or HCP Plus cluster. + + +These are unauthenticated endpoints. + +~> **Note**: As of Vault 1.11.0, these endpoints now serve a [version 2](https://datatracker.ietf.org/doc/html/rfc5280#section-5.1.2.1) CRL response. + +~> Note: this endpoint accepts the `If-Modified-Since` header, to respond with + 304 Not Modified when the requested resource has not changed. This header + needs to be allowed on the PKI mount by tuning the `passthrough_request_headers` + option. In order for clients to know the last modified time, the response + header `Last-Modified` needs to be added to the mount tunable + `allowed_response_headers`. + +| Method | Path | Issuer | Format | Type | Source | +| :----- | :---------------------------------------------- | :-------- | :-------------------------------------------------------------------------------- | :------- | :------ | +| `GET` | `/pki/cert/crl` | `default` | JSON | Complete | Local | +| `GET` | `/pki/crl` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Local | +| `GET` | `/pki/crl/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Local | +| `GET` | `/pki/cert/delta-crl` | `default` | JSON | Delta | Local | +| `GET` | `/pki/crl/delta` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Local | +| `GET` | `/pki/crl/delta/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Local | +| `GET` | `/pki/issuer/:issuer_ref/crl` | Selected | JSON | Complete | Local | +| `GET` | `/pki/issuer/:issuer_ref/crl/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Local | +| `GET` | `/pki/issuer/:issuer_ref/crl/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Local | +| `GET` | `/pki/issuer/:issuer_ref/crl/delta` | Selected | JSON | Delta | Local | +| `GET` | `/pki/issuer/:issuer_ref/crl/delta/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Local | +| `GET` | `/pki/issuer/:issuer_ref/crl/delta/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Local | +| `GET` | `/pki/cert/unified-crl` | `default` | JSON | Complete | Unified | +| `GET` | `/pki/unified-crl` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Unified | +| `GET` | `/pki/unified-crl/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Unified | +| `GET` | `/pki/cert/unified-delta-crl` | `default` | JSON | Delta | Unified | +| `GET` | `/pki/unified-crl/delta` | `default` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Unified | +| `GET` | `/pki/unified-crl/delta/pem` | `default` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Unified | +| `GET` | `/pki/issuer/:issuer_ref/unified-crl` | Selected | JSON | Complete | Unified | +| `GET` | `/pki/issuer/:issuer_ref/unified-crl/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Unified | +| `GET` | `/pki/issuer/:issuer_ref/unified-crl/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Complete | Unified | +| `GET` | `/pki/issuer/:issuer_ref/unified-crl/delta` | Selected | JSON | Delta | Unified | +| `GET` | `/pki/issuer/:issuer_ref/unified-crl/delta/der` | Selected | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Unified | +| `GET` | `/pki/issuer/:issuer_ref/unified-crl/delta/pem` | Selected | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Delta | Unified | + +#### Parameters + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +~> Note: This parameter is not present on the `/pki/cert/crl` and + `/pki/crl(/pem)?` paths and takes the implicit value `default`. + +#### Sample request + +```shell-session +$ curl \ + http://127.0.0.1:8200/v1/pki/issuer/root-x1/crl +``` + +#### Sample response + +```json +{ + "data": { + "crl": "-----BEGIN X509 CRL-----\nMIIBizB1AgEBMA0GCSqGSIb3DQEBCwUAMBIxEDAOBgNVBAMTB3Jvb3QgeDEXDTIy\n..." + } +} +``` + +### OCSP request + +This endpoint retrieves an OCSP response (revocation status) for a given serial number. The request/response formats are +based on [RFC 6960](https://datatracker.ietf.org/doc/html/rfc6960) + +Endpoints with source `local` only include cluster-local revocations. When +the `unified_crl` parameters is enabled in the [CRL +configuration](#set-crl-configuration), endpoints with source `unified` +will have revocations from all clusters. Generally use of the `unified` +source is more consistent with expectations of external apps, but see +the [PKI Considerations](/vault/docs/secrets/pki/considerations) page +for a discussion on cluster size and unified CRLs/OCSP. + + + Unified OCSP requires a Vault Enterprise license or HCP Plus cluster. + + +At this time there are certain limitations of the OCSP implementation at this path: + + 1. Only a single serial number within the request will appear in the response, + 1. None of the extensions defined in the RFC are supported for requests or responses, + 1. Ed25519 backed CA's are not supported for OCSP requests, + 1. Note that this API will not work with the Vault client as both request and responses are DER encoded, and + 1. Note that KMS based issuers which require PSS support are not supported either (such as PKCS#11 HSMs or GCP in certain scenarios). + +~> Note: The OCSP implementation for GET requests can lead to intermittent +400 errors when an encoded OCSP request contains consecutive '/' characters. +Until this is resolved it is recommended to use POST based OCSP requests. + +These are unauthenticated endpoints. + +| Method | Path | Response Format | Source | +| :----- | :--------------------------------------------------------- | :-------------------------------------------------------------------------------- | :------ | +| `GET` | `/pki/ocsp/` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Local | +| `POST` | `/pki/ocsp` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Local | +| `GET` | `/pki/unified-ocsp/` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Unified | +| `POST` | `/pki/unified-ocsp` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | Unified | + +#### Parameters + + - None + +#### Sample request + +```shell-session +openssl ocsp -no_nonce -issuer issuer.pem -CAfile ca_chain.pem -cert cert-to-revoke.pem -text -url $VAULT_ADDR/v1/pki/ocsp +``` + +### List certificates + +This endpoint returns a list of the current certificates by serial number only. +The response does not include the [special serial numbers](#read-certificate-serial-param-values) +(`ca`, `ca_chain`, and `crl`) that can be used with `/pki/cert/:serial`. + +This includes only certificates issued by this mount with `no_store=false`. +While root generation does create entries here, importing certificates +(including both roots and intermediates) will not cause the imported +certificate's serial number to appear in this list. + +~> Note: The endpoint to list all certificates is authenticated. This is to + prevent automated enumeration of issued certificates for internal services; + however, this information should generally be considered non-sensitive and + the certificates themselves are exposed without authentication (provided + their serial number is known).

+ Many Public CAs participate in the Certificate Transparency initiative, + where all issued certificates are publicly disclosed in the interest + of third-party verification of CA integrity. + +| Method | Path | +| :----- | :----------- | +| `LIST` | `/pki/certs` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/pki/certs +``` + +#### Sample response + +```json +{ + "data": { + "keys": [ + "17:67:16:b0:b9:45:58:c0:3a:29:e3:cb:d6:98:33:7a:a6:3b:66:c1", + "26:0f:76:93:73:cb:3f:a0:7a:ff:97:85:42:48:3a:aa:e5:96:03:21" + ] + } +} +``` + + + +### Read certificate + +This endpoint retrieves the certificate specified by its serial number, +including issued certificates. + +~> Note: With the exception of the special values (`ca`, `crl`, and + `ca_chain`), `/pki/cert/:serial` will return different results on + different clusters. This is because stored certificates are not + replicated across different Performance Replication clusters. + +These are unauthenticated endpoints. + +| Method | Path | Format | +| :----- | :-------------------------- |:----------------------------------------------------------------------------------| +| `GET` | `/pki/cert/:serial` | JSON | +| `GET` | `/pki/cert/:serial/raw` | DER [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | +| `GET` | `/pki/cert/:serial/raw/pem` | PEM [\[1\]](#vault-cli-with-der-pem-responses "Vault CLI With DER/PEM Responses") | + +#### Parameters + +- `serial` `(string: )` - Specifies the serial of the key to read. + This is part of the request URL. Valid values for `serial` are: + + + + - `` for the certificate with the given serial number, in hyphen-separated or colon-separated hexadecimal. + - `ca` for the _default_ issuer's CA certificate + - `crl` for the _default_ issuer's CRL + - `ca_chain` for the _default_ issuer's CA trust chain. + +~> **Note**: As of Vault 1.11.0, these endpoints return the full chain + (including this certificate and all parent issuers known to Vault) in + the `ca_chain` response, for both the `certificate` and newer `ca_chain` + fields. The root certificate is no longer elided. + +#### Sample request + +```shell-session +$ curl \ + http://127.0.0.1:8200/v1/pki/cert/67:b4:f7:2c:aa:ef:b9:30:f6:ae:f5:12:21:79:ac:08:8a:86:89:72 +``` + +#### Sample response + +```json +{ + "data": { + "certificate": "-----BEGIN CERTIFICATE-----\nMIIGmDCCBYCgAwIBAgIHBzEB3fTzhTANBgkqhkiG9w0BAQsFADCBjDELMAkGA1UE\n...", + "revocation_time": 1667400107, + "revocation_time_rfc3339": "2022-11-02T14:41:47.327515Z", + "issuer_id": "e27bf456-51e1-d937-0001-4a609184fd9b" + } +} +``` + +### Read Batch Certificate + +This endpoint retrieves multiple certificates (a batch) in a single +call. In order to accomodate the potentially long list of serial +numbers of the certificates to be retrieved, this is a POST call. + +| Method | Path | Format | +| :----- | :----------------- | :----- | +| `POST` | `/pki/batch/certs` | JSON | + +#### Parameters + +- `serial_numbers` `([]string: "") - Specifies a list of serial numbers of +certificates to be fetched. + +#### Sample Payload + +```json +{ + "serial_numbers": [ + "38:1f:29:ad:99:e8:c9:ae:7b:33:4d:b2:a5:c8:30:7c:71:93:77:ee", + "67:b4:f7:2c:aa:ef:b9:30:f6:ae:f5:12:21:79:ac:08:8a:86:89:72" + ] +} +``` + +#### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/batch/certs/ +``` + +#### Sample Response + +```json +{ + "certificates": { + "38:1f:29:ad:99:e8:c9:ae:7b:33:4d:b2:a5:c8:30:7c:71:93:77:ee": "----- BEGIN CERTIFICATE..." + "67:b4:f7:2c:aa:ef:b9:30:f6:ae:f5:12:21:79:ac:08:8a:86:89:72": null, + } +} +``` + +### Read Certificate Metadata + +This endpoint retrieves the metadata associated with the certificate +specified by the serial number. + +| Method | Path | Format | +| :----- | :----------------------------------- |:------ | +| `GET` | `/pki/cert-metadata/:serial` | JSON | + +#### Parameters + +- `serial` `(string: )` - Specifies the serial of the certificate +whose metadata to read. This is part of the request URL. + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/cert-metadata/67:b4:f7:2c:aa:ef:b9:30:f6:ae:f5:12:21:79:ac:08:8a:86:89:72 +``` + +#### Sample response + +```json +{ + "data": { + "issuer_id": "e27bf456-51e1-d937-0001-4a609184fd9b", + "expiration": "2022-11-02T14:41:47.327515Z", + "cert_metadata": "dXNlci1wcm92aWRlZC1tZXRhZGF0YQ==", + "role": "role-name", + "serial_number": "67:b4:f7:2c:aa:ef:b9:30:f6:ae:f5:12:21:79:ac:08:8a:86:89:72" + } +} +``` + +#### Sample cert_metadata fetch + +```shell-session +$ base64 --decode <<< $(vault read --field=cert_metadata pki/cert-metadata/67:b4:f7:2c:aa:ef:b9:30:f6:ae:f5:12:21:79:ac:08:8a:86:89:72 ) +user-provided-metadata +``` + +### List Certificate Metadata + +This endpoint returns a list of stored certificate metadata. Only the +serial numbers of the certificates the metadata is associated with are +returned, not the certificate metadata itself. + +| Method | Path | +| :----- | :------------------- | +| `LIST` | `/pki/cert-metadata` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/pki/cert-metadata +``` + +#### Sample response + +```json +{ + "auth": null, + "data": { + "keys": ["38:1f:29:ad:99:e8:c9:ae:7b:33:4d:b2:a5:c8:30:7c:71:93:77:ee", "67:b4:f7:2c:aa:ef:b9:30:f6:ae:f5:12:21:79:ac:08:8a:86:89:72"] + }, + "lease_duration": 0, + "lease_id": "", + "renewable": false +} +``` + +--- + +## Managing keys and issuers + +The following endpoints are highly privileged and allow operators to generate +or import new issuer certificates and keys, remove existing keys and issuers, +or read internal information about keys and issuers. + +### List issuers + +Refer to the [earlier section](#list-issuers) for more information about +listing issuers. + +### List keys + +This endpoint returns a list of keys currently provisioned in this mount. +The response includes both the key's identifier as well as the name chosen +by the operators; either can be used to refer to the key later. + +This endpoint is authenticated. + +| Method | Path | +| :----- | :----------- | +| `LIST` | `/pki/keys` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/pki/keys +``` + +#### Sample response + +```json +{ + "data": { + "key_info": { + "f9244f54-adc7-4a5c-6b08-6ca3a3325620": { + "key_name": "imported-root-key" + }, + }, + "keys": [ + "f9244f54-adc7-4a5c-6b08-6ca3a3325620", + ] + } +} +``` + +### Generate key + +This endpoint generates a new private key for use in the PKI mount. This key +can be used with either the [root](#generate-root) or [intermediate](#generate-intermediate-csr) +endpoints, using the `type=existing` variant. + +If the path ends with `exported`, the private key will be returned in the +response; if it is `internal` the private key will not be returned and _cannot +be retrieved later_; if it is `kms`, a [managed keys](#managed-keys) will be +used. + +| Method | Path | +| :----- | :--------------------------------- | +| `POST` | `/pki/keys/generate/:type` | + +#### Parameters + +- `type` `(string: )` - Specifies the type of the key to + create. If `exported`, the private key will be returned in the response; if + `internal` the private key will not be returned and _cannot be retrieved + later_; `kms` is also supported: [see below for more details about managed + keys](#managed-keys). This parameter is part of the request URL. + +- `key_name` `(string: "")` - When a new key is created with this request, + optionally specifies the name for this. The global ref `default` may not + be used as a name. + +- `key_type` `(string: "rsa")` - Specifies the desired key type; must be `rsa`, `ed25519` + or `ec`. + +- `key_bits` `(int: 0)` - Specifies the number of bits to use for the + generated keys. Allowed values are 0 (universal default); with + `key_type=rsa`, allowed values are: 2048 (default), 3072, 4096 or 8192; + with `key_type=ec`, allowed values are: 224, 256 (default), + 384, or 521; ignored with `key_type=ed25519`. + +#### Managed keys parameters + +See [Managed Keys](#managed-keys) for additional details on this feature, if +`type` was set to `kms`. One of the following parameters must be set + +- `managed_key_name` `(string: "")` - The managed key's configured name. + +- `managed_key_id` `(string: "")` - The managed key's UUID. + +#### Sample payload + +```json +{ + "key_type": "ec", + "key_bits": "256", + "key_name": "root-key-2022" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/keys/generate/internal +``` + +#### Sample response + +```json +{ + "request_id": "8ad22b2f-7d14-f2cd-a10a-d1abc33676ab", + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "key_id": "adda2443-a8aa-d181-9d07-07c7be6a76ab", + "key_name": "root-key-2022", + "key_type": "ec" + }, + "warnings": null +} +``` + +### Generate root + +This endpoint generates a new self-signed CA certificate and private key. If +the path ends with `exported`, the private key will be returned in the +response; if it is `internal` the private key will not be returned and _cannot +be retrieved later_; if it is `existing`, the key specified by `key_ref` will +be reused for this root; if it is `kms`, a [managed keys](#managed-keys) will +be used. + +This generated root will sign its own CRL. Authority Access distribution points +use the values set via `config/urls`. + +~> **Note**: As of Vault 1.11.0, the PKI Secrets Engine now supports multiple + issuers under a single mount. Use the management operations in this section + to [list](#list-issuers) and [modify issuers](#update-issuer) within this + mount. No issuers will be overridden by calling this operation. Deleting + individual keys and issuers should be preferred to calling `DELETE /pki/root`, + [which deletes everything](#delete-all-issuers-and-keys). + +| Method | Path | +| :----- | :--------------------------------- | +| `POST` | `/pki/root/generate/:type` | +| `POST` | `/pki/issuers/generate/root/:type` | +| `POST` | `/pki/root/rotate/:type` | + +#### Parameters + +- `type` `(string: )` - Specifies the type of the root to + create. If `exported`, the private key will be returned in the response; if + `internal` the private key will not be returned and _cannot be retrieved + later_; if `existing`, we use the value of the `key_ref` parameter to find + existing key material to create the CSR; `kms` is also supported: [see below + for more details about managed keys](#managed-keys). This parameter is part + of the request URL. + +- `issuer_name` `(string: "")` - Provides a name to the specified issuer. The + name must be unique across all issuers and not be the reserved value + `default`. When no value is supplied and the path is `/pki/root/rotate/:type`, + the default value of `"next"` will be used. + +- `key_name` `(string: "")` - When a new key is created with this request, + optionally specifies the name for this. The global ref `default` may not + be used as a name. + +- `key_ref` `(string: "default")` - Specifies the key (either `default`, by + name, or by identifier) to use for generating this request. Only suitable + for `type=existing` requests. + +- `common_name` `(string: )` - Specifies the requested CN for the + certificate. If more than one `common_name` is desired, specify the + alternative names in the `alt_names` list. + +- `alt_names` `(string: "")` - Specifies the requested Subject Alternative + Names, in a comma-delimited list. These can be host names or email addresses; + they will be parsed into their respective fields. + +- `ip_sans` `(string: "")` - Specifies the requested IP Subject Alternative + Names, in a comma-delimited list. + +- `uri_sans` `(string: "")` - Specifies the requested URI Subject Alternative + Names, in a comma-delimited list. + +- `other_sans` `(string: "")` - Specifies custom OID/UTF8-string SANs. These + must match values specified on the role in `allowed_other_sans` (see role + creation for allowed_other_sans globbing rules). + The format is the same as OpenSSL: `;:` where the + only current valid type is `UTF8`. This can be a comma-delimited list or a + JSON string slice. + +- `ttl` `(string: "")` - Specifies the requested Time To Live (after which the + certificate will be expired). This cannot be larger than the engine's max (or, + if not set, the system max). See `not_after` as an alternative for setting an + absolute end date (rather than a relative one). + +- `format` `(string: "pem")` - Specifies the format for returned data. Can be + `pem`, `der`, or `pem_bundle`. If `der`, the output is base64 encoded. If + `pem_bundle`, the `certificate` field will contain the private key (if + exported) and certificate, concatenated; if the issuing CA is not a + Vault-derived self-signed root, this will be included as well. + +- `private_key_format` `(string: "der")` - Specifies the format for marshaling + the private key within the private_key response field. Defaults to `der` which will + return either base64-encoded DER or PEM-encoded DER, depending on the value of + `format`. The other option is `pkcs8` which will return the key marshalled as + PEM-encoded PKCS8. + +~> **Note** that this does not apply to the private key within the certificate + field if `format=pem_bundle` parameter is specified. + +- `key_type` `(string: "rsa")` - Specifies the desired key type; must be `rsa`, `ed25519` + or `ec`. + +- `key_bits` `(int: 0)` - Specifies the number of bits to use for the + generated keys. Allowed values are 0 (universal default); with + `key_type=rsa`, allowed values are: 2048 (default), 3072, 4096 or 8192; + with `key_type=ec`, allowed values are: 224, 256 (default), + 384, or 521; ignored with `key_type=ed25519`. + +- `max_path_length` `(int: -1)` - Specifies the maximum path length to encode in + the generated certificate. `-1` means no limit. Unless the signing certificate + has a maximum path length set, in which case the path length is set to one + less than that of the signing certificate. A limit of `0` means a literal + path length of zero. + +- `key_usage` `([]string: CRL,CertSign)` - This list of key usages will be added + to the existing set of key usages, CRL,CertSign, on the generated certificate. + Per the CAB Forum, Vault ignores additional values other than `DigitalSignature`. + +- `exclude_cn_from_sans` `(bool: false)` - If true, the given `common_name` will + not be included in DNS or Email Subject Alternate Names (as appropriate). + Useful if the CN is not a hostname or email address, but is instead some + human-readable identifier. + +- `permitted_dns_domains` `(string: "")` - A comma separated string (or, string + array) containing DNS domains for which certificates are allowed to be issued + or signed by this CA certificate. Note that subdomains are allowed, as per + [RFC 5280 Section 4.2.1.10 - Name + Constraints](https://tools.ietf.org/html/rfc5280#section-4.2.1.10). + +- `excluded_dns_domains` `(string: "")` - A comma separated string (or, string + array) containing DNS domains for which certificates are not allowed to be issued + or signed by this CA certificate. Supports subdomains via a `.` in front of + the domain, as per [RFC 5280 Section 4.2.1.10 - Name + Constraints](https://tools.ietf.org/html/rfc5280#section-4.2.1.10) + +- `permitted_ip_ranges` `(string: "")` - A comma separated string (or, string + array) containing IP ranges for which certificates are allowed to be issued or + signed by this CA certificate. IP ranges must be in the CIDR notation of IP + address and prefix length like "192.0.2.0/24" or "2001:db8::/32", as defined + in RFC 4632 and RFC 4291. + +- `excluded_ip_ranges` `(string: "")` - A comma separated string (or, string + array) containing IP ranges for which certificates are not allowed to be + issued or signed by this CA certificate. IP ranges must be in the CIDR + notation of IP address and prefix length like "192.0.2.0/24" or + "2001:db8::/32", as defined in RFC 4632 and RFC 4291. + +- `permitted_email_addresses` `(string: "")` - A comma separated string (or, string + array) containing email addresses for which certificates are allowed to be issued or + signed by this CA certificate. + +- `excluded_email_addresses` `(string: "")` - A comma separated string (or, + string array) containing email addresses for which certificates are not + allowed to be issued or signed by this CA certificate. + +- `permitted_uri_domains` `(string: "")` - A comma separated string (or, string + array) containing fully qualified domain names for which certificates are + allowed to be issued or signed by this CA certificate. Supports subdomains via + a `.` in front of the domain, as per [RFC 5280 Section 4.2.1.10 - Name + Constraints](https://tools.ietf.org/html/rfc5280#section-4.2.1.10) + +- `excluded_uri_domains` `(string: "")` - A comma separated string (or, string + array) containing fully qualified domain names for which certificates are not + allowed to be issued or signed by this CA certificate. Supports subdomains via + a `.` in front of the domain, as per [RFC 5280 Section 4.2.1.10 - Name + Constraints](https://tools.ietf.org/html/rfc5280#section-4.2.1.10) + +- `ou` `(string: "")` - Specifies the OU (OrganizationalUnit) values in the + subject field of the resulting certificate. This is a comma-separated string + or JSON array. + +- `organization` `(string: "")` - Specifies the O (Organization) values in the + subject field of the resulting certificate. This is a comma-separated string + or JSON array. + +- `country` `(string: "")` - Specifies the C (Country) values in the subject + field of the resulting certificate. This is a comma-separated string or JSON + array. + +- `locality` `(string: "")` - Specifies the L (Locality) values in the subject + field of the resulting certificate. This is a comma-separated string or JSON + array. + +- `province` `(string: "")` - Specifies the ST (Province) values in the subject + field of the resulting certificate. This is a comma-separated string or JSON + array. + +- `street_address` `(string: "")` - Specifies the Street Address values in the + subject field of the resulting certificate. This is a comma-separated string + or JSON array. + +- `postal_code` `(string: "")` - Specifies the Postal Code values in the + subject field of the resulting certificate. This is a comma-separated string + or JSON array. + +- `serial_number` `(string: "")` - - Specifies the default Subject's named + [Serial Number](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31) + value, if any. If you want more than one, specify alternative names in the + `alt_names` map using OID 2.5.4.5. Note that this has no impact on the + Certificate's serial number field, which Vault randomly generates. + +- `signature_bits` `(int: 0)` - Specifies the number of bits to use in + the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, + and 512 for SHA-2-512. Defaults to 0 to automatically detect based + on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size + for NIST P-Curves). + +- `not_before_duration` `(duration: "30s")` - Specifies the duration by which to + backdate the NotBefore property. This value has no impact in the validity period + of the requested certificate, specified in the `ttl` field. + Uses [duration format strings](/vault/docs/concepts/duration-format). + +- `not_after` `(string)` - Set the Not After field of the certificate with + specified date value. The value format should be given in UTC format + `YYYY-MM-ddTHH:MM:SSZ`. Supports the Y10K end date for IEEE 802.1AR-2018 + standard devices, `9999-12-31T23:59:59Z`. + +- `use_pss` `(bool: false)` - Specifies whether or not to use PSS signatures + over PKCS#1v1.5 signatures when a RSA-type issuer is used. Ignored for + ECDSA/Ed25519 issuers. + +#### Managed keys parameters + +See [Managed Keys](#managed-keys) for additional details on this feature, if +`type` was set to `kms`. One of the following parameters must be set + +- `managed_key_name` `(string: "")` - The managed key's configured name. + +- `managed_key_id` `(string: "")` - The managed key's UUID. + +#### Sample payload + +```json +{ + "common_name": "example.com" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/root/generate/internal +``` + +#### Sample response + +```json +{ + "lease_id": "", + "lease_duration": 0, + "renewable": false, + "data": { + "expiration": "1654105687", + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "issuing_ca": "-----BEGIN CERTIFICATE-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE-----\n", + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58", + "issuer_id": "7b493f17-6c08-ff73-cf1a-99bfcc448a73", + "issuer_name": "", + "key_id": "22b82e37-529d-7251-7d78-3862bfd069ac", + "key_name": "" + }, + "auth": null +} +``` + + + +### Generate intermediate CSR + +This endpoint returns a new CSR for signing, optionally generating a new private +key. If using Vault as a root (and, like many other CAs), the various parameters +on the final signed certificate are set at signing time and _may or may not honor +the parameters set here_ (and transmitted in the returned CSR). + +Note that this API supports [Managed Keys](/vault/docs/enterprise/managed-keys); +additional details are available [below in a dedicated section](#managed-keys). + +The parameters below are mostly meant as a helper function; not all possible +parameters that can be set in a CSR are supported in this request. + +No new issuer is yet created by this call; note that a new key may be +generated depending on the `type` request parameter. + +~> **Note**: In order to complete the intermediate generation, the CSR must be + signed and the resulting certificate imported. This may involve working with + external systems (such as an external or offline root CA) to transmit the + CSR and complete the signing before the signed intermediate certificate is + [imported](#import-ca-certificate-and-keys) into this mount. + +| Method | Path | Private key source (`type`) | +| :----- |:-------------------------------------------| :-------------------------- | +| `POST` | `/pki/intermediate/generate/:type` | specified per request | +| `POST` | `/pki/issuers/generate/intermediate/:type` | specified per request | +| `POST` | `/pki/intermediate/cross-sign` | `existing` | + +#### Parameters + +- `type` `(string: )` - Specifies the type of the intermediate to + create. If `exported`, the private key will be returned in the response; if + `internal` the private key will not be returned and _cannot be retrieved + later_; if `existing`, we expect the `key_ref` parameter to use existing + key material to create the CSR; `kms` is also supported: [see below for more + details](#managed-keys). This parameter is part of the request URL. + +- `common_name` `(string: )` - Specifies the requested CN for the + certificate. If more than one `common_name` is desired, specify the + alternative names in the `alt_names` list. + +- `alt_names` `(string: "")` - Specifies the requested Subject Alternative + Names, in a comma-delimited list. These can be host names or email addresses; + they will be parsed into their respective fields. + +- `ip_sans` `(string: "")` - Specifies the requested IP Subject Alternative + Names, in a comma-delimited list. + +- `uri_sans` `(string: "")` - Specifies the requested URI Subject Alternative + Names, in a comma-delimited list. + +- `other_sans` `(string: "")` - Specifies custom OID/UTF8-string SANs. These + must match values specified on the role in `allowed_other_sans` (see role + creation for allowed_other_sans globbing rules). + The format is the same as OpenSSL: `;:` where the + only current valid type is `UTF8`. This can be a comma-delimited list or a + JSON string slice. + +- `format` `(string: "pem")` - Specifies the format for returned data. This can be + `pem`, `der`, or `pem_bundle`; defaults to `pem`. If `der`, the output is + base64 encoded. If `pem_bundle`, the `csr` field will contain the private key + (if exported) and CSR, concatenated. + +- `private_key_format` `(string: "der")` - Specifies the format for marshaling + the private key within the private_key response field. Defaults to `der` which will + return either base64-encoded DER or PEM-encoded DER, depending on the value of + `format`. The other option is `pkcs8` which will return the key marshalled as + PEM-encoded PKCS8. + +~> **Note** that this does not apply to the private key within the certificate + field if `format=pem_bundle` parameter is specified. + +- `key_type` `(string: "rsa")` - Specifies the desired key type; must be `rsa`, `ed25519` + or `ec`. Not suitable for `type=existing` requests. + +~> **Note**: Keys of type `rsa` currently only support PKCS#1 v1.5 signatures. + This includes any managed keys. + +- `key_bits` `(int: 0)` - Specifies the number of bits to use for the + generated keys. Allowed values are 0 (universal default); with + `key_type=rsa`, allowed values are: 2048 (default), 3072, 4096, or 8192; + with `key_type=ec`, allowed values are: 224, 256 (default), + 384, or 521; ignored with `key_type=ed25519`. Not suitable for + `type=existing` requests. + +- `key_name` `(string: "")` - When a new key is created with this request, + optionally specifies the name for this. The global ref `default` may not + be used as a name. + +- `key_ref` `(string: "default")` - Specifies the key (either `default`, by + name, or by identifier) to use for generating this request. Only suitable + for `type=existing` requests. + +- `signature_bits` `(int: 0)` - Specifies the number of bits to use in + the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, + and 512 for SHA-2-512. Defaults to 0 to automatically detect based + on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size + for NIST P-Curves). + +~> **Note**: ECDSA and Ed25519 issuers do not follow configuration of the +`signature_bits` value; only RSA issuers will change signature types +based on this parameter. + +- `exclude_cn_from_sans` `(bool: false)` - If true, the given `common_name` will + not be included in DNS or Email Subject Alternate Names (as appropriate). + Useful if the CN is not a hostname or email address, but is instead some + human-readable identifier. + +- `ou` `(string: "")` - Specifies the OU (OrganizationalUnit) values in the + subject field of the resulting CSR. This is a comma-separated string + or JSON array. + +- `organization` `(string: "")` - Specifies the O (Organization) values in the + subject field of the resulting CSR. This is a comma-separated string + or JSON array. + +- `country` `(string: "")` - Specifies the C (Country) values in the subject + field of the resulting CSR. This is a comma-separated string or JSON + array. + +- `locality` `(string: "")` - Specifies the L (Locality) values in the subject + field of the resulting CSR. This is a comma-separated string or JSON + array. + +- `province` `(string: "")` - Specifies the ST (Province) values in the subject + field of the resulting CSR. This is a comma-separated string or JSON + array. + +- `street_address` `(string: "")` - Specifies the Street Address values in the + subject field of the resulting CSR. This is a comma-separated string + or JSON array. + +- `postal_code` `(string: "")` - Specifies the Postal Code values in the + subject field of the resulting CSR. This is a comma-separated string + or JSON array. + +- `serial_number` `(string: "")` - Specifies the requested Subject's named + [Serial Number](https://datatracker.ietf.org/doc/html/rfc4519#section-2.31) + value, if any. If you want more than one, specify alternative names in the + `alt_names` map using OID 2.5.4.5. Note that this has no impact on the + Certificate's serial number field, which Vault randomly generates. + +- `add_basic_constraints` `(bool: false)` - Whether to add a Basic Constraints + extension with CA: true. Only needed as a workaround in some compatibility + scenarios with Active Directory Certificate Services. + +- `key_usage` `([]string: )` - Specifies key_usage to encode in the + generated certificate. This is a list of the names of each key usage, valid + values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage part of the + name. If not set, key usage will not appear on the CSR. + +#### Managed keys parameters + +See [Managed Keys](#managed-keys) for additional details on this feature, if +`type` was set to `kms`. One of the following parameters must be set + +- `managed_key_name` `(string: "")` - The managed key's configured name. + +- `managed_key_id` `(string: "")` - The managed key's UUID. + +#### Sample payload + +```json +{ + "common_name": "www.example.com" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/intermediate/generate/exported +``` + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIIDzDCCAragAwIBAgIUOd0ukLcjH43TfTHFG9qE0FtlMVgwCwYJKoZIhvcNAQEL\n...\numkqeYeO30g1uYvDuWLXVA==\n-----END CERTIFICATE REQUEST-----\n", + "private_key": "-----BEGIN RSA PRIVATE KEY-----\\nMIIEpAIBAAKCAQEAwsANtGz9gS3o5SwTSlOG1l-----END RSA PRIVATE KEY-----", + "private_key_type": "rsa" + }, + "warnings": null, + "auth": null +} +``` + + + + + +### Import CA certificates and keys + +This endpoint allows submitting (importing) the CA information for the backend +via a PEM file containing the CA certificate and any private keys, concatenated +together, in any order. + +Each certificate will be validated to ensure it is a valid CA (has an asserted +isCA basic constraint); non-CA certs will err. Any provided CRLs will be +ignored. Each unique certificate and private key will be imported as its own +issuer or key entry; duplicates (including with existing keys) will be ignored. + +The response will indicate what issuers and keys were created as part of this +request (in the `imported_issuers` and `imported_keys`), along with a `mapping` +field, indicating which keys belong to which issuers (including from already +imported entries present in the same bundle). In Vault 1.14.0, the response +also contains an `existing_issuers` and `existing_keys` fields, which specifies +the issuer and key IDs of any entries in the bundle that already +existed within this mount. + +| Method | Path | Allows private keys | Request Parameter | +| :----- | :----------------------------- | :------------------ | :---------------- | +| `POST` | `/pki/config/ca` | yes | `pem_bundle` | +| `POST` | `/pki/issuers/import/bundle` | yes | `pem_bundle` | +| `POST` | `/pki/issuers/import/cert` | no | `pem_bundle` | +| `POST` | `/pki/intermediate/set-signed` | no | `certificate` | + +~> **Note**: endpoints which allow importing private keys _should_ be considered + highly privileged and restricted appropriately. Endpoints which allow + importing issuers should also be restricted, but note that issuers without + keys are unable to issue certificates or CRLs. + +~> Note: Vault will deduplicate differently-encoded but same-valued keys and + issuers. This means the returned certificate _may_ differ in encoding from + the one provided on subsequent re-imports of the same issuer or key. + +~> Note: This import may fail due to CRL rebuilding issues or other potential + issues; this may impact long-term use of these issuers, but some issuers or + keys may still be imported as a result of this process. + +~> Warning: See the [note](/vault/docs/secrets/pki/considerations#issuer-subjects-and-crls) + regarding Subject naming on externally created CA certificates and + shortcomings with CRL building. + +#### Parameters + +- `pem_bundle` `(string: )` - Specifies the unencrypted private key + and certificate, concatenated in PEM format. + +~> Note: this parameter is on the `/pki/config/ca` and `/pki/issuers/import/*` + paths; it is not on the `/pki/intermediate/set-signed` path. + +- `certificate` `(string: )` - Specifies the certificates to import, + concatenated in PEM format. + +~> Note: this parameter is **only** on the `/pki/intermediate/set-signed` path. + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data "@payload.json" \ + http://127.0.0.1:8200/v1/pki/config/ca +``` + +Note that if you provide the data through the HTTP API, it must be +JSON-formatted, with newlines replaced with `\n`, like so: + +```json +{ + "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----" +} +``` + +#### Sample response + +```json +{ + "data": { + "imported_issuers": ["1ae8ce9d-2f70-0761-a465-8c9840a247a2"], + "imported_keys": ["97be2525-717a-e2f7-88da-0a20e11aad88"], + "mapping": { + "1ae8ce9d-2f70-0761-a465-8c9840a247a2": "97be2525-717a-e2f7-88da-0a20e11aad88" + }, + "existing_issuers": [], + "existing_keys": [] + } +} +``` + +### Read issuer + +This endpoint allows an operator to fetch a single issuer certificate and its +chain, including internal information not exposed on the [unauthenticated +`/pki/issuer/:issuer_ref/json`](#read-issuer-certificate) endpoint. This +includes information about the name, the key material, if an explicitly +constructed chain has been set, what the behavior is for signing longer TTL'd +certificates, and what usage modes are set on this issuer. + +| Method | Path | +| :----- | :------------------------ | +| `GET` | `/pki/issuer/:issuer_ref` | + +#### Parameters + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/issuer/default +``` + +#### Sample response + +```text +{ + "data": { + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...", + "-----BEGIN CERTIFICATE-----\nMIIDFTCCAf2gAwIBAgIUUo/qwLm5AyqUWqFHw1MlgwUtS/kwDQYJKoZIhvcNAQEL\n..." + ], + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...", + "issuer_id": "7545992c-1910-0898-9e64-d575549fbe9c", + "issuer_name": "root-x1", + "key_id": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf", + "leaf_not_after_behavior": "truncate", + "manual_chain": null, + "usage": "read-only,issuing-certificates,crl-signing,ocsp-signing" + } +} +``` + +### Update issuer + +This endpoint allows an operator to manage a single issuer, updating various +properties about it, including its name, an explicitly constructed chain, +what the behavior is for signing longer TTL'd certificates, and what usage +modes are set on this issuer. + +Note that it is not possible to change the certificate of this issuer; to +do so, import a new issuer and a new `issuer_id` will be assigned. + +| Method | Path | +| :------ | :------------------------ | +| `POST` | `/pki/issuer/:issuer_ref` | +| `PATCH` | `/pki/issuer/:issuer_ref` | + +~> **Note** `POST`ing to this endpoint causes Vault to overwrite the previous + contents of the issuer, using the provided request data (and any defaults + for elided parameters). It does not update only the provided fields.

+ Since Vault 1.11.0, Vault supports the PATCH operation to this endpoint, + using the [JSON patch format](https://datatracker.ietf.org/doc/html/rfc6902) + supported by KVv2, allowing update of specific fields. Note that + `vault write` uses `POST`. + +#### Parameters + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. + +- `issuer_name` `(string: "")` - Provides a name to the specified issuer. The + name must be unique across all issuers and not be the reserved value + `default`. + +- `leaf_not_after_behavior` `(string: "err")` - Behavior of a leaf's + `NotAfter` field during issuance. Valid options are: + - `always_enforce_err` overrides all hardcoded behaviors to enforce an + error if any requested TTL is beyond the issuer. This applies to CA issuance, + and ACME issuance, along with the normal err on leaf certificates through Vault's API. (Available from 1.18.2+) + - `err`, to error if the computed `NotAfter` exceeds that of this issuer; + - **Note** for CA issuance and ACME issuance this behavior is overridden + with truncate behavior, use `always_enforce_err` to disable these overrides + - `truncate` to silently truncate the requested `NotAfter` value to that + of this issuer; or + - `permit` to allow this issuance to succeed with a `NotAfter` value + exceeding that of this issuer. + +~> Note: Not all values result in leaf certificates that can be validated + through the entire validity period. It is suggested to use `truncate` for + intermediate CAs and `permit` only for root CAs. This is because + (root) certificates in browsers' trust stores typically aren't checked + for validity, whereas intermediate CA certificates sent in TLS connections + are checked for validity at the time of use. This means that a leaf + certificate permitted to be issued for longer than the intermediate likely + won't continue to validate after the intermediate has expired. + +- `manual_chain` `([]string: nil)` - Chain of issuer references to build this + issuer's computed CAChain field from, when non-empty. + +~> Note: the `manual_chain` field is an advanced field useful when automatic + chain building isn't desired. The first element _must_ be the present + issuer's reference. Subsequent references _should_ validate previous + entries, terminating with a root certificate. _Ideally_ a single linear + chain would come first (from this issuer to a single root certificate) + before any parallel, alternate chains appear.

+ This field is especially useful for cross-signed intermediates within + Vault. Because each cross-signed intermediate will only know of the + one root, but issuance should serve both, update the issuers' entries + with the desired `manual_chain` value.

+ The CA Chain returned by a GET to the issuer configuration is the same + chain presented during signing and (if this issuer is the default) on + the `/ca_chain` path. Setting `manual_chain` thus allows controlling + the presented chain as desired. + +- `usage` `([]string: read-only,issuing-certificates,crl-signing,ocsp-signing)` - Allowed + usages for this issuer. Valid options are: + + - `read-only`, to allow this issuer to be read; implict; always allowed; + - `issuing-certificates`, to allow this issuer to be used for issuing other + certificates; or + - `crl-signing`, to allow this issuer to be used for signing CRLs. This is + separate from the CRLSign KeyUsage on the x509 certificate, but this usage + cannot be set unless that KeyUsage is allowed on the x509 certificate. + - `ocsp-signing`, to allow this issuer to be used for signing OCSP responses + +~> Note: The `usage` field allows for a soft-delete capability on the issuer, + or to prevent use of the issuer prior to it being enabled. For example, + as issuance is rotated to a new issuer, the old issuer could be marked + `usage=read-only,crl-signing,ocsp-signing`, allowing existing certificates to be revoked + (and the CRL updated), but preventing new certificate issuance. After all + certificates issued under this certificate have expired, this certificate + could be marked `usage=read-only`, freezing the CRL. Finally, after a grace + period, the issuer could be deleted. + +- `revocation_signature_algorithm` `(string: "")` - Which signature algorithm + to use when building CRLs. See Go's [`x509.SignatureAlgorithm`](https://pkg.go.dev/crypto/x509#SignatureAlgorithm) + constant for possible values. This flag allows control over hash function + and signature scheme (PKCS#1v1.5 vs PSS). The default (empty string) value + is for Go to select the signature algorithm automatically, which may not + always work. + +~> Note: This can fail if the underlying key does not support the requested + signature algorithm; this may not always be known at modification time. + This most commonly needs to be modified when using PKCS#11 managed keys + with the `CKM_RSA_PKCS_PSS` mechanism type. + +- `issuing_certificates` `(array: nil)` - Specifies the URL values for + the Issuing Certificate field. This can be an array or a comma-separated + string list. See also [RFC 5280 Section 4.2.2.1](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) + for information about the Authority Information Access field. + +- `crl_distribution_points` `(array: nil)` - Specifies the URL values + for the CRL Distribution Points field. This can be an array or a + comma-separated string list. See also [RFC 5280 Section 4.2.1.13](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.13) + for information about the CRL Distribution Points field. + +- `delta_crl_distribution_points` `(array: nil)` - Specifies the URL + values for the Delta CRL Distribution Points field. This can be an array or a comma- + separated string list. See also [RFC5280 Section 4.2.1.15](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.15) + for information about the Delta CRL Distribution Points field. + +~> Note: When multiple Performance Replication clusters are enabled, each + cluster will have its own CRL. Additionally, when multiple issuers are + in use under a single mount, each issuer will also have its own CRL + distribution point. These separate CRLs should either be aggregated into a + single CRL (externally; as Vault does not support this functionality) + or multiple `crl_distribution_points` and `delta_crl_distribution_points` + should be specified here, pointing to each cluster and issuer. + +- `ocsp_servers` `(array: nil)` - Specifies the URL values for the OCSP + Servers field. This can be an array or a comma-separated string list. See also + [RFC 5280 Section 4.2.2.1](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) + for information about the Authority Information Access field. + +- `enable_aia_url_templating` `(bool: false)` - Specifies that the above AIA + URL values (`issuing_certificates`, `crl_distribution_points`, + `delta_crl_distribution_points`, and `ocsp_servers`) should be templated. + This replaces the literal value `{{issuer_id}}` with the ID of the issuer + doing the issuance, the literal value `{{cluster_path}}` with the value + of `path` from the cluster-local configuration endpoint `/config/cluster`, + and the literal value `{{cluster_aia_path}}` with the value of `aia_path` + from the cluster-local configuration endpoint `/config/cluster`. + +~> **Note**: If no cluster-local address is present and templating is used, + issuance will fail. + +- `disable_critical_extension_checks` `(bool: false)` - This determines whether this issuer is able + to issue certificates where the chain of trust (including the issued + certificate) contain critical extensions not processed by vault, breaking the + behavior required by [RFC 5280 Section 6.1](https://www.rfc-editor.org/rfc/rfc5280#section-6.1). + +- `disable_path_length_checks` `(bool: false)` - This determines whether this issuer is able + to issue certificates where the chain of trust (including the final issued + certificate) is longer than allowed by a certificate authority in that chain, + breaking the behavior required by + [RFC 5280 Section 4.2.1.9](https://www.rfc-editor.org/rfc/rfc5280#section-4.2.1.9). + +- `disable_name_checks` `(bool: false)` - This determines whether this issuer is able + to issue certificates where the chain of trust (including the final issued + certificate) contains a link in which the subject of the issuing certificate + does not match the named issuer of the certificate it signed, breaking the + behavior required by [RFC 5280 Section 4.1.2.4](https://www.rfc-editor.org/rfc/rfc5280#section-4.1.2.4). + +- `disable_name_constraint_checks` `(bool: false)` - This determines whether this issuer is able + to issue certificates where the chain of trust (including the final issued + certificate) violates the name constraints critical extension of one of the + issuer certificates in the chain, breaking the behavior required by + [RFC 5280 Section 4.2.1.10](https://www.rfc-editor.org/rfc/rfc5280#section-4.2.1.10). + +#### Sample payload + +```json +{ + "issuer_name": "root-x1" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/issuer/default +``` + +#### Sample response + +```text +{ + "data": { + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...", + "-----BEGIN CERTIFICATE-----\nMIIDFTCCAf2gAwIBAgIUUo/qwLm5AyqUWqFHw1MlgwUtS/kwDQYJKoZIhvcNAQEL\n..." + ], + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...", + "issuer_id": "7545992c-1910-0898-9e64-d575549fbe9c", + "issuer_name": "root-x1", + "key_id": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf", + "leaf_not_after_behavior": "truncate", + "manual_chain": null, + "usage": "read-only,issuing-certificates,crl-signing,ocsp-signing", + "revocation_signature_algorithm": "", + "issuing_certificates": ["", ""], + "crl_distribution_points": ["", ""], + "delta_crl_distribution_points": ["", ""] + "ocsp_servers": ["", ""] + } +} +``` + +### Revoke issuer + +This endpoint allows an operator to revoke an issuer certificate, marking it +unable to issue new certificates and adding it to other issuers' CRLs, if they +have signed this issuer's certificate. This will cause all CRLs to be rebuilt. + +This is mostly provided for book-keeping and as a soft-delete feature, to +ensure this issuer is not accidentally reused in the future. + +~> **Warning**: This operation cannot be undone! + +~> Note: This operation **does not** have any impact on other clusters or + mounts and **may not** have any impact on whether clients consider these + issuers revoked. Revoked issuers will not appear on their own CRLs. Revoked + issuers may not appear on other CRLs if a suitable parent is not present in + the same mount point. Revoked issuers will still need to be revoked in any + other mounts they appear in, both as issuers, in the event of issuer reuse, + and as issued certificates, in the event of an external parent mount. + +| Method | Path | +| :------ | :------------------------------- | +| `POST` | `/pki/issuer/:issuer_ref/revoke` | + +#### Parameters + +No parameters. + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/pki/issuer/old-intermediate/revoke +``` + +#### Sample response + +```text +{ + "data": { + "ca_chain": [ + "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...", + "-----BEGIN CERTIFICATE-----\nMIIDFTCCAf2gAwIBAgIUUo/qwLm5AyqUWqFHw1MlgwUtS/kwDQYJKoZIhvcNAQEL\n..." + ], + "certificate": "-----BEGIN CERTIFICATE-----\nMIIDFDCCAfygAwIBAgIUXgxy54mKooz5soqQoRINazH/3pQwDQYJKoZIhvcNAQEL\n...", + "issuer_id": "7545992c-1910-0898-9e64-d575549fbe9c", + "issuer_name": "old-intermediate", + "key_id": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf", + "leaf_not_after_behavior": "truncate", + "manual_chain": null, + "usage": "read-only,issuing-certificates,crl-signing" + "revocation_time": 1433269787, + } +} +``` + +### Delete issuer + +This endpoint deletes the specified issuer. A warning is emitted and the +default is cleared if this issuer is the default issuer. + +~> **Note**: If an issuer is incorrectly deleted, but its key material + remains, it is possible to re-import just the issuer certificate. The + `issuer_id` will change, but the name can be re-assigned to the new + issuer. + +| Method | Path | +| :------- | :------------------------ | +| `DELETE` | `/pki/issuer/:issuer_ref` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/pki/issuer/root-x1 +``` + +### Import key + +This endpoint allows an operator to import a single pem encoded `rsa`, `ec`, or `ed25519` +key. + +~> **Note**: This API does not protect against importing keys using insecure combinations of + algorithm and key length. + +| Method | Path | +|:-------|:-------------------| +| `POST` | `/pki/keys/import` | + +#### Parameters + +- `pem_bundle` `(string: )` - Specifies the unencrypted private key in PEM format. + +- `key_name` `(string: "")` - Provides a name to the specified key. The + name must be unique across all keys and not be the reserved value + `default`. + +#### Sample payload + +```json +{ + "key_name": "my-imported-key", + "pem_bundle": "-----BEGIN RSA PRIVATE KEY-----\n...\n-----END CERTIFICATE-----" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/keys/import +``` + +#### Sample response + +```text +{ + "data": { + "key_id": "2cf03991-b052-1dc3-393e-374b41f8dcd8", + "key_name": "my-imported-key", + "key_type": "rsa" + }, +} +``` + +### Read key + +This endpoint allows an operator to fetch information about an existing key. + +~> **Note**: Vault does not allow reading the value of the private key after + it has been created. + +| Method | Path | +| :----- | :------------------ | +| `GET` | `/pki/key/:key_ref` | + +#### Parameters + +- `key_ref` `(string: )` - Reference to an existing key, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default key, or the name assigned + to a key. This parameter is part of the request URL. + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/key/default +``` + +#### Sample response + +```text +{ + "data": { + "key_id": "8c4046f8-52a8-0974-29d2-745d8a0dd848", + "key_name": "key-root-x1", + "key_type": "rsa" + } +} +``` + +### Update key + +This endpoint allows an operator to manage a single key. Currently, the only +parameter that is configurable is the key's name. + +Note that it is not possible to change the private key of this key; to +do so, import a new key and a new `key_id` will be assigned. + +| Method | Path | +| :----- | :------------------ | +| `POST` | `/pki/key/:key_ref` | + +~> **Note** `POST`ing to this endpoint causes Vault to overwrite the previous + contents of the key, using the provided request data (and any defaults + for elided parameters). It does not update only the provided fields. + +#### Parameters + +- `key_ref` `(string: )` - Reference to an existing key, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default key, or the name assigned + to a key. This parameter is part of the request URL. + +- `key_name` `(string: "")` - Provides a name to the specified key. The + name must be unique across all keys and not be the reserved value + `default`. + +#### Sample payload + +```json +{ + "key_name": "key-root-x1" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/key/default +``` + +#### Sample response + +```text +{ + "data": { + "key_id": "8c4046f8-52a8-0974-29d2-745d8a0dd848", + "key_name": "key-root-x1", + "key_type": "rsa" + } +} +``` + +### Delete key + +This endpoint deletes the specified key. A warning is emitted and the +default is cleared if this key is the default key. + +~> **Note**: Because Vault does not allow exporting the private key + after it is initially generated, deletion of keys is a sensitive + operation. Additionally, one key may be used by more than one issuer. + As a result, Vault prohibits deletion of keys until **all** issuers + using this key have also been deleted. If these issuers are still + necessary for chain building, re-import them without the corresponding + keys after the key has been deleted or use the soft-delete feature + of issuers. + +| Method | Path | +| :------- | :------------------ | +| `DELETE` | `/pki/key/:key_ref` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/pki/key/key-root-x1 +``` + +### Delete all issuers and keys + +This endpoint deletes all issuers and keys within the mount. It is highly +recommended to use the individual delete operations instead. This mount +will be unusable until new issuers and keys are provisioned. + +_This endpoint requires sudo/root privileges._ + +| Method | Path | +| :------- | :---------- | +| `DELETE` | `/pki/root` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/pki/root +``` + +--- + +## Managing authority information + +The following privileged endpoints allow the operator to control information +about the core contents of certificates and to perform privileged operations +like rotating the CRLs or performing tidy operations. + +### List roles + +Refer to the [earlier section](#list-roles) for more information about +listing roles. + +### Create/Update role + +This endpoint creates or updates the role definition. Note that the +`allowed_domains`, `allow_subdomains`, `allow_glob_domains`, and +`allow_any_name` attributes are additive; between them nearly and across +multiple roles nearly any issuing policy can be accommodated. `server_flag`, +`client_flag`, and `code_signing_flag` are additive as well. If a client +requests a certificate that is not allowed by the CN policy in the role, the +request is denied. + +| Method | Path | +| :------ | :----------------- | +| `POST` | `/pki/roles/:name` | +| `PATCH` | `/pki/roles/:name` | + +~> **Note** `POST`ing to this endpoint when the role already exists causes + Vault to overwrite the contents of the role, using the provided request + data (and any defaults for elided parameters). It does not update only + the provided fields.

+ Since Vault 1.11.0, Vault supports the PATCH operation to this endpoint, + using the [JSON patch format](https://datatracker.ietf.org/doc/html/rfc6902) + supported by KVv2, allowing update of specific fields. Note that + `vault write` uses `POST`. + +#### Parameters + +- `name` `(string: )` - Specifies the name of the role to create. This + is part of the request URL. + +- `issuer_ref`: `(string: "default")` - Specifies the default issuer of this + request. May be the value `default`, a name, or an issuer ID. Use ACLs to + prevent access to the `/pki/issuer/:issuer_ref/{issue,sign}/:name` paths + to prevent users overriding the role's `issuer_ref` value. + +~> Note: This parameter is stored as-is; if the reference is to a name, it + is **not** resolve to an identifier. Deletion of issuers (or updating their + names) **may** result in issuance failing or using an unexpected issuer. + +~> **Note**: existing roles from previous Vault versions are migrated to use + the `issuer_ref=default`. + +- `ttl` `(string: "")` - Specifies the Time To Live value to be used for the + validity period of the requested certificate, provided as a string duration + with time suffix. Hour is the largest suffix. The value specified is strictly + used for future validity. If not set, uses the system default value or the + value of `max_ttl`, whichever is shorter. See `not_after` as an alternative + for setting an absolute end date (rather than a relative one). + +- `max_ttl` `(string: "")` - Specifies the maximum Time To Live provided as a + string duration with time suffix. Hour is the largest suffix. If not set, + defaults to the system maximum lease TTL. + +- `allow_localhost` `(bool: true)` - Specifies if clients can request + certificates for `localhost` as one of the requested common names. This is + useful for testing and to allow clients on a single host to talk securely. + +~> **Note**: This strictly applies to `localhost` and `localdomain` when this + option is enabled. Additionally, even if this option is disabled, if either + name is included in `allowed_domains`, the match rules for that option + could permit issuance of a certificate for `localhost`. + +- `allowed_domains` `(list: [])` - Specifies the domains this role is allowed + to issue certificates for. This is used with the `allow_bare_domains`, + `allow_subdomains`, and `allow_glob_domains` options to determine the type + of matching between these domains and the values of common name, DNS-typed + SAN entries, and Email-typed SAN entries. When `allow_any_name` is used, + this attribute has no effect. + +~> **Note**: The three options `allow_bare_domains`, `allow_subdomains`, and + `allow_glob_domains` are each independent of each other. That is, at least + one type of allowed matching must describe the relationship between the + `allowed_domains` list and the names on the issued certificate. For example, + given `allowed_domain=foo.*.example.com` and `allow_subdomains=true` and + `allow_glob_domains=true`, a request for `bar.foo.baz.example.com` won't + be permitted, even though it `foo.baz.example.com` matches the glob + `foo.*.example.com` and `bar` is a subdomain of that. + +- `allowed_domains_template` `(bool: false)` - When set, `allowed_domains` + may contain templates, as with [ACL Path Templating](/vault/docs/concepts/policies). + Non-templated domains are also still permitted. + +- `allow_bare_domains` `(bool: false)` - Specifies if clients can request + certificates matching the value of the actual domains themselves; e.g. if a + configured domain set with `allowed_domains` is `example.com`, this allows + clients to actually request a certificate containing the name `example.com` as + one of the DNS values on the final certificate. In some scenarios, this can be + considered a security risk. Note that when an `allowed_domain` field contains + a potential wildcard character (for example, `allowed_domains=*.example.com`) + and `allow_bare_domains` and `allow_wildcard_certificates` are both enabled, + issuance of a wildcard certificate for `*.example.com` will be permitted. + +- `allow_subdomains` `(bool: false)` - Specifies if clients can request + certificates with CNs that are subdomains of the CNs allowed by the other role + options. _This includes wildcard subdomains._ For example, an + `allowed_domains` value of `example.com` with this option set to true will + allow `foo.example.com` and `bar.example.com` as well as `*.example.com`. To + restrict issuance of wildcards by this option, see `allow_wildcard_certificates` + below. This option is redundant when using the `allow_any_name` option. + +- `allow_glob_domains` `(bool: false)` - Allows names specified in + `allowed_domains` to contain glob patterns (e.g. `ftp*.example.com`). Clients + will be allowed to request certificates with names matching the glob + patterns. + +~> **Note**: These globs behave like shell-style globs and can match + across multiple domain parts. For example, `allowed_domains=*.example.com` + with `allow_glob_domains` enabled will match not only `foo.example.com` but + also `baz.bar.foo.example.com`. + +~> **Warning**: Glob patterns will match wildcard domains and permit their + issuance unless otherwise restricted by `allow_wildcard_certificates`. For + instance, with `allowed_domains=*.*.example.com` and both `allow_glob_domains` + and `allow_wildcard_certificates` enabled, we will permit the issuance of + a wildcard certificate for `*.foo.example.com`. + +- `allow_wildcard_certificates` `(bool: true)` - Allows the issuance of + certificates with [RFC 6125](https://tools.ietf.org/html/rfc6125) wildcards + in the CN field. When set to `false`, this prevents wildcards from being + issued even if they would've been allowed by an option above. We support + the following four wildcard types: + + - `*.example.com`, a single wildcard as the entire left-most label, + - `foo*.example.com`, a single suffixed wildcard in the left-most label, + - `*foo.example.com`, a single prefixed wildcard in the left-most label, and + - `f*o.example.com`, a single interior wildcard in the left-most label. + +- `allow_any_name` `(bool: false)` - Specifies if clients can request any CN. + Useful in some circumstances, but make sure you understand whether it is + appropriate for your installation before enabling it. Note that both + `enforce_hostnames` and `allow_wildcard_certificates` are still checked, + which may introduce limitations on issuance with this option. + +- `enforce_hostnames` `(bool: true)` - Specifies if only valid host names are + allowed for CNs, DNS SANs, and the host part of email addresses. + +- `allow_ip_sans` `(bool: true)` - Specifies if clients can request IP Subject + Alternative Names. No authorization checking is performed except to verify + that the given values are valid IP addresses. + +- `allowed_uri_sans` `(string: "")` - Defines allowed URI Subject + Alternative Names. No authorization checking is performed except to verify + that the given values are valid URIs. This can be a comma-delimited list or + a JSON string slice. Values can contain glob patterns (e.g. + `spiffe://hostname/*`). + +- `allowed_uri_sans_template` `(bool: false)` - When set, `allowed_uri_sans` + may contain templates, as with [ACL Path Templating](/vault/docs/concepts/policies). + Non-templated domains are also still permitted. + +- `allowed_other_sans` `(string: "")` - Defines allowed custom OID/UTF8-string + SANs. This can be a comma-delimited list or a JSON string slice, where + each element has the same format as OpenSSL: `;:`, but + the only valid type is `UTF8` or `UTF-8`. The `value` part of an element + may be a `*` to allow any value with that OID. + Alternatively, specifying a single `*` will allow any `other_sans` input. + +- `allowed_serial_numbers` `(string: "")` - If set, an array of allowed serial + numbers to be requested during certificate issuance. These values support + shell-style globbing. When empty, custom-specified serial numbers will be + forbidden. It is strongly recommended to allow Vault to generate random + serial numbers instead. + +- `server_flag` `(bool: true)` - Specifies if certificates are flagged for + server authentication use. See [RFC 5280 Section 4.2.1.12](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12) + for information about the Extended Key Usage field. + +- `client_flag` `(bool: true)` - Specifies if certificates are flagged for + client authentication use. See [RFC 5280 Section 4.2.1.12](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12) + for information about the Extended Key Usage field. + +- `code_signing_flag` `(bool: false)` - Specifies if certificates are flagged + for code signing use. See [RFC 5280 Section 4.2.1.12](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12) + for information about the Extended Key Usage field. + +- `email_protection_flag` `(bool: false)` - Specifies if certificates are + flagged for email protection use. See [RFC 5280 Section 4.2.1.12](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12) + for information about the Extended Key Usage field. + +- `key_type` `(string: "rsa")` - Specifies the type of key to generate for + generated private keys and the type of key expected for submitted CSRs. + Currently, `rsa`, `ec`, and `ed25519` are supported, or when signing + existing CSRs, `any` can be specified to allow keys of either type + and with any bit size (subject to >=2048 bits for RSA keys or >= 224 for EC keys). + When `any` is used, this role cannot generate certificates and can only + be used to sign CSRs. + +- `key_bits` `(int: 0)` - Specifies the number of bits to use for the + generated keys. Allowed values are 0 (universal default); with + `key_type=rsa`, allowed values are: 2048 (default), 3072, 4096 or 8192; + with `key_type=ec`, allowed values are: 224, 256 (default), + 384, or 521; ignored with `key_type=ed25519` or in signing operations + when `key_type=any`. + +- `signature_bits` `(int: 0)` - Specifies the number of bits to use in + the signature algorithm; accepts 256 for SHA-2-256, 384 for SHA-2-384, + and 512 for SHA-2-512. Defaults to 0 to automatically detect based + on issuer's key length (SHA-2-256 for RSA keys, and matching the curve size + for NIST P-Curves). + +~> **Note**: ECDSA and Ed25519 issuers do not follow configuration of the + `signature_bits` value; only RSA issuers will change signature types + based on this parameter. + +- `use_pss` `(bool: false)` - Specifies whether or not to use PSS signatures + over PKCS#1v1.5 signatures when a RSA-type issuer is used. Ignored for + ECDSA/Ed25519 issuers. + +- `key_usage` `(list: ["DigitalSignature", "KeyAgreement", "KeyEncipherment"])` - + Specifies the allowed key usage constraint on issued certificates. Valid + values can be found at https://golang.org/pkg/crypto/x509/#KeyUsage - simply + drop the `KeyUsage` part of the value. Values are not case-sensitive. To + specify no key usage constraints, set this to an empty list. See + [RFC 5280 Section 4.2.1.3](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.3) + for more information about the Key Usage field. + +- `ext_key_usage` `(list: [])` - + Specifies the allowed extended key usage constraint on issued certificates. Valid + values can be found at https://golang.org/pkg/crypto/x509/#ExtKeyUsage - simply + drop the `ExtKeyUsage` part of the value. Values are not case-sensitive. To + specify no key usage constraints, set this to an empty list. See + [RFC 5280 Section 4.2.1.12](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.12) + for information about the Extended Key Usage field. + +- `ext_key_usage_oids` `(string: "")` - A comma-separated string or list of extended + key usage oids. Useful for adding EKUs not supported by the Go standard library. + +- `use_csr_common_name` `(bool: true)` - When used with the CSR signing + endpoint, the common name in the CSR will be used instead of taken from the + JSON data. This does not include any requested SANs in the CSR; use + `use_csr_sans` for that. + +- `use_csr_sans` `(bool: true)` - When used with the CSR signing endpoint, the + subject alternate names in the CSR will be used instead of taken from the JSON + data. This does not include the common name in the CSR; use + `use_csr_common_name` for that. + +- `ou` `(string: "")` - Specifies the OU (OrganizationalUnit) values in the + subject field of issued certificates. This is a comma-separated string or + JSON array. + +- `organization` `(string: "")` - Specifies the O (Organization) values in the + subject field of issued certificates. This is a comma-separated string or + JSON array. + +- `country` `(string: "")` - Specifies the C (Country) values in the + subject field of issued certificates. This is a comma-separated string or + JSON array. + +- `locality` `(string: "")` - Specifies the L (Locality) values in the + subject field of issued certificates. This is a comma-separated string or + JSON array. + +- `province` `(string: "")` - Specifies the ST (Province) values in the + subject field of issued certificates. This is a comma-separated string or + JSON array. + +- `street_address` `(string: "")` - Specifies the Street Address values in the + subject field of issued certificates. This is a comma-separated string or + JSON array. + +- `postal_code` `(string: "")` - Specifies the Postal Code values in the + subject field of issued certificates. This is a comma-separated string or + JSON array. + +- `generate_lease` `(bool: false)` - Specifies if certificates issued/signed + against this role will have Vault leases attached to them. Certificates can be + added to the CRL by `vault revoke ` when certificates are associated + with leases. It can also be done using the `pki/revoke` endpoint. However, + when lease generation is disabled, invoking `pki/revoke` would be the only way + to add the certificates to the CRL. When large number of certificates are + generated with long lifetimes, it is recommended that lease generation be + disabled, as large amount of leases adversely affect the startup time of Vault. + +- `no_store` `(bool: false)` - If set, certificates issued/signed against this + role will not be stored in the storage backend. This can improve performance + when issuing large numbers of certificates. However, certificates issued in + this way cannot be enumerated or revoked via serial number. Certificates may + still be revoked via [BYOC revocation](#certificate-1). + This option is recommend only for certificates that are non-sensitive, + extremely short-lived, or have high volume/turn-over that would prohibit + storage. This option implies a value of `false` for `generate_lease`. + +- `require_cn` `(bool: true)` - If set to false, makes the `common_name` field + optional while generating a certificate. + +- `policy_identifiers` `(list: [])` - A comma-separated string or list of policy + OIDs. + +- `basic_constraints_valid_for_non_ca` `(bool: false)` - Mark Basic Constraints + valid when issuing non-CA certificates. + +- `not_before_duration` `(duration: "30s")` - Specifies the duration by which to + backdate the NotBefore property. This value has no impact in the validity period + of the requested certificate, specified in the `ttl` field. + +- `not_after` `(string)` - Set the Not After field of the certificate with + specified date value. The value format should be given in UTC format + `YYYY-MM-ddTHH:MM:SSZ`. Supports the Y10K end date for IEEE 802.1AR-2018 + standard devices, `9999-12-31T23:59:59Z`. + +- `cn_validations` `(list: ["email", "hostname"])` - Validations to run on the + Common Name field of the certificate. Valid values include: + + - `email`, to ensure the Common Name is an email address (contains an `@` sign), + - `hostname`, to ensure the Common Name is a hostname (otherwise). + + Multiple values can be separated with a comma or specified as a list and use + OR semantics (either email or hostname in the CN are allowed). When the + special value "disabled" is used (must be specified alone), none of the usual + validation is run (including but not limited to `allowed_domains` and basic + correctness validation around email addresses and domain names). This allows + non-standard CNs to be used verbatim from the request. + +- `allowed_user_ids` `(string: "")` - Comma separated, globbing list of User ID + Subject components to allow on requests. By default, no user IDs are allowed. + Use the bare wildcard `*` value to allow any value. See also the `user_ids` + request parameter. + +- `no_store_metadata` `(bool: false)` - allows + metadata to be stored keyed on the certificate's serial number. The field is + independent of `no_store`, allowing metadata storage regardless of whether + certificates are stored. If true, metadata is not stored and an error is returned + if the `metadata` field is specified on issuance APIs + +- `serial_number_source` `(string: "json-csr")` - Specifies the source of the subject serial + number. Valid values are `json-csr` (default) or `json`. + When set to `json-csr`, the subject serial number is taken from the `serial_number` parameter + and falls back to the serial number in the CSR. When set to `json`, the subject serial number + is taken from the `serial_number` parameter but will ignore any value in the CSR. + For backwards compatibility an empty value for this field will default to the `json-csr` behavior. + +#### Sample payload + +```json +{ + "allowed_domains": ["example.com"], + "allow_subdomains": true +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/roles/my-role +``` + +### Read role + +Refer to the [earlier section](#read-role) for more information about +reading roles. + +### Delete role + +This endpoint deletes the role definition. Deleting a role **does not** +revoke certificates previously issued under this role. + +| Method | Path | +| :------- | :----------------- | +| `DELETE` | `/pki/roles/:name` | + +#### Parameters + +- `name` `(string: )` - Specifies the name of the role to delete. This + is part of the request URL. + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/pki/roles/my-role +``` + +### Read Certificate Issuance External Policy Service (CIEPS) configuration + +This endpoint reads the Certificate Issuance External Policy Service +(CIEPS) engine connection properties. + +On top of the configuration parameters documented below, this endpoint +returns the following parameters: + + - `external_service_last_updated` - An RFC 3339 timestamp indicating when the + configuration was last modified. + + - `external_service_validated` - Indicates whether a successful connection to + the external policy engine has been made under this configuration. + + - `last_successful_request` - Timestamp of the last successful request to + the external policy engine. + +Note that the last two parameters are node-specific and will be reset +whenever the mount reloads (e.g., leadership election or seal/unseal). + +| Method | Path | +| :----- | :---------------------------- | +| `GET` | `/pki/config/external-policy` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/config/external-policy +``` + +#### Sample Response + +``` +{ + "data": { + "enabled": false, + "external_service_last_updated": "0001-01-01T00:00:00Z", + "external_service_url": "", + "external_service_validated": false, + "last_successful_request": "", + "timeout": 15000000000, + "trusted_ca": "", + "trusted_leaf_certificate_bundle": "", + "vault_client_cert_bundle": "" + }, +} + +``` + +### Set Certificate Issuance External Policy Service (CIEPS) configuration + +This endpoint allows enabling the Certificate Issuance External Policy Service +(CIEPS) engine and configuring connection +properties. + +| Method | Path | +| :----- | :---------------------------- | +| `POST` | `/pki/config/external-policy` | + +#### Parameters + + - `enabled` `(bool: false)` - Enables or disables the external policy + service. When disabled, issuance mechanisms under `external-policy` + paths (e.g., `/pki/external-policy/sign/:policy`) will not work. + + - `external_service_url` `(string: )` - URI to the external + policy engine. Must use the `https://` scheme. + + - `timeout` `(string: "")` - This is how long any particular API request + should wait for a timeout at various layers of the stack. Defaults to + `15s`. + + - `trusted_ca` `(string: "")` - A PEM bundle of trusted CAs to verify the + certificates presented by the external policy engine against. Optional; + one of `trusted_ca` or `trusted_leaf_certificate_bundle` must be specified. + + - `trusted_leaf_certificate_bundle` `(string: "")` - A PEM bundle of pinned + non-CA leaf certificates that must be presented by the external policy + engine. Optional; one of `trusted_ca` or `trusted_leaf_certificate_bundle` + must be specified. + + - `vault_client_cert_bundle` `(string: "")` - A PEM bundle of a private key + and one or more certificates to present during authentication to the + external policy service. + - `entity_jmespath` `(string: "")` - A JMESPath expression that will select and filter entity metadata to the service. By default no entity metadata beyond the entity id is sent, use "@" to send all information + + - `group_jmespath` `(string: "")` - A JMESPath expression that will select and filter entity group metadata to the service. By default no group entity metadata is sent, use "@" to send all information +#### Sample payload + +```json +{ + "enabled": true, + "external_service_url": "https://cieps.dadgarcorp.internal", + "trusted_ca": "-----BEGIN CERTIFICATE-----...." +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/config/external-policy +``` + +### Read URLs + +This endpoint fetches the URLs to be encoded in generated certificates. No URL +configuration will be returned until the configuration is set. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/pki/config/urls` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/config/urls +``` + +#### Sample response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "issuing_certificates": ["", ""], + "crl_distribution_points": ["", ""], + "delta_crl_distribution_points": ["", ""] + "ocsp_servers": ["", ""] + }, + "auth": null +} +``` + +### Set URLs + +This endpoint allows setting the issuing certificate endpoints, CRL distribution +points, and OCSP server endpoints that will be encoded into issued certificates. +You can update any of the values at any time without affecting the other +existing values. To remove the values, simply use a blank string as the +parameter. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/pki/config/urls` | + +~> **Note**: When using multiple issuers within the same mount, it is strongly + suggested to use the per-issuer AIA information instead of the global + AIA information. If any of the per-issuer AIA fields are set, the entire + issuer's preferences will be used instead. Otherwise, these fields are used + as a fallback.

+ This can be achieved by using _templated_ global AIA values, but setting + the cluster-local address in configuration. When used, this value **must** + be set on all performance replication clusters, otherwise issuance will + fail! + +#### Parameters + +- `issuing_certificates` `(array: nil)` - Specifies the URL values for + the Issuing Certificate field. This can be an array or a comma-separated + string list. See also [RFC 5280 Section 4.2.2.1](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) + for information about the Authority Information Access field. + +- `crl_distribution_points` `(array: nil)` - Specifies the URL values + for the CRL Distribution Points field. This can be an array or a + comma-separated string list. See also [RFC 5280 Section 4.2.1.13](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.13) + for information about the CRL Distribution Points field. + +- `delta_crl_distribution_points` `(array: nil)` - Specifies the URL + values for the Delta CRL Distribution Points field. This can be an array or a comma- + separated string list. See also [RFC5280 Section 4.2.1.15](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.1.15) + for information about the Delta CRL Distribution Points field. + +~> Note: When multiple Performance Replication clusters are enabled, each + cluster will have its own CRL. Additionally, when multiple issuers are + in use under a single mount, each issuer will also have its own CRL + distribution point. These separate CRLs should either be aggregated into a + single CRL (externally; as Vault does not support this functionality) + or multiple `crl_distribution_points` and `delta_crl_distribution_points` + should be specified here, pointing to each cluster and issuer. + +- `ocsp_servers` `(array: nil)` - Specifies the URL values for the OCSP + Servers field. This can be an array or a comma-separated string list. See also + [RFC 5280 Section 4.2.2.1](https://datatracker.ietf.org/doc/html/rfc5280#section-4.2.2.1) + for information about the Authority Information Access field. + +- `enable_templating` `(bool: false)` - Specifies that the above AIA + URL values (`issuing_certificates`, `crl_distribution_points`, + `delta_crl_distribution_points`, and `ocsp_servers`) should be templated. + This replaces the literal value `{{issuer_id}}` with the ID of the issuer + doing the issuance, the literal value `{{cluster_path}}` with the value + of `path` from the cluster-local configuration endpoint `/config/cluster`, + and the literal value `{{cluster_aia_path}}` with the value of `aia_path` + from the cluster-local configuration endpoint `/config/cluster`. + + For example, the following values can be used globally to ensure all AIA + URIs use the cluster-local, per-issuer canonical reference, but with + the issuing CA certificate and CRL distribution points to potentially + use an external, non-Vault CDN. + + - `issuing_certificates={{cluster_aia_path}}/issuer/{{issuer_id}}/der` + - `crl_distribution_points={{cluster_aia_path}}/issuer/{{issuer_id}}/crl/der` + - `delta_crl_distribution_points={{cluster_aia_path}/issuer/{{issuer_id}}/crl/delta/der` + - `ocsp_servers={{cluster_aia_path}}/ocsp` + +~> **Note**: If no cluster-local address is present and templating is used, + issuance will fail. + +#### Sample payload + +```json +{ + "issuing_certificates": ["{{cluster_aia_path}}/issuer/{{issuer_id}}/der"], + "crl_distribution_points": ["{{cluster_aia_path}}/issuer/{{issuer_id}}/crl/der"], + "delta_crl_distribution_points": ["{{cluster_aia_path}}/issuer/{{issuer_id}}/crl/delta/der"] + "ocsp_servers": ["{{cluster_aia_path}}/ocsp"] +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/config/urls +``` + +### Read issuers configuration + +This endpoint allows getting the value of the default issuer. + +| Method | Path | +| :----- | :-------------------- | +| `GET` | `/pki/config/issuers` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/config/issuers +``` + +#### Sample response + +```json +{ + "data": { + "default": "3dc79a5a-7a6c-70e2-1123-94b88557ba12", + "default_follows_latest_issuer": "false" + } +} +``` + +### Set issuers configuration + +This endpoint allows setting the value of the default issuer. + +| Method | Path | +| :----- | :-------------------- | +| `POST` | `/pki/config/issuers` | +| `POST` | `/pki/root/replace` | + +#### Parameters + +- `default` `(string: "")` - Specifies the default issuer (by reference; + either a name or an ID). When no value is specified and the path is + `/pki/root/replace`, the default value of `"next"` will be used. + +- `default_follows_latest_issuer` `(bool: false)` - Specifies whether a + root creation or an issuer import operation updates the default issuer + to the newly added issuer. + + While the new multi-issuer functionality of 1.11 was backwards compatible + on a per-API basis, some applications relied explicitly on unsafe behavior + across multiple APIs that we addressed. For instance, calling + `/intermediate/generate/:type` would silently remove any (potentially + in-use!) key material and generate new private keys. While our response to + this endpoint is backwards compatible (returning a new key and safely + preserving old keys), some applications implicitly relied on this behavior. + This new option is meant to provide compatibility across API calls to these + callers: the newly created issuer (once _imported_ -- not on intermediate + generation) will become the default and it will look (to anyone strictly + using old APIs) that it is the only issuer in the mount. However, it is + encouraged for applications to update to the newer, safer semantics + associated with [multi-issuer rotation](/vault/docs/secrets/pki/rotation-primitives). + +~> Note: When an import creates more than one new issuer with key material + known to this mount, no default update will occur. + +#### Sample payload + +```json +{ + "default": "root-x1" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/config/issuers +``` + +#### Sample response + +```json +{ + "data": { + "default": "3dc79a5a-7a6c-70e2-1123-94b88557ba12" + } +} +``` + +### Read keys configuration + +This endpoint allows getting the value of the default key. + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/pki/config/keys` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/config/keys +``` + +#### Sample response + +```json +{ + "data": { + "default": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf" + } +} +``` + +### Set keys configuration + +This endpoint allows setting the value of the default key. + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/pki/config/keys` | + +#### Parameters + +- `default` `(string: "")` - Specifies the default key (by reference; + either a name or an ID). + +#### Sample payload + +```json +{ + "default": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/config/keys +``` + +#### Sample response + +```json +{ + "data": { + "default": "baadd98d-ec5a-66ac-06b7-dfc91c02c9cf" + } +} +``` + +### Read cluster configuration + +This endpoint fetches the cluster-local configuration. + +The cluster-local config has `path`, which sets the URL to this mount on +a particular performance replication cluster. This is useful for populating +`{{cluster_path}}` during AIA URL templating, but may be used for other +values in the future. + +It also has `aia_path`, which allows using a non-Vault, external responder, +setting the `{{cluster_aia_path}}` value for AIA URL templating. This is +useful for distributing CA and CRL information over an unsecured, non-TLS +channel. + +| Method | Path | +| :----- | :-------------------- | +| `GET` | `/pki/config/cluster` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/config/cluster +``` + +#### Sample response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "path": "", + "aia_path": "" + }, + "auth": null +} +``` + +### Set cluster configuration + +This endpoint sets cluster-local configuration. + +The cluster-local config has `path`, which sets the URL to this mount on +a particular performance replication cluster. This is useful for populating +`{{cluster_path}}` during AIA URL templating, but may be used for other +values in the future. + +It also has `aia_path`, which allows using a non-Vault, external responder, +setting the `{{cluster_aia_path}}` value for AIA URL templating. This is +useful for distributing CA and CRL information over an unsecured, non-TLS +channel. + +| Method | Path | +| :----- | :-------------------- | +| `POST` | `/pki/config/cluster` | + +#### Parameters + +- `path` `(string: "")` - Specifies the path to this performance replication + cluster's API mount path, including any namespaces as path components. + For example, `https://pr-a.vault.example.com/v1/ns1/pki-root`. + +- `aia_path` `(string: "")` - Specifies the path to this performance replication + cluster's AIA distribution point; may refer to an external, non-Vault responder. + This is for resolving AIA URLs and providing the `{{cluster_aia_path}}` template + parameter and will not be used for other purposes. As such, unlike `path` above, + this could safely be an insecure transit mechanism (like HTTP without TLS). + +#### Sample payload + +```json +{ + "path": "https://...", + "aia_path": "http://..." +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/config/cluster +``` + +### Read CRL configuration + +This endpoint allows getting the duration for which the generated CRL should be +marked valid. No CRL configuration will be returned until the configuration is +set, but the CRL will still default to enabled with 72h expiration. + +| Method | Path | +| :----- | :---------------- | +| `GET` | `/pki/config/crl` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/config/crl +``` + +#### Sample response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "disable": false, + "expiry": "72h", + "ocsp_disable": false, + "ocsp_expiry": "12h", + "auto_rebuild": false, + "auto_rebuild_grace_period": "12h", + "enable_delta": false, + "delta_rebuild_interval": "15m", + "cross_cluster_revocation": true, + "unified_crl": true, + "unified_crl_on_existing_paths": true, + "max_crl_entries": 100000 + }, + "auth": null +} +``` + + + +### Set revocation configuration + +This endpoint allows setting the duration for which the generated CRL should be +marked valid. If the CRL is disabled, it will return a signed but zero-length +CRL for any request. If enabled, it will re-build the CRL. + +If the `ocsp_disable` key is set to `true`, the OCSP responder will always +respond with an Unauthorized OCSP response to any request. + +~> **Note**: This parameter is global, across all clusters and issuers. Use + the per-issuer `usage` field to disable CRL building for a specific + issuer, while leaving the global CRL building enabled. + +~> Note: Disabling the CRL does not affect whether revoked certificates are +stored internally. Certificates that have been revoked when a role's +certificate storage is enabled will continue to be marked and stored as +revoked until `tidy` has been run with the desired safety buffer. Re-enabling +CRL generation will then result in all such certificates becoming a part of +the CRL. + +~> Note: Enabling automatic rebuilding of CRLs disables immediate regeneration + on revocation. This is in line with the behavior of other CAs which only + rebuild CRLs periodically. We suggest manually hitting the rotate if a + fresh CRL is necessary after a revocation. For the most part though, CRLs + should not be relied upon for the latest certificate status information, + and OCSP should be used instead. + +~> Note: The periodic function which controls automatic rebuilding of CRLs + and delta CRLs only executes once a minute; this prevents high system load + but limits the granularity of the temporal options below. + +~> Note: The `unified_crl`, `unified_crl_on_existing_paths`, and + `cross_cluster_revocation` parameters are all Vault Enterprise only + functionality. While they appear in the responses on Vault Community Edition, they cannot + be enabled. + +| Method | Path | +| :----- | :---------------- | +| `POST` | `/pki/config/crl` | + +#### Parameters + +- `expiry` `(string: "72h")` - The amount of time the generated CRL should be valid. + +- `disable` `(bool: false)` - Disables or enables CRL building. + +- `ocsp_disable` `(bool: false)` - Disables or enables the OCSP responder in Vault. + +- `ocsp_expiry` `(string: "12h")` - The amount of time an OCSP response can be cached for, + (controls the NextUpdate field), useful for OCSP stapling refresh durations. If set to 0 + the NextUpdate field is not set, indicating newer revocation information is available + all the time. + +- `auto_rebuild` `(bool: false)` - Enables or disables periodic rebuilding of + the CRL upon expiry. + +- `auto_rebuild_grace_period` `(string: "12h")` - Grace period before CRL expiry + to attempt rebuild of CRL. Must be shorter than the CRL expiry period. + +- `enable_delta` `(bool: false)` - Enables or disables building of delta CRLs + with up-to-date revocation information, augmenting the last complete CRL. + This option requires `auto_rebuild` to also be enabled. + +- `delta_rebuild_interval` `(string: "15m")` - Interval to check for new + revocations on, to regenerate the delta CRL. Must be shorter than CRL + expiry. + +- `cross_cluster_revocation` `(bool: false)` - + Enables cross-cluster revocation + request queues. When a serial not issued on this local cluster is presented + to Vault via the [`/revoke` API](#revoke-certificate), it is replicated + across clusters and the cluster which issued that certificate will revoke + it if it is online. + +~> Note: API calls to revoke a certificate with Bring Your Own Certificate + (BYOC) will always trigger a local revocation of that certificate. No + cross-cluster revocation request will be created.

+ API calls to revoke a certificate with Proof of Possession (PoP) cannot + be satisfied if the certificate is not available locally and will + not result in a cross-cluster revocation request. + +- `unified_crl` `(bool: false)` - + Enables unified CRL and OCSP building. This + synchronizes all revocations between clusters; a single, unified CRL will be + built on the active node of the primary performance replication (PR) + cluster. Any node in any PR cluster will be able to serve this unified CRL + and respond to unified OCSP inquiries. + +~> Note: This option ensures existing, non-expired revocations are + consistently reported. If a certificate was issued and stored on one + cluster, but revoked via BYOC on another, this option will inform the + issuing cluster of the revocation. + +- `unified_crl_on_existing_paths` `(bool: false)` - + Enables serving the + unified CRL and OCSP on the existing, previously cluster-local paths + (e.g., `/pki/crl` will now contain the unified CRL when enabled). This + allows transitioning AIA-based consumption of CRLs to a unified view + without having to re-issue certificates or update scripts pulling + a single CRL. + +- `max_crl_entries` `(int: 100000)` - + The maximum number of entries a CRL can contain. This option exists to + prevent accidental runaway issuance/revocation from overloading Vault. + If set to -1, the limit is disabled. + +#### Sample payload + +```json +{ + "expiry": "48h", + "disable": "false", + "ocsp_disable": "false", + "ocsp_expiry": "12h", + "auto_rebuild": "true", + "auto_rebuild_grace_period": "8h", + "enable_delta": "true", + "delta_rebuild_interval": "10m", + "cross_cluster_revocation": true, + "unified_crl": true, + "unified_crl_on_existing_paths": true, + "max_crl_entries": 100000 +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/config/crl +``` + +### Rotate CRLs + +This endpoint forces a rotation of all issuers' CRLs. This can be used by +administrators to cut the size of the CRL if it contains a number of +certificates that have now expired, but has not been rotated due to no further +certificates being revoked. If no certificates have been revoked, but the CRL +has expired or is close to expiring, administrators **must** hit this endpoint +to manually rotate the CRL. This rotates all CRLs on the present cluster, +and **must** be called on every cluster. + +~> **Note**: Mirroring the behavior of earlier Vault versions, we add + certificates revoked by an unknown issuer to the default issuer's CRL. + To fully purge old revoked, unexpired certificates, it is not sufficient + to delete their issuer and is instead necessary to **remove** the mount + completely. + +~> **Note**: As of Vault 1.12, it is suggested to switch to enabling the CRL's + `auto_rebuild` functionality to avoid having to manually hit the Rotate + endpoint when the CRL expires. This ensures a valid CRL is always + maintained, at the expense of potentially not being up-to-date. If a + revocation occurs that must be immediately propagated, this endpoint can + be used to regenerate the CRL, though distribution must still occur outside + of Vault (either manually or via AIA where supported). + +| Method | Path | +| :----- | :---------------- | +| `GET` | `/pki/crl/rotate` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/crl/rotate +``` + +#### Sample response + +```json +{ + "data": { + "success": true + } +} +``` + +### Rotate delta CRLs + +This endpoint forces a rotation of all issuers' delta CRLs, when enabled. +This can be used by administrators to force a rebuild of a delta CRL if +high-profile revocations have occurred and there's a long high interval +between delta rebuilds (`delta_rebuild_interval`). + +See notes about rotating regular CRLs above as they apply here as well. + +| Method | Path | +| :----- | :---------------------- | +| `GET` | `/pki/crl/rotate-delta` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/crl/rotate +``` + +#### Sample response + +```json +{ + "data": { + "success": true + } +} +``` + +### Combine CRLs from the same issuer + +This endpoint allows combining multiple different CRLs that have been signed by the +same issuer into a single signed CRL. This is useful to generate a single authoritative +CRL of revocations across distinct Vault clusters such as primary and performance replica +clusters. + + +| Method | Path | +|:-------|:--------------------------------------| +| `POST` | `/pki/issuer/:issuer_ref/resign-crls` | + + +#### Parameters + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. +- `crls` `(list of strings: )` - A list of PEM encoded CRLs that have been + signed by the issuer +- `crl_number` `(int: )` - The sequence number to be written within the CRL + Number extension. +- `delta_crl_base_number` `(int: -1)` - Using a value of 0 or greater specifies the base CRL revision + number to encode within a Delta CRL indicator extension, otherwise the extension will + not be added; defaults to -1. +- `format` `(string: pem)` - The format of the combined CRL, can be "pem" or "der". + If "der", the value will be base64 encoded; Defaults to "pem". +- `next_update` `(string: 72h)` - The amount of time the generated CRL should be + valid; defaults to 72 hours. + +#### Sample payload + +```json +{ + "crl_number": "10", + "next_update": "24h", + "crls": ["", ""], + "format": "pem" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + -request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/issuer/default/resign-crls +``` + +#### Sample response + +```json +{ + "data": { + "crl": "" + } +} +``` + +### Sign revocation list + +This endpoint allows generating a CRL based on the provided parameter data from any external +source and signed by the specified issuer. Values are taken verbatim from the parameters provided. + +**This is a potentially dangerous endpoint and only highly trusted users should have access.** + +| Method | Path | +|:-------|:-----------------------------------------------| +| `POST` | `/pki/issuer/:issuer_ref/sign-revocation-list` | + + +#### Parameters + +- `issuer_ref` `(string: )` - Reference to an existing issuer, + either by Vault-generated identifier, the literal string `default` to + refer to the currently configured default issuer, or the name assigned + to an issuer. This parameter is part of the request URL. +- `crl_number` `(int: )` - The sequence number to be written within the CRL + Number extension. +- `delta_crl_base_number` `(int: -1)` - Using a value of 0 or greater specifies the base CRL revision + number to encode within a Delta CRL indicator extension, otherwise the extension will + not be added; defaults to -1. +- `format` `(string: pem)` - The format of the combined CRL, can be "pem" or "der". + If "der", the value will be base64 encoded; Defaults to "pem". +- `next_update` `(string: 72h)` - The amount of time the generated CRL should be + valid; defaults to 72 hours. +- `revoked_certs` `(type: slice of maps)` - Each element contains revocation information for a + single serial number along with the revocation time and the serial's extensions if any. Each + element can have the following key/values + - `serial_number` `(type: string)` - the serial number of the revoked cert + - `revocation_time` `(type: string)` - the revocation time, unix int format or RFC3339 encoding supported + - `extensions` `(type: slice of maps)` - A slice of all extensions that should be added to the revoked + certificate entry. Each ele,ent contains a map with the following entries + - `id` `(type: string)` - an ASN1 object identifier in dot notation + - `critical` `(type: bool)` - should the extension be marked critical + - `value` `(type: string)` - base64 encoded bytes for extension value +- `extensions` `(type: slice of maps)` - A slice of all extensions that should be added to the generated + CRL each element containing a map with the following entries. + - `id` `(type: string)` - an ASN1 object identifier in dot notation + - `critical` `(type: bool)` - should the extension be marked critical + - `value` `(type: string)` - base64 encoded bytes for extension value + +~> **Note**:: The following extension ids are not allowed to be provided and can be influenced by other parameters + - `2.5.29.20`: CRL Number + - `2.5.29.27`: Delta CRL + - `2.5.29.35`: Authority Key Identifier + +#### Sample payload + +```json +{ + "crl_number": "10", + "next_update": "24h", + "format": "pem", + "revoked_certs": [ + { + "serial_number": "39:dd:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58", + "revocation_time": "2009-11-10T23:00:00Z" + }, + { + "serial_number": "40:33:2e:90:b7:23:1f:8d:d3:7d:31:c5:1b:da:84:d0:5b:65:31:58", + "revocation_time": "1257894000" + } + ] +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + -request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/issuer/default/sign-revocation-list +``` + +#### Sample response + +```json +{ + "data": { + "crl": "" + } +} +``` + +### Tidy + +This endpoint allows tidying up the storage backend and/or CRL by removing +certificates that have expired and are past a certain buffer period beyond their +expiration time. + +| Method | Path | +| :----- | :---------- | +| `POST` | `/pki/tidy` | + +~> Note: it is encouraged to use the [automatic tidy capabilities](#configure-automatic-tidy) + to ensure this gets run periodically. + +#### Parameters + +- `tidy_cert_store` `(bool: false)` - Specifies whether to tidy up the certificate + store. + +- `tidy_revoked_certs` `(bool: false)` - Set to true to remove all invalid and + expired certificates from storage. A revoked storage entry is considered + invalid if the entry is empty, or the value within the entry is empty. If a + certificate is removed due to expiry, the entry will also be removed from the + CRL, and the CRL will be rotated. + +- `tidy_revoked_cert_issuer_associations` `(bool: false)` - Set to true to associate + revoked certificates with their corresponding issuers; this improves the + performance of OCSP and CRL building, by shifting work to a tidy operation + instead. + +~> Note: With multiple issuers, a CA which issued a particular revoked + certificate may be removed and re-added, resulting in a different issuer + ID value. When building CRLs, these links are automatically updated for any + missing or added issuers, but during OCSP this value is computed and then + discarded, potentially causing a performance penalty on each request. + During regular CA operations, it is not necessary to run this operation. +

+ It is suggested to run this tidy when removing or importing new issuers and + on the first upgrade to a post-1.11 Vault version, but otherwise not to run + it during automatic tidy operations. + +- `tidy_expired_issuers` `(bool: false)` - Set to true to automatically remove + expired issuers after the `issuer_safety_buffer` duration has elapsed. We + log the issuer certificate on removal to allow recovery; no keys are removed + during this process. + +~> Note: The default issuer will not be removed even if it has expired and is + past the `issuer_safety_buffer` specified. + +- `tidy_move_legacy_ca_bundle` `(bool: false)` - Set to true to backup any + legacy CA/issuers bundle (from Vault versions earlier than 1.11) to + `config/ca_bundle.bak`. This can be restored with `sys/raw` back to + `config/ca_bundle` if necessary, but won't impact mount startup (as + mounts will attempt to read the latter and do a migration of CA issuers + if present). Migration will only occur after `issuer_safety_buffer` has + passed since the last successful migration. + +- `tidy_revocation_queue` `(bool: false)` - Set to true to remove stale + revocation request entries that haven't been confirmed by any active + node of a performance replication (PR) cluster. Only runs on the active + node of the primary cluster. + +~> Note: this tidy is only applicable on Vault Enterprise. + +- `tidy_cross_cluster_revoked_certs` `(bool: false)` - Set to true to remove + expired, cross-cluster revocation entries. This is the cross-cluster + equivalent of `tidy_revoked_certs`. Only runs on the active node of the + primary cluster. + +~> Note: this tidy is only applicable on Vault Enterprise. + +- `safety_buffer` `(string: "")` - Specifies a duration using [duration format strings](/vault/docs/concepts/duration-format) + used as a safety buffer to ensure certificates are not expunged prematurely; as an example, this can keep + certificates from being removed from the CRL that, due to clock skew, might + still be considered valid on other hosts. For a certificate to be expunged, + the time must be after the expiration time of the certificate (according to + the local clock) plus the duration of `safety_buffer`. Defaults to `72h`. + +- `issuer_safety_buffer` `(string: "")` - Specifies a duration that issuers + should be kept for, past their `NotAfter` validity period. Defaults to + 365 days as hours (`8760h`). + +- `pause_duration` `(string: "0s")` - Specifies the duration to pause + between tidying individual certificates. This releases the revocation + lock and allows other operations to continue while tidy is paused. + This allows an operator to control tidy's resource utilization within + a timespan: the LIST operation will remain in memory, but the space + between reading, parsing, and updates on-disk cert entries will be + increased, decreasing resource utilization. + + Does not affect `tidy_expired_issuers`. + +~> Note: Using too long of a `pause_duration` can result in tidy operations + not concluding during this lifetime! Using too short of a pause duration + (but non-zero) can lead to lock contention. Use [tidy's cancellation](#cancel-tidy) + to stop a running operation after the sleep period is over. + +- `revocation_queue_safety_buffer` `(string: "")` - Specifies a duration + after which cross-cluster revocation requests will be removed as expired. + This should be set high enough that, if a cluster disappears for a while + but later comes back, any revocation requests which it should process will + still be there, but not too long as to fill up storage with too many invalid + requests. Defaults to `48h`. + + - `tidy_acme` `(bool: false)` - Set to true to tidy stale ACME accounts, + orders, authorizations, EABs, and challenges. ACME orders are tidied (deleted) + `safety_buffer` after the certificate associated with them expires, or after + the order and relevant authorizations have expired if no certificate was + produced. Authorizations are tidied with the corresponding order. + + When a valid ACME Account is at least `acme_account_safety_buffer` + old, and has no remaining orders associated with it, the account is + marked as revoked. After another `acme_account_safety_buffer` has + passed from the revocation or deactivation date, a revoked or + deactivated ACME account is deleted. + + - `acme_account_safety_buffer` `(string: "720h")` - The amount of time that + must pass after creation that an account with no orders is marked revoked, + and the amount of time after being marked revoked or deactivated. The + default is 30 days as hours. + + - `tidy_cert_metadata` `(bool: false)` - Specifies whether to tidy metadata + for expired certificates. + + - `tidy_cmpv2_nonce_store` `(bool: false)` - Specifies whether to tidy expired +nonces in the CMPv2 nonce store. + +#### Sample payload + +```json +{ + "safety_buffer": "24h" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/tidy +``` + +### Read automatic tidy configuration + +This endpoint fetches the current automatic tidy configuration. + +This is the combination of the periodic invocation parameters described +[in the below write handler](#set-automatic-tidy-configuration) and +the tidy parameters [described above in the tidy endpoint](#tidy). + +| Method | Path | +| :----- | :---------------------- | +| `GET` | `/pki/config/auto-tidy` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/config/auto-tidy +``` + +#### Sample response + +```json +{ + "lease_id": "", + "renewable": false, + "lease_duration": 0, + "data": { + "enabled": false, + "interval_duration": 43200, + "issuer_safety_buffer": 31536000, + "maintain_stored_certificate_counts": false, + "max_startup_backoff_duration": 1200, + "min_startup_backoff_duration": 900, + "pause_duration": "0s", + "publish_stored_certificate_count_metrics": false, + "revocation_queue_safety_buffer": 172800, + "safety_buffer": 259200, + "tidy_cert_store": false, + "tidy_cross_cluster_revoked_certs": false, + "tidy_expired_issuers": false, + "tidy_move_legacy_ca_bundle": false, + "tidy_revocation_queue": false, + "tidy_revoked_cert_issuer_associations": false, + "tidy_revoked_certs": false, + "tidy_cert_metadata": false, + "tidy_cmpv2_nonce_store": false + }, + "auth": null +} +``` + + + +### Set automatic tidy configuration + +This endpoint allows configuring periodic tidy operations, using the tidy mechanism +described above. Status is from automatically run tidies are still reported at the +status endpoint described below. + +| Method | Path | +| :----- | :---------------------- | +| `POST` | `/pki/config/auto-tidy` | + +#### Parameters + +The below parameters are in addition to the regular parameters accepted by the +[`/pki/tidy` endpoint](#tidy) documented above. + +- `enabled` `(bool: false)` - Specifies whether automatic tidy is enabled or not. + +- `interval_duration` `(string: "")` - Specifies the duration between automatic tidy + operations; note that this is from the end of one operation to the start of + the next so the time of the operation itself does not need to be considered. + Defaults to 12h + +- `maintain_stored_certificate_counts` `(bool: false)` - When enabled, + maintains expensive counts of certificates. During initialization of the + mount, a LIST of all certificates is performed to get a baseline figure and + throughout operations like issuance, revocation, and subsequent tidies, the + figure is updated. + +~> *Note*: It is strongly recommend to not enable this value if 50k or more + certificates are stored in the mount or if many PKI mounts are in use in + this cluster. Instead, use audit logs and aggregate this data externally + to Vault so as not to impact Vault performance. + +- `min_startup_backoff_duration` `(string: "5m")` - The minimum amount of time auto-tidy + will be delayed after startup. Defaults to 5 minutes. + +- `max_startup_backoff_duration` `(string: "15m")` - The maximum amount of time auto-tidy + will be delayed after startup. Defaults to 15 minutes. + +- `publish_stored_certificate_count_metrics` `(bool: false)` - When enabled, + publishes the value computed by `maintain_stored_certificate_counts` to + the mount's metrics. This requires the former to be enabled. + +#### Sample payload + +```json +{ + "enabled": true, + "tidy_revoked_cert_issuer_associations": true, + "safety_buffer": "24h" +} +``` + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/config/auto-tidy +``` + +### Tidy status + +This is a read only endpoint that returns information about the current tidy +operation, or the most recent if none are currently running. + +The result includes the following fields: + +* `safety_buffer`: the value of this parameter when initiating the tidy operation +* `tidy_cert_store`: the value of this parameter when initiating the tidy operation +* `tidy_revoked_certs`: the value of this parameter when initiating the tidy operation +* `state`: one of *Inactive*, *Running*, *Finished*, *Error*, *Cancelling*, or *Cancelled* +* `error`: the error message, if the operation ran into an error +* `time_started`: the time the operation started +* `time_finished`: the time the operation finished +* `message`: One of *Tidying certificate store: checking entry N of TOTAL* or + *Tidying revoked certificates: checking certificate N of TOTAL* +* `cert_store_deleted_count`: The number of certificate storage entries deleted +* `revoked_cert_deleted_count`: The number of revoked certificate entries deleted +* `missing_issuer_cert_count`: The number of revoked certificates which were missing a valid issuer reference +* `tidy_expired_issuers`: the value of this parameter when initiating the tidy operation +* `issuer_safety_buffer`: the value of this parameter when initiating the tidy operation +* `tidy_move_legacy_ca_bundle`: the value of this parameter when initiating the tidy operation +* `tidy_revocation_queue`: the value of this parameter when initiating the tidy operation +* `revocation_queue_deleted_count`: the number of revocation queue entries deleted +* `tidy_cross_cluster_revoked_certs`: the value of this parameter when initiating the tidy operation +* `cross_revoked_cert_deleted_count`: the number of cross-cluster revoked certificate entries deleted +* `revocation_queue_safety_buffer`: the value of this parameter when initiating the tidy operation +* `pause_duration`: the value of this parameter when initiating the tidy operation +* `last_auto_tidy_finished`: the time when the last auto-tidy operation finished; may be different than `time_finished` especially if the last operation was a manually executed tidy operation. Set to current time at mount startup if no previous value was persisted. +* `tidy_cert_metadata`: the value of this parameter when initiating the tidy operation +* `cert_metadata_deleted_count`: the number of metadata entries deleted +* `cmpv2_nonce_deleted_count`: the number of CMPv2 nonces deleted + + +| Method | Path | +| :----- | :----------------- | +| `GET` | `/pki/tidy-status` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request GET \ + http://127.0.0.1:8200/v1/pki/tidy-status + +``` + +#### Sample response + +```json + "data": { + "safety_buffer": 60, + "tidy_cert_store": true, + "tidy_revoked_certs": true, + "error": null, + "message": "Tidying certificate store: checking entry 234 of 488", + "revoked_cert_deleted_count": 0, + "cert_store_deleted_count": 2, + "state": "Running", + "time_started": "2021-10-20T14:52:13.510161-04:00", + "time_finished": null + }, +``` + +### Cancel tidy + +This endpoint allows cancelling a running tidy operation. It takes no +parameter and cancels the tidy at the next available checkpoint, which +may process additional certificates between when the operation was +marked as cancelled and when the operation stopped. + +The response to this endpoint is the same as the [status](#tidy-status). + +| Method | Path | +| :----- | :----------------- | +| `POST` | `/pki/tidy-cancel` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/pki/tidy-cancel + +``` + +#### Sample response + +```json + "data": { + "safety_buffer": 60, + "tidy_cert_store": true, + "tidy_revoked_certs": true, + "error": null, + "message": "Tidying certificate store: checking entry 234 of 488", + "revoked_cert_deleted_count": 0, + "cert_store_deleted_count": 2, + "state": "Cancelling", + "time_started": "2021-10-20T14:52:13.510161-04:00", + "time_finished": null + }, +``` +--- + +## Cluster scalability + +See [PKI Cluster Scalability](/vault/docs/secrets/pki/considerations#cluster-scalability) in the considerations page. + +## Managed keys + +~> Note: Managed keys are an Enterprise only feature. + +The [Generate Root](#generate-root) and [Generate Intermediate](#generate-intermediate) +API calls can leverage the Managed Keys feature, delegating operations that +require private key material to an external system. + +To leverage a Managed Key, assuming it has already been configured, set the type +parameter to `kms` within either, [Generate Root](#generate-root) or +[Generate Intermediate](#generate-intermediate) APIs, and one of either +`managed_key_name` or `managed_key_id` parameters specifying a Managed Key to use. +As with the `internal` type for those APIs, if the type parameter is set to `kms`, +there is no way to read/fetch the private key. + +The API call will fail if the specified Managed Key is not properly configured or +arguments detailing private key attributes are specified such as `key_type` or +`key_bits`. + +Once either of the certificate APIs have successfully executed, all other PKI +operations behave the same, with no other special configuration or parameters required. + + +## Vault CLI with DER/PEM responses + +The Vault CLI can only display JSON responses. For APIs that return non-JSON formatted +data such as DER and PEM formats, `vault read` will fail without the `-format=raw` +option added in Vault 1.13 or another client such as `curl` must be used. diff --git a/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/issuance.mdx b/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/issuance.mdx new file mode 100644 index 0000000000..61ff1f1e9c --- /dev/null +++ b/content/vault/v1.21.x (rc)/content/api-docs/secret/pki/issuance.mdx @@ -0,0 +1,1021 @@ +--- +layout: api +page_title: PKI - Secrets Engines - Issuance Protocols +description: This is the API documentation for the issuance protocol support in Vault PKI. +--- + +# Standard Issuance Protocols (API) + +- [ACME Certificate Issuance](#acme-certificate-issuance) + - [ACME Directories](#acme-directories) + - [Get ACME EAB Binding Token](#get-acme-eab-binding-token) + - [List Unused ACME EAB Binding Tokens](#list-unused-acme-eab-binding-tokens) + - [Delete Unused ACME EAB Binding Tokens](#delete-unused-acme-eab-binding-tokens) + - [Get ACME Configuration](#get-acme-configuration) + - [Set ACME Configuration](#set-acme-configuration) + - [List ACME Account Keys](#list-acme-account-keys) + - [Get ACME Account Info](#get-acme-account-info) + - [Update ACME Account Info](#update-acme-account-info) +- [EST - Certificate Issuance ](#est-certificate-issuance) + - [EST Protocol Paths ](#est-protocol-paths) + - [Read EST Configuration ](#read-est-configuration) + - [Set EST Configuration ](#set-est-configuration) +- [CMPv2 - Certificate Management Protocol (v2) ](#cmpv2-certificate-issuance) + - [CMPv2 Protocol Paths ](#cmpv2-protocol-paths) + - [Read CMPv2 Configuration ](#read-cmpv2-configuration) + - [Set CMPv2 Configuration ](#set-cmpv2-configuration) +- [SCEP - Simple Certificate Enrollment Protocol ](#scep-certificate-issuance) + - [SCEP Protocol Paths ](#scep-protocol-paths) + - [Read SCEP Configuration ](#read-scep-configuration) + - [Set SCEP Configuration ](#set-scep-configuration) + +## ACME certificate issuance + +Starting with Vault 1.14, Vault supports the [ACME certificate lifecycle +management protocol](https://datatracker.ietf.org/doc/html/rfc8555) for issuing +and renewing leaf server certificates. + +In order to use ACME, a [cluster path](#set-cluster-configuration) must be +set and ACME must be [enabled in its configuration](#set-acme-configuration) +with the [required headers](#acme-required-headers) enabled on the mount +tuning. + +Using ACME with a role requires `no_store=false` to be set on the role; this +allows the certificate to be stored and later fetched through the ACME +protocol. + +### ACME directories + +Vault PKI supports the following ACME directories, providing different +restrictions around usage (defaults, a specific issuer and/or a specific +role). To interact with these directories, specify the directory URL in +an ACME client. For example, with the EFF's [CertBot](https://certbot.eff.org/): + +``` +$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory ... +``` + +These endpoints are unauthenticated from a Vault authentication model, but +internally authenticated via the ACME protocol. + +| Method | Path | Default Directory Policy | Issuer | Role | +|:-------|:-------------------------------------------------------------------|:---------------------------|:----------------------|:--------------| +| `ACME` | `/pki/acme/directory` | `sign-verbatim` | `default` | Sign-Verbatim | +| `ACME` | `/pki/acme/directory` | `role:role_ref` | Specified by the role | `:role_ref` | +| `ACME` | `/pki/acme/directory` | `external-policy(:policy)` | Specified by CIEPS | CIEPS | +| `ACME` | `/pki/issuer/:issuer_ref/acme/directory` | `sign-verbatim` | `:issuer_ref` | Sign-Verbatim | +| `ACME` | `/pki/issuer/:issuer_ref/acme/directory` | `role:role_ref` | `:issuer_ref` | `:role_ref` | +| `ACME` | `/pki/roles/:role/acme/directory` | (any) | Specified by the role | `:role` | +| `ACME` | `/pki/issuer/:issuer_ref/roles/:role/acme/directory` | (any) | `:issuer_ref` | `:role` | +| `ACME` | `/pki/external-policy(/:policy)/acme/directory` | (any) | Specified by CIEPS | CIEPS | +| `ACME` | `/pki/issuer/:issuer_ref/external-policy(/:policy)/acme/directory` | (any) | Specified by CIEPS | CIEPS | + +When a role is not explicitly specified, behavior is specified by the +`default_directory_policy` in the [ACME configuration](#set-acme-configuration). +These directories can also be forbidden by setting that policy as `forbid`. If +the policy is `sign-verbatim` then _any_ identifier for which the client can +prove ownership of will be issued for. This is similar to using the +[Sign Verbatim](#sign-verbatim) endpoint, but with additional verification +that the client has proven ownership (within the ACME protocol) of the +requested certificate identifiers. When `external-policy` is specified as the +default value, the Certificate Issuance External +Policy Service (CIEPS) is used for +validating and templating the certificate instead of a role; ACME's challenge +validation is still enforced. An optional policy name can be specified by using +`external-policy:policy`. Roles are not used when CIEPS is used. + +#### ACME challenge types + +Vault supports the following ACME challenge types presently: + + - `http-01`, supporting both `dns` and `ip` identifiers. + - `dns-01`, supporting `dns` identifiers including wildcards. + - `tls-alpn-01`, supporting only non-wildcard `dns` identifiers. + +A custom DNS resolver used by the server for looking up DNS names for use +with both mechanisms can be added via the [ACME configuration](#set-acme-configuration). + +#### ACME external account bindings + +ACME External Account Binding (EAB) Policy can enforce that clients need to +have a valid external account binding to Vault. Before registering a new account, +an authenticated Vault client will need to [fetch a new EAB +token](#get-acme-eab-binding-token). This returns two values: a key identifier +and an HMAC key used by the ACME client to authenticate with EAB. For example: + +``` +$ vault write -f /pki/acme/new-eab +$ certbot certonly --server https://localhost:8200/v1/pki/acme/directory \ + --eab-kid --eab-hmac-key +``` + +With or without EAB, requests from the ACME client are not authenticated using +traditional Vault authentication, but are instead authenticated through the +ACME protocol. With EAB however, a Vault authenticated client will have to +fetch an EAB token and pass it to the ACME client for use on the initial +registration: this binds the ACME client's registration to an authenticated +Vault endpoint, but not further to the client's entity or other information. + + + +We strongly recommend enabling EAB for public-facing Vault +deployments. Use the `VAULT_DISABLE_PUBLIC_ACME` environment +variable to force-enable EAB for all ACME instances. + + + +#### ACME accounts + +ACME Accounts are created specific to a particular directory and are not +portable across Performance Secondary clusters. + +#### ACME required headers + +ACME requires the following response headers (`allowed_response_headers`) +to be specified by [mount tuning](/vault/api-docs/system/mounts#tune-mount-configuration): + + - `Replay-Nonce` + - `Link` + - `Location` + +On an existing mount, these can be specified by running the following command: + +``` +$ vault secrets tune -allowed-response-headers=Location -allowed-response-headers=Replay-Nonce \ + -allowed-response-headers=Link \ + pki/ +``` + +### Get ACME EAB binding token + +This endpoint returns a new ACME binding token. The `id` response field can +be used as the key identifier and the `key` response field be used as the +EAB HMAC key in the ACME Client. + +Each call to this endpoint will generate and return a new EAB binding token +that is linked to the specific ACME directory it resides under. EAB tokens +are not usable across different ACME directories. + +| Method | Path | +|:-------|:---------------------------------------------------| +| `POST` | `/pki/acme/new-eab` | +| `POST` | `/pki/issuer/:issuer_ref/acme/new-eab` | +| `POST` | `/pki/roles/:role/acme/new-eab` | +| `POST` | `/pki/issuer/:issuer_ref/roles/:role/acme/new-eab` | + +#### Parameters + +No parameters. + +#### Sample request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + http://127.0.0.1:8200/v1/pki/acme/new-eab +``` + +#### Sample response + +``` +{ + "data": { + "created_on": "2023-05-24T14:33:00-04:00", + "id": "bc8088d9-3816-5177-ae8e-d8393265f7dd", + "key_type": "hs", + "acme_directory": "acme/directory", + "key": "MHcCAQE... additional data elided ...", + } +} +``` + +### List unused ACME EAB binding tokens + +This endpoint returns a list of all unused ACME binding tokens; once used, +they will be removed from this list. + +| Method | Path | +|:-------|:-----------| +| `LIST` | `/pki/eab` | + +#### Sample request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/pki/eab +``` + +#### Sample response + +``` +{ + "data": { + "key_info": { + "bc8088d9-3816-5177-ae8e-d8393265f7dd": { + "created_on": "2023-05-24T14:33:00-04:00", + "key_type": "hs", + "acme_directory": "acme/directory" + } + }, + "keys": [ + "bc8088d9-3816-5177-ae8e-d8393265f7dd" + ] + } +} +``` + +### Delete unused ACME EAB binding tokens + +This endpoint allows the deletion of an unused ACME binding token. + +| Method | Path | +|:---------|:-------------------| +| `DELETE` | `/pki/eab/:key_id` | + +#### Parameters + + - `key_id` `(string: )` - The id of the EAB binding token to + delete. This is part of the request URL. + +#### Sample request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request DELETE \ + http://127.0.0.1:8200/v1/pki/eab/bc8088d9-3816-5177-ae8e-d8393265f7dd +``` + +### Get ACME configuration + +This endpoint allows reading of the current ACME server configuration used by +this mount. + +| Method | Path | +|:-------|:-------------------| +| `GET` | `/pki/config/acme` | + +#### Sample request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/config/acme +``` + +#### Sample response + +``` +{ + "data": { + "allowed_issuers": [ + "*" + ], + "allowed_roles": [ + "*" + ], + "default_directory_policy": "sign-verbatim", + "dns_resolver": "", + "eab_policy": "not-required", + "enabled": true, + "max_ttl": 776000 + }, +} +``` + +### Set ACME configuration + +This endpoint allows setting the ACME server configuration used by this +mount. + +| Method | Path | +|:-------|:-------------------| +| `POST` | `/pki/config/acme` | + +#### Parameters + + - `allowed_issuers` `(list: ["*"])` - Specifies a list issuers allowed to + issue certificates via explicit ACME paths. If an allowed role specifies + an issuer outside this list, it will be allowed. The default value `*` + allows every issuer within the mount. + + - `allow_role_ext_key_usage` `(bool: false)` - whether the ExtKeyUsage field + from a role is used, defaults to false meaning that certificate will be + signed with ServerAuth. + + - `allowed_roles` `(list: ["*"])` - Specifies a list of roles allowed to + issue certificates via explicit ACME paths. The default value `*` allows + every role within the mount to be used. If the `default_directory_policy` + specifies a role, it must be allowed under this configuration. + + - `default_directory_policy` `(string: "sign-verbatim")` - Specifies the + behavior of the default ACME directory. Can be `forbid`, `sign-verbatim` + or a role given by `role:`. If a role is used, it must be + present in `allowed_roles`. + + - `dns_resolver` `(string: "")` - An optional overriding DNS resolver to + use for challenge verification lookups. When not specified, the default + system resolver will be used. This allows domains on peered networks with + an accessible DNS resolver to be validated. + + - `eab_policy` `(string: "not-required")` - Specified policy to enforce + around [External Account Bindings (EABs)](#acme-external-account-bindings). + The allowed values are: + + - `not-required`, where EABs are not enforced but are validated if + specified. + + - `new-account-required`, where new accounts are required to have EAB + but existing accounts can still be used. + + - `always-required`, where all accounts regardless of age are required + to have EABs set. + + - `enabled` `(bool: false)` - Whether ACME is enabled on this mount. When + ACME is disabled, all requests to ACME directory URLs will return 404. + + - `max_ttl` `(string: "")` - Specifies the maximum Time To Live provided as a + string duration with time suffix. Hour is the largest suffix. If not set, + defaults to the previous hard-coded behavior of 90 days (2160 hours). + +#### Sample payload + +``` +{ + "enabled": true +} +``` + +#### Sample request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request POST \ + --data @payload.json \ + http://127.0.0.1:8200/v1/pki/config/acme +``` + +#### Sample response + +``` +{ + "data": { + "allowed_issuers": [ + "*" + ], + "allowed_roles": [ + "*" + ], + "default_directory_policy": "sign-verbatim", + "dns_resolver": "", + "eab_policy": "not-required", + "enabled": true + } +} +``` + +### List ACME account keys + +The `ListAcmeAccountKeys` endpoint returns a list of ACME account key +identifiers. + +| Method | Path | +|:-------|:-------------------------------| +| `LIST` | `/pki/acme/mgmt/account/keyid` | + +#### Sample request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + --request LIST \ + http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid +``` + +#### Sample response + +``` +{ + "data": { + "keys": [ + "2ea9859a-eba8-ff24-cd03-2a51639fc7d5" + ] + } +} +``` + +### Get ACME account info + +The `GetAcmeAccountInfo` endpoint returns account information, +including orders and certificate details, for the provided ACME account +key. + +| Method | Path | +|:-------|:---------------------------------------| +| `GET` | `/pki/acme/mgmt/account/keyid/:key_id` | + +#### Path parameters + +- `key_id` `(string: )` - ID of the target ACME account. + +#### Sample request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid/2ea9859a-eba8-ff24-cd03-2a51639fc7d5 +``` + +#### Sample response + +``` +{ + "data": { + "contacts": null, + "created_time": "2024-12-12T12:55:50-05:00", + "directory": "acme/", + "eab": { + "created_time": "2024-12-12T12:55:29-05:00", + "directory": "acme/", + "eab_id": "24c0673a-df53-0671-a628-e7b9c995485c", + "key_type": "hs" + }, + "key_id": "2ea9859a-eba8-ff24-cd03-2a51639fc7d5", + "orders": [ + { + "cert_expiry": "2024-12-13T17:55:28Z", + "cert_serial_number": "4a:6f:d0:f7:13:55:f7:c9:19:82:fc:34:69:67:77:2e:58:27:02:8b", + "identifiers": [ + "testing.dadgarcorp.com" + ], + "order_expiry": "2024-12-13T12:56:04-05:00", + "order_id": "90699994-8863-571c-26b0-46755e0db351", + "status": "valid" + } + ], + "revoked_time": "", + "status": "valid" + }, +} +``` + +### Update ACME account info + +The `UpdateAcmeAccountInfo` endpoint revokes or re-enables an ACME +account and returns the account details excluding order or certificate +details. + +| Method | Path | +|:-------|:---------------------------------------| +| `POST` | `/pki/acme/mgmt/account/keyid/:key_id` | + +#### Path parameters + +- `key_id` `(string: )` - ID of the target ACME account. + + +### Parameters + +- `status` `(string: )` - The new account status. Must be one of: + `revoked`, `valid`. + + + +Revoking an ACME account forbids further operations on the account +without revoking existing certificates. You must revoke any existing +certificates manually. + + + +#### Sample request + +``` +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/acme/mgmt/account/keyid/2ea9859a-eba8-ff24-cd03-2a51639fc7d5 +``` + +#### Sample response + +``` +{ + "data": { + "contacts": null, + "created_time": "2024-12-12T12:55:50-05:00", + "directory": "acme/", + "eab": { + "created_time": "2024-12-12T12:55:29-05:00", + "directory": "acme/", + "eab_id": "24c0673a-df53-0671-a628-e7b9c995485c", + "key_type": "hs" + }, + "key_id": "2ea9859a-eba8-ff24-cd03-2a51639fc7d5", + "revoked_time": "2024-12-12T12:59:02-05:00", + "status": "revoked" + }, +} +``` + +## EST Certificate issuance + +Within Vault Enterprise, support can be enabled for the +[EST (Enrollment over Secure Transport) protocol](https://datatracker.ietf.org/doc/html/rfc7030) +for issuing and renewing leaf certificates. + +### EST Protocol Paths + +These are the EST protocol API paths currently supported from Vault's authentication +point of view. Note that the `cacerts` endpoint is unauthenticated. + +@include 'pki-est-default-policy.mdx' + +### Read EST Configuration + +This endpoint fetches the current EST configuration. + +| Method | Path | +|:-------|:------------------| +| `GET` | `/pki/config/est` | + +#### Sample request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + http://127.0.0.1:8200/v1/pki/config/est +``` + +#### Sample response + +```json +{ + "data": { + "audit_fields": ["common_name", "alt_names", "ip_sans", "uri_sans"], + "authenticators": { + "cert": { + "accessor": "auth_cert_7fe0c1cc", + "cert_role": "est-ca" + }, + "userpass": { + "accessor": "auth_userpass_2b333949" + } + }, + "default_mount": true, + "default_path_policy": "sign-verbatim", + "enable_sentinel_parsing": true, + "enabled": true, + "label_to_path_policy": { + "test-label": "role:est-clients" + }, + "last_updated": "2024-01-31T10:45:22-05:00" + } +} +``` + +### Set EST Configuration + +This endpoint will update EST related configuration, returning the +updated values as a response along with an updated `last_updated` field. + +| Method | Path | +|:-------|:------------------| +| `POST` | `/pki/config/est` | + +#### Parameters + +- `enabled` `(bool: false)` - Specifies whether EST is enabled or not. + +- `default_mount` `(bool: false)` - Should this mount register the default .well-known/est URL path. + Only a single mount can enable this across a Vault cluster + +- `default_path_policy` `(string: "")` - Required to be set if `default_mount` is enabled. Specifies the + behavior for requests using the default EST label. Can be `sign-verbatim` or a role given by `role:`. + +- `label_to_path_policy` `(map[string]string: "")` - Configures a pairing of an EST label with the redirected + behavior for requests hitting that role. The path policy can be `sign-verbatim` or a role given by `role:`. + Labels must be unique across Vault cluster, and will register `.well-known/est/