Skip to main content
The Microsoft 365 Terraform Provider supports flexible configuration for authentication, cloud environments, and network settings.

Provider Block

provider "microsoft365" {
  # Cloud Environment
  cloud          = "public"  # public, usgovernment, china
  tenant_id      = "00000000-0000-0000-0000-000000000000"
  
  # Authentication
  client_id      = "00000000-0000-0000-0000-000000000000"
  client_secret  = var.client_secret  # Use variables for secrets
  
  # Network Configuration
  enable_proxy   = false
  proxy_url      = "http://proxy.example.com:8080"
  
  # API Configuration
  use_graph_beta = true
  timeout        = 60
}

Configuration Options

Cloud Environment

cloud
string
default:"public"
The Microsoft cloud environment to use. Supported values:
  • public - Microsoft Public Cloud (default)
  • usgovernment - US Government Cloud (GCC, GCC High, DoD)
  • china - Microsoft China Cloud (21Vianet)
tenant_id
string
required
The Microsoft Entra ID (Azure AD) tenant ID (GUID) for your organization.

Authentication Configuration

The provider supports multiple authentication methods:

Client Credentials (Service Principal)

client_id
string
The Application (client) ID of the Azure AD application/service principal.
client_secret
string
The client secret for the Azure AD application. Note: Store secrets in variables or use secret management tools.
client_certificate_path
string
Path to the client certificate file (.pfx or .p12) for certificate-based authentication.
client_certificate_password
string
Password for the client certificate file (if encrypted).

Interactive Authentication

use_device_code
boolean
default:"false"
Enable device code flow for interactive authentication. Useful for development or when browser access is limited.
use_interactive_browser
boolean
default:"false"
Enable interactive browser authentication. Opens a browser window for user login.

Managed Identity

use_managed_identity
boolean
default:"false"
Enable Azure Managed Identity authentication. Works on Azure VMs, App Services, and other Azure resources.
managed_identity_client_id
string
The client ID of a user-assigned managed identity (optional, uses system-assigned if not specified).

Workload Identity & OIDC

use_oidc
boolean
default:"false"
Enable OpenID Connect (OIDC) authentication. Supports GitHub Actions and Azure DevOps workload identity federation.
oidc_token
string
The OIDC token for workload identity federation.
oidc_token_file_path
string
Path to a file containing the OIDC token.

Azure Developer CLI

use_azure_cli
boolean
default:"false"
Use credentials from the Azure Developer CLI (azd).

API Configuration

use_graph_beta
boolean
default:"false"
Use the Microsoft Graph Beta API endpoint. Set to true to access preview features.
  • false - Use Graph v1.0 API (generally available features)
  • true - Use Graph Beta API (preview features)
timeout
number
default:"60"
Default timeout in seconds for API requests. Individual resources may override this.
retry_max_attempts
number
default:"3"
Maximum number of retry attempts for failed API requests (e.g., throttling, transient errors).
retry_delay
number
default:"2"
Delay in seconds between retry attempts. Uses exponential backoff.

Network Configuration

