[v18] docs: entra id integration group filters and tctl command reference

docs/pages/identity-governance/entra-id/advanced-options.mdx

@@ -0,0 +1,84 @@
+---
+title: Advanced Entra ID Integration Options
+description: Advanced Teleport Entra ID integration configuration options.
+sidebar_position: 5
+tags:
+ - identity-governance
+ - azure
+ - privileged-access
+---
+
+This page lists advanced configuration options related to the
+Teleport Entra ID integration. 
+
+## Group filters
+
+By default, all the groups that exists in the Microsoft Entra ID directory gets 
+imported to Teleport. 
+
+This import behavior can be controlled by using the group filters, which can 
+include or exclude certain groups based on their matching group object ID or group 
+display name. 
+
+Group filter can only be configured using `tctl` and the ability to configure it 
+using Teleport Web UI is in the works.
+
+
+### Group filter precedence
+
+- If no filters are configured, all the groups are imported (default behavior).
+- If an include filter is defined, only the matching group is imported. 
+- If a group is matched in both the include filter and exclude filter, exclude 
+filter gets precedence. 
+
+
+### Configure group filters during installation
+
+Example to configure group filters during installation:
+```code
+$ tctl plugins install entraid \
+    --name entra-id-default \
+    --auth-connector-name entra-id \
+    --default-owner=admin \
+    --no-access-graph \
+    --use-system-credentials \
+    --manual-setup \
+    --group-id 25f9c527-2314-414c-a75d-ef7efabcc99b \
+    --group-name "admin*" \
+    --exclude-group-id 080b50c3-1c98-4d8e-a54e-20143dbd4f99 \
+    --exclude-group-name "fin*" 
+```
+- `--group-id`: Include group matching the specified group ID. 
+  Multiple flags allowed.
+- `--group-name`: Include groups matching the specified group name regex. 
+  Multiple flags allowed.
+- `--exclude-group-id`. Exclude group matching the specified group ID. 
+  Multiple flags allowed.
+- `--exclude-group-name`. Exclude groups matching the specified group name regex. 
+  Multiple flags allowed.
+
+### Updating group filters
+Group filters can be updated using `group_filters` flag, which is available in 
+the `sync_settings` of the Teleport Entra ID plugin resource spec. 
+
+Reference configuration spec:
+```yaml
+kind: plugin
+metadata:
+  name: entra-id
+spec:
+  Settings:
+    entra_id:
+      sync_settings:
+        ... # other settings omitted for brevity
+        group_filters:
+        - id: 080b50c3-1c98-4d8e-a54e-20143dbd4f99
+        - id: 45f9c527-2314-414c-a75d-ef7efabcc99b
+        - id: 35f9c527-2314-414c-a75d-ef7efabcc99b
+        - nameRegex: 'admin*'
+        - excludeId: 080b50c52-1c98-4d8e-a54e-20143dbd4f99
+        - excludeNameRegex: 'finance*'
+version: v1
+```
+
+The plugin spec can be edited using the `tctl edit plugins/entra-id` command.

docs/pages/identity-governance/entra-id/faq.mdx

@@ -1,7 +1,7 @@
 ---
 title: Entra ID Integration FAQ
 description: Frequently asked questions on the Teleport Entra ID integration.
-sidebar_position: 5
+sidebar_position: 6
 tags:
  - identity-governance
  - azure
@@ -12,12 +12,15 @@ This page provides answers to frequently asked questions about Teleport Entra ID
 
 ## What resources are imported to Teleport?
 
-Teleport imports all the users, user groups and its members from the Entra ID directory.
-There is no filter available to control custom import rules.
+Teleport imports users, user groups and its members from the Microsoft Entra ID 
+directory.
 
 If Teleport Identity Security integration is enabled, Teleport will import 
 applications and policies as well. 
 
