Getting started with Entra ID integration

Report an issue with this page

This guide shows how to configure Entra ID integration in a guided configuration set up.

Teleport will generate a script that will configure your Entra ID tenant with the properties required for the Teleport Entra ID integration.

Prerequisites

• Your user must have privileged administrator permissions in the Microsoft Entra ID tenant.
• Choose Microsoft Graph API authentication method.

Step 1/3: Generate configuration script

Teleport as OIDC provider (Web UI)

In the Teleport Web UI, from the side-navigation, select “Add New > Integration”.

Next, select the “Microsoft Entra ID” tile.

In the Teleport Microsoft Entra ID configuration UI, you will notice a default integration name “entra-id” is already populated for you. You will need to select Teleport user(s) that will be assigned as the default owner of Access Lists that are created for your Entra ID groups.

In the next step, you will be provided with a Entra ID configuration script.

Teleport as OIDC provider (tctl)

To begin integration, run the tctl plugins install entraid command.

tctl plugins install entraid \    --name entra-id-default \    --auth-connector-name entra-id \    --default-owner=Access List Owner \    --auth-server example.teleport.sh:443 

The --name flag specifies the resource name of the Entra ID plugin. The --auth-connector-name flag specifies the name of the auth connector this integration will create. The --default-owner flag specifies default owners for the Access Lists that will be created in Teleport based on the groups imported from the Entra ID.

The command will generate a configuration script in the current directory from where the tctl is invoked.

System credential (tctl)

You will need to grant Azure Identity with the necessary permissions required for the Entra ID integration.

In the Azure Portal, find the identities linked to your Teleport Auth Service, and copy the Principal ID of the identity you wish to update with the new permissions.

After obtaining the Principal ID, open the Azure Cloud Shell in PowerShell mode and run the following script to assign the required permissions to Principal ID.

Assign required permissions to Azure Identity

# 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 '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.ReadWrite.OwnedBy"   # Permission to read application
  "Group.Read.All"     # Permission to read groups
  "User.Read.All"        # Permission to read users
)

# 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 Principal ID now has the necessary permissions to list Applications, Directories, and Policies.

Now, to begin integration, run the tctl plugins install entraid command.

tctl plugins install entraid \    --name entra-id-default \    --auth-connector-name entra-id \    --default-owner=Access List Owner \    --auth-server example.teleport.sh:443 \    --use-system-credentials 

The --name flag specifies the resource name of the Entra ID plugin. The --auth-connector-name flag specifies the name of the auth connector this integration will create. The --default-owner flag specifies default owners for the Access Lists that will be created in Teleport based on the groups imported from the Entra ID. The --use-system-credentials flag specifies the plugin will use the system credential configured for the Auth Service.

The command will generate a configuration script in the current directory from where the tctl is invoked.

Step 2/3: Configure Entra ID

Open Azure Cloud Shell by navigating to shell.azure.com, or by clicking the Cloud Shell icon in the Azure Portal. Make sure to use the bash version of Cloud Shell. Once a Cloud Shell instance opens, paste the Teleport generated bash script that downloads the Teleport binary in your Azure Shell and run the teleport integration configure azure-oidc command. The command performs the following actions:

• Creates an enterprise application.
• Configures Teleport as an OIDC IdP for the application.
• Assigns read-only Microsoft Graph API permissions to read your directory's data (such as users and groups).
• Configures authentication by setting up a Teleport SAML service provider.

Azure Shell
bash -c "$(curl 'https://example.teleport.sh/webapi/scripts/integrations/configure/azureoidc.sh?authConnectorName=entra-id')"

> teleport integration configure azure-oidc --proxy-public-addr=https://example.teleport.sh --auth-connector-name=entra-id ...Success! Use the following information to finish the integration onboarding in Teleport:Tenant ID: entra-tenant-idClient ID: enterprise-app-idSuccess! You can now go back to the Teleport Web UI to use the integration with Azure.

Once the script is done setting up the Entra ID tenant with the necessary properties that are required for the Teleport Entra ID integration, it prints out the Entra ID tenant ID and the client ID of the enterprise application set up by the script.

Step 3/3: Finish plugin installation

Teleport as OIDC provider (Web UI)

Copy the Entra ID tenant ID and enterprise application client ID from the script output and enter it in the Web UI to finish the integration.

Teleport as OIDC provider (tctl)

Copy the Entra ID tenant ID and enterprise application client ID from the script output and enter it in the tctl to finish the integration.

System credential (tctl)

Copy the Entra ID tenant ID and enterprise application client ID from the script output and enter it in the tctl to finish the integration.

The integration is now configured and the Teleport Entra ID service will start importing resources from Entra ID to Teleport.

Next steps

• Take a deeper look into setting up Entra ID auth connector.
• Learn more about Access List management.
• Learn how the Identity Security integration with Entra ID works.
• See FAQs related to the Teleport Entra ID integration.