Announcement - Upcoming changes in AzureAD v2.0 and Microsoft Graph Support

[manicminer]

Our goal for the AzureAD provider is to transition to using Microsoft Graph for all resources, and eventually drop support for the deprecated Azure Active Directory Graph API. This involves building out SDK support and working out a strategy for migrating existing configurations. We are not planning any new features using the old API.

The provider recently had a v1.0 release which resolved some outstanding issues with the currently implemented resources. Some groundwork was also laid to enable us to implement multiple services, similarly to AzureRM. We'll be able to support resources backed by either API, in the same provider version.

Proposal

Whilst we work to achieve feature parity when using Microsoft Graph, we'll introduce partial support using a feature toggle. This will be implemented either as provider configuration, as an environment variable, or both, and will enable operators to switch to Microsoft Graph for the resources that support it. This will look something like:

provider "azuread" {
  use_microsoft_graph = true
}

Toggling with an environment variable would look something like AAD_USE_MICROSOFT_GRAPH=1.

Once the provider has feature parity using MS Graph, a major release v2.0 will be readied and we'll switch to using MS Graph by default exclusively.

Benefits

• The Azure Active Directory Graph is deprecated and will at some point be switched off.
• Microsoft Graph models resources much closer to their current implementation than Azure Active Directory Graph, which has been, to a degree, feature frozen and unable to maintain compatibility in some cases.
• Lots more resources will be available to implement in the provider, for example
  • fully featured applications
  • expanded service principal configuration
  • guest users
  • directory roles
  • directory schema extensions
  • conditional access
  • dynamic group membership
  • entitlement management
  • privileged identity management
  • B2C
  • Office 365 features such as Mail, Calendars, OneDrive, SharePoint, Teams

Caveats

• Existing configurations may require modification in places to work seamlessly with the next major version (this is fairly common for any major release).
• It's not clear at this time whether we'll be able to continue supporting Azure CLI authentication, although we will strive to do so. We will be able to continue supporting Azure CLI authentication

Plan

• Investigate feature toggle by provider config and/or environment variable
• Build initial SDK support
• Resolve compatibility issues
  • Provider configuration - environment differences, authentication differences, toggling MS Graph support
  • Computed vs Required fields
  • Applications: API and Web blocks, other field renames and boolean -> enum changes
  • Applications: native and public client consistent behavior
  • Application certificates
  • Application and service principal passwords
• Field and resource deprecations
• Work out and document a migration guide
• Get feature parity with current resources (Initial support for Microsoft Graph with opt-in beta #373)
• Release initial support with AAD Graph compatibility (v1.5.0)
• Bug fixes
• Remove AAD Graph support
• Acceptance testing cleanup and improvements
• Documentation updates
• Enable missing fields in existing resources
• Select new resources to be added
• Resolve any outstanding issues
• Major release (v2.0)
• 🚀 Additional features and resources - this is when we can start merging PRs for Microsoft Graph features

---

Whilst this reflects our current action plan, there are some details yet to be worked out and so it's subject to change. However, this is a priority for us and we hope to make it straightforward for operators and contributors to consume/implement the newer API.

Comments, suggestions and feedback are welcomed. If there's a particular resource or service you'd like to see implemented, please look for an issue and upvote it, or create a new issue. We use upvotes as a metric to help determine demand for features.

[no-acl]

Is there an ETA on the release of this release?

[hbuckle]

Great news - are you building out your own Go SDK for msgraph, or have Microsoft finally decided to release an official one?

[tombuildsstuff]

@hbuckle we'll likely be using our own - to be honest this is part of a larger question we're trying to work out with regards to the Azure SDK/Swagger going forward (for AzureRM too), we're still working through that - but hope to have something to share in the not-too-distant-future :)

[petr-stupka]

btw, you can vote for the MSFT golang SDK here: https://microsoftgraph.uservoice.com/forums/920506-microsoft-graph-feature-requests/suggestions/37576909-graph-api-golang-sdk

[tombuildsstuff]

@petr-x thanks for the link, unfortunately there's larger issues with the upcoming Azure SDK which makes it unsuitable for us - instead it's likely we'll be using our own SDK.

As mentioned above we're working through this at the moment as a part of some broader changes to enable both the AzureAD and AzureRM Provider to move faster going forward - we're hoping to share some more information in the near future :)

[Mayeu]

Are you aware of yaegashi/terraform-provider-msgraph? I'm not sure if that's a possibility but you could be merging that provider in.

[manicminer]

