Hello! I’m Sue Bohn, Partner Director of Program Management for Identity and Access Management. In this Voice of the ISV blog post, we’ve invited Tom Bamford, Senior Engineer at HashiCorp, to discuss the migration of their Terraform Azure AD provider to the new Microsoft Graph API. HashiCorp made a commitment to move away from Azure AD Graph and Azure Active Directory Authentication Library (ADAL) well before the June 30, 2022 end-of-support date. According to Tom, the decision is already paying dividends.
Building solution-based software
HashiCorp is an open-source software company that was founded in 2012 with the goal of revolutionizing datacenter management, including application development, delivery, and maintenance. Our tools manage both physical and virtual machines, Windows, Linux, SaaS, and IaaS. We build solutions that span the gaps, and we’re committed to supporting next-generation technologies. The company is based in San Francisco, but about 80 percent of our roughly 1,500 employees work remotely.
Terraform integration with Azure AD
HashiCorp Terraform is an infrastructure as code (IaC) tool that allows users to build, change, and version infrastructure safely and efficiently. With Terraform, you can design your configurations to match your company’s structure and goals, delegate between teams, and enable self-service infrastructure—all while maintaining accountability. The Terraform Azure AD provider enables you to manage your Azure Active Directory (Azure AD) resources with Terraform. Our goal is to make Azure AD more approachable and accessible, giving our customers a great workflow. In addition, HashiCorp Vault manages authentication principals on behalf of users and closely integrates with Azure AD.
Figure 1: Terraform & Azure Active Directory
Embracing change
As an open-source software company, we build our products in the open to provide maximum value to customers. We’ve been watching the development of Microsoft Graph with great interest since 2019, when Microsoft announced that all new identity capabilities moving forward would be available only in Microsoft Authentication Library (MSAL) and Microsoft Graph. We knew we wanted to commit to the new API sooner rather than later to ensure that our customers were in good shape well ahead of the June 30, 2022 end-of-support date for Azure AD Graph API and Active Directory Authentication Library (ADAL). Due to constant updates to Azure AD, it can become increasingly difficult to rely on the older APIs over time.
Migrating to Microsoft Graph
The two-year timeline for moving to Microsoft Graph was perfect for us. Microsoft invested heavily in documentation and support, which made our migration experience quite easy—the whole process lasted about six months, without any major issues. Our main concern was maintaining compatibility for our customers throughout the migration process. Now, when customers choose to swap to the new Microsoft Graph API, they can do so without any undesired changes to the resources in their directory and without needing to update their configurations.
Enabling customer success
We created a comprehensive migration guide to assist customers through updating their configurations—from the principals Terraform needs to authenticate to the Graph API, to any resource configuration updates. The guide includes changes introduced to existing resources and data sources. The provider migration to Microsoft Graph API corresponds to a major version release (v2.0.0); so, our customers are aware of the changes. There’s also a section in the migration guide where we explain the permission changes for Microsoft Graph. For those in the process of migrating, we held off on introducing any new features. We’re beginning to roll out some first-class support for Microsoft Graph while dropping support for Azure AD Graph.
In addition, we’ve created the Manage Azure Active Directory Users and Groups Learn tutorial, which guides users through using Terraform and the Azure AD v2.0.0 provider. In the process, you’ll learn Terraform's configuration language, the Terraform Azure AD provider, and how to leverage both to simplify and automate your workflows.
Better performance and user experience
Since migrating to Microsoft Graph, we’ve seen immediate performance benefits that create a better user experience. With the legacy API, we had to set up custom polling mechanisms to verify the changes made to the resources. Microsoft Graph API’s much faster response time and better data consistency address these concerns, and will enable us to deliver many more of our customers’ feature requests.
For our customers, the most significant benefit is Microsoft Graph API's increased reliability. With previous providers using Azure AD Graph, customers would have to assign administrative directory roles to their principals to do certain operations. With Microsoft Graph, the permissions are more granular, manageable, auditable, and maintainable. Also, we’re able to provide increased coverage to automate customers' tenants and their associated products.
Lessons learned and looking ahead
For developers planning this migration, consider the schema differences that may affect your particular configuration in your tenant, mainly around applications. Be sure you can maintain continued availability while you migrate; so that you do not inadvertently change something that is difficult to track down. It is possible to migrate fairly seamlessly if you plan it out carefully.
Learn more about Microsoft identity:
- Return to the Azure Active Directory Identity blog home
- Join the conversation on Twitter and LinkedIn
- Share product suggestions on the Azure Feedback Forum
Microsoft
