Skip to main content
Version: 19.x (unreleased)

Configure the Entra ID Integration using Terraform

Report an issue with this page

This guide shows you how to integrate Teleport with Microsoft Entra ID using Terraform and tctl. You will configure the Entra ID side of the configuration using Terraform and install the Entra ID plugin in Teleport using tctl.

For other supported configuration methods, see the following guides:

If you are new to the Teleport Entra ID integration, start by reading how the integration works.

Prerequisites​

  • Teleport Identity Governance enabled for your Teleport cluster.
  • Your user must have privileged administrator permissions in Microsoft Azure and Entra ID tenant.

Step 1/3. Prepare Terraform​

Clone the Teleport Entra ID integration example module, which is available in the Teleport Github repository.

The example provides a configurable Terraform module to set up Entra ID tenant with attributes that are required for the Teleport Entra ID integration. The module is based on the azuread provider.

The example expects an authenticated Azure CLI session available in your environment. The azuread provider expects tenant-level access, so the Azure CLI must be authenticated using the --allow-no-subscriptions flag.

$ az login --allow-no-subscriptions

Step 2/3. Configure and apply​

The example Terraform module provides Entra ID configuration options are based on the Microsoft Graph API authentication method you wish to configure for the Teleport Entra ID integration.

Teleport supports two types of Microsoft Graph API authentication methods: Teleport as an OIDC IdP and system credentials.

Setting up Teleport as an OIDC IdP option is the only supported method if you are using Teleport Cloud. If you have a self-hosted Teleport Cluster, you must ensure that the Teleport Proxy Service is publicly accessible.

Alternatively, using system credentials setup is best suited if you have a self-hosted Teleport cluster or when the Teleport Proxy Service is not publicly accessible. You can learn more about the differences on these authentication methods on this page.

At minimum, the Terraform example expects the following input variables:

  • app_name: Name of the enterprise application that will be created in Entra ID.
  • proxy_service_address: Teleport Proxy Service host, e.g., example.teleport.sh.
  • certificate_expiry_date: SAML assertion signing certificate expiry date. E.g., 2026-05-01T01:02:03Z. Note that an expired certificate will prevent users from signing in to Teleport. If it expires, you will need to update this value in Terraform, as well as in the SAML-based Teleport Auth Connector created for the Entra ID.

Create tfvars with your inputs.

cat > variables.auto.tfvars << EOF
app_name                = "Enterprise app name"
proxy_service_address   = "Teleport Proxy host"
certificate_expiry_date = "SAML certificate expiry"
EOF

Applying this plan will perform the following actions:

  • Create an enterprise application.
  • Set up SAML SSO for Teleport.
  • Grant Microsoft Graph API permissions necessary for the Teleport Entra ID integration.
  • Setup Teleport as an OIDC-based federated credential provider.

After you configure tfvars, apply the plan.

$ terraform plan 

$ terraform apply

Once the changes are applied, the Terraform module will produce an application client ID and Entra ID tenant ID values as an output. You will need these values in the next step.

Entra ID is now configured with the required attributes needed for the Teleport Entra ID integration.

Step 3/3. Install the Entra ID plugin​

To complete the integration setup, install the Entra ID plugin in Teleport. The plugin can be installed with the tctl plugins install entraid command.

tctl plugins install entraid \    --name entra-id-default \    --auth-connector-name entra-id \    --default-owner=Access List Owner \    --no-access-graph \    --manual-setup
  • --name flag specifies the resource name of the Entra ID plugin.
  • --auth-connector-name flag specifies the name of the auth connector this integration will create.
  • --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.
  • --no-access-graph flag specifies Identity Security integration is to be skipped.
  • --use-system-credentials flag specifies to use system credential configured using Managed Identity. Use this flag only if you with to set up system credential based authentication.
  • --manual-setup flag specifies a manual Entra ID configuration is selected by the user.

tctl will then prompt for an Entra ID tenant ID and an application client ID of the enterprise application created by using Terraform in step 2.

After you enter these values, the installation command will create a SAML Auth Connector in Teleport, along with the plugin service that imports users and groups from Entra ID to Teleport.

Next steps​