@Mayeu We did take a look at that project and it informed some of our planning. It is promising but as it stands is only partially complete, and we've made some distinctly different architectural choices along the way.

[lukeplausin]

Hi @manicminer , thanks for the info.
I am working on a project to deploy a lot of Azure AD resources which are not currently supported by the Azure AD terraform provider. If we can't use terraform we will probably end up with a powershell implementation which might not be as maintainable.

I'll have some time allocated to do this. I was wondering if I could use some of the time to contribute towards the TF provider Graph API implementation? I'm keen to get involved but don't really know what the plans for Graph are or how I could start. Is there a forum somewhere for TF contributors?

[manicminer]

@lukeplausin We have a Slack workspace for this and the azurerm providers, which you are welcome to join (details in the project readme). At present the development is largely internal - as tombuildsstuff mentioned we have been working on an SDK implementation - and we hope to have something to publish soon. Once we have this in place, we'd welcome any community contributions to bolster support for AAD resources.

In the interim, you might consider using Terraform and calling out to powershell as needed? This should give you an upgrade path as we roll out additional resource support.

[darrelmiller]

@tombuildsstuff The Graph SDKs are built by a different team than Azure SDKs. We use a completely different toolchain, and while we try to provide as much consistency as possible with Azure SDKs where reasonable, we have a distinct set of constraints.
I've have been the PM for the Graph SDKs for the last few years and now play more of an architect role. We are currently in the planning stage for our future SDK efforts and so any feedback you have around your requirements would be much appreciated.

[derekschauland]

Any news on a release date?

[bytemech]

@petr-x thanks for the link, unfortunately there's larger issues with the upcoming Azure SDK which makes it unsuitable for us - instead it's likely we'll be using our own SDK.

As mentioned above we're working through this at the moment as a part of some broader changes to enable both the AzureAD and AzureRM Provider to move faster going forward - we're hoping to share some more information in the near future :)

@tombuildsstuff is there any update now it's 6 months later?

[sirlatrom]

@tombuildsstuff is there any update now it's 6 months later?

@bytemech I'm pretty sure the right place to look for progress is https://github.com/hashicorp/terraform-provider-azuread/milestone/16, and then avoiding any more "+1" or "ETA?" type of comments, as they don't add value but do spam all subscribed users. Also, you could see the task list in the issue description and start creating well-written issues for the concrete tasks if you believe you know what should be done.

[manicminer]

Version 1.5.0 is now released with beta support for Microsoft Graph. Thanks for everyone's patience whilst we work through the transition. Please open issues to report any problems you might have!

To enable beta support for MS Graph, update your provider block:

provider "azuread" {
  use_microsoft_graph = true
}

Alternatively, you can set an environment variable:

# sh
export AAD_USE_MICROSOFT_GRAPH=1

# PowerShell
$env:AAD_USE_MICROSOFT_GRAPH = "1"

We have also published a Migration Guide to aid in updating your configuration in preparation for v2.0.

[BHoggs]

Any thoughts about expanding this into a full-blown M365 provider? We've been looking at Microsoft365DSC as a solution to M365 config management, but unfortunately it's quite clunky. A Terraform option would be much preferred.

[manicminer]

@BHoggs We've been looking at various aspects of M365 to see how feasible it would be to support. We are planning to expand support but it depends on API availability and suitability for Terraform. I would encourage you to raise specific feature requests (as many as you like) as issues in this repository and each one will be looked at.

[manicminer]

Version 2.0.0 is now released and concludes our initial migration to Microsoft Graph. This version of the provider uses MS Graph exclusively and no longer connects to Azure Active Directory Graph.

Please review the updated Upgrade Guide before embarking on upgrading to v2.0, taking note of the breaking changes introduced in this release including:

• Authentication requirements, e.g. API permissions
• Removed resources
• Renamed and updated properties
• New required properties
• Properties that are no longer Computed
• New API constraints, notably for Groups

This version is now available on the Terraform Registry and you can start using it right away:

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

Please report any issues you might have that are not covered in our upgrade guide, thanks!

[manicminer]

FYI there is a patch release v2.0.1 to address a validation bug with application roles/scopes

I'm going to go ahead and close this long-running issue, for further updates please check the changelog and latest milestones on GitHub. Thanks!

[github-actions]

This functionality has been released in v2.0.0 of the Terraform Provider. Please see the Terraform documentation on provider versioning or reach out if you need any assistance upgrading.

For further feature requests or bug reports with this functionality, please create a new GitHub issue following the template. Thank you!

[github-actions]

I'm going to lock this issue because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems similar to this, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.