From 28853818cdfcff45f76c9057651740b4980d484b Mon Sep 17 00:00:00 2001 From: Matt Brock Date: Tue, 4 Feb 2025 10:22:17 -0600 Subject: [PATCH] Initial docs for Azure integration (#51631) * Initial docs for Azure integration * Linting * Fixing multiline issue * Adding variables * A few more nitpicks * Apply suggestions from code review Suggestions from @ptgott Co-authored-by: Paul Gottschling * PR feedback * Rewriting verification instructions * Updating wording for access graph verification --------- Co-authored-by: Paul Gottschling --- .../teleport-policy/crown-jewels.mdx | 6 +- .../teleport-policy/integrations/aws-sync.mdx | 48 +++---- .../integrations/azure-sync.mdx | 121 ++++++++++++++++++ .../teleport-policy/integrations/entra-id.mdx | 44 +++---- .../teleport-policy/integrations/gitlab.mdx | 14 +- .../integrations/ssh-keys-scan.mdx | 7 +- .../teleport-policy/teleport-policy.mdx | 9 +- 7 files changed, 177 insertions(+), 72 deletions(-) create mode 100644 docs/pages/admin-guides/teleport-policy/integrations/azure-sync.mdx diff --git a/docs/pages/admin-guides/teleport-policy/crown-jewels.mdx b/docs/pages/admin-guides/teleport-policy/crown-jewels.mdx index cfb4d101bef..51f476f15a7 100644 --- a/docs/pages/admin-guides/teleport-policy/crown-jewels.mdx +++ b/docs/pages/admin-guides/teleport-policy/crown-jewels.mdx @@ -27,11 +27,9 @@ log in via Teleport Auth Connectors. Check [Access Graph page](teleport-policy.mdx) for details on how to set up Access Graph. -Access Graph is a feature of the [Teleport Policy](https://goteleport.com/platform/policy/) product -available to Teleport Enterprise edition customers. +Access Graph is a feature of the [Teleport Policy](https://goteleport.com/platform/policy/) product available to Teleport Enterprise edition customers. -After logging in to the Teleport UI, navigate to the Management tab. If enabled, Access Graph options can be found -under the Permission Management section. +To verify the availability of the Access Graph, ensure that the Policy icon is present in the navigation sidebar. ## Required RBAC permissions diff --git a/docs/pages/admin-guides/teleport-policy/integrations/aws-sync.mdx b/docs/pages/admin-guides/teleport-policy/integrations/aws-sync.mdx index 421a732a443..6d417d55be9 100644 --- a/docs/pages/admin-guides/teleport-policy/integrations/aws-sync.mdx +++ b/docs/pages/admin-guides/teleport-policy/integrations/aws-sync.mdx @@ -3,30 +3,27 @@ title: Discover AWS Access Patterns with Teleport Policy description: Describes how to import and visualize AWS accounts access patterns using Teleport Policy and Access Graph. --- -Teleport Policy streamlines and centralizes access management across your entire infrastructure. You can view access relationships in seconds, +Teleport Policy streamlines and centralizes access management across your entire infrastructure. You can view access relationships in seconds, viewing unified, up-to-date relationships and policies between all users, groups, and computing resources. -Teleport Policy with Access Graph offers insights into access patterns within your AWS account. By scanning IAM -permissions, users, groups, resources, and identities, it provides a visual representation and aids in +Teleport Policy with Access Graph offers insights into access patterns within your AWS account. By scanning IAM +permissions, users, groups, resources, and identities, it provides a visual representation and aids in enhancing the permission model within your AWS environment. This functionality enables you to address queries such as: - What resources are accessible to AWS users and roles? - Which resources can be reached via identities associated with EC2 instances? - What AWS resources can Teleport users access when connecting to EC2 nodes? -Utilizing the Access Graph to analyze IAM permissions within an AWS account necessitates the setup of the Access Graph (AG) +Utilizing the Access Graph to analyze IAM permissions within an AWS account necessitates the setup of the Access Graph service, a Discovery Service, and integration with your AWS account. -Access Graph is a feature of the [Teleport Policy](https://goteleport.com/platform/policy/) product that is +Access Graph is a feature of the [Teleport Policy](https://goteleport.com/platform/policy/) product that is available to Teleport Enterprise customers. -After logging in to the Teleport UI, go to the Management tab. If enabled, -Access Graph options can be found under the Permission Management section. - ## How it works Access Graph discovers AWS access patterns, synchronizes various AWS resources, -including IAM Policies, Groups, Users, User Groups, EC2 instances, EKS clusters, and RDS databases. +including IAM Policies, Groups, Users, User Groups, EC2 instances, EKS clusters, and RDS databases. These resources are then visualized using the graph representation detailed in the [Teleport Policy usage page](../policy-how-to-use.mdx). @@ -34,7 +31,7 @@ The importing process involves two primary steps: ### Polling Cloud APIs -The Teleport Discovery Service continuously scans the configured AWS accounts. +The Teleport Discovery Service continuously scans the configured AWS accounts. At intervals of 15 minutes, it retrieves the following resources from your AWS account: - Users @@ -47,13 +44,13 @@ At intervals of 15 minutes, it retrieves the following resources from your AWS a - RDS Databases - S3 Buckets -Once all the necessary resources are fetched, the Teleport Discovery Service pushes them to the +Once all the necessary resources are fetched, the Teleport Discovery Service pushes them to the Access Graph, ensuring that it remains updated with the latest information from your AWS environment. ### Importing resources Teleport Policy’s Access Graph feature delves into the IAM policies, identities, -and resources retrieved from your AWS account, crafting a +and resources retrieved from your AWS account, crafting a graphical representation thereof. @@ -72,22 +69,20 @@ how to set up Access Graph. -If you have a managed Teleport Enterprise cluster, you can disregard -this step, as managed Teleport Enterprise already operates a properly configured +If you have a cloud-hosted Teleport Enterprise cluster, you can disregard +this step, as cloud-hosted Teleport Enterprise already operates a properly configured Discovery Service within your cluster. -To activate the Teleport Discovery Service, -add the provided snippet to your Auth Service configuration. -This service monitors dynamic `discovery_config` resources -that are set up with the `discovery_group` matching -. - +To activate the Teleport Discovery Service, add a top level discovery_service section to the teleport.yaml +config used by the Auth Service. This service monitors dynamic `discovery_config` resources that are set up +with the `discovery_group` matching. +. ```yaml discovery_service: enabled: true - discovery_group: + discovery_group: ``` Notice that if you already operate a Discovery Service within your cluster, @@ -100,14 +95,11 @@ it's possible to reuse it as long as the following requirements are met: ## Step 2/2. Set up Access Graph AWS Sync To initiate the setup wizard for configuring AWS Sync, access the Teleport UI, -navigate to the Management tab, and choose the Access Graph option within the -Permission Management section. +click the Policy sidebar button, and then click Integrations. -If both Teleport and Access Graph support AWS sync, you'll notice a new button -adjacent to the Access Graph navigation bar labeled `Analyze AWS IAM policies with Access Graph`. - -You'll be prompted to create a new Teleport AWS integration if you haven't configured -one already. Alternatively, you can opt for a previously established integration. +Click the "Setup new integration" button, and then select "AWS". You'll be prompted +to create a new Teleport AWS integration if you haven't configured one already. +Alternatively, you can opt for a previously established integration. Upon selecting or creating the integration, you'll be instructed to execute a bash script within your AWS Cloud Shell to configure the necessary permissions. diff --git a/docs/pages/admin-guides/teleport-policy/integrations/azure-sync.mdx b/docs/pages/admin-guides/teleport-policy/integrations/azure-sync.mdx new file mode 100644 index 00000000000..0783c1e9ff0 --- /dev/null +++ b/docs/pages/admin-guides/teleport-policy/integrations/azure-sync.mdx @@ -0,0 +1,121 @@ +--- +title: Discover Azure Access Patterns with Teleport Policy +description: Describes how to import and visualize Azure subscription access patterns using Teleport Policy and Access Graph. +--- + +Teleport Policy streamlines and centralizes access management across your entire infrastructure. You can view access +relationships in seconds, viewing unified, up-to-date relationships and policies between all users, groups, and +computing resources. + +Teleport Policy with Access Graph offers insights into access patterns within your Azure subscription. By scanning +users, groups, service principals, and role definitions, it provides a visual representation and aids in enhancing the permission model +within your Azure environment. This functionality enables you to address queries such as: + +- What resources are accessible to Azure users and roles? +- Which groups belong to other groups and how does that impact resource access? +- How broad or narrow is scoping across the subscription when assigning roles to users and groups? + +Utilizing the Access Graph to analyze permissions within an Azure subscription necessitates the setup of the Access +Graph service, a Discovery Service, and integration with your Azure subscription. + +Access Graph is a feature of the [Teleport Policy](https://goteleport.com/platform/policy/) product that is available to Teleport Enterprise customers. + +## How it works + +Access Graph discovers Azure access patterns, synchronizes various Azure resources, +including users, groups, service principals, and role definitions. +These resources are then visualized using the graph representation detailed in the +[Teleport Policy usage page](../policy-how-to-use.mdx). + +The importing process involves two primary steps: + +### Polling Cloud APIs + +The Teleport Discovery Service continuously scans the configured Azure subscriptions. At configurable intervals as +low as 15 minutes, it retrieves the following resources from your Azure account: + +- Users +- Groups +- Service Principals +- Role Definitions +- Role Assignments +- Virtual Machines + +Once all the necessary resources are fetched, the Teleport Discovery Service pushes them to Access Graph, ensuring +that it remains updated with the latest information from your Azure environment. + +### Importing resources + +Teleport Policy’s Access Graph feature visualizes the resources retrieved from your Azure subscription. + +## Prerequisites + +- A running Teleport Enterprise cluster v17.2.1 or later. +- Teleport Policy enabled for your account. +- For self-hosted clusters: + - Ensure that an up-to-date `license.pem` is used in the Auth Service configuration. + - A running Access Graph node v1.27.0 or later. Check the [Teleport Policy page](../teleport-policy.mdx) for details on +how to set up Access Graph. + - The node running the Access Graph service must be reachable from the Teleport Auth Service. + +## Step 1/2. Configure the Discovery Service (Self-hosted only) + + + If you have a cloud-hosted Teleport Enterprise cluster, you can disregard + this step, as cloud-hosted Teleport Enterprise already operates a properly configured + Discovery Service within your cluster. + + +To activate the Teleport Discovery Service, add a top level discovery_service section to the `teleport.yaml` +config file used by the Auth Service. This service monitors dynamic `discovery_config` resources that are set up +with the `discovery_group` matching. + +. +```yaml +discovery_service: + enabled: true + discovery_group: +``` + +Notice that if you already operate a Discovery Service within your cluster, +it's possible to reuse it as long as the following requirements are met: + +- On step 2, you match the `discovery_group` with the existing Discovery Service's +`discovery_group`. +- Access Graph service is reachable from the machine where Discovery Service runs. + +Once the Auth Service is configured, add the following to the Discovery Service configuration file to enable it +for fetching Azure resources: + +```yaml +discovery_service: + access_graph: + azure: + - subscription_id: +``` + +The Discovery Service will now periodically fetch resources from your Azure subscription. + +## Step 2/2. Set up Access Graph Azure Sync + +To configure the Teleport Discovery Service, the Azure managed identity running the Discovery Service within +Azure must be given the right permissions to fetch Azure resources. Within the +[Azure Cloud Shell](https://portal.azure.com/#cloudshell/), download the +[Teleport binary](https://goteleport.com/download/#install-links) in `.tar.gz` format and use it to run the integration +command. + +You'll need to specify the following in the commands/configuration below: +- +- +- +- + +Download and extract the Teleport binary: +```shell +curl -L https://cdn.teleport.dev/teleport-v-linux-amd64-bin.tar.gz | tar xz +``` + +Run the integration command: +```shell +./teleport integration configure access-graph azure --principal-id --role-name --subscription-id +``` diff --git a/docs/pages/admin-guides/teleport-policy/integrations/entra-id.mdx b/docs/pages/admin-guides/teleport-policy/integrations/entra-id.mdx index dd6d30a6c12..cd6df93ec09 100644 --- a/docs/pages/admin-guides/teleport-policy/integrations/entra-id.mdx +++ b/docs/pages/admin-guides/teleport-policy/integrations/entra-id.mdx @@ -45,8 +45,8 @@ how to set up Access Graph. - For OIDC setup, the Teleport cluster must be publicly accessible from the internet. - For air gapped clusters, `tctl` must be v16.4.7 or later. -To verify that Access Graph is set up correctly for your cluster, sign in to the Teleport Web UI and navigate to the Management tab. -If enabled, the Access Graph menu item will appear in the Permission Management section. +To verify that Access Graph is set up correctly for your cluster, sign in to the Teleport Web UI, click the +Policy sidebar button, and then the Browse menu item. Identities, resources, etc. should be listed. ## Step 1/3. Choose a setup method @@ -76,7 +76,7 @@ tokens issued by Teleport. Designed for air-gapped Teleport clusters that are not publicly accessible, this setup accommodates environments where Azure cannot validate OIDC tokens issued by Teleport. -Instead, Teleport relies on Azure credentials available on the VMs where Teleport Auth Service is running. +Instead, Teleport relies on Azure credentials available on the VMs where Teleport Auth Service is running. These credentials must have the following Entra ID permissions: - `Application.Read.All` @@ -88,10 +88,10 @@ These credentials must have the following Entra ID permissions: ### Manual setup -This setup describes how to manually configure Entra ID integration without relying on automated scripts +This setup describes how to manually configure Entra ID integration without relying on automated scripts to setup Entra ID Application. -This guide covers the +This guide covers the [**Automatic Setup with Teleport as OIDC Provider for Entra ID**](./entra-id.mdx#automatic-setup-with-teleport-as-an-oidc-provider-for-entra-id) and [**Automatic Setup with System Credentials**](./entra-id.mdx#automatic-setup-with-system-credentials-for-entra-id-authentication) setup but has a limitation of not being possible to enable the [Teleport Policy](../teleport-policy.mdx) integration. @@ -102,7 +102,7 @@ setup but has a limitation of not being possible to enable the [Teleport Policy] -### Start integration onboarding +### Start integration onboarding To start the onboarding process, access the Teleport Web UI, navigate to the "Access Management" tab, and choose "Enroll New Integration", then pick "Microsoft Entra ID". @@ -177,7 +177,7 @@ Connect-MgGraph -Scopes 'Directory.ReadWrite.All', 'AppRoleAssignment.ReadWrite. # Retrieve the managed identity's service principal object using its unique principal ID (UUID). $managedIdentity = Get-MgServicePrincipal -ServicePrincipalId '' -# Set the Microsoft Graph enterprise application object. +# Set the Microsoft Graph enterprise application object. # This is a service principal object representing Microsoft Graph in Azure AD with a specific app ID. $graphSPN = Get-MgServicePrincipal -Filter "AppId eq '00000003-0000-0000-c000-000000000000'" @@ -197,7 +197,7 @@ $appRoles = $graphSPN.AppRoles | # Iterate over each app role to assign it to the managed identity. foreach ($appRole in $appRoles) { - # Define the parameters for the role assignment, including the managed identity's principal ID, + # Define the parameters for the role assignment, including the managed identity's principal ID, # the Microsoft Graph service principal's resource ID, and the specific app role ID. $bodyParam = @{ PrincipalId = $managedIdentity.Id # The ID of the managed identity (service principal) @@ -221,9 +221,9 @@ Directories, and Policies. The Teleport `tctl` command provides an interactive guide to set up and configure Entra ID integration for air-gapped clusters. -To use it, ensure you have `tctl` version v16.4.7 or later and select a default list of Access List owners. -These specified Teleport users will become the owners of Access Lists imported by the Entra ID integration. -`` must be an existing Teleport user. +To use it, ensure you have `tctl` version v16.4.7 or later and select a default list of Access List owners. +These specified Teleport users will become the owners of Access Lists imported by the Entra ID integration. +`` must be an existing Teleport user. If you prefer multiple Access List owners, repeat the flag with each user, e.g., `--default-owner=owner1 --default-owner=owner2`. You'll also need to provide the Teleport Auth Service address as ``. @@ -253,7 +253,7 @@ Be sure to follow each step in the `tctl plugins install entraid` guide closely This step configures the Azure Identity on your Auth Service machine with the required Entra ID permissions. -Follow this step only if you want to use system-available credentials to authenticate Teleport with Entra ID. +Follow this step only if you want to use system-available credentials to authenticate Teleport with Entra ID. If you intend to use Teleport as an OIDC provider for Entra ID, you can skip this step. @@ -281,7 +281,7 @@ Connect-MgGraph -Scopes 'Directory.ReadWrite.All', 'AppRoleAssignment.ReadWrite. # Retrieve the managed identity's service principal object using its unique principal ID (UUID). $managedIdentity = Get-MgServicePrincipal -ServicePrincipalId '' -# Set the Microsoft Graph enterprise application object. +# Set the Microsoft Graph enterprise application object. # This is a service principal object representing Microsoft Graph in Azure AD with a specific app ID. $graphSPN = Get-MgServicePrincipal -Filter "AppId eq '00000003-0000-0000-c000-000000000000'" @@ -301,7 +301,7 @@ $appRoles = $graphSPN.AppRoles | # Iterate over each app role to assign it to the managed identity. foreach ($appRole in $appRoles) { - # Define the parameters for the role assignment, including the managed identity's principal ID, + # Define the parameters for the role assignment, including the managed identity's principal ID, # the Microsoft Graph service principal's resource ID, and the specific app role ID. $bodyParam = @{ PrincipalId = $managedIdentity.Id # The ID of the managed identity (service principal) @@ -333,7 +333,7 @@ To proceed, you need to define the following parameters: - ``: Your Teleport Proxy address. - ``: The Teleport Auth Connector name, usually set to `entra-id`. -Once these parameters are defined, open the [Azure Cloud Shell](https://portal.azure.com/#cloudshell/) in +Once these parameters are defined, open the [Azure Cloud Shell](https://portal.azure.com/#cloudshell/) in PowerShell mode, or use the session created in the previous step.
` must be an existing Teleport user. +To use it, ensure you have `tctl` version v16.4.7 or later and select a default list of Access List owners. +These specified Teleport users will become the owners of Access Lists imported by the Entra ID integration. +`` must be an existing Teleport user. If you prefer multiple Access List owners, repeat the flag with each user, e.g., `--default-owner=owner1 --default-owner=owner2`. You'll also need to provide the Teleport Auth Service address as ``. diff --git a/docs/pages/admin-guides/teleport-policy/integrations/gitlab.mdx b/docs/pages/admin-guides/teleport-policy/integrations/gitlab.mdx index 3a25ef7ad22..5e78f3e604a 100644 --- a/docs/pages/admin-guides/teleport-policy/integrations/gitlab.mdx +++ b/docs/pages/admin-guides/teleport-policy/integrations/gitlab.mdx @@ -13,9 +13,6 @@ your GitLab environment. This functionality enables you to answer queries such a Access Graph is a feature of the [Teleport Policy](https://goteleport.com/platform/policy/) product available to Teleport Enterprise edition customers. -After logging in to the Teleport UI, navigate to the Management tab. If enabled, Access Graph options can be found -under the Permission Management section. - ## How it works Access Graph synchronizes various GitLab resources, including users, projects and groups. @@ -42,7 +39,6 @@ Access Graph, ensuring that it remains updated with the latest information from Teleport Policy’s Access Graph feature delves into the resources imported and their relationships, crafting a graphical representation thereof. - ## Prerequisites - A running Teleport Enterprise cluster v14.3.20/v15.3.1/v16.0.0 or later. @@ -84,12 +80,12 @@ The token will be used in the next step to configure the GitLab Sync integration ## Step 2/3. Set up Access Graph GitLab Sync -To initiate the setup wizard for configuring GitLab Sync, access the Teleport UI, -navigate to the Management tab, and choose the Access Graph option within the -Permission Management section. +To initiate the setup wizard for configuring Gitlab Sync, access the Teleport UI, +click the Policy sidebar button, and then click Integrations. -In the Access Graph page, you'll notice a button labeled `Integrations`. Click on it to -to access the Integrations page. On the Integrations page, click on the `Setup` button next to the GitLab integration. +Click the "Setup new integration" button, and then select "Gitlab". You'll be prompted +to create a new Teleport Gitlab integration if you haven't configured one already. +Alternatively, you can opt for a previously established integration. You'll be prompted to provide the GitLab token created in Step 1 and the GitLab instance domain. Once the token is successfully validated, you'll be able to see the resources imported in Access Graph. diff --git a/docs/pages/admin-guides/teleport-policy/integrations/ssh-keys-scan.mdx b/docs/pages/admin-guides/teleport-policy/integrations/ssh-keys-scan.mdx index c9c212a1798..a72c9c0717b 100644 --- a/docs/pages/admin-guides/teleport-policy/integrations/ssh-keys-scan.mdx +++ b/docs/pages/admin-guides/teleport-policy/integrations/ssh-keys-scan.mdx @@ -13,11 +13,10 @@ This functionality gives you insights into the following areas: - Which users have SSH private keys that grant access to SSH servers? - Which laptops have unprotected SSH private keys? -Access Graph is a feature of the [Teleport Policy](https://goteleport.com/platform/policy/) product -available to Teleport Enterprise edition customers. +Access Graph is a feature of the [Teleport Policy](https://goteleport.com/platform/policy/) product available to Teleport Enterprise edition customers. -After logging in to the Teleport UI, navigate to the Management tab. If enabled, Access Graph options can be found -under the Permission Management section. +To verify that Access Graph is set up correctly for your cluster, sign in to the Teleport Web UI, click the +Policy sidebar button, and then the Browse menu item. Identities, resources, etc. should be listed. ## How it works diff --git a/docs/pages/admin-guides/teleport-policy/teleport-policy.mdx b/docs/pages/admin-guides/teleport-policy/teleport-policy.mdx index 1d9d659a1c8..137f94b226d 100644 --- a/docs/pages/admin-guides/teleport-policy/teleport-policy.mdx +++ b/docs/pages/admin-guides/teleport-policy/teleport-policy.mdx @@ -3,7 +3,7 @@ title: Teleport Policy description: A reference for Access Graph with Teleport Policy. --- -Teleport Policy unifies management of access policies across your infrastructure. +Teleport Policy unifies management of access policies across your infrastructure. It hardens your access controls and visually shows up-to-date relationships and policies of all users, groups, and computing resources It can help you answer questions like: @@ -14,15 +14,14 @@ It can help you answer questions like: ## Getting started with Teleport Policy Teleport Policy is a separately licensed product and is available to Teleport Enterprise customers. -Access Graph is a major capability of Teleport Policy that visually shows the relationships of +Access Graph is a major capability of Teleport Policy that visually shows the relationships of policies of users, groups, and computing resources. -After logging into the Teleport UI, go to the Management tab. If enabled, Teleport Policy’s Access Graph options -can be found under the Permission Management section. +To verify the availability of the Access Graph, ensure that the Policy icon is present in the navigation sidebar. Note: For managed Enterprise customers, Teleport Policy is enabled by default. -If you are a self-hosted Teleport customer, you will need to [deploy the Access Graph Service](../deploy-a-cluster/access-graph/access-graph.mdx) and ensure you have an updated +If you are a self-hosted Teleport customer, you will need to [deploy the Access Graph Service](../deploy-a-cluster/access-graph/access-graph.mdx) and ensure you have an updated `license.pem` with Teleport Policy enabled to use it.