document JWT Groups Filter setting (#1770)

Add two reference pages, one for the global setting and one for the
per-route setting. Add the new 'removed-groups-count' field to the
Authorize Log Fields reference page.

content/docs/reference/authorize-log-fields.mdx

@@ -114,6 +114,7 @@ The table below lists all available authorize log fields:
 | `method` | The HTTP request method, such as `GET`, `POST`, or `PUT` | Yes |
 | `path` | The HTTP request path (for example, `/some/path`) | Yes |
 | `query` | The HTTP request query (for example, `?test=one&other=13`) | No |
+| `removed-groups-count` | The number of groups removed during [JWT groups filtering](/docs/reference/jwt-groups-filter) | Yes |
 | `request-id` | The request's unique identifier as assigned by Pomerium | Yes |
 | `service-account-id` | if using a service account, the service account ID | Yes |
 | `session-id` | the session ID | Yes |

content/docs/reference/jwt-groups-filter.mdx

@@ -0,0 +1,56 @@
+---
+id: jwt-groups-filter
+title: JWT Groups Filter
+description: |
+  The JWT Groups Filter setting allows you to reduce the size of the groups claim in the Pomerium JWT.
+keywords:
+  - reference
+  - JWT Groups Filter
+pagination_prev: null
+pagination_next: null
+toc_max_heading_level: 2
+---
+
+:::enterprise
+
+This setting is available only in [Pomerium Enterprise](/docs/deploy/enterprise).
+
+:::
+
+## Summary
+
+The **JWT Groups Filter** setting allows you to reduce the size of the groups claim in the [Pomerium JWT](/docs/capabilities/getting-users-identity) when used in combination with [directory sync]. This may be useful for organizations with large numbers of directory groups.
+
+When directory sync is enabled, Pomerium will include directory groups membership information in a `groups` claim in the Pomerium JWT. By default, all of a user's groups are included in this claim. However, if the average number of groups is very large, this may grow unwieldy and potentially lead to HTTP header size issues with some upstream services.
+
+This feature allows you to limit the size of the `groups` claim by specifying a subset of groups that are relevant for your deployment. Only groups belonging to this subset will be included in the `groups` claim in the Pomerium JWT.
+
+The groups eligible for inclusion may be specified explicitly, or inferred automatically from the policies that apply to a given route.
+
+The setting also applies to the `Impersonate-Group` header, for Kubernetes API server authentication.
+
+This setting can also be customized for a particular route, see [**JWT Groups Filter (per route)**](/docs/reference/routes/jwt-groups-filter).
+
+## How to configure
+
+The **JWT Groups Filter** setting is available in the Enterprise Console on the "Settings" page, under the "Proxy" tab.
+
+![screenshot of JWT Groups Filter setting](./img/jwt-groups-filter.png)
+
+Select the "Filter to groups referenced in policies" option if you want to automatically filter based on any group IDs referenced in any policies associated with a specific route. Or you can enter specific groups using the "Filter to specific groups" input field.
+
+If both are specified, a group will be eligible for inclusion in the Pomerium JWT if it is _either_ referenced in an associated policy, or present in the list of specific groups.
+
+:::info
+
+This setting has no effect if [directory sync] is not enabled.
+
+:::
+
+## Logging
+
+When this feature is enabled, a new field `removed-groups-count` will be present in the [authorize logs](/docs/reference/authorize-log-fields). This field will indicate the number of groups that were removed by groups filtering for a specific request.
+
+To verify that groups filtering is working as expected, you can also set the [log level](/docs/reference/log-level) to "debug." At this level, Pomerium will log an additional entry with the message `JWT group filtering removed groups` along with the IDs of all removed and included groups.
+
+[directory sync]: /docs/integrations/user-standing/directory-sync

content/docs/reference/reference.json

@@ -711,9 +711,16 @@
   "jwt-groups-filter": {
     "id": "jwt-groups-filter",
     "title": "JWT Groups Filter",
-    "description": "If set, filters the set of group memberships in the Pomerium JWT and Impersonate-Group headers to this subset of groups (based on an exact string match).",
-    "services": [],
-    "type": "array of string"
+    "path": "/jwt-groups-filter",
+    "description": "Restricts the set of groups allowed in the Pomerium JWT and Impersonate-Group headers, either based on applied policies or using a specific list of groups.",
+    "services": []
+  },
+  "jwt-groups-filter-route": {
+    "id": "jwt-groups-filter-route",
+    "title": "JWT Groups Filter (per route)",
+    "path": "/routes/jwt-groups-filter",
+    "description": "Restricts the set of groups allowed in the Pomerium JWT and Impersonate-Group headers, either based on applied policies or using a specific list of groups.",
+    "services": []
   },
   "override-certificate-name": {
     "id": "override-certificate-name",

content/docs/reference/routes/jwt-groups-filter.mdx

@@ -0,0 +1,31 @@
+---
+title: JWT Groups Filter (per route)
+description: |
+  The JWT Groups Filter setting allows you to reduce the size of the groups claim in the Pomerium JWT.
+keywords:
+  - reference
+  - JWT Groups Filter
+pagination_prev: null
+pagination_next: null
+toc_max_heading_level: 2
+---
+
+:::enterprise
+
+This setting is available only in [Pomerium Enterprise](/docs/deploy/enterprise).
+
+:::
+
+## Summary
+
+The **JWT Groups Filter (per route)** setting allows you to reduce the size of the groups claim in the [Pomerium JWT](/docs/capabilities/getting-users-identity). See the global [**JWT Groups Filter**](/docs/reference/jwt-groups-filter) reference page for more information about this feature.
+
+When the global setting is enabled, the per-route option will _expand_ the set of allowed groups. A group will be eligible for inclusion in the groups claim if is allowed by either the global setting or the per-route setting.
+
+When the global setting is not enabled, the per-route option will enable groups filtering for a specific route.
+
+## How to configure
+
+The **JWT Groups Filter** setting is available in the Enterprise Console on the route settings page, under the "Headers" tab.
+
+![screenshot of JWT Groups Filter setting](../img/jwt-groups-filter.png)