# Getting Started with the Entra ID Integration

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](https://goteleport.com/docs/identity-governance/integrations/entra-id.md#choosing-the-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.

![Entra ID Integration](/docs/assets/images/entra-default-owners-4acdedd47d52fef0b55503d55c37652a.png)

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](https://portal.azure.com/#cloudshell/) 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 Entra ID 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](https://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-id
Client ID: enterprise-app-id
Success! 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.

![Entra ID Integration](/docs/assets/images/entra-finish-9af146e2afa4e0b72eb2337cfbe17515.png)

**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

- [Configure Access](https://goteleport.com/docs/identity-governance/integrations/entra-id/configure-access.md) for Entra ID users.
- Configure [group filters](https://goteleport.com/docs/identity-governance/integrations/entra-id/advanced-options.md#group-filters).
- Learn more about [Access List](https://goteleport.com/docs/identity-governance/access-lists.md) management.
- Take a deeper look into setting up [Entra ID auth connector](https://goteleport.com/docs/zero-trust-access/sso/integrate-idp/entra-id.md).
- Learn how the [Identity Security integration with Entra ID](https://goteleport.com/docs/identity-security/integrations/entra-id.md) works.
- See [FAQs](https://goteleport.com/docs/identity-governance/integrations/entra-id/faq.md) related to the Teleport Entra ID integration.