diff --git a/website/content/api-docs/system/audit-hash.mdx b/website/content/api-docs/system/audit-hash.mdx index 6823f4f59..ee36a34c8 100644 --- a/website/content/api-docs/system/audit-hash.mdx +++ b/website/content/api-docs/system/audit-hash.mdx @@ -14,6 +14,8 @@ for a hashed value when the original value is known. ## Calculate hash +@include 'alerts/restricted-admin.mdx' + This endpoint hashes the given input data with the specified audit device's hash function and salt. This endpoint can be used to discover whether a given plaintext string (the `input` parameter) appears in the audit log in obfuscated diff --git a/website/content/api-docs/system/auth.mdx b/website/content/api-docs/system/auth.mdx index 1742b3e7a..a1721dc45 100644 --- a/website/content/api-docs/system/auth.mdx +++ b/website/content/api-docs/system/auth.mdx @@ -12,6 +12,8 @@ token which can be used for all future requests. ## List auth methods +@include 'alerts/restricted-admin.mdx' + This endpoint lists all enabled auth methods. | Method | Path | @@ -81,6 +83,8 @@ $ curl \ ## Enable auth method +@include 'alerts/restricted-admin.mdx' + This endpoint enables a new auth method. After enabling, the auth method can be accessed and configured via the auth path specified as part of the URL. This auth path will be nested under the `auth` prefix. @@ -143,13 +147,13 @@ relevant functionality is only supported in Vault Enterprise: - `local` `(bool: false)` – Specifies if the auth method is local only. Local auth methods are not replicated nor (if a secondary) removed by replication. - Local auth mounts also generate entities for tokens issued. The entity will - be replicated across clusters and the aliases generated on the local auth - mount will be local to the cluster. If the goal of marking an auth method - as `local` was to comply with GDPR guidelines, then care must be taken to not - set the data pertaining to local auth mount or local auth mount aliases in the - metadata of the associated entity. Metadata related to local auth mount aliases - can be stored as `custom_metadata` on the alias itself which will also be + Local auth mounts also generate entities for tokens issued. The entity will + be replicated across clusters and the aliases generated on the local auth + mount will be local to the cluster. If the goal of marking an auth method + as `local` was to comply with GDPR guidelines, then care must be taken to not + set the data pertaining to local auth mount or local auth mount aliases in the + metadata of the associated entity. Metadata related to local auth mount aliases + can be stored as `custom_metadata` on the alias itself which will also be retained locally to the cluster. ~> ** Warning:** Remember, policies when using replication secondaries are @@ -182,6 +186,8 @@ $ curl \ ## Read auth method configuration +@include 'alerts/restricted-admin.mdx' + This endpoints returns the configuration of the auth method at the given path. | Method | Path | @@ -231,6 +237,8 @@ $ curl \ ## Disable auth method +@include 'alerts/restricted-admin.mdx' + This endpoint disables the auth method at the given auth path. - **`sudo` required** – This endpoint requires `sudo` capability in addition to @@ -256,7 +264,9 @@ $ curl \ ## Read auth method tuning -This endpoint reads the given auth path's configuration. _This endpoint requires +@include 'alerts/restricted-admin.mdx' + +- This endpoint reads the given auth path's configuration. This endpoint requires `sudo` capability on the final path, but the same functionality can be achieved without `sudo` via `sys/mounts/auth/[auth-path]/tune`._ @@ -293,6 +303,8 @@ $ curl \ ## Tune auth method +@include 'alerts/restricted-admin.mdx' + Tune configuration parameters for a given auth path. _This endpoint requires `sudo` capability on the final path, but the same functionality can be achieved without `sudo` via `sys/mounts/auth/[auth-path]/tune`._ @@ -349,13 +361,13 @@ can be achieved without `sudo` via `sys/mounts/auth/[auth-path]/tune`._ - `user_lockout_config` `(map: nil)` – Specifies the user lockout configuration for the mount. User lockout feature was added in Vault 1.13. These are the possible values: - - `lockout_threshold` `(string: "")` - Specifies the number of failed login attempts after + - `lockout_threshold` `(string: "")` - Specifies the number of failed login attempts after which the user is locked out, specified as a string like "15". - - `lockout_duration` `(string: "")` - Specifies the duration for which an user will be locked out, + - `lockout_duration` `(string: "")` - Specifies the duration for which an user will be locked out, specified as a string duration like "5s" or "30m". - - `lockout_counter_reset` `(string: "")` - Specifies the duration after which the lockout counter is + - `lockout_counter_reset` `(string: "")` - Specifies the duration after which the lockout counter is reset with no failed login attempts, specified as a string duration like "5s" or "30m". - `lockout_disable` `(bool: false)` - Disables the user lockout feature for this mount diff --git a/website/content/api-docs/system/capabilities-self.mdx b/website/content/api-docs/system/capabilities-self.mdx index 1fb0eb7cf..20a1cc6e1 100644 --- a/website/content/api-docs/system/capabilities-self.mdx +++ b/website/content/api-docs/system/capabilities-self.mdx @@ -16,6 +16,8 @@ memberships. ## Query self capabilities +@include 'alerts/restricted-admin.mdx' + This endpoint returns the capabilities of client token on the given paths. The client token is the Vault token with which this API call is made. Multiple paths are taken in at once and the capabilities of the token for each path is diff --git a/website/content/api-docs/system/capabilities.mdx b/website/content/api-docs/system/capabilities.mdx index db06f1181..e655307c6 100644 --- a/website/content/api-docs/system/capabilities.mdx +++ b/website/content/api-docs/system/capabilities.mdx @@ -15,6 +15,8 @@ through the entity and entity's group memberships. ## Query token capabilities +@include 'alerts/restricted-admin.mdx' + This endpoint returns the list of capabilities of a given token on the given paths. Multiple paths are taken in at once and the capabilities of the token for each path is returned. For backwards compatibility, if a single path is diff --git a/website/content/api-docs/system/config-control-group.mdx b/website/content/api-docs/system/config-control-group.mdx index c7602e682..d2f3fdd72 100644 --- a/website/content/api-docs/system/config-control-group.mdx +++ b/website/content/api-docs/system/config-control-group.mdx @@ -13,6 +13,8 @@ settings. ## Read control group settings +@include 'alerts/restricted-admin.mdx' + This endpoint returns the current Control Group configuration. | Method | Path | @@ -37,6 +39,8 @@ $ curl \ ## Configure control group settings +@include 'alerts/restricted-admin.mdx' + This endpoint allows configuring control groups. | Method | Path | @@ -67,6 +71,8 @@ $ curl \ ## Delete control group settings +@include 'alerts/restricted-admin.mdx' + This endpoint removes any control group configuration. | Method | Path | diff --git a/website/content/api-docs/system/control-group.mdx b/website/content/api-docs/system/control-group.mdx index 02aa6b6c1..12dea2688 100644 --- a/website/content/api-docs/system/control-group.mdx +++ b/website/content/api-docs/system/control-group.mdx @@ -7,6 +7,7 @@ description: The '/sys/control-group' endpoint handles the Control Group workflo ## Authorize control group request @include 'alerts/enterprise-and-hcp-plus.mdx' +@include 'alerts/restricted-admin.mdx' This endpoint authorizes a control group request. @@ -48,6 +49,8 @@ $ curl \ ## Check control group request status +@include 'alerts/restricted-admin.mdx' + This endpoint checks the status of a control group request. | Method | Path | diff --git a/website/content/api-docs/system/ha-status.mdx b/website/content/api-docs/system/ha-status.mdx index 86183b325..affb1f95c 100644 --- a/website/content/api-docs/system/ha-status.mdx +++ b/website/content/api-docs/system/ha-status.mdx @@ -11,6 +11,8 @@ It lists the active node and the peers that it's heard from since it became acti ## HA status +@include 'alerts/restricted-admin.mdx' + This endpoint returns the HA status of the Vault cluster. | Method | Path | diff --git a/website/content/api-docs/system/internal-counters.mdx b/website/content/api-docs/system/internal-counters.mdx index 9d841e13a..c041376b8 100644 --- a/website/content/api-docs/system/internal-counters.mdx +++ b/website/content/api-docs/system/internal-counters.mdx @@ -13,6 +13,8 @@ The `/sys/internal/counters` endpoints are used to return data about the number ## Entities +@include 'alerts/restricted-admin.mdx' + This endpoint returns the total number of Entities. | Method | Path | @@ -51,6 +53,8 @@ $ curl \ ## Tokens +@include 'alerts/restricted-admin.mdx' + This endpoint returns the total number of Tokens. | Method | Path | @@ -89,24 +93,26 @@ $ curl \ ## Client count +@include 'alerts/restricted-admin.mdx' + This endpoint returns client activity information for a given billing period, which is represented by the `start_time` and `end_time` parameters. There are a few things to keep in mind while using this API. -- For Vault versions before 1.11, the activity information only accounts for -the activity of the latest contiguous months in the billing period. +- For Vault versions before 1.11, the activity information only accounts for +the activity of the latest contiguous months in the billing period. For example, if the billing period is from Jan 2022 to June 2022, and the activity subsystem in Vault was not capturing data for the months Jan to March, -the response will only include information for May and June. Note that if no -`start_time` and `end_time` parameters are specified, the billing period defaults -to 12 months, so the endpoint will return activity information from the end of the -previous month to the start of 12 months prior to that date. +the response will only include information for May and June. Note that if no +`start_time` and `end_time` parameters are specified, the billing period defaults +to 12 months, so the endpoint will return activity information from the end of the +previous month to the start of 12 months prior to that date. -- As of 1.11, this behavior has been modified to return all available data within +- As of 1.11, this behavior has been modified to return all available data within the specified billing period. -- As of 1.12, the `end_time` can be the current month. +- As of 1.12, the `end_time` can be the current month. - The response contains the total activity for the billing period and the attributions of the total activity against specific components in Vault. This @@ -259,10 +265,10 @@ information, it will not be added to the API response. match the query parameters due to the month granularity of data or missing months in the requested time range. -- Note that if the `end_date` specified is the current month, +- Note that if the `end_date` specified is the current month, the last element in the `months` response stanza, signifying the current month, will -not have namespace attribution for the `new_clients` stanza. Furthermore, the -`new_clients` counts returned for the current month will be an approximation. +not have namespace attribution for the `new_clients` stanza. Furthermore, the +`new_clients` counts returned for the current month will be an approximation. That is to say, the response will appear as follows. ```json @@ -270,7 +276,7 @@ That is to say, the response will appear as follows. "months":[ { "timestamp":"current_month_timestamp", - "counts":{ + "counts":{ "distinct_entities":"exact int value", "entity_clients":"exact int value", "non_entity_tokens":"exact int value", @@ -281,7 +287,7 @@ That is to say, the response will appear as follows. { "namespace_id":"root", "namespace_path":"path", - "counts":{ + "counts":{ "distinct_entities":"exact int value", "entity_clients":"exact int value", "non_entity_tokens":"exact int value", @@ -291,7 +297,7 @@ That is to say, the response will appear as follows. "mounts":[ { "path":"auth/up2/", - "counts":{ + "counts":{ "distinct_entities":"exact int value", "entity_clients":"exact int value", "non_entity_tokens":"exact int value", @@ -320,7 +326,7 @@ That is to say, the response will appear as follows. Please visit the [client count](/vault/docs/concepts/client-count) concepts page for more information on how clients map to these client IDs and how they are -counted, or for more information about how the new clients for the current month +counted, or for more information about how the new clients for the current month are estimated in a billing period. The response will include all child namespaces of the namespace in which the @@ -344,7 +350,7 @@ This endpoint was added in Vault 1.6. for which client counts will be reported. If no end time is specified, the end of the previous calendar month will be used. - `limit_namespaces` `(int, optional)` - Controls the total number of by_namespace data returned. This can - be used to return the client counts for the specified number of namespaces having highest activity. + be used to return the client counts for the specified number of namespaces having highest activity. If no `limit_namespaces` parameter is specified, client counts for all namespaces in specified usage period is returned. - `current_billing_period` `(bool, optional)` - Uses the builtin billing start timestamp as `start_time` and the current time as the `end_time`, returning a @@ -720,6 +726,8 @@ $ curl \ ## Partial month client count +@include 'alerts/restricted-admin.mdx' + This endpoint returns the client activity in the current month. The response will have activity attributions per namespace, per mount within each namespaces, and new clients information. @@ -863,6 +871,8 @@ $ curl \ ## Update the client count configuration +@include 'alerts/restricted-admin.mdx' + The `/sys/internal/counters/config` endpoint is used to configure logging of active clients. | Method | Path | @@ -901,6 +911,8 @@ $ curl \ ## Read the client count configuration +@include 'alerts/restricted-admin.mdx' + Reading the configuration shows the current settings, as well as a flag as to whether any data can be queried. - `enabled` `(string)` - returns `default-enabled` or `default-disabled` if the configuration is `default`. @@ -938,6 +950,8 @@ $ curl \ ## Activity export +@include 'alerts/restricted-admin.mdx' + This endpoint returns an export of the clients that had activity within the provided start and end times. The returned set of client information will be deduplicated over the time window and will show the earliest activity logged for diff --git a/website/content/api-docs/system/internal-specs-openapi.mdx b/website/content/api-docs/system/internal-specs-openapi.mdx index 0ffc62dce..8622612a1 100644 --- a/website/content/api-docs/system/internal-specs-openapi.mdx +++ b/website/content/api-docs/system/internal-specs-openapi.mdx @@ -25,6 +25,8 @@ structure, and other endpoints will be modified incrementally. ## Get OpenAPI document +@include 'alerts/restricted-admin.mdx' + This endpoint returns a single OpenAPI document describing all paths visible to the requester. | Method | Path | diff --git a/website/content/api-docs/system/internal-ui-feature.mdx b/website/content/api-docs/system/internal-ui-feature.mdx index 138a807e0..d201a483d 100644 --- a/website/content/api-docs/system/internal-ui-feature.mdx +++ b/website/content/api-docs/system/internal-ui-feature.mdx @@ -16,6 +16,8 @@ guarantee on backwards compatibility for this endpoint. ## Get enabled feature flags +@include 'alerts/restricted-admin.mdx' + This endpoint lists the enabled feature flags relevant to the UI. | Method | Path | diff --git a/website/content/api-docs/system/internal-ui-mounts.mdx b/website/content/api-docs/system/internal-ui-mounts.mdx index c3815a2c3..682e30301 100644 --- a/website/content/api-docs/system/internal-ui-mounts.mdx +++ b/website/content/api-docs/system/internal-ui-mounts.mdx @@ -22,6 +22,8 @@ compatibility for this endpoint. ## Get available visible mounts +@include 'alerts/restricted-admin.mdx' + This endpoint lists all enabled auth methods. | Method | Path | @@ -59,6 +61,8 @@ $ curl \ ## Get single mount details +@include 'alerts/restricted-admin.mdx' + This endpoint lists details for a specific mount path. This is an authenticated endpoint, and is currently only being used internally. diff --git a/website/content/api-docs/system/internal-ui-resultant-acl.mdx b/website/content/api-docs/system/internal-ui-resultant-acl.mdx index d2990a9ce..2aa502ed3 100644 --- a/website/content/api-docs/system/internal-ui-resultant-acl.mdx +++ b/website/content/api-docs/system/internal-ui-resultant-acl.mdx @@ -15,6 +15,8 @@ intended usage, there is no guarantee on backwards compatibility for this endpoi ## Get resultant-acl +@include 'alerts/restricted-admin.mdx' + This endpoint lists the resultant-acl relevant to the UI. | Method | Path | diff --git a/website/content/api-docs/system/leader.mdx b/website/content/api-docs/system/leader.mdx index e7717859a..a5449dcbc 100644 --- a/website/content/api-docs/system/leader.mdx +++ b/website/content/api-docs/system/leader.mdx @@ -13,6 +13,8 @@ current leader of Vault. ## Read leader status +@include 'alerts/restricted-admin.mdx' + This endpoint returns the high availability status and current leader instance of Vault. diff --git a/website/content/api-docs/system/leases.mdx b/website/content/api-docs/system/leases.mdx index a8a2f8938..e8756cfc5 100644 --- a/website/content/api-docs/system/leases.mdx +++ b/website/content/api-docs/system/leases.mdx @@ -10,6 +10,8 @@ The `/sys/leases` endpoints are used to view and manage leases in Vault. ## Read lease +@include 'alerts/restricted-admin.mdx' + This endpoint retrieve lease metadata. | Method | Path | @@ -53,6 +55,8 @@ $ curl \ ## List leases +@include 'alerts/restricted-admin.mdx' + This endpoint returns a list of lease ids. **This endpoint requires 'sudo' capability.** @@ -82,6 +86,8 @@ $ curl \ ## Renew lease +@include 'alerts/restricted-admin.mdx' + This endpoint renews a lease, requesting to extend the lease. Token leases cannot be renewed using this endpoint, use instead the auth/token/renew endpoint. @@ -91,9 +97,9 @@ cannot be renewed using this endpoint, use instead the auth/token/renew endpoint ### Parameters -- `lease_id` `(string: )` – Specifies the ID of the lease to extend. This +- `lease_id` `(string: )` – Specifies the ID of the lease to extend. This parameter can either be specified in a json request, as shown below, or provided as - a path parameter to the endpoint, like /sys/leases/revoke/:lease_id. If both are + a path parameter to the endpoint, like /sys/leases/revoke/:lease_id. If both are provided, the leaseID in the request json takes precedence. - `increment` `(int: 0)` – Specifies the requested amount of time (in seconds) @@ -130,6 +136,8 @@ $ curl \ ## Revoke lease +@include 'alerts/restricted-admin.mdx' + This endpoint revokes a lease immediately. | Method | Path | @@ -138,9 +146,9 @@ This endpoint revokes a lease immediately. ### Parameters -- `lease_id` `(string: )` – Specifies the ID of the lease to revoke. This +- `lease_id` `(string: )` – Specifies the ID of the lease to revoke. This parameter can either be specified in a json request, as shown below, or provided as - a path parameter to the endpoint, like /sys/leases/revoke/:lease_id. If both are + a path parameter to the endpoint, like /sys/leases/revoke/:lease_id. If both are provided, the leaseID in the request json takes precedence. - `sync` `(bool: false)` - Instead of the default behaviour of queueing the lease revocation, sync=true will revoke the lease immediately and only return once @@ -166,6 +174,8 @@ $ curl \ ## Revoke force +@include 'alerts/restricted-admin.mdx' + This endpoint revokes all secrets or tokens generated under a given prefix immediately. Unlike `/sys/leases/revoke-prefix`, this path ignores backend errors encountered during revocation. This is _potentially very dangerous_ and should @@ -198,6 +208,8 @@ $ curl \ ## Revoke prefix +@include 'alerts/restricted-admin.mdx' + This endpoint revokes all secrets (via a lease ID prefix) or tokens (via the tokens' path property) generated under a given prefix immediately. This requires `sudo` capability and access to it should be tightly controlled as it can be @@ -228,6 +240,8 @@ $ curl \ ## Tidy leases +@include 'alerts/restricted-admin.mdx' + This endpoint cleans up the dangling storage entries for leases: for each lease entry in storage, Vault will verify that it has an associated valid non-expired token in storage, and if not, the lease will be revoked. @@ -251,6 +265,8 @@ $ curl \ ## Lease counts +@include 'alerts/restricted-admin.mdx' + This endpoint returns the total count of a `type` of lease, as well as a count per mount point. Note that it currently only supports type "irrevocable". @@ -281,6 +297,8 @@ $ curl \ ## Leases list +@include 'alerts/restricted-admin.mdx' + This endpoint returns the total count of a `type` of lease, as well as a list of leases per mount point. Note that it currently only supports type "irrevocable". diff --git a/website/content/api-docs/system/license.mdx b/website/content/api-docs/system/license.mdx index cca96f148..48a531382 100644 --- a/website/content/api-docs/system/license.mdx +++ b/website/content/api-docs/system/license.mdx @@ -15,6 +15,8 @@ Vault. ## License status +@include 'alerts/restricted-admin.mdx' + This endpoint returns information about licensing. See [license autoloading](/vault/docs/enterprise/license/autoloading) for additional background. In the response: diff --git a/website/content/api-docs/system/managed-keys.mdx b/website/content/api-docs/system/managed-keys.mdx index 9fac46db2..5bbdebd60 100644 --- a/website/content/api-docs/system/managed-keys.mdx +++ b/website/content/api-docs/system/managed-keys.mdx @@ -11,6 +11,8 @@ See the [Managed Keys](/vault/docs/enterprise/managed-keys) section for further ## List managed keys. +@include 'alerts/restricted-admin.mdx' + This endpoint lists all the Managed Keys of a certain type within the namespace. | Method | Path | @@ -43,6 +45,8 @@ $ curl \ ## Create/Update managed key +@include 'alerts/restricted-admin.mdx' + An endpoint that will create or update a Managed Key within a given namespace. The :type refers to the backend type that the key is to use, such as `pkcs11`. The :name argument is unique name within all managed key types in the namespace. @@ -262,6 +266,8 @@ $ curl \ ## Read managed key +@include 'alerts/restricted-admin.mdx' + This endpoint returns the managed key configuration at the given path. | Method | Path | @@ -306,6 +312,8 @@ $ curl \ ## Test sign with a managed key +@include 'alerts/restricted-admin.mdx' + This endpoint allows an operator to validate that a managed key configuration works by signing and verifying some randomly generated data. If the call returns a successful HTTP status code, the configuration can be considered valid. @@ -347,6 +355,8 @@ $ curl \ ## Delete managed key +@include 'alerts/restricted-admin.mdx' + This endpoint deletes the managed key at the given path provided it is not listed within any mount point's `allowed_managed_keys`. diff --git a/website/content/api-docs/system/mfa/index.mdx b/website/content/api-docs/system/mfa/index.mdx index 0a114c1a6..dd005369f 100644 --- a/website/content/api-docs/system/mfa/index.mdx +++ b/website/content/api-docs/system/mfa/index.mdx @@ -8,6 +8,8 @@ description: >- # `/sys/mfa` +@include 'alerts/restricted-admin.mdx' + The `/sys/mfa` endpoint focuses on managing Multi-factor Authentication (MFA) behaviors in Vault Enterprise MFA. diff --git a/website/content/api-docs/system/monitor.mdx b/website/content/api-docs/system/monitor.mdx index 35579a14e..4529796f0 100644 --- a/website/content/api-docs/system/monitor.mdx +++ b/website/content/api-docs/system/monitor.mdx @@ -13,6 +13,8 @@ some log lines will be dropped. ## Monitor system logs +@include 'alerts/restricted-admin.mdx' + This endpoint streams logs back to the client from Vault. Note that unlike most API endpoints in Vault, this one does not return JSON by default. This will send back data in whatever log format Vault has been configured with. By default, this is text. diff --git a/website/content/api-docs/system/mounts.mdx b/website/content/api-docs/system/mounts.mdx index 8ecf1c387..a93e5100c 100644 --- a/website/content/api-docs/system/mounts.mdx +++ b/website/content/api-docs/system/mounts.mdx @@ -10,6 +10,8 @@ The `/sys/mounts` endpoint is used to manage secrets engines in Vault. ## List mounted secrets engines +@include 'alerts/restricted-admin.mdx' + This endpoints lists all the mounted secrets engines. | Method | Path | @@ -119,6 +121,8 @@ are used by this backend. ## Enable secrets engine +@include 'alerts/restricted-admin.mdx' + This endpoint enables a new secrets engine at the given path. | Method | Path | @@ -215,6 +219,8 @@ $ curl \ ## Disable secrets engine +@include 'alerts/restricted-admin.mdx' + This endpoint disables the mount point specified in the URL. | Method | Path | | @@ -243,12 +249,14 @@ simple as increasing the timeout (in the event of timeout errors). For recovery situations where the secret was manually removed from the secrets backing service, one can force a secrets engine disable in Vault by performing a [force revoke](/vault/api-docs/system/leases) -on the mount prefix, followed by a secrets disable when that completes. +on the mount prefix, followed by a secrets disable when that completes. If the underlying secrets were not manually cleaned up, this method might result in dangling credentials. This is meant for extreme circumstances. ## Get the configuration of a secret engine +@include 'alerts/restricted-admin.mdx' + This endpoint returns the configuration of a specific secret engine. | Method | Path | @@ -310,6 +318,8 @@ $ curl \ ## Read mount configuration +@include 'alerts/restricted-admin.mdx' + This endpoint reads the given mount's configuration. Unlike the `mounts` endpoint, this will return the current time in seconds for each TTL, which may be the system default or a mount-specific value. @@ -338,6 +348,8 @@ $ curl \ ## Tune mount configuration +@include 'alerts/restricted-admin.mdx' + This endpoint tunes configuration parameters for a given mount point. | Method | Path | diff --git a/website/content/api-docs/system/plugins-catalog.mdx b/website/content/api-docs/system/plugins-catalog.mdx index 10e6c1ecf..cb1a2e841 100644 --- a/website/content/api-docs/system/plugins-catalog.mdx +++ b/website/content/api-docs/system/plugins-catalog.mdx @@ -12,6 +12,8 @@ once registered backends can use the plugin by querying the catalog. ## LIST plugins +@include 'alerts/restricted-admin.mdx' + This endpoint lists the plugins in the catalog by type. | Method | Path | @@ -83,6 +85,8 @@ $ curl \ ## LIST plugins +@include 'alerts/restricted-admin.mdx' + This endpoint lists the plugins in the catalog by type. | Method | Path | @@ -118,6 +122,8 @@ $ curl \ ## Register plugin +@include 'alerts/restricted-admin.mdx' + This endpoint registers a new plugin, or updates an existing one with the supplied name. @@ -175,6 +181,8 @@ $ curl \ ## Read plugin +@include 'alerts/restricted-admin.mdx' + This endpoint returns the configuration data for the plugin with the given name. - **`sudo` required** – This endpoint requires `sudo` capability in addition to @@ -221,6 +229,8 @@ $ curl \ ## Remove plugin from catalog +@include 'alerts/restricted-admin.mdx' + This endpoint removes the plugin with the given name. - **`sudo` required** – This endpoint requires `sudo` capability in addition to diff --git a/website/content/api-docs/system/plugins-reload-backend.mdx b/website/content/api-docs/system/plugins-reload-backend.mdx index 261371876..4a9f8e851 100644 --- a/website/content/api-docs/system/plugins-reload-backend.mdx +++ b/website/content/api-docs/system/plugins-reload-backend.mdx @@ -13,6 +13,8 @@ provided, all mounted paths that use that plugin backend will be reloaded. ## Reload plugins +@include 'alerts/restricted-admin.mdx' + This endpoint reloads mounted plugin backends. | Method | Path - | diff --git a/website/content/api-docs/system/policies-password.mdx b/website/content/api-docs/system/policies-password.mdx index 9e17f8403..1708290cb 100644 --- a/website/content/api-docs/system/policies-password.mdx +++ b/website/content/api-docs/system/policies-password.mdx @@ -18,6 +18,8 @@ as well as the syntax of the policies themselves. ## Create/Update password policy +@include 'alerts/restricted-admin.mdx' + This endpoint adds a new or updates an existing password policy. Once a policy is updated, it takes effect immediately to all associated secret engines. @@ -79,6 +81,8 @@ $ vault write sys/policies/password/my-policy policy=@my-policy.hcl ## List password policies +@include 'alerts/restricted-admin.mdx' + This endpoints list the password policies. | Method | Path | @@ -116,6 +120,8 @@ $ curl \ ## Read password policy +@include 'alerts/restricted-admin.mdx' + This endpoint retrieves information about the named password policy. | Method | Path | @@ -145,6 +151,8 @@ $ curl \ ## Delete password policy +@include 'alerts/restricted-admin.mdx' + This endpoint deletes the password policy with the given name. This does not check if any secret engines are using it prior to deletion, so you should ensure that any engines that are utilizing this password policy are changed to a different policy (or to that engines' @@ -170,6 +178,8 @@ $ curl \ ## Generate password from password policy +@include 'alerts/restricted-admin.mdx' + This endpoint generates a password from the specified existing password policy. | Method | Path | diff --git a/website/content/api-docs/system/policies.mdx b/website/content/api-docs/system/policies.mdx index 8ce662873..aca88598c 100644 --- a/website/content/api-docs/system/policies.mdx +++ b/website/content/api-docs/system/policies.mdx @@ -18,6 +18,8 @@ Vault Open Source or basic Vault Enterprise installations. ## List ACL policies +@include 'alerts/restricted-admin.mdx' + This endpoint lists all configured ACL policies. | Method | Path | @@ -42,6 +44,8 @@ $ curl \ ## Read ACL policy +@include 'alerts/restricted-admin.mdx' + This endpoint retrieves information about the named ACL policy. | Method | Path | @@ -72,6 +76,8 @@ $ curl \ ## Create/Update ACL policy +@include 'alerts/restricted-admin.mdx' + This endpoint adds a new or updates an existing ACL policy. Once a policy is updated, it takes effect immediately to all associated users. @@ -107,6 +113,8 @@ $ curl \ ## Delete ACL policy +@include 'alerts/restricted-admin.mdx' + This endpoint deletes the ACL policy with the given name. This will immediately affect all users associated with this policy. (A deleted policy set on a token acts as an empty policy.) @@ -131,6 +139,8 @@ $ curl \ ## List RGP policies +@include 'alerts/restricted-admin.mdx' + This endpoint lists all configured RGP policies. | Method | Path | @@ -155,6 +165,8 @@ $ curl \ ## Read RGP policy +@include 'alerts/restricted-admin.mdx' + This endpoint retrieves information about the named RGP policy. | Method | Path | @@ -186,6 +198,8 @@ $ curl \ ## Create/Update RGP policy +@include 'alerts/restricted-admin.mdx' + This endpoint adds a new or updates an existing RGP policy. Once a policy is updated, it takes effect immediately to all associated users. @@ -226,6 +240,8 @@ $ curl \ ## Delete RGP policy +@include 'alerts/restricted-admin.mdx' + This endpoint deletes the RGP policy with the given name. This will immediately affect all users associated with this policy. (A deleted policy set on a token acts as an empty policy.) @@ -250,6 +266,8 @@ $ curl \ ## List EGP policies +@include 'alerts/restricted-admin.mdx' + This endpoint lists all configured EGP policies. Since EGP policies act on a path, this endpoint returns two identifiers: @@ -280,6 +298,8 @@ $ curl \ ## Read EGP policy +@include 'alerts/restricted-admin.mdx' + This endpoint retrieves information about the named EGP policy. | Method | Path | @@ -312,6 +332,8 @@ $ curl \ ## Create/Update EGP policy +@include 'alerts/restricted-admin.mdx' + This endpoint adds a new or updates an existing EGP policy. Once a policy is updated, it takes effect immediately to all associated users. @@ -358,6 +380,8 @@ $ curl \ ## Delete EGP policy +@include 'alerts/restricted-admin.mdx' + This endpoint deletes the EGP policy with the given name from all paths on which it was configured. | Method | Path | diff --git a/website/content/api-docs/system/policy.mdx b/website/content/api-docs/system/policy.mdx index 52863af36..af77ffd3b 100644 --- a/website/content/api-docs/system/policy.mdx +++ b/website/content/api-docs/system/policy.mdx @@ -10,6 +10,8 @@ The `/sys/policy` endpoint is used to manage ACL policies in Vault. ## List policies +@include 'alerts/restricted-admin.mdx' + This endpoint lists all configured policies. | Method | Path | @@ -34,6 +36,8 @@ $ curl \ ## Read policy +@include 'alerts/restricted-admin.mdx' + This endpoint retrieve the policy body for the named policy. | Method | Path | @@ -64,6 +68,8 @@ $ curl \ ## Create/Update policy +@include 'alerts/restricted-admin.mdx' + This endpoint adds a new or updates an existing policy. Once a policy is updated, it takes effect immediately to all associated users. @@ -98,6 +104,8 @@ $ curl \ ## Delete policy +@include 'alerts/restricted-admin.mdx' + This endpoint deletes the policy with the given name. This will immediately affect all users associated with this policy. diff --git a/website/content/api-docs/system/remount.mdx b/website/content/api-docs/system/remount.mdx index 8fc32ebc0..b2e7cc2dc 100644 --- a/website/content/api-docs/system/remount.mdx +++ b/website/content/api-docs/system/remount.mdx @@ -12,11 +12,14 @@ The Remount documentation details the endpoints required to trigger and monitor ## Move backend -The `/sys/remount` endpoint moves an already-mounted backend to a new mount point. This process works for both secret +@include 'alerts/restricted-admin.mdx' + +The `/sys/remount` endpoint moves an already-mounted backend to a new mount point. Remounting works for both secret engines and auth methods. -The remount operation returns a migration ID to the user. The user may utilize the migration ID to look up -the status of the mount migration. More details about the remount operation are described in +Vault returns a migration ID when the remount operation completes. You +can use the migration ID to look up the status of the mount migration. +More details about the remount operation are described in [Mount Migration](/vault/docs/concepts/mount-migration). ~> Note: This endpoint requires a policy with both `sudo` and `update` capabilities to `sys/remount` @@ -82,6 +85,8 @@ $ curl \ ## Monitor migration status +@include 'alerts/restricted-admin.mdx' + This endpoint is used to monitor the status of a mount migration operation, using the ID returned in the response of the `sys/remount` call. The response contains the passed-in ID, the source and target mounts, and a status field that displays `in-progress`, `success` or `failure`. @@ -113,4 +118,4 @@ $ curl \ "status": "in-progress", } } -``` \ No newline at end of file +``` diff --git a/website/content/api-docs/system/seal-status.mdx b/website/content/api-docs/system/seal-status.mdx index feb69e68e..1750f8bc6 100644 --- a/website/content/api-docs/system/seal-status.mdx +++ b/website/content/api-docs/system/seal-status.mdx @@ -10,6 +10,8 @@ The `/sys/seal-status` endpoint is used to check the seal status of a Vault. ## Seal status +@include 'alerts/restricted-admin.mdx' + This endpoint returns the seal status of the Vault. This is an unauthenticated endpoint. diff --git a/website/content/api-docs/system/tools.mdx b/website/content/api-docs/system/tools.mdx index 04990e31b..d34f0d9a9 100644 --- a/website/content/api-docs/system/tools.mdx +++ b/website/content/api-docs/system/tools.mdx @@ -10,6 +10,8 @@ The `/sys/tools` endpoints are a general set of tools. ## Generate random bytes +@include 'alerts/restricted-admin.mdx' + This endpoint returns high-quality random bytes of the specified length. | Method | Path | @@ -25,7 +27,7 @@ This endpoint returns high-quality random bytes of the specified length. are `hex` or `base64`. - `source` `(string: "platform")` - Specifies the source of the requested bytes. - `platform`, the default, sources bytes from the platform's entropy source. + `platform`, the default, sources bytes from the platform's entropy source. `seal` sources from entropy augmentation (enterprise only). `all` mixes bytes from all available sources. @@ -59,6 +61,8 @@ $ curl \ ## Hash data +@include 'alerts/restricted-admin.mdx' + This endpoint returns the cryptographic hash of given data using the specified algorithm. diff --git a/website/content/api-docs/system/user-lockout.mdx b/website/content/api-docs/system/user-lockout.mdx index b27eaeba2..d7d5a02ae 100644 --- a/website/content/api-docs/system/user-lockout.mdx +++ b/website/content/api-docs/system/user-lockout.mdx @@ -6,20 +6,22 @@ description: The `/sys/locked-users` endpoint is used to manage locked users in # `/sys/locked-users` -The `/sys/locked-users` endpoint is used to list and unlock locked users in Vault. +The `/sys/locked-users` endpoint is used to list and unlock locked users in Vault. -Please visit [user lockout](/vault/docs/concepts/user-lockout) concepts page for more details about the feature. +Refer to the [user lockout](/vault/docs/concepts/user-lockout) overview for more details about how Vault handles lockouts. ## List locked users -This endpoint lists the locked users information in Vault. +@include 'alerts/restricted-admin.mdx' + +The list endpoint returns information on the users currently locked by Vault. The response will include all child namespaces of the namespace in which the request was made. If some namespace has subsequently been deleted, its path will be listed as "deleted namespace :ID:." Deleted namespaces are reported only for queries in the root namespace because the information about the namespace path is unknown. The response will be returned in the decreasing order of locked user -counts. +counts. This endpoint was added in Vault 1.13. @@ -31,7 +33,7 @@ This endpoint was added in Vault 1.13. - `mount_accessor` `(string, optional)` - Specifies the identifier of the auth mount entry to which the user belongs in the namespace in which the request was made. If no mount accessor is specified, -the response will include locked users in all child namespaces of the namespace in which the request was made. +the response includes locked users in all child namespaces of the namespace in which the request was made. ### Sample request @@ -193,9 +195,11 @@ $ curl \ ## Unlock user -This endpoint unlocks a locked user with provided mount_accessor and alias_identifier in namespace in which the request was made if locked. -This command is idempotent, meaning it succeeds even if user with the given mount_accessor and alias_identifier is not locked. - +@include 'alerts/restricted-admin.mdx' + +The unlock user endpoint frees a locked user with the provided `mount_accessor` and `alias_identifier` in the given namespace. +The unlock command is idempotent. Calls to the endpoint succeed even if the user matching the provided `mount_accessor` and `alias_identifier` is not currently locked. + This endpoint was added in Vault 1.13. @@ -207,7 +211,7 @@ This endpoint was added in Vault 1.13. - `mount_accessor` `(string, required)` - Specifies the identifier of the auth mount entry to which the user belongs -- `alias_identifier` `(string, required)` - It is the name of the alias (user). For example, if the alias +- `alias_identifier` `(string, required)` - The name of the alias (user). 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 an approle auth method, the name should be a valid RoleID. If the alias belongs to an ldap auth method, the name should be a valid username. @@ -219,4 +223,4 @@ $ curl \ --header "X-Vault-Token: ..." \ --request POST \ http://127.0.0.1:8200/v1/sys/locked-users/auth_userpass_af8d1d32/unlock/bsmith -``` \ No newline at end of file +``` diff --git a/website/content/api-docs/system/version-history.mdx b/website/content/api-docs/system/version-history.mdx index da76e0d24..3a3345f3c 100644 --- a/website/content/api-docs/system/version-history.mdx +++ b/website/content/api-docs/system/version-history.mdx @@ -13,6 +13,8 @@ The `/sys/version-history` endpoint is used to retrieve the version history of a ## Read version history +@include 'alerts/restricted-admin.mdx' + This endpoint returns the version history of the Vault. The response will contain the following keys: - `keys`: a list of installed versions in chronological order based on the time installed diff --git a/website/content/api-docs/system/wrapping-lookup.mdx b/website/content/api-docs/system/wrapping-lookup.mdx index 146c3770d..3183ba4a4 100644 --- a/website/content/api-docs/system/wrapping-lookup.mdx +++ b/website/content/api-docs/system/wrapping-lookup.mdx @@ -10,6 +10,8 @@ The `/sys/wrapping/lookup` endpoint returns wrapping token properties. ## Wrapping lookup +@include 'alerts/restricted-admin.mdx' + This endpoint looks up wrapping properties for the given token. | Method | Path | diff --git a/website/content/api-docs/system/wrapping-rewrap.mdx b/website/content/api-docs/system/wrapping-rewrap.mdx index 6da9f02e2..0ced31662 100644 --- a/website/content/api-docs/system/wrapping-rewrap.mdx +++ b/website/content/api-docs/system/wrapping-rewrap.mdx @@ -13,6 +13,8 @@ refresh its TTL. ## Wrapping rewrap +@include 'alerts/restricted-admin.mdx' + This endpoint rewraps a response-wrapped token. The new token will use the same creation TTL as the original token and contain the same response. The old token will be invalidated. This can be used for long-term storage of a secret in a diff --git a/website/content/api-docs/system/wrapping-unwrap.mdx b/website/content/api-docs/system/wrapping-unwrap.mdx index 49297a4a8..176ac9eee 100644 --- a/website/content/api-docs/system/wrapping-unwrap.mdx +++ b/website/content/api-docs/system/wrapping-unwrap.mdx @@ -10,6 +10,8 @@ The `/sys/wrapping/unwrap` endpoint unwraps a wrapped response. ## Wrapping unwrap +@include 'alerts/restricted-admin.mdx' + This endpoint returns the original response inside the given wrapping token. Unlike simply reading `cubbyhole/response` (which is deprecated), this endpoint provides additional validation checks on the token, returns the original value diff --git a/website/content/api-docs/system/wrapping-wrap.mdx b/website/content/api-docs/system/wrapping-wrap.mdx index 8071097fe..8ad5849a0 100644 --- a/website/content/api-docs/system/wrapping-wrap.mdx +++ b/website/content/api-docs/system/wrapping-wrap.mdx @@ -13,6 +13,8 @@ token. ## Wrapping wrap +@include 'alerts/restricted-admin.mdx' + This endpoint wraps the given user-supplied data inside a response-wrapped token. diff --git a/website/content/docs/enterprise/namespaces.mdx b/website/content/docs/enterprise/namespaces.mdx index 68e78dd1f..a2d3bc78d 100644 --- a/website/content/docs/enterprise/namespaces.mdx +++ b/website/content/docs/enterprise/namespaces.mdx @@ -60,6 +60,19 @@ identities. This behavior can be configured using the [group-policy-application] can be set to allow policies to be applied irrespective of namespace hierarchy, allowing sharing across any namespace. +### Administrative namespaces + +The Vault API includes system backend endpoints, which are mounted under the sys/ path. +System endpoints let you interact with the internal features of your Vault instance. +For security reasons, some of the system backend endpoints are restricted, and can only be called +from the root namespace or using a token in the root namespace with elevated permissions. + +By default, Vault allows non-root calls to the less sensitive system backend endpoints. +However, there may be instances where a Vault operator needs to provide access to a subset +of the restricted endpoints, like sys/audit-hash and sys/monitor, without granting access +to the full set of privileged sys/ paths. An administrative namespace lets Vault operators grant +access to a subset of privileged endpoints by setting a parameter in their Vault configuration file. + ## Usage API operations performed under a namespace can be done by providing the relative @@ -95,7 +108,7 @@ Consider the following namespace name restrictions: - Cannot end with `/` - Cannot contain spaces - The `root` is the top-level namespace. You cannot create another namespace - named "root" under the `root` namespace + named "root" under the `root` namespace In addition, the following paths are reserved by Vault so that they cannot be the namespace name. diff --git a/website/content/partials/alerts/restricted-admin.mdx b/website/content/partials/alerts/restricted-admin.mdx new file mode 100644 index 000000000..38dd3c053 --- /dev/null +++ b/website/content/partials/alerts/restricted-admin.mdx @@ -0,0 +1,3 @@ + + The API path can only be called from the root or administrative namespace. + diff --git a/website/content/partials/alerts/restricted-root.mdx b/website/content/partials/alerts/restricted-root.mdx new file mode 100644 index 000000000..829800234 --- /dev/null +++ b/website/content/partials/alerts/restricted-root.mdx @@ -0,0 +1,3 @@ + + The API path can only be called from the root namespace. +