From 69df897a10b8e273eaf734fbd2d24d4410e54a89 Mon Sep 17 00:00:00 2001 From: Sakshyam Shah Date: Tue, 14 Oct 2025 12:39:24 -0400 Subject: [PATCH] docs: entra id integration group filters and tctl command reference (#59403) * docs: entra id integration group filters * move group filter docs to advance option page --- .../entra-id/advanced-options.mdx | 84 +++++++++++++++++++ .../identity-governance/entra-id/faq.mdx | 9 +- .../entra-id/getting-started.mdx | 1 + .../entra-id/manual-installation.mdx | 1 + .../entra-id/terraform.mdx | 1 + docs/pages/reference/cli/tctl.mdx | 47 +++++++++++ 6 files changed, 140 insertions(+), 3 deletions(-) create mode 100644 docs/pages/identity-governance/entra-id/advanced-options.mdx diff --git a/docs/pages/identity-governance/entra-id/advanced-options.mdx b/docs/pages/identity-governance/entra-id/advanced-options.mdx new file mode 100644 index 0000000000000..3a0b3f521fc29 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/docs/pages/identity-governance/entra-id/faq.mdx b/docs/pages/identity-governance/entra-id/faq.mdx index 8ccf3d2c40ff1..055179b7c3955 100644 --- a/docs/pages/identity-governance/entra-id/faq.mdx +++ b/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 diff --git a/docs/pages/identity-governance/entra-id/getting-started.mdx b/docs/pages/identity-governance/entra-id/getting-started.mdx index 7bf984c51abe2..e99dfdc4de169 100644 --- a/docs/pages/identity-governance/entra-id/getting-started.mdx +++ b/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. diff --git a/docs/pages/identity-governance/entra-id/manual-installation.mdx b/docs/pages/identity-governance/entra-id/manual-installation.mdx index 1cecaa29e897f..c09069c149466 100644 --- a/docs/pages/identity-governance/entra-id/manual-installation.mdx +++ b/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. diff --git a/docs/pages/identity-governance/entra-id/terraform.mdx b/docs/pages/identity-governance/entra-id/terraform.mdx index a7ad54d825de6..830124d45cadc 100644 --- a/docs/pages/identity-governance/entra-id/terraform.mdx +++ b/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. diff --git a/docs/pages/reference/cli/tctl.mdx b/docs/pages/reference/cli/tctl.mdx index ef8e9a226f57f..312b631feb7aa 100644 --- a/docs/pages/reference/cli/tctl.mdx +++ b/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 + +| 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 \ + --default-owner=root@example.com \ + --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 `root@example.com`. + + ## tctl plugins rotate awsic Rotate the bearer token used by Teleport to authenticate with the AWS IAM Identity