diff --git a/website/content/api-docs/system/config-group-policy-application.mdx b/website/content/api-docs/system/config-group-policy-application.mdx new file mode 100644 index 000000000000..de3e80926617 --- /dev/null +++ b/website/content/api-docs/system/config-group-policy-application.mdx @@ -0,0 +1,81 @@ +--- +layout: api +page_title: /sys/config/group-policy-application - HTTP API +description: The '/sys/config/group-policy-application' endpoint is used to configure the global mode for group policy application. +--- + +# `/sys/config/group-policy-application` + +~> **Enterprise Only** – These endpoints require Vault Enterprise Platform. + +The `sys/config/group-policy-application` endpoint can be used to configure the +mode of policy application for identity groups in Vault. This setting dictates +the behavior across all groups in all namespaces in Vault. + +Vault allows you to add entities and groups from any namespace into an identity group. +However, historically, any policies attached to that group would only apply when the +Vault token authorizing a request was created in the same namespace as that group, +or a descendent namespace. This endpoint allows relaxing that restriction: when the mode is set to the default, +`within_namespace_hierarchy`, the historical behaviour is maintained, +but when set to `any`, group policies apply to all members of a group, +regardless of what namespace the request token came from. + +Note that this configuration will be replicated between primary and secondaries, that +is to say, primaries cannot have a different policy application mode to secondaries. + +## Get Group Policy Application Information + +This endpoint returns the current group policy application mode, which will be +either `within_namespace_hierarchy` or `any`. + + +| Method | Path | +| :----- | :---------------------------- | +| `GET` | `/sys/config/group-policy-application` | + +### Sample Request + +```shell-session +$ curl \ + --header "X-Vault-Token: ..." \ + 'http://127.0.0.1:8200/v1/sys/config/group-policy-application' +``` + +### Sample Response + +```json +{ + "group_policy_application_mode": "within_namespace_hierarchy" +} +``` + +## Set Group Policy Application Information + +This endpoint allows you to modify the current group policy application mode, which can be +either `within_namespace_hierarchy` or `any`. `within_namespace_hierarchy` +restricts policy application to only policies from groups from parent namespaces, and +`any` does not restrict policy application in any way, and policies will apply from any namespace, +irrespective of namespace hierarchy. + + +| Method | Path | +| :----- | :---------------------------- | +| `POST`, `PUT` | `/sys/config/group-policy-application` | + +### Sample Payload + +```json +{ + "group_policy_application_mode": "any" +} +``` + +### Sample Request + +```shell-session +$ curl \ + --request POST \ + --header "X-Vault-Token: ..." \ + --data @payload.json \ + 'http://127.0.0.1:8200/v1/sys/config/group-policy-application' +``` diff --git a/website/content/docs/enterprise/namespaces.mdx b/website/content/docs/enterprise/namespaces.mdx index 22bc350c2005..2e37addb1ad9 100644 --- a/website/content/docs/enterprise/namespaces.mdx +++ b/website/content/docs/enterprise/namespaces.mdx @@ -67,6 +67,7 @@ There are certain API paths that can only be called from the root namespace: - `sys/leader` - `sys/health` - `sys/metrics` +- `sys/config/group-policy-application` - `sys/config/state` - `sys/host-info` - `sys/key-status` @@ -95,7 +96,9 @@ of delegate admins. Child namespaces can share policies from their parent namespaces. For example, a child namespace may refer to parent identities (entities and groups) when writing policies that function only within that child namespace. Similarly, a parent namespace can have policies asserted on child -identities. +identities. This behavior can be configured using the [group-policy-application](/api-docs/system/config-group-policy-application) API, and +can be set to allow policies to be applied irrespective of namespace hierarchy, allowing sharing +across any namespace. ## Tutorial diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json index 488d6bb761cc..224c75963da1 100644 --- a/website/data/api-docs-nav-data.json +++ b/website/data/api-docs-nav-data.json @@ -421,6 +421,15 @@ "title": "/sys/config/cors", "path": "system/config-cors" }, + { + "title": "/sys/config/group-policy-application", + "path": "system/config-group-policy-application", + "badge": { + "text": "ENT", + "type": "outlined", + "color": "neutral" + } + }, { "title": "/sys/config/reload", "path": "system/config-reload"