A new terraform provider for Entra ID

Last month, in the middle of everyone's summer holidays, Microsoft released a new Terraform provider for the Graph API. I have been waiting for this for quite some time after first hearing about the development in one of the "Terraform on Azure" community calls. (which you can sign up for at https://aka.ms/aztfcommunity), as I have been a bit annoyed and frustrated with the existing provider maintained by Hashicorp.

To put it bluntly: The development and maintenance of terraform-provider-azuread seems to be stuck in some kind of virtual marshland, where issues are left unanswered, pull requests doesn't get merged, and the gap in functionality keeps growing larger and larger.

A bit of background

If we compare this with working on Azure resources, we have the option of using terraform-provider-azapi instead of terraform-provider-azurerm to mitigate a lot of the same issues. Where azurerm has been the default experience for a long time, providing stability and ease of use, it has at time struggled with providing day 1 support for new functionality, and it would not be fair to the development team to add the additional burden of keeping up with functions for preview services.

azapi solves this by taking a different approach. Instead of a separate resource type per Azure resource, it is just a thin layer on top of the Azure Resource Manager API and we interact almost exclusively with the provider by creating azapi_resource blocks where we specify the type, version and (optionally) the body of parameters for the object we want to create.

e.g. to create a new resource group we can do this in two different ways:

# azapi
resource "azapi_resource" "example1" {
  type = "Microsoft.Resources/resourceGroups@2020-06-01"
  name = "rg-azapi-example"
  location = "norwayeast"
}

# azurerm
resource "azurerm_resource_group" "example2" {
  name = "rg-azurerm-example"
  location = "norwayeast"
}

This approach gives us two main benefits:

  1. We get access to the API versions for the object we want to create
  2. We get access to the entire Azure Resource Manager API, including preview services, API versions with functionality that is not in azurerm yet etc.

So what are these azuread and msgraph things?

The Microsoft ecosystem relies mainly on two separate APIs: Azure Resource Manager and Graph. (in reality, there are more, but we can ignore the rest of them for now), and if you want to configure something in Entra ID you most probably interact with the latter. This includes things like users and groups, entitlement management and identity governance to control who has access to resources, security features like conditional access policies, app registrations for machine access and many other.

And to interact with the Graph API we have been using terraform-provider-azuread (which I imagine it is a challenge to get renamed from Azure AD to Entra ID). A provider that has taken the same approach as the azurerm provider described above. To mitigate a lot of the same challenges, Microsoft has now released an early version of terraform-provider-msgraph and re-used the same approach we know from azapi: Just provide a thin layer on top of the API and make (almost) everything available to the developer.

The msgraph_resource works in almost the same way. You specify the url to the API endpoint you want to use, override the api_version if you need functionality that is only available in beta, add query parameters (e.g. to add filters to the API response) and have a dynamic and flexible body attribute to pass in the expected request body.

It is a bit harder both to get started with this approach and require a bit of effort to become familiar with the underlying APIs instead of relying on the terraform provider to have abstracted away the nuances and details. The good news is that the Microsoft Terraform-extension for VSCode has also been upgraded to give you a bit of help.

Should I start migrating my configuration to msgraph? Or start using it at all?

No, you should probably not starting a big migration project to get rid of your existing configuration and rewrite everything using the msgraph provider yet. It is a very early release. It has bugs. It is missing features. It does not cover every API endpoint (or even every important endpoint).

But should you start testing it out? Yes. Familiarize yourself with how it works. Report bugs and provide feedback. If it solves a problem you can't solve with azuread, keep in mind that breaking changes might happen and have a plan for how to deal with them.