enable_proxy
boolean
default:"false"
Enable HTTP proxy for API requests.
proxy_url
string
HTTP/HTTPS proxy URL (e.g., http://proxy.example.com:8080).
proxy_username
string
Username for proxy authentication (if required).
proxy_password
string
Password for proxy authentication (if required).
user_agent
string
Custom User-Agent header for API requests. Useful for tracking or compliance.
disable_compression
boolean
default:"false"
Disable HTTP response compression. May be useful for debugging.
max_redirects
number
default:"5"
Maximum number of HTTP redirects to follow.

Telemetry & Logging

disable_telemetry
boolean
default:"false"
Disable telemetry data collection sent to Microsoft.
enable_request_logging
boolean
default:"false"
Enable detailed logging of HTTP requests/responses (for debugging). Warning: May log sensitive data.

Environment Variables

All provider configuration options can be set via environment variables using the prefix M365_:
# Authentication
export M365_TENANT_ID="00000000-0000-0000-0000-000000000000"
export M365_CLIENT_ID="00000000-0000-0000-0000-000000000000"
export M365_CLIENT_SECRET="your-secret-here"

# Cloud Environment
export M365_CLOUD="public"

# API Configuration
export M365_USE_GRAPH_BETA="true"
export M365_TIMEOUT="60"

# Proxy Configuration
export M365_ENABLE_PROXY="true"
export M365_PROXY_URL="http://proxy.example.com:8080"
Environment variables take precedence over provider block configuration.

Authentication Examples

Client Secret (Production)

provider "microsoft365" {
  tenant_id     = var.tenant_id
  client_id     = var.client_id
  client_secret = var.client_secret
}

Client Certificate

provider "microsoft365" {
  tenant_id                  = var.tenant_id
  client_id                  = var.client_id
  client_certificate_path    = "/path/to/cert.pfx"
  client_certificate_password = var.cert_password
}

Managed Identity (Azure VM/App Service)

provider "microsoft365" {
  tenant_id            = var.tenant_id
  use_managed_identity = true
}

OIDC with GitHub Actions

provider "microsoft365" {
  tenant_id     = var.tenant_id
  client_id     = var.client_id
  use_oidc      = true
  oidc_token_file_path = "/var/run/secrets/azure/tokens/azure-identity-token"
}

Device Code (Interactive Development)

provider "microsoft365" {
  tenant_id        = var.tenant_id
  client_id        = var.client_id
  use_device_code  = true
}

Required Permissions

The service principal or user authenticating to the provider requires appropriate Microsoft Graph API permissions. Required permissions vary by resource:

Common Permission Sets

Device Management (Intune):
  • DeviceManagementConfiguration.ReadWrite.All
  • DeviceManagementApps.ReadWrite.All
  • DeviceManagementManagedDevices.ReadWrite.All
Identity & Access:
  • Directory.ReadWrite.All
  • Group.ReadWrite.All
  • User.ReadWrite.All
  • Policy.ReadWrite.ConditionalAccess
Microsoft 365 Apps:
  • Application.ReadWrite.All
  • ServicePrincipalEndpoint.ReadWrite.All
Refer to individual resource documentation for specific permission requirements.

Cloud Environment Details

Microsoft Public Cloud

provider "microsoft365" {
  cloud = "public"
  # Uses graph.microsoft.com
}

US Government Cloud

provider "microsoft365" {
  cloud = "usgovernment"
  # Uses graph.microsoft.us (GCC High/DoD)
}

Microsoft China Cloud

provider "microsoft365" {
  cloud = "china"
  # Uses microsoftgraph.chinacloudapi.cn
}

Best Practices

  • Never hardcode secrets in provider configuration
  • Use Terraform variables and store secrets in:
    • Environment variables
    • HashiCorp Vault
    • Azure Key Vault
    • AWS Secrets Manager
    • Terraform Cloud/Enterprise workspace variables
  • Follow principle of least privilege
  • Create separate service principals for different environments (dev/staging/prod)
  • Regularly audit and rotate credentials
  • Use certificate-based authentication in production for enhanced security
  • Test proxy configuration before production deployment
  • Configure appropriate timeouts for your network conditions
  • Use retry settings to handle transient API failures
  • Enable request logging only in development (may expose sensitive data)
  • Use different tenant IDs for dev/staging/prod environments
  • Leverage Terraform workspaces or separate state files
  • Consider using use_graph_beta only in non-production environments

Troubleshooting

Authentication Issues

Error: Invalid client secret
  • Verify client secret hasn’t expired
  • Check for whitespace or special characters in secret value
  • Ensure service principal has required API permissions
Error: AADSTS700016 (Application not found)
  • Verify client_id and tenant_id are correct
  • Ensure application exists in the correct tenant
  • Check that service principal is enabled

Network Issues

Error: Connection timeout
  • Increase timeout value
  • Verify network connectivity to Microsoft Graph API
  • Check proxy configuration if applicable
Error: Too many requests (429)
  • Microsoft Graph API is throttling requests
  • Provider will automatically retry with exponential backoff
  • Consider spreading operations across multiple terraform apply runs

API Version Issues

Error: Resource not found in v1.0
  • Resource may only be available in beta API
  • Set use_graph_beta = true in provider configuration
  • Check resource documentation for API version requirements

Build docs developers (and LLMs) love