+You can control which groups from Microsoft Entra ID gets imported to Teleport 
+by configuring [group filters](advanced-options.mdx#group-filters). 
+
 ## How does it work with nested Access Lists?
 
 If an Entra ID group is assigned as a member to another group, Teleport preserves this assignment 

docs/pages/identity-governance/entra-id/getting-started.mdx

@@ -183,6 +183,7 @@ importing resources from Entra ID to Teleport.
 ## Next steps
 
 - [Configure Access](configure-access.mdx) for Entra ID users.
+- Configure [group filters](advanced-options.mdx#group-filters). 
 - Learn more about [Access List](../access-lists/access-lists.mdx) management.
 - Take a deeper look into setting up [Entra ID auth connector](../../zero-trust-access/sso/entra-id.mdx). 
 - Learn how the [Identity Security integration with Entra ID](../../identity-security/integrations/entra-id.mdx) works. 

docs/pages/identity-governance/entra-id/manual-installation.mdx

@@ -111,6 +111,7 @@ After you enter these values, Entra ID plugin will be installed with the OIDC Id
 ## Next steps
 
 - [Configure Access](configure-access.mdx) for Entra ID users.
+- Configure [group filters](advanced-options.mdx#group-filters). 
 - Learn more about [Access List](../access-lists/access-lists.mdx) management.
 - Take a deeper look into setting up [Entra ID auth connector](../../zero-trust-access/sso/entra-id.mdx). 
 - Learn how the [Identity Security integration with Entra ID](../../identity-security/integrations/entra-id.mdx) works. 

docs/pages/identity-governance/entra-id/terraform.mdx

@@ -226,5 +226,6 @@ plugin service that imports users and groups from Entra ID to Teleport.
 
 - Learn how to [configure access](configure-access.mdx) for Entra ID users.
 - Take a deeper look into setting up [Entra ID auth connector](../../zero-trust-access/sso/entra-id.mdx). 
+- Configure [group filters](advanced-options.mdx#group-filters). 
 - Learn how the [Identity Security integration with Entra ID](../../identity-security/integrations/entra-id.mdx) works. 
 - See [FAQs](faq.mdx) related to the Teleport Entra ID integration. 

docs/pages/reference/cli/tctl.mdx

@@ -2203,6 +2203,53 @@ $ tctl plugins install okta \
     --no-appgroup-sync
 ```
 
+## tctl plugins install entraid
+
+Install the Entra ID plugin.
+
+```code
+$ tctl plugins install entraid <flags>
+```
+
+### Flags
+
+| Name | Default Value(s) | Allowed Value(s) | Description |
+| - | - | - | - |
+| `--name` | `entra-id` | string | Name of the plugin resource to create. |
+| `--auth-connector-name` | `entra-id-default` | string | Name of the SAML connector resource to create. |
+| `--default-owner` | none | string | Required. A Teleport username to set as the default owner for the imported Access Lists. Multiple flags allowed. |
+| `--[no-]access-graph` | `--access-graph` | boolean | Optional. Enable Access Graph cache build. |
+| `--[no-]use-system-credentials` | `--no-use-system-credentials` | boolean | Optional. Use system credentials instead of OIDC. |
+| `--[no-]manual-setup` | `--no-manual-setup` | boolean | Optional. Manually set up the EntraID integration. |
+| `--[no-]force` | `--no-force` | boolean | Optional. Proceed with the installation even if the plugin already exists. |
+| `--group-id` | none | string | Optional. Include group matching the specified group ID. Multiple flags allowed. |
+| `--group-name` | none | string | Optional. Include groups matching the specified group name regex. Multiple flags allowed.  |
+| `--exclude-group-id` | none | string | Optional. Exclude group matching the specified group ID. Multiple flags allowed. |
+| `--exclude-group-name` | none | string | Optional. Exclude groups matching the specified group name regex. Multiple flags allowed. |
+
+
+### Example
+
+```code
+$ tctl plugins install entraid \
+    --name entra-id-default \
+    --auth-connector-name entra-id \
+    --default-owner=admin \
+    [email protected] \
+    --no-access-graph \
+    --use-system-credentials \
+    --manual-setup \
+    --group-id 25f9c527-2314-414c-a75d-ef7efabcc99b \
+    --group-name "admin*" \
+    --exclude-group-id 080b50c3-1c98-4d8e-a54e-20143dbd4f99 \
+    --exclude-group-name "fin*" 
+```
+
+Multiple flags are collected together. In the given example, based on the 
+two `default-owner` flags, all the Access Lists imported by the integration will 
+be created with owners `admin` and `[email protected]`.
+
+
 ## tctl plugins rotate awsic
 
 Rotate the bearer token used by Teleport to authenticate with the AWS IAM Identity