[entraid] Add docs to setup integration for air gapped clusters

docs/cspell.json

@@ -59,6 +59,7 @@
     "Elastcsearch",
     "Elasticvue",
     "Entra",
+    "entraid",
     "Exadata",
     "Exfiltrate",
     "Exrch",

docs/pages/admin-guides/teleport-policy/integrations/entra-id.mdx

@@ -42,11 +42,62 @@ 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.
 - Your user must have privileged administrator permissions in the Azure account
+- 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.
 
-## Step 1/3. Start Integration onboarding
+## Entra ID integration operational modes
+
+To begin onboarding, select your preferred setup method. Teleport offers various methods based on your cluster
+configuration and user requirements.
+
+### Automatic Setup with Teleport as OIDC Provider for Entra ID
+
+This method is suitable for Teleport clusters that are publicly accessible and lack Azure credentials on Auth
+server nodes or pods.
+
+In this setup, Teleport is configured as an OpenID Connect (OIDC) identity provider, establishing a trusted
+connection with an Entra ID application created during setup. This trust allows Teleport to authenticate using
+the Entra ID application, accessing permissions tied to it without requiring additional credentials or managed
+identities.
+
+**Requirements:**
+- Direct bidirectional connectivity between Teleport and Azure is necessary for Azure to validate the OIDC
+tokens issued by Teleport.
+
+### Automatic Setup with System Credentials for Entra ID Authentication
+
+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. 
+These credentials must have the following Entra ID permissions:
+
+- `Application.Read.All`
+- `Directory.Read.All`
+- `Policy.Read.All`
+
+**Requirements:**
+- Unidirectional connectivity from Teleport to Azure infrastructure.
+
+### Manual Setup with System Credentials for Entra ID Authentication
+
+This setup mirrors the [**Automatic Setup with System Credentials**](./entra-id.mdx#automatic-setup-with-system-credentials-for-entra-id-authentication) 
+approach but requires manual configuration.
+Users need to complete the necessary steps for Entra ID application setup independently, without relying on automated scripts.
+
+
+
+## Configure Entra ID integration
+
+Please choose the preferred operational mode from the menu below.
+
+<Tabs>
+<TabItem label="Teleport as OIDC provider" >
+
+### Step 1/2. 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".
@@ -59,7 +110,7 @@ In the onboarding wizard, choose a Teleport user that will be assigned as the de
 ![First step of the Entra ID integration onboarding](../../../../img/access-graph/entra-id/integration-wizard-step-1.png)
 </Figure>
 
-## Step 2/3. Grant permissions in Azure and finish onboarding
+### Step 2/2. Grant permissions in Azure and finish onboarding
 
 The wizard will now provide you with a script that will set up the necessary permissions in Azure.
 
@@ -90,7 +141,276 @@ Back in the Teleport Web UI, fill out the required data and click "Finish".
 ![Second step of the Entra ID integration onboarding with required fields filled in](../../../../img/access-graph/entra-id/integration-wizard-step-2-filled.png)
 </Figure>
 
-## Step 3/3. Analyze Entra ID directory in Teleport Access Graph
+</TabItem>
+
+<TabItem label="Automatic setup with system credentials" >
+
+### Step 1/2. Assign permissions to Azure Identity of your Auth Service VMs
+
+To set up the Azure Identity with the necessary permissions:
+
+- `Application.Read.All`
+- `Directory.Read.All`
+- `Policy.Read.All`
+
+Go to your Azure Dashboard, find the identities linked to your Teleport Auth Service VMs,
+and copy the `Object (principal) ID`. Paste this value into `<Var name="Principal ID" />`.
+
+After obtaining the Principal ID, open the [Azure Cloud Shell](https://portal.azure.com/#cloudshell/)
+in PowerShell mode and run the following script to assign the required permissions to `<Var name="Principal ID" />`.
+
+```text
+
+# Connect to Microsoft Graph with the required scopes for directory and app role assignment permissions.
+Connect-MgGraph -Scopes 'Directory.ReadWrite.All', 'AppRoleAssignment.ReadWrite.All'
+
+# Retrieve the managed identity's service principal object using its unique principal ID (UUID).
+$managedIdentity = Get-MgServicePrincipal -ServicePrincipalId '<Var name="Principal ID" />'
+
+# 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'"
+
+# Define the permission scopes that we want to assign to the managed identity.
+# These are Microsoft Graph API permissions required by the managed identity.
+$permissions = @(
+  "Application.Read.All"   # Permission to read applications in the directory
+  "Directory.Read.All"     # Permission to read directory data
+  "Policy.Read.All"        # Permission to read policies within the directory
+)
+
+# Filter and find the app roles in the Microsoft Graph service principal that match the defined permissions.
+# Only include roles where "AllowedMemberTypes" includes "Application" (suitable for managed identities).
+$appRoles = $graphSPN.AppRoles |
+    Where-Object Value -in $permissions |
+    Where-Object AllowedMemberTypes -contains "Application"
+
+# 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, 
+    # 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)
+        ResourceId  = $graphSPN.Id         # The ID of the Microsoft Graph service principal
+        AppRoleId   = $appRole.Id          # The ID of the app role being assigned
+    }
+
+    # Create a new app role assignment for the managed identity, granting it the specified permissions.
+    New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $managedIdentity.Id -BodyParameter $bodyParam
+}
+
+```
+
+Your identity principal `<Var name="Principal ID" />` now has the necessary permissions to list Applications,
+Directories, and Policies.
+
+
+### Step 2/2. Setup Entra ID and Teleport resources
+
+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. 
+`<Var name="Access List Owner"/>` 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 `<Var name="example.teleport.sh:443" />`.
+For clusters running in multiplex mode, this address will be the same as your proxy address.
+
+If your Teleport license includes [Teleport Policy](../teleport-policy.mdx), add the `--access-graph` flag.
+If not, add the `--no-access-graph` flag instead.
+
+```code
+# enable Access Graph integration if your license supports Teleport Policy.
+$ tctl plugins install entraid \
+    --default-owner=<Var name="Access List Owner"/> \
+    [email protected]  \
+    --[no-]access-graph  \ 
+    --use-system-credentials \
+    --auth-server <Var name="example.teleport.sh:443" />
+
+```
+
+Follow the detailed instructions provided by the `tctl plugins install entraid` guide to install and configure the Entra ID plugin.
+This guide will walk you through each step required to enable Entra ID integration within your Teleport environment.
+Be sure to follow each step in the `tctl plugins install entraid` guide closely to complete the installation and configuration.
+
+</TabItem>
+
+        <TabItem label="Manual setup" >
+
+### Step 1/3. Assign permissions to Azure Identity of your Auth Service VMs
+
+To set up the Azure Identity with the necessary permissions:
+
+- `Application.Read.All`
+- `Directory.Read.All`
+- `Policy.Read.All`
+
+Go to your Azure Dashboard, find the identities linked to your Teleport Auth Service VMs,
+and copy the `Object (principal) ID`. Paste this value into `<Var name="Principal ID" />`.
+
+After obtaining the Principal ID, open the [Azure Cloud Shell](https://portal.azure.com/#cloudshell/)
+in PowerShell mode and run the following script to assign the required permissions to `<Var name="Principal ID" />`.
+
+```text
+
+# Connect to Microsoft Graph with the required scopes for directory and app role assignment permissions.
+Connect-MgGraph -Scopes 'Directory.ReadWrite.All', 'AppRoleAssignment.ReadWrite.All'
+
+# Retrieve the managed identity's service principal object using its unique principal ID (UUID).
+$managedIdentity = Get-MgServicePrincipal -ServicePrincipalId '<Var name="Principal ID" />'
+
+# 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'"
+
+# Define the permission scopes that we want to assign to the managed identity.
+# These are Microsoft Graph API permissions required by the managed identity.
+$permissions = @(
+  "Application.Read.All"   # Permission to read applications in the directory
+  "Directory.Read.All"     # Permission to read directory data
+  "Policy.Read.All"        # Permission to read policies within the directory
+)
+
+# Filter and find the app roles in the Microsoft Graph service principal that match the defined permissions.
+# Only include roles where "AllowedMemberTypes" includes "Application" (suitable for managed identities).
+$appRoles = $graphSPN.AppRoles |
+    Where-Object Value -in $permissions |
+    Where-Object AllowedMemberTypes -contains "Application"
+
+# 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, 
+    # 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)
+        ResourceId  = $graphSPN.Id         # The ID of the Microsoft Graph service principal
+        AppRoleId   = $appRole.Id          # The ID of the app role being assigned
+    }
+
+    # Create a new app role assignment for the managed identity, granting it the specified permissions.
+    New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $managedIdentity.Id -BodyParameter $bodyParam
+}
+
+```
+
+Your identity principal `<Var name="Principal ID" />` now has the necessary permissions to list Applications,
+Directories, and Policies.
+
+
+### Step 2/3. Setup Entra ID Application
+
+In this step, you will manually configure an Entra ID Enterprise Application to be used by the Teleport Auth Connector.
+
+We provide a PowerShell script that creates the specified application, assigns the token signing request, and sets up the necessary SAML parameters.
+
+To proceed, you need to define the following parameters:
+
+- `<Var name="Application name" />`: The Entra ID Application name, typically set to `Teleport your.cluster.address`.
+- `<Var name="example.teleport.sh:443" />`: Your Teleport Proxy address.
+- `<Var name="Auth Connector Name" />`: 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 
+PowerShell mode, or use the session created in the previous step.
+
+```text
+# Connect to Microsoft Graph with required scopes for application creation and app role assignment permissions.
+Connect-MgGraph -Scopes "Application.ReadWrite.All", "AppRoleAssignment.ReadWrite.All"
+
+# Import the Microsoft Graph module for managing applications.
+Import-Module Microsoft.Graph.Applications
+
+# Define application parameters, including the display name.
+$params = @{
+	displayName = '<Var name="Application name" />'  # Set the display name of the new application.
+}
+
+# Set the SAML application template ID.
+# This ID corresponds to a non-gallery SAML application template.
+$applicationTemplateId = "8adf8e6e-67b2-4cf2-a259-e3dc5476c621"
+
+# Instantiate the application template to create a new application and its service principal.
+$app = Invoke-MgInstantiateApplicationTemplate -ApplicationTemplateId $applicationTemplateId -BodyParameter $params
+
+# Extract the Application ID, Object ID, and Service Principal ID of the newly created application.
+$appId = $app.Application.AppId       # The unique identifier for the application (client ID).
+$objectId = $app.Application.Id       # The unique object ID for the application in Azure AD.
+$servicePrincipal = $app.ServicePrincipal.Id  # The unique object ID for the service principal.
+
+# Define parameters for the token signing certificate used for SAML.
+$principalTokenSigningCertificateParams = @{
+	displayName = "CN=azure-sso"  # Common Name (CN) for the SAML token signing certificate.
+}
+
+# Add a token signing certificate to the service principal, which is required for SAML authentication.
+$cert = Add-MgServicePrincipalTokenSigningCertificate -ServicePrincipalId $servicePrincipal -BodyParameter $principalTokenSigningCertificateParams
+
+# Extract the thumbprint of the certificate, which will be used to configure SAML.
+$thumbprint = $cert.Thumbprint
+
+# Set additional SAML-specific properties for the service principal.
+$updateServicePrincipalParams = @{
+	preferredSingleSignOnMode = "saml"                    # Set SAML as the single sign-on mode.
+	preferredTokenSigningKeyThumbprint = $thumbprint      # Use the thumbprint of the added certificate for token signing.
+	appRoleAssignmentRequired = $false                    # Allow app access without explicit app role assignments.
+}
+
+# Update the service principal with the SAML configuration.
+Update-MgServicePrincipal -ServicePrincipalId $servicePrincipal -BodyParameter $updateServicePrincipalParams
+
+# Define the URL for the proxy (Teleport Auth Service address).
+# This URL will be used as the Redirect URI and Identifier URI.
+$proxyURL = 'https://<Var name="example.teleport.sh:443" />'.TrimEnd("/").TrimEnd(":443")  # Remove the default 443 port for standard formatting.
+$acsURL = '$proxyURL/v1/webapi/saml/acs/<Var name="Auth Connector Name"/>'
+
+# Define web properties, including the redirect URI for SAML authentication.
+$web = @{
+	redirectUris = @($acsURL)  # Set the application's redirect URI.
+}
+
+# Update the application with the web properties and identifier URI.
+# This enables SAML-based authentication and includes security group claims.
+Update-MgApplication -ApplicationId $objectId -Web $web -GroupMembershipClaims "SecurityGroup" -IdentifierUris @($acsURL)
+
+# Retrieve the tenant ID for display purposes.
+$tenant = Get-AzTenant
+
+# Output the Application ID, Tenant ID, and additional information for reference.
+Write-Output "-------------------------------------------------------" "Application ID: $appId" "Tenant ID: $tenant" "-------------------------------------------------------"
+
+```
+
+### Step 3/3. Setup Teleport resources
+
+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. 
+`<Var name="Access List Owner"/>` 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 `<Var name="example.teleport.sh:443"/>`.
+For clusters running in multiplex mode, this address will be the same as your proxy address.
+
+```code
+# enable Access Graph integration if your license supports Teleport Policy.
+$ tctl plugins install entraid \
+    --default-owner=<Var name="Access List Owner"/> \
+    --auth-connector-name="<Var name="Auth Connector Name"/>" \
+    [email protected]  \
+    --use-system-credentials \
+    --no-access-graph \
+    --manual-setup \
+    --auth-server <Var name="example.teleport.sh:443" />
+
+```
+
+Follow the detailed instructions provided by the `tctl plugins install entraid` guide to install and configure the Entra ID plugin.
+    </TabItem>
+</Tabs>
+
+## Analyze Entra ID directory in Teleport Access Graph
 
 Shortly after the integration onboarding is finished,
 your Entra ID directory will be imported into your Teleport cluster and Access Graph.