[2.9.0] 1370 optional filter on azuread auth group memberships (#1394)

* 1370-optional-filter-on-azure-ad-auth-group-memberships

* assorted revisions, including adding a section and moving the step for initial setup

* reduce repetition by linking to section

* added image

* slight reword

* apply to 2.9

docs/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md

@@ -167,7 +167,7 @@ Custom Endpoints are not tested or fully supported by Rancher.
 
 You'll also need to manually enter the Graph, Token, and Auth Endpoints.
 
-- From <b>App registrations</b>, click <b>Endpoints</b>:
+- From **App registrations**, click **Endpoints**:
 
 ![Click Endpoints](/img/endpoints.png)
 
@@ -221,6 +221,8 @@ To complete configuration, enter information about your AD instance in the Ranch
 
     <code>http<span>s://g</span>raph.microsoft.com<del>/abb5adde-bee8-4821-8b03-e63efdc7701c</del></code>
 
+1. (Optional) In Rancher v2.9.0 and later, you can filter users' group memberships in Azure AD to reduce the amount of log data generated. See steps 4–5 of [Filtering Users by Azure AD Auth Group Memberships](#filtering-users-by-azure-ad-auth-group-memberships) for full instructions.
+
 1. Click **Enable**.
 
 **Result:** Azure Active Directory authentication is configured.
@@ -314,6 +316,29 @@ Endpoint         | https://login.partner.microsoftonline.cn/
 Graph Endpoint   | https://microsoftgraph.chinacloudapi.cn
 Token Endpoint   | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/token
 
+## Filtering Users by Azure AD Auth Group Memberships
+
+In Rancher v2.9.0 and later, you can filter users' group memberships from Azure AD to reduce the amount of log data generated. If you did not filter group memberships during initial setup, you can still add filters on an existing Azure AD configuration.
+
+:::warning
+    
+Filtering out a user group membership affects more than just logging. 
+
+Since the filter prevents Rancher from seeing that the user belongs to an excluded group, it also does not see any permissions from that group. This means that excluding a group from the filter can have the side effect of denying users permissions they should have.
+
+:::
+
+1. In Rancher, in the top left corner, click **☰ > Users & Authentication**.
+
+1. In the left navigation menu, click **Auth Provider**.
+
+1. Click **AzureAD**.
+
+1. Click the checkbox next to **Limit users by group membership**.
+    
+1. Enter an [OData filter clause](https://learn.microsoft.com/en-us/odata/concepts/queryoptions-overview#filter) into the **Group Membership Filter** field. For example, if you want to limit logging to group memberships whose name starts with `test`, click the checkbox and enter `startswith(displayName,'test')`.
+
+![Adding a group membership filter to Azure AD](/img/auth-setup-azure-ad-filter.png)
 
 ## Deprecated Azure AD Graph API
 

versioned_docs/version-2.9/how-to-guides/new-user-guides/authentication-permissions-and-global-configuration/authentication-config/configure-azure-ad.md

@@ -167,7 +167,7 @@ Custom Endpoints are not tested or fully supported by Rancher.
 
 You'll also need to manually enter the Graph, Token, and Auth Endpoints.
 
-- From <b>App registrations</b>, click <b>Endpoints</b>:
+- From **App registrations**, click **Endpoints**:
 
 ![Click Endpoints](/img/endpoints.png)
 
@@ -221,6 +221,8 @@ To complete configuration, enter information about your AD instance in the Ranch
 
     <code>http<span>s://g</span>raph.microsoft.com<del>/abb5adde-bee8-4821-8b03-e63efdc7701c</del></code>
 
+1. (Optional) In Rancher v2.9.0 and later, you can filter users' group memberships in Azure AD to reduce the amount of log data generated. See steps 4–5 of [Filtering Users by Azure AD Auth Group Memberships](#filtering-users-by-azure-ad-auth-group-memberships) for full instructions.
+
 1. Click **Enable**.
 
 **Result:** Azure Active Directory authentication is configured.
@@ -314,6 +316,29 @@ Endpoint         | https://login.partner.microsoftonline.cn/
 Graph Endpoint   | https://microsoftgraph.chinacloudapi.cn
 Token Endpoint   | https://login.partner.microsoftonline.cn/{tenantID}/oauth2/v2.0/token
 
+## Filtering Users by Azure AD Auth Group Memberships
+
+In Rancher v2.9.0 and later, you can filter users' group memberships from Azure AD to reduce the amount of log data generated. If you did not filter group memberships during initial setup, you can still add filters on an existing Azure AD configuration.
+
+:::warning
+    
+Filtering out a user group membership affects more than just logging. 
+
+Since the filter prevents Rancher from seeing that the user belongs to an excluded group, it also does not see any permissions from that group. This means that excluding a group from the filter can have the side effect of denying users permissions they should have.
+
+:::
+
+1. In Rancher, in the top left corner, click **☰ > Users & Authentication**.
+
+1. In the left navigation menu, click **Auth Provider**.
+
+1. Click **AzureAD**.
+
+1. Click the checkbox next to **Limit users by group membership**.
+    
+1. Enter an [OData filter clause](https://learn.microsoft.com/en-us/odata/concepts/queryoptions-overview#filter) into the **Group Membership Filter** field. For example, if you want to limit logging to group memberships whose name starts with `test`, click the checkbox and enter `startswith(displayName,'test')`.
+
+![Adding a group membership filter to Azure AD](/img/auth-setup-azure-ad-filter.png)
 
 ## Deprecated Azure AD Graph API