Terraform Provider
Manage governed Microsoft Entra application registrations as code through the dedicated AZExecute Terraform API. The provider supports tenant approval, metadata policy, API-permission requests, selected registration settings, import, drift reads, and controlled deletion without bypassing AZExecute governance.
What You Can Manage
Application requests and lifecycle
Submit idempotent application requests, track PendingApproval, Provisioning, Ready, and Rejected, read Entra identifiers after provisioning, import existing Terraform-managed requests, and delete resources when tenant policy allows it.
Tenant-controlled metadata
Manage business justification, project and department ownership, environment, criticality, intended audience, go-live date, technical and data requirements, compliance notes, elevated-permission context, and contact details.
Registration configuration
Manage sign-in audience, identifier URIs, web, SPA and public-client redirect URIs, home and logout URLs, implicit token issuance, fallback public-client behavior, and requested access-token version.
API-permission requests
Submit external API or internal AZExecute application requests for app roles, delegated scopes, or authorized-client access. Permission handling follows the tenant's separate Terraform permission approval setting.
Policy and application reads
Read the live Terraform capabilities, included and required metadata fields, approval settings, and an application's current request status and identifiers through provider data sources.
State-safe operations
Use stable provider-generated UUIDs for retry safety, import by that UUID, and migrate from the synchronous resource to the approval-aware resource without recreating the remote application.
Before You Begin
1. Assign the calling user or service principal User, Operator, or TenantAdmin on the customer tenant's AZExecute enterprise application.
2. In Tenant administration → Application Configuration → Terraform, enable the Terraform API and application creation.
3. Decide whether application creation and permission requests require their normal approval flows.
4. Configure the metadata fields that Terraform callers may use and which of those fields are required.
5. Enable registration configuration, API-permission requests, and application deletion only for workflows that need them.
A User identity can manage only Terraform resources it created. Operator and TenantAdmin identities can manage Terraform resources across the tenant. Terraform never grants a broader role.
Choose the Correct Resource
azexecute_application_request — recommended
Works in approval-based and automatic tenants. It submits once, stores the returned status, and releases the Terraform state lock. It never waits for a person to approve a request. Use this resource for normal pipelines and whenever tenant approval could be enabled.
azexecute_application — automatic tenants only
Waits for automatic provisioning to reach Ready. Planning fails when application approval is enabled and directs the caller to the request resource. Use it only when the tenant contract guarantees automatic provisioning and one blocking apply is desired.
Approval and Repeated Pipeline Runs
1. Terraform plan reads the live tenant capabilities and validates the requested operations and metadata.
2. Apply submits one idempotent application request.
3. With approval enabled, apply succeeds with PendingApproval. With automatic provisioning, it may succeed with Provisioning or Ready.
4. A tenant administrator approves or rejects a pending request in AZExecute. Terraform cannot approve itself.
5. AZExecute provisions approved applications through its durable background workflow.
6. Run the same Terraform pipeline again. It refreshes status and identifiers and applies configured registration settings after the application is Ready.
Dynamic Metadata Requirements
Only display_name is always required by the Terraform resource. All tenant-controlled metadata fields are optional in the provider schema. During planning, the provider reads the tenant's live required_metadata_fields and reports a clear error when a currently required value is missing. The API validates the same policy again before creating anything, so invalid input does not leave an approval request behind.
Use the azexecute_capabilities data source to inspect whether creation, deletion, permission requests, registration configuration and approval flows are enabled, and which metadata fields are included or required.
Authentication and CI/CD
The provider requests a token for https://api.azexecute.com/.default in the customer tenant. It supports a pre-acquired token, OIDC workload identity federation, certificates, client secrets, managed identity, Azure workload identity, Azure CLI, Azure Developer CLI, Azure PowerShell, and supported developer credentials.
For GitHub Actions and Azure DevOps, use workload identity federation. In Azure DevOps, an Azure Resource Manager service connection can expose a short-lived OIDC assertion to both the Azure Blob Terraform backend and the AZExecute provider. Each exchanges it for its own access token; no stored client secret or long-lived AZExecute token is needed.
Blob access on the state storage account and an AZExecute application role are separate requirements. One does not grant the other.
Permissions, Registration, and Boundaries
Permission requests
Terraform can request permissions for an external Microsoft Entra API by application/client ID or an internal AZExecute application by application entity UUID. Supported grant types are app role, delegated scope, and authorized client. The tenant decides whether those permission requests wait for normal approval or are applied automatically with configured tenant-admin authority.
Registration settings
Set configure_registration = true only when the tenant enables Terraform registration configuration. Registration updates occur after the application is ready and use concurrency protection to avoid overwriting unrelated changes.
Owners and drift
Set owner_object_ids to the complete desired set of customer-managed Entra owner object UUIDs. Terraform adds missing owners and removes AZExecute-managed owners that are no longer configured. Manual owner changes made in AZExecute appear in the next plan. Graph-only operational owners required by AZExecute are preserved.
Intentionally outside the provider
The provider does not manage app-role definitions, exposed OAuth scopes, pre-authorized client definitions, secrets, certificates, integrations, or tenant settings. Continue to manage those through the dedicated AZExecute experiences and workflows.
State, Import, Migration, and Destroy
• The provider generates a stable UUID and the API enforces it per tenant, making retries safe after timeouts or lost responses.
• Import uses the stable Terraform resource UUID, not an Entra client ID, object ID, numeric request ID, or AZExecute application entity UUID.
• A Terraform moved block can move from azexecute_application to azexecute_application_request without recreating the application.
• Destroying a pending or rejected request cancels it without application-deletion permission.
• Destroying a provisioned application requires Allow Application Deletion in the tenant Terraform settings.