From d30fddd61735a26eb0cb190499e395dfaa47591c Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Fri, 6 Jan 2023 11:16:15 -0500 Subject: [PATCH 1/6] VAULT-12491 Add docs for group policy config --- .../config-group-policy-application.mdx | 78 +++++++++++++++++++ .../content/docs/enterprise/namespaces.mdx | 5 +- website/data/api-docs-nav-data.json | 9 +++ 3 files changed, 91 insertions(+), 1 deletion(-) create mode 100644 website/content/api-docs/system/config-group-policy-application.mdx 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..20d7fc31b7d0 --- /dev/null +++ b/website/content/api-docs/system/config-group-policy-application.mdx @@ -0,0 +1,78 @@ +--- +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` + +The `sys/config/group-policy-application` endpoint can be used to configure the +mode of policy application for identity groups in Vault. +Currently, it only supports two modes, `within_namespace_hierarchy` (default), which +restricts policy application to only policies from groups from parent namespaces, and +`any` which does not restrict policy application, and policies will apply from any namespace, +irrespective of namespace hierarchy. + +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` + +~> **Enterprise Only** – This endpoint requires Vault Enterprise. + +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` + +~> **Enterprise Only** – This endpoint requires Vault Enterprise. + +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..cf7eb494aebc 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" From 37d4b7ca415d3f3e1f8a12c5c0b36847f6138386 Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Fri, 6 Jan 2023 11:24:17 -0500 Subject: [PATCH 2/6] VAULT-12491 typo --- website/content/docs/enterprise/namespaces.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/content/docs/enterprise/namespaces.mdx b/website/content/docs/enterprise/namespaces.mdx index cf7eb494aebc..2e37addb1ad9 100644 --- a/website/content/docs/enterprise/namespaces.mdx +++ b/website/content/docs/enterprise/namespaces.mdx @@ -96,7 +96,7 @@ 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. This behavior can be configured using the [group-policy-application](/api-docs/system/config-group-policy-application") API, and +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. From 54e9e03586ce4de814bf73ba826e515a841b1e7e Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Fri, 6 Jan 2023 11:25:09 -0500 Subject: [PATCH 3/6] VAULT-12491 typo --- .../api-docs/system/config-group-policy-application.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/content/api-docs/system/config-group-policy-application.mdx b/website/content/api-docs/system/config-group-policy-application.mdx index 20d7fc31b7d0..98f4094c8b02 100644 --- a/website/content/api-docs/system/config-group-policy-application.mdx +++ b/website/content/api-docs/system/config-group-policy-application.mdx @@ -16,7 +16,7 @@ irrespective of namespace hierarchy. 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` +## Get Group Policy Application Information ~> **Enterprise Only** – This endpoint requires Vault Enterprise. @@ -44,7 +44,7 @@ $ curl \ } ``` -## `Set Group Policy Application Information` +## Set Group Policy Application Information ~> **Enterprise Only** – This endpoint requires Vault Enterprise. From 13350ff8c196d6e02279ed8105ba5bb91c1f9405 Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Mon, 9 Jan 2023 09:36:05 -0500 Subject: [PATCH 4/6] VAULT-12491 Update language a bit --- .../api-docs/system/config-group-policy-application.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/website/content/api-docs/system/config-group-policy-application.mdx b/website/content/api-docs/system/config-group-policy-application.mdx index 98f4094c8b02..29b391804560 100644 --- a/website/content/api-docs/system/config-group-policy-application.mdx +++ b/website/content/api-docs/system/config-group-policy-application.mdx @@ -7,11 +7,11 @@ description: The '/sys/config/group-policy-application' endpoint is used to conf # `/sys/config/group-policy-application` The `sys/config/group-policy-application` endpoint can be used to configure the -mode of policy application for identity groups in Vault. +mode of policy application for identity groups in Vault. Policy application in this case +refers to whether or not a policy as defined in a group will apply to a member of that group. Currently, it only supports two modes, `within_namespace_hierarchy` (default), which -restricts policy application to only policies from groups from parent namespaces, and -`any` which does not restrict policy application, and policies will apply from any namespace, -irrespective of namespace hierarchy. +means that policies will only be applied and asserted on from groups in parent namespaces, and +`any` which means that every policy will be applied, irrespective of namespace hierarchy. 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. From 6ac3f8ab30b26635b7941628a2c094d786a3fc0e Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Mon, 9 Jan 2023 10:25:19 -0500 Subject: [PATCH 5/6] VAULT-12491 Update language a bit --- .../system/config-group-policy-application.mdx | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/website/content/api-docs/system/config-group-policy-application.mdx b/website/content/api-docs/system/config-group-policy-application.mdx index 29b391804560..6b5f25e63afd 100644 --- a/website/content/api-docs/system/config-group-policy-application.mdx +++ b/website/content/api-docs/system/config-group-policy-application.mdx @@ -7,11 +7,15 @@ description: The '/sys/config/group-policy-application' endpoint is used to conf # `/sys/config/group-policy-application` The `sys/config/group-policy-application` endpoint can be used to configure the -mode of policy application for identity groups in Vault. Policy application in this case -refers to whether or not a policy as defined in a group will apply to a member of that group. -Currently, it only supports two modes, `within_namespace_hierarchy` (default), which -means that policies will only be applied and asserted on from groups in parent namespaces, and -`any` which means that every policy will be applied, irrespective of namespace hierarchy. +mode of policy application for identity groups 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. From 65b05440c221947d33f3406dbb7dec12771c7442 Mon Sep 17 00:00:00 2001 From: VioletHynes Date: Mon, 9 Jan 2023 12:07:12 -0500 Subject: [PATCH 6/6] VAULT-12491 Update language a bit --- .../api-docs/system/config-group-policy-application.mdx | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/website/content/api-docs/system/config-group-policy-application.mdx b/website/content/api-docs/system/config-group-policy-application.mdx index 6b5f25e63afd..de3e80926617 100644 --- a/website/content/api-docs/system/config-group-policy-application.mdx +++ b/website/content/api-docs/system/config-group-policy-application.mdx @@ -6,8 +6,11 @@ description: The '/sys/config/group-policy-application' endpoint is used to conf # `/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. +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 @@ -22,8 +25,6 @@ is to say, primaries cannot have a different policy application mode to secondar ## Get Group Policy Application Information -~> **Enterprise Only** – This endpoint requires Vault Enterprise. - This endpoint returns the current group policy application mode, which will be either `within_namespace_hierarchy` or `any`. @@ -50,8 +51,6 @@ $ curl \ ## Set Group Policy Application Information -~> **Enterprise Only** – This endpoint requires Vault Enterprise. - 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