Skip to main content

Device Trust is available only with Teleport Enterprise. Start your free trial.

Start your free trial
Version: 19.x (unreleased)

Microsoft Intune Integration

Report an Issue

The Device Trust Microsoft Intune integration lets you automatically sync your managed devices from Intune into Teleport, including macOS, Windows, Linux, iOS, and iPadOS devices. In this guide, you will set up the Microsoft Intune integration.

How it works​

The Teleport Intune integration periodically reads your managed device inventory from Microsoft Intune and syncs it to Teleport. It performs both incremental (called "partial") and full syncs, as well as removals from Teleport if a device is removed from Intune.

Syncing devices from Intune is an inventory management step, equivalent to automatically running the corresponding tctl devices add commands.

See the Device Trust guide for fundamental Device Trust concepts and behavior.

note

The Microsoft Intune integration is available exclusively as a hosted plugin through the Teleport Web UI or tctl. Running it as a standalone service is not currently supported.

Prerequisites​

  • A running Teleport Enterprise cluster accessible at a hostname with a valid TLS certificate. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.

  • The tctl and tsh clients.

    Installing tctl and tsh clients

    1. Determine the version of your Teleport cluster. The tctl and tsh clients must be at most one major version behind your Teleport cluster version. Send a GET request to the Proxy Service at /v1/webapi/find and use a JSON query tool to obtain your cluster version. Replace teleport.example.com:443 with the web address of your Teleport Proxy Service:

      TELEPORT_DOMAIN=teleport.example.com:443
      TELEPORT_VERSION="$(curl -s https://$TELEPORT_DOMAIN/v1/webapi/find | jq -r '.server_version')"

    2. Follow the instructions for your platform to install tctl and tsh clients:

      Download the signed macOS .pkg installer for Teleport, which includes the tctl and tsh clients:

      curl -O https://cdn.teleport.dev/teleport-${TELEPORT_VERSION?}.pkg

      In Finder double-click the pkg file to begin installation.

      danger

      Using Homebrew to install Teleport is not supported. The Teleport package in Homebrew is not maintained by Teleport and we can't guarantee its reliability or security.

    Connecting with TLS routing disabled

    This guide's commands assume your Teleport cluster uses TLS routing (proxy_listener_mode: multiplex), where the tctl and tsh clients reach every Teleport service through the Proxy Service's web address on port 443. If you're not sure whether this applies to your cluster, check with whoever manages it.

    If your cluster uses separate listener ports instead, adjust ports as follows:

    • tsh commands (e.g., tsh login --proxy=...): continue using the Proxy Service web address on port 3080 (or 443 if behind a load balancer). Do not change these to port 3025.

    • Direct tctl or Auth Service API commands: use port 3025 for the Auth Service gRPC listener:

      tctl status --auth-server=teleport.example.com:3025
  • Access to Microsoft Entra ID with the Global Administrator role, or with both the Application Administrator and Privileged Role Administrator roles. Granting the Microsoft Graph permission in Step 2 requires Global Administrator or Privileged Role Administrator.
  • An active Microsoft Intune subscription with managed devices.

Step 1/3. Register an application in Microsoft Entra ID​

This step is only needed for setup using an app registration, either with a client secret or with Azure Workload Identity. If you're using system credentials with a managed identity, skip to Step 2/3.

Create and configure an application in Microsoft Entra ID that Teleport will use to access your Intune data:

  1. Sign in to the Microsoft Entra admin center with an account that has Global Administrator or Application Administrator permissions.
  2. Navigate to Entra ID > App registrations and select New registration.
  3. Configure the application:
    • Name: enter a descriptive name (e.g., "Teleport Intune Integration").
    • Supported account types: select "Accounts in this organizational directory only".
    • Redirect URI: leave this blank and click "Register".
  4. Once created, copy the Application (client) ID from the Overview page. You'll need this when configuring the integration in Teleport.

In case of problems with the above instructions, follow the official docs for registering an application.

Step 2/3. Grant the Microsoft Graph permission​

The integration authenticates as the managed identity of the Teleport Auth Service, either on Azure VMs or with Azure Workload Identity on AKS.

If the Azure VM running the Auth Service has no managed identity yet, enable a system-assigned identity or attach a user-assigned identity. If the VM has more than one managed identity, set the AZURE_CLIENT_ID environment variable of the Auth Service to the client ID of the identity to use.

