While setting up Azure API Management with Azure Active Directory (AAD) as an identity provider using Terraform, I encountered a subtle but frustrating bug related to the client_library setting in the azurerm_api_management_identity_provider_aadresource.

The Issue with client_library

The root of the problem is that the Terraform provider documentation doesn’t specify what values are valid for the client_library attribute. Although the schema defines it as a string, no examples or enumerated options are provided. This lack of documentation can lead to confusion, especially since this field has a significant impact on how authentication works.

To better understand the expected values, I checked the Azure Portal. There, when configuring an AAD identity provider manually, there’s a dropdown menu for the client library selection. The dropdown presents two options: ADAL and MSAL. If the field is left blank in Terraform, Azure defaults to ADAL.

However, leaving it blank in code doesn’t always result in smooth deployment.

Alt

The Error

When I initially omitted the client_library value in my Terraform configuration, the deployment failed with an unhelpful error message:

Your developer portal is configured to use the ADAL library for user authentication, but your Azure AD application is configured for the MSAL version. Select “MSAL” as the client library from the dropdown, save the settings, and republish the developer portal. Learn more

Alt

Trial and Error: MSAL vs MSAL-2

Assuming that the newer MSAL library would be appropriate, I tried setting client_library = “MSAL” in my Terraform script. However, this still didn’t work and resulted in the same or similar error.

Alt

At this point, I turned to the Azure Portal and updated the identity provider settings manually using the GUI — a method sometimes referred to as “ClickOps.” After making the change manually and then running terraform plan, Terraform helpfully showed me the correct value that matched the Portal configuration.

The Fix: MSAL-2

The correct value turned out to be “MSAL-2”, not simply “MSAL”. Once I updated my Terraform code to reflect this, everything worked as expected.

Alt

Here is the corrected Terraform configuration:

resource "azurerm_api_management_identity_provider_aad" "main" {
  resource_group_name = azurerm_resource_group.main.name
  api_management_name = azurerm_api_management.main.name
  client_id           = azuread_application_registration.main.client_id
  client_secret       = azuread_service_principal_password.main.value
  allowed_tenants     = [data.azurerm_client_config.current.tenant_id]
  client_library      = "MSAL-2"
  signin_tenant       = data.azurerm_client_config.current.tenant_id

  depends_on = [azuread_application_redirect_uris.main]
}

Conclusion

This experience highlights an important point: even when using infrastructure as code, it can sometimes be necessary to use the Azure Portal to uncover undocumented configuration details.

It would be helpful if the Terraform provider documentation explicitly listed “ADAL” and “MSAL-2” as valid values for client_library, especially since using an incorrect or blank value leads to opaque errors. It would also be helpful for the documentation to note the relationship between invoking the client_library argument and how this causes the signing_tenant argument to go from optional to required.

For anyone facing similar issues, I recommend temporarily using the Portal to verify the correct configuration and then syncing it back to your Terraform scripts to maintain consistency and reproducibility.

Now that I’ve updated my code with the proper value, everything is working smoothly.