Client Secret Authentication

The Microsoft 365 provider can use a Service Principal with Client Secret to authenticate to Microsoft 365 services. This is a common authentication method for automated processes and CI/CD pipelines.

How Client Secret Authentication Works

Load Configuration

The provider loads authentication configuration from either Terraform configuration or environment variables (M365_TENANT_ID, M365_CLIENT_ID, M365_CLIENT_SECRET)

Request Token

The provider constructs an OAuth 2.0 token request to Microsoft Entra ID’s token endpoint:

POST https://login.microsoftonline.com/{tenant-id}/oauth2/v2.0/token
Content-Type: application/x-www-form-urlencoded

client_id={client-id}&client_secret={client-secret}&scope=https://graph.microsoft.com/.default&grant_type=client_credentials

Validate Credentials

Microsoft Entra ID validates the client credentials by checking:

Client ID exists
Client secret is correct and not expired
App has been granted the requested permissions

Receive Access Token

If validation succeeds, Entra ID issues an access token in JWT format:

{
  "token_type": "Bearer",
  "expires_in": 3599,
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk..."
}

Make API Requests

The provider uses the access token for Microsoft Graph API requests:

GET https://graph.microsoft.com/v1.0/deviceManagement/deviceConfigurations
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImtpZCI6Imk...

Prerequisites

A Microsoft Entra ID tenant
Permissions to create an app registration in your tenant

Setup

Manual Setup
Using Terraform
Using PowerShell

Create App Registration

Create an app registration in Microsoft Entra ID

Add API Permissions

Navigate to “API permissions” in your app registration
Click “Add a permission” and select “Microsoft Graph”
Choose “Application permissions” for automation scenarios
Apply least privilege principles: Only add permissions specific to the resources you need to manage
Click “Grant admin consent” for these permissions

Create Client Secret

Navigate to “Certificates & secrets” in your app registration
Click “New client secret”
Provide a description and select an expiration period
Copy the secret value immediately (it won’t be displayed again)

terraform {
  required_providers {
    azuread = {
      source  = "hashicorp/azuread"
      version = "~> 2.47.0"
    }
  }
}

# Create an application registration
resource "azuread_application" "microsoft365_app" {
  display_name = "Microsoft365 Terraform Provider"
}

# Create a service principal
resource "azuread_service_principal" "microsoft365_sp" {
  application_id = azuread_application.microsoft365_app.application_id
}

# Add Microsoft Graph permissions
resource "azuread_application_api_permission" "graph_permissions" {
  application_id = azuread_application.microsoft365_app.id
  api_id         = "00000003-0000-0000-c000-000000000000"
  
  api_permissions {
    id   = "78145de6-330d-4800-a6ce-494ff2d33d07" # DeviceManagementApps.ReadWrite.All
    type = "Role"
  }
}

# Create client secret
resource "azuread_application_password" "microsoft365_app_secret" {
  application_id = azuread_application.microsoft365_app.id
  display_name   = "Terraform Generated Secret"
  end_date       = "2024-12-31T00:00:00Z"
}

output "client_id" {
  value = azuread_application.microsoft365_app.application_id
}

output "client_secret" {
  value     = azuread_application_password.microsoft365_app_secret.value
  sensitive = true
}

# Connect to Microsoft Graph
Connect-MgGraph -Scopes "Application.ReadWrite.All", "Directory.ReadWrite.All"

# Create app registration
$app = New-MgApplication -DisplayName "Microsoft365 Terraform Provider"

# Create service principal
$sp = New-MgServicePrincipal -AppId $app.AppId

# Create client secret
$credential = Add-MgApplicationPassword -ApplicationId $app.Id -DisplayName "Terraform Access" -EndDateTime (Get-Date).AddYears(1)

# Output credentials
Write-Output "Tenant ID: $((Get-MgContext).TenantId)"
Write-Output "Client ID: $($app.AppId)"
Write-Output "Client Secret: $($credential.SecretText)"

Provider Configuration

Environment Variables (Recommended)
Terraform Configuration

export M365_TENANT_ID="00000000-0000-0000-0000-000000000000"
export M365_AUTH_METHOD="client_secret"
export M365_CLIENT_ID="00000000-0000-0000-0000-000000000000"
export M365_CLIENT_SECRET="your-client-secret"

Then configure the provider:

provider "microsoft365" {
  auth_method = "client_secret"
}

The provider automatically reads values from environment variables if they’re not specified in the provider configuration.

provider "microsoft365" {
  auth_method = "client_secret"
  tenant_id   = "00000000-0000-0000-0000-000000000000"
  entra_id_options = {
    client_id     = "00000000-0000-0000-0000-000000000000"
    client_secret = "your-client-secret"
  }
}

Never commit secrets to version control. Use environment variables or a secret manager instead.

HashiCorp Vault Integration

HashiCorp Vault provides a secure way to store and access secrets.

Store Credentials in Vault

vault kv put secret/microsoft365/credentials \
  tenant_id="00000000-0000-0000-0000-000000000000" \
  client_id="00000000-0000-0000-0000-000000000000" \
  client_secret="your-client-secret"

Retrieve with Vault Provider

data "vault_kv_secret_v2" "microsoft365_creds" {
  mount = "secret"
  name  = "microsoft365/credentials"
}

provider "microsoft365" {
  auth_method = "client_secret"
  tenant_id   = data.vault_kv_secret_v2.microsoft365_creds.data["tenant_id"]
  entra_id_options = {
    client_id     = data.vault_kv_secret_v2.microsoft365_creds.data["client_id"]
    client_secret = data.vault_kv_secret_v2.microsoft365_creds.data["client_secret"]
  }
}

Security Considerations

Important Security Practices

Follow the principle of least privilege
Never commit secrets to version control
Regularly rotate your client secrets (typically every 90 days)
Use a secrets manager (Azure Key Vault, HashiCorp Vault, GitHub Secrets)
Consider using certificate-based authentication or OIDC for production environments

Troubleshooting

Authentication failed

Verify the tenant ID, client ID, and client secret are correct. Check for typos and ensure the values haven’t been truncated.

Permission denied

Ensure you’ve granted admin consent for the required permissions in your app registration.

Secret expired

Check if your client secret has expired and create a new one if necessary. Set up alerts before expiration.

Insufficient permissions

Your app registration needs appropriate Microsoft Graph permissions. Consult the provider documentation for the specific permissions required by each resource.

Getting Started

Authentication

Configuration

Core Concepts

Guides

How Client Secret Authentication Works

Prerequisites

Setup

Provider Configuration

HashiCorp Vault Integration

Store Credentials in Vault

Retrieve with Vault Provider

Security Considerations

Troubleshooting

Build docs developers (and LLMs) love

Getting Started

Authentication

Configuration

Core Concepts

Guides

​How Client Secret Authentication Works

​Prerequisites

​Setup

​Provider Configuration

​HashiCorp Vault Integration

​Store Credentials in Vault

​Retrieve with Vault Provider

​Security Considerations

​Troubleshooting

Build docs developers (and LLMs) love

How Client Secret Authentication Works

Prerequisites

Setup

Provider Configuration

HashiCorp Vault Integration

Store Credentials in Vault

Retrieve with Vault Provider

Security Considerations

Troubleshooting