To set up the Azure Identity with the necessary permissions:

  • DeviceManagementManagedDevices.Read.All

Go to your Azure Dashboard, find the identity used by your Teleport Auth Service, and copy the Object (principal) ID. Paste this value into 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 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 = @(
  "DeviceManagementManagedDevices.Read.All"   # Permission to read Intune managed devices
)

# 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 read Intune managed devices.

Step 3/3. Configure the Intune integration in Teleport​

  1. Follow the official docs to find your tenant identifier (e.g., contoso.onmicrosoft.com or the tenant GUID).
  2. In the Web UI, navigate to Add New > Integration and select "Microsoft Intune".
  3. Select either System Credentials or Client Secret. On Teleport Cloud, only Client Secret is supported.
  4. Fill in the required information:
    • Primary domain or Microsoft Entra tenant ID: enter your tenant identifier.
    • For a client secret, Application (client) ID: Paste the Application ID you copied in Step 1.
    • For a client secret, Client secret value: Paste the client secret value you copied in Step 2.
  5. Click "Connect Microsoft Intune" to complete the setup.

If you're installing the integration with tctl, set --use-system-credentials to use system credentials, or provide --client-id to use a client secret. tctl prompts for the client secret.

Using system credentials
tctl plugins install intune --tenant=tenant --use-system-credentials
Using a client secret
tctl plugins install intune --tenant=tenant --client-id=Application (client) ID

The integration will begin syncing devices from your Intune inventory within two minutes. Depending on the size of your inventory, the initial sync may take a few minutes to complete.

How syncing works​

Sync schedule​

The Intune integration uses the following fixed schedule that starts when the integration is installed, updated, or when the Auth Service is restarted:

  • Full sync: every 24 hours – fetches all devices from Intune, reconciles the complete inventory and removes missing devices.
  • Partial sync: every 6 hours between full syncs – fetches only devices that have been modified in Intune since the last sync.

The integration tracks the last sync time from Intune to fetch only changed devices during partial syncs.

Device requirements​

For a device to be synced, it must have a serial number, its device registration state must be set to "registered" and its operating system must be either macOS, Windows, Linux, iOS, or iPadOS.

Device ownership and removal​

When syncing inventory, the Intune integration claims ownership of all synced devices. This can be verified by inspecting a device's source field:

# tctl get device/mydevice
kind: device
metadata:
  name: 20ec6373-9e8e-46e0-8f1c-47ad6b06a768
spec:
  asset_tag: mydevice
  os_type: macos
  # ...
  source:
    name: intune
    origin: intune
  update_time: "2023-06-21T19:44:40.40601Z"
version: v1

During full syncs, devices that are no longer present in Intune or have mismatched properties (different serial number or OS type for the same Intune device ID) will be automatically removed from Teleport's inventory.

note

Only devices synced by Intune are subject to automatic deletion. Devices added manually via tctl devices add or synced from other sources won't be deleted by the Intune integration.

For immediate removal of unwanted devices, first lock the device in Teleport, then remove it from Intune:

tctl devices lock --asset-tag=SERIAL_NUMBER --message='reason for locking'
Created a lock with name "a2f1491c-4a3e-4daf-9c83-2fe931668076".

Manual removal via tctl devices rm is possible, but note that if the device is still in the Intune inventory, it'll be recreated during the next sync.

Monitoring the integration​

After configuration, you can monitor the integration status in the Web UI. Navigate to Zero Trust Access > Integrations. If the integration status indicates an error, check the Auth Service logs for errors from the Intune integration.

You can also verify synced devices using the command line:

tctl devices ls
Asset Tag    OS      Source Enroll Status Owner Device ID------------ ------- ------ ------------- ----- ------------------------------------CXXXXXXXXX17 macOS   Intune not enrolled        20ec6373-9e8e-46e0-8f1c-47ad6b06a768CXXXXXXXXX2T macOS   Intune not enrolled        79755778-7cbe-4e2c-83ec-7eaa3d4d7e36CXXXXXXXXX3T Windows Intune not enrolled        665e59d5-393a-4894-841d-edad06329717DXXXXXXXXX01 iPadOS  Intune not enrolled        dd032e90-bfb0-47d5-bce5-e57545f6788fDXXXXXXXXX02 iOS     Intune not enrolled        bf189863-a94a-40dc-9013-d96f8dada2f1(...)

Next steps​

Automatically enroll synced devices on user login with auto-enrollment.