Authentication: Support Azure Federated Identity environment variables directly

[mrsheepuk]

While using an Azure AKS Workload Identity to authenticate the provider is supported (as noted in issues #21635 and #18612), it isn't obvious from the documentation that all that is needed is to map the environment variables over (and indeed I didn't find those issues when searching for how to do this and ended up trying many different things before ending up with the working combination).

As these environment variables are standardised by Azure, this PR proposes supporting them natively to automatically detect this configuration and work as expected when executed inside an AKS cluster with the federated identity presented.

With this, a provider that is authenticated and working inside an AKS pod with workload identity configured becomes simply:

provider "azurerm" {
  features {}
  subscription_id = "12345678-abcd-458d-aa01-0123abcd1234"
  use_aks_workload_identity = true
}

... with the federated identity, tenant ID and client ID all auto-populated from the environment.

• make pr-check passing

[mrsheepuk]

Thanks for taking a look at this @manicminer - I've tested this by building the provider locally and transferring it into a pod with a workload identity configured using kubectl cp as follows:

apiVersion: v1
kind: Secret
metadata:
  name: config-mark
  namespace: terraform-test
stringData:
  backend.tf: |
    terraform {
      backend "kubernetes" {
        in_cluster_config = true
        namespace         = "terraform-system"
        secret_suffix     = "marktest"
      }
    }
  provider.tf: |
    provider "azurerm" {
      features {}
      subscription_id = "REDACTED"
      use_aks_workload_identity = true
    }
  main.tf: |
    resource "azurerm_storage_account" "sa" {
      name                     = "testbob2023111702"
      resource_group_name      = "mark-aks-2-infra-uksouth"
      location                 = "uksouth"
      account_tier             = "Standard"
      account_replication_type = "LRS"
    }
  tfrc: |
    provider_installation {
      dev_overrides {
        "hashicorp/azurerm" = "/data/bin/"
      }
      direct {}
    }
type: Opaque
---
apiVersion: v1
kind: Pod
metadata:
  labels:
    azure.workload.identity/use: "true"
  name: marktest
  namespace: terraform-test
spec:
  containers:
  - args:
    - -F
    - /data/logcat
    command:
    - tail
    env:
    - name: HOME
      value: /data
    - name: KUBE_NAMESPACE
      valueFrom:
        fieldRef:
          apiVersion: v1
          fieldPath: metadata.namespace
    image: hashicorp/terraform:1.6.4
    imagePullPolicy: IfNotPresent
    name: terraform
    volumeMounts:
    - mountPath: /data
      name: source
    - mountPath: /data/bin
      name: bin
    - mountPath: /data/config
      name: config
    workingDir: /data
  securityContext:
    fsGroup: 65534
    runAsGroup: 65534
    runAsUser: 65534
  serviceAccount: terraform-executor
  serviceAccountName: terraform-executor
  volumes:
  - emptyDir: {}
    name: source
  - emptyDir: {}
    name: bin
  - name: config
    secret:
      defaultMode: 420
      items:
      - key: backend.tf
        path: backend.tf
      - key: provider.tf
        path: provider.tf
      - key: main.tf
        path: main.tf
      - key: tfrc
        path: ".terraformrc"
      optional: false
      secretName: config-mark

Copy the locally-built provider in to the pod:

kubectl cp ./bin/terraform-provider-azurerm terraform-test/marktest:/data/bin/

Then exec'ing into the pod (kubectl -n terraform-test exec marktest -it -- /bin/sh) and running the following:

cp ./config/* ./
cp ./config/.terraformrc ./
terraform init
terraform plan -out tfplan
terraform apply tfplan
terraform destroy -auto-approve

All works as expected and self-configures from the Azure-provided environment variables injected via the azure.workload.identity/use: "true" label.

[manicminer]

Hi @mrsheepuk, thanks for suggesting this. I agree that whilst it's relatively straightforward to set up the necessary environment variables based on those set when using ASK Workload Identity, there are valid points to be made about documenting this or potentially supporting it directly as per your proposal.

We've chatted internally about this and since this is now a mature and stable implementation in AKS, this is something we'd like to support. However, we think it's important to mitigate any risk of disrupting existing configurations (whether using workload identity or not, or even OIDC or not), and also to ensure reliable testing in isolation, so that we have confidence in this being stable across future releases.

With that in mind, would you be able to rework this as follows:

1. Add a new provider-level boolean configuration option use_aks_workload_identity, with a corresponding environment variable ARM_USE_AKS_WORKLOAD_IDENTITY
2. When this provider property is true, we can specifically consume the AKS-native environment variables in the provider's configure function.
3. In the providerConfigure() function, if the client_id / client_id_file_path properties are set and produce different value(s) to that specified in the AZURE_CLIENT_ID environment variable, we should raise an error and warn the user to either set one of these, or ensure they are set to the same value. This check should happen in the getClientId() function.
4. Perform the same validation for tenant_id / AZURE_TENANT_ID respectively. A new getTenantId() function will be needed in provider.go for this (based on getClientId()).
5. The use_aks_workload_identity feature should fall back gracefully - that is, if it's set to true and the environment variables are not all set, we should make a best effort to configure the provider with the existing provider properties / environment variables.
   • If the AZURE_FEDERATED_TOKEN_FILE env var is not set, we should skip over it. If it is set, but points to an invalid file, or the contents cannot be read, we should raise an error.
   • If the AZURE_TENANT_ID env var is not set, we should use the value of tenant_id.
   • If the AZURE_CLIENT_ID env var is not set, we should use the value of client_id / client_id_file_path.
   • If any of the above env vars are set, appear to be valid, but are different to any of their existing corresponding properties, we should raise an error.
6. For testing, we'd prefer to create a new test function to test this in isolation, for example TestAccProvider_aksWorkloadIdentity().

This approach would on balance be preferable to specifying the environment variables for client_id, tenant_id and oidc_token_file_path in the provider schema, as it means they will only be consumed conditionally when enabled by the practitioner. It will also establish an order of precedence and prevent users from inadvertently supplying the wrong authentication primitives.

Please do let me know what you think, and whether you'd be keen to work on this? Thanks!

[mrsheepuk]

Thanks for discussing it and for the feedback @manicminer - I like the approach you have suggested, and most of it sounds reasonably straightforward. I might need some help with the new test function, but let me start from the top and work down your list and see how far I get.

I have to admit I was a bit worried about implicitly picking up the wrong tenant ID / client ID if my approach was run in an existing flow that happened to have AZURE_TENANT_ID and/or AZURE_CLIENT_ID set (less so the AZURE_FEDERATED_TOKEN_FILE as that is unlikely to be set in other flows), so I prefer the intentionality of a new provider property.

[mrsheepuk]

I think I've covered all the points in dc0932d

I'm not sure how you typically run the acceptance tests, so I, ahem, borrowed a token file from an AKS cluster into a local file named 'auth' so I could run the new acceptance test:

$ ARM_SUBSCRIPTION_ID=(redacted) AZURE_FEDERATED_TOKEN_FILE=${PWD}/auth AZURE_CLIENT_ID=(redacted) AZURE_TENANT_ID=(redacted) TF_ACC=1 go test ./internal/provider -v -run=TestAccProvider_aksWorkloadIdentityAuth -timeout 1m -ldflags="-X=github.com/hashicorp/terraform-provider-azurerm/version.ProviderVersion=acc"
=== RUN   TestAccProvider_aksWorkloadIdentityAuth
--- PASS: TestAccProvider_aksWorkloadIdentityAuth (2.28s)
PASS
ok  	github.com/hashicorp/terraform-provider-azurerm/internal/provider	4.132s

I also ran it with incorrect values etc to check that it does indeed fail when the values are not correct.

I repeated my above manual test inside an AKS pod as well, using the new 'use_aks_workload_identity = true' in my provider.tf instead of use_oidc and it worked perfectly 🎉

I think it could use more documentation, but writing a whole document on how to set up AKS Workload Identity feels a bit out of scope, so not sure how far we'd need to take that?

[manicminer]

@mrsheepuk Thanks for making the changes, and for the typo fixes along the way - that looks great at first pass. I'll play a bit locally and come back with some thoughts on how we might want to test this. We may elect to do the same as with GitHub OIDC and rely on the execution environment being set up out of band, or possibly add some extra tooling to spin up a cluster as needed, deploy to a pod, and run it there. Don't want to delay this unnecessarily but I think it warrants some thought.

For the docs, I was thinking it would be fine to add this as a new section in the existing OIDC Guide. If you want to have a go at this, please feel free (what you've written up so far is great) but I'm also happy to help with that prior to merging.

[mrsheepuk]

I tried adding it to the existing OIDC guide but couldn't quite make it fit, so I've pushed a first draft of doing it as a separate doc. Feel free to make changes / amend / delete the whole thing 😆 but it's a start.

[mrsheepuk]

Just noticed the lint failure - will fix up. @manicminer any further thoughts on how we can test this? anything I can do to help with that?

[manicminer]

@mrsheepuk Given that we currently do not perform complete automated end-to-end testing for all the authentication methods we support, I'm happy to approve this based on the manual testing that you and I have conducted - I can confirm that this works great in the two setups that I have tested with.

Thanks again for this contribution. This is a great quality-of-life improvement and I appreciate the time taken to document this, as well as tidying up some typos in general. I pushed a couple of wording tweaks but aside from those, this is good to merge!

---

Testing with client ID annotation:

[mrsheepuk]

Ah brilliant, thanks for taking the time to review and test it out @manicminer :)

[github-actions]

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