Documentation: be clearer on how to use OIDC authentication

[jpenna]

Is there an existing issue for this?

• I have searched the existing issues

Community Note

• Please vote on this issue by adding a 👍 reaction to the original issue to help the community and maintainers prioritize this request
• Please do not leave comments along the lines of "+1", "me too" or "any updates", they generate extra noise for issue followers and do not help prioritize the request
• If you are interested in working on this issue or have submitted a pull request, please leave a comment and review the contribution guide to help.

Hello, I've spent half a day figuring out how to authenticate using a Service Principal with OIDC. The documentation didn't help at all...

Target documentation page

https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/service_principal_oidc

It mentions the steps to configure the federated credentials through Azure Portal, but in the section on how to use these credentials it forgets to say we must set the backend with use_oidc = true or the environment variable ARM_USE_OIDC: true. This can be found in this other doc: Backend: Azure AD Service Principal or User Assigned Managed Identity via OIDC (Workload Identity Federation)

After I figured out the solution and came here to open this issue, I found this 1-year-old issue about the confusion on authenticating and this last comment on how to solve it with Github Actions. I implemented the same thing as they are suggesting here, but I only found this issue after understanding what the problem was.

Suggestion

Please, add in the documentation below the following note in the Github Actions section:
https://registry.terraform.io/providers/hashicorp/azurerm/latest/docs/guides/service_principal_oidc#oidc-token

You must configure the backend to use OIDC with: use_oidc = true or the environment variable ARM_USE_OIDC: true. For an example, check https://developer.hashicorp.com/terraform/language/backend/azurerm#backend-azure-ad-service-principal-or-user-assigned-managed-identity-via-oidc-workload-identity-federation

Terraform Version

1.9.6

AzureRM Provider Version

4.3.0

Affected Resource(s)/Data Source(s)

backend "azurerm"

Terraform Configuration Files

.

Debug Output/Panic Output

Error building ARM Config: obtain subscription(***) from Azure CLI: parsing json result from the Azure CLI: waiting for the Azure CLI: exit status 1: ERROR: Please run 'az login' to setup account.

Expected Behaviour

No response

Actual Behaviour

No response

Steps to Reproduce

No response

Important Factoids

No response

References

No response

[lonegunmanb]

Hi @jpenna thanks for opening this issue!

I believe this requirement has been covered already in the current document:

https://github.com/hashicorp/terraform-provider-azurerm/blob/v4.3.0/website/docs/guides/service_principal_oidc.html.markdown?plain=1#L190

[jpenna]

Hello @rcskosir , I didn't see that one 😢... But anyway, I don't think this note is in the correct section. I would disregard it as being related to Azure Pipelines.

This is a general remark. Maybe a better location would be in a higher section, like under "Configuring the Service Principal in Terraform" and above "OIDC token".