Add WorkloadIdentityCredential (Azure#19503)

Author: chlowell

sdk/azidentity/CHANGELOG.md

@@ -1,8 +1,13 @@
 # Release History
 
-## 1.2.1 (Unreleased)
+## 1.3.0-beta.1 (Unreleased)
 
 ### Features Added
+* `WorkloadIdentityCredential` and `DefaultAzureCredential` support
+  Workload Identity Federation on Kubernetes. `DefaultAzureCredential`
+  support requires environment variable configuration as set by the
+  Workload Identity webhook.
+  ([#15615](https://github.com/Azure/azure-sdk-for-go/issues/15615))
 
 ### Breaking Changes
 

sdk/azidentity/README.md

@@ -55,8 +55,9 @@ an Azure AD access token. See [Credential Types](#credential-types "Credential T
 ![DefaultAzureCredential authentication flow](img/mermaidjs/DefaultAzureCredentialAuthFlow.svg)
 
 1. **Environment** - `DefaultAzureCredential` will read account information specified via [environment variables](#environment-variables) and use it to authenticate.
-2. **Managed Identity** - If the app is deployed to an Azure host with managed identity enabled, `DefaultAzureCredential` will authenticate with it.
-3. **Azure CLI** - If a user or service principal has authenticated via the Azure CLI `az login` command, `DefaultAzureCredential` will authenticate that identity.
+1. **Workload Identity** - If the app is deployed on Kubernetes with environment variables set by the workload identity webhook, `DefaultAzureCredential` will authenticate the configured identity.
+1. **Managed Identity** - If the app is deployed to an Azure host with managed identity enabled, `DefaultAzureCredential` will authenticate with it.
+1. **Azure CLI** - If a user or service principal has authenticated via the Azure CLI `az login` command, `DefaultAzureCredential` will authenticate that identity.
 
 > Note: `DefaultAzureCredential` is intended to simplify getting started with the SDK by handling common scenarios with reasonable default behaviors. Developers who want more control or whose scenario isn't served by the default settings should use other credential types.
 
@@ -128,6 +129,7 @@ client := armresources.NewResourceGroupsClient("subscription ID", chain, nil)
 |[ChainedTokenCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#ChainedTokenCredential)|Define custom authentication flows, composing multiple credentials
 |[EnvironmentCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#EnvironmentCredential)|Authenticate a service principal or user configured by environment variables
 |[ManagedIdentityCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#ManagedIdentityCredential)|Authenticate the managed identity of an Azure resource
+|[WorkloadIdentityCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#WorkloadIdentityCredential)|Authenticate a workload identity on Kubernetes
 
 ### Authenticating Service Principals
 

sdk/azidentity/azidentity.go

@@ -30,6 +30,7 @@ const (
 	azureClientCertificatePath     = "AZURE_CLIENT_CERTIFICATE_PATH"
 	azureClientID                  = "AZURE_CLIENT_ID"
 	azureClientSecret              = "AZURE_CLIENT_SECRET"
+	azureFederatedTokenFile        = "AZURE_FEDERATED_TOKEN_FILE"
 	azurePassword                  = "AZURE_PASSWORD"
 	azureRegionalAuthorityName     = "AZURE_REGIONAL_AUTHORITY_NAME"
 	azureTenantID                  = "AZURE_TENANT_ID"

sdk/azidentity/client_assertion_credential.go

@@ -18,13 +18,15 @@ import (
 const credNameAssertion = "ClientAssertionCredential"
 
 // ClientAssertionCredential authenticates an application with assertions provided by a callback function.
-// This credential is for advanced scenarios. ClientCertificateCredential has a more convenient API for
+// This credential is for advanced scenarios. [ClientCertificateCredential] has a more convenient API for
 // the most common assertion scenario, authenticating a service principal with a certificate. See
 // [Azure AD documentation] for details of the assertion format.
 //
 // [Azure AD documentation]: https://docs.microsoft.com/azure/active-directory/develop/active-directory-certificate-credentials#assertion-format
 type ClientAssertionCredential struct {
 	client confidentialClient
+	// name enables replacing "ClientAssertionCredential" with "WorkloadIdentityCredential" in log messages
+	name string
 }
 
 // ClientAssertionCredentialOptions contains optional parameters for ClientAssertionCredential.
@@ -49,7 +51,7 @@ func NewClientAssertionCredential(tenantID, clientID string, getAssertion func(c
 	if err != nil {
 		return nil, err
 	}
-	return &ClientAssertionCredential{client: c}, nil
+	return &ClientAssertionCredential{client: c, name: credNameAssertion}, nil
 }
 
 // GetToken requests an access token from Azure Active Directory. This method is called automatically by Azure SDK clients.
@@ -59,15 +61,15 @@ func (c *ClientAssertionCredential) GetToken(ctx context.Context, opts policy.To
 	}
 	ar, err := c.client.AcquireTokenSilent(ctx, opts.Scopes)
 	if err == nil {
-		logGetTokenSuccess(c, opts)
+		logGetTokenSuccessImpl(c.name, opts)
 		return azcore.AccessToken{Token: ar.AccessToken, ExpiresOn: ar.ExpiresOn.UTC()}, err
 	}
 
 	ar, err = c.client.AcquireTokenByCredential(ctx, opts.Scopes)
 	if err != nil {
-		return azcore.AccessToken{}, newAuthenticationFailedErrorFromMSALError(credNameAssertion, err)
+		return azcore.AccessToken{}, newAuthenticationFailedErrorFromMSALError(c.name, err)
 	}
-	logGetTokenSuccess(c, opts)
+	logGetTokenSuccessImpl(c.name, opts)
 	return azcore.AccessToken{Token: ar.AccessToken, ExpiresOn: ar.ExpiresOn.UTC()}, err
 }
 

sdk/azidentity/default_azure_credential.go

@@ -30,11 +30,15 @@ type DefaultAzureCredentialOptions struct {
 
 // DefaultAzureCredential is a default credential chain for applications that will deploy to Azure.
 // It combines credentials suitable for deployment with credentials suitable for local development.
-// It attempts to authenticate with each of these credential types, in the following order, stopping when one provides a token:
+// It attempts to authenticate with each of these credential types, in the following order, stopping
+// when one provides a token:
 //
-//	EnvironmentCredential
-//	ManagedIdentityCredential
-//	AzureCLICredential
+//   - [EnvironmentCredential]
+//   - [WorkloadIdentityCredential], if environment variable configuration is set by the Azure workload
+//     identity webhook. Use [WorkloadIdentityCredential] directly when not using the webhook or needing
+//     more control over its configuration.
+//   - [ManagedIdentityCredential]
+//   - [AzureCLICredential]
 //
 // Consult the documentation for these credential types for more information on how they authenticate.
 // Once a credential has successfully authenticated, DefaultAzureCredential will use that credential for
@@ -60,9 +64,35 @@ func NewDefaultAzureCredential(options *DefaultAzureCredentialOptions) (*Default
 		creds = append(creds, &defaultCredentialErrorReporter{credType: "EnvironmentCredential", err: err})
 	}
 
+	// workload identity requires values for AZURE_AUTHORITY_HOST, AZURE_CLIENT_ID, AZURE_FEDERATED_TOKEN_FILE, AZURE_TENANT_ID
+	haveWorkloadConfig := false
+	clientID, haveClientID := os.LookupEnv(azureClientID)
+	if haveClientID {
+		if file, ok := os.LookupEnv(azureFederatedTokenFile); ok {
+			if _, ok := os.LookupEnv(azureAuthorityHost); ok {
+				if tenantID, ok := os.LookupEnv(azureTenantID); ok {
+					haveWorkloadConfig = true
+					workloadCred, err := NewWorkloadIdentityCredential(tenantID, clientID, file, &WorkloadIdentityCredentialOptions{
+						ClientOptions: options.ClientOptions},
+					)
+					if err == nil {
+						creds = append(creds, workloadCred)
+					} else {
+						errorMessages = append(errorMessages, credNameWorkloadIdentity+": "+err.Error())
+						creds = append(creds, &defaultCredentialErrorReporter{credType: credNameWorkloadIdentity, err: err})
+					}
+				}
+			}
+		}
+	}
+	if !haveWorkloadConfig {
+		err := errors.New("missing environment variables for workload identity. Check webhook and pod configuration")
+		creds = append(creds, &defaultCredentialErrorReporter{credType: credNameWorkloadIdentity, err: err})
+	}
+
 	o := &ManagedIdentityCredentialOptions{ClientOptions: options.ClientOptions}
-	if ID, ok := os.LookupEnv(azureClientID); ok {
-		o.ID = ClientID(ID)
+	if haveClientID {
+		o.ID = ClientID(clientID)
 	}
 	msiCred, err := NewManagedIdentityCredential(o)
 	if err == nil {

sdk/azidentity/default_azure_credential_test.go

@@ -9,10 +9,16 @@ package azidentity
 import (
 	"context"
 	"fmt"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strings"
 	"testing"
 
+	"github.com/Azure/azure-sdk-for-go/sdk/azcore/cloud"
 	"github.com/Azure/azure-sdk-for-go/sdk/azcore/policy"
 	"github.com/Azure/azure-sdk-for-go/sdk/internal/log"
+	"github.com/Azure/azure-sdk-for-go/sdk/internal/mock"
 )
 
 func TestDefaultAzureCredential_GetTokenSuccess(t *testing.T) {
@@ -89,3 +95,45 @@ func TestDefaultAzureCredential_UserAssignedIdentity(t *testing.T) {
 		})
 	}
 }
+
+func TestDefaultAzureCredential_Workload(t *testing.T) {
+	expectedAssertion := "service account token"
+	tempFile := filepath.Join(t.TempDir(), "service-account-token-file")
+	if err := os.WriteFile(tempFile, []byte(expectedAssertion), os.ModePerm); err != nil {
+		t.Fatalf(`failed to write temporary file "%s": %v`, tempFile, err)
+	}
+	pred := func(req *http.Request) bool {
+		if err := req.ParseForm(); err != nil {
+			t.Fatal(err)
+		}
+		if actual := req.PostForm["client_assertion"]; actual[0] != expectedAssertion {
+			t.Fatalf(`unexpected assertion "%s"`, actual[0])
+		}
+		if actual := req.PostForm["client_id"]; actual[0] != fakeClientID {
+			t.Fatalf(`unexpected assertion "%s"`, actual[0])
+		}
+		if actual := strings.Split(req.URL.Path, "/")[1]; actual != fakeTenantID {
+			t.Fatalf(`unexpected tenant "%s"`, actual)
+		}
+		return true
+	}
+	srv, close := mock.NewServer(mock.WithTransformAllRequestsToTestServerUrl())
+	defer close()
+	srv.AppendResponse(mock.WithBody(instanceDiscoveryResponse))
+	srv.AppendResponse(mock.WithBody(tenantDiscoveryResponse))
+	srv.AppendResponse(mock.WithPredicate(pred), mock.WithBody(accessTokenRespSuccess))
+	srv.AppendResponse()
+	for k, v := range map[string]string{
+		azureAuthorityHost:      cloud.AzurePublic.ActiveDirectoryAuthorityHost,
+		azureClientID:           fakeClientID,
+		azureFederatedTokenFile: tempFile,
+		azureTenantID:           fakeTenantID,
+	} {
+		t.Setenv(k, v)
+	}
+	cred, err := NewDefaultAzureCredential(&DefaultAzureCredentialOptions{ClientOptions: policy.ClientOptions{Transport: srv}})
+	if err != nil {
+		t.Fatal(err)
+	}
+	testGetTokenSuccess(t, cred)
+}

sdk/azidentity/img/mermaidjs/DefaultAzureCredentialAuthFlow.md

@@ -5,14 +5,14 @@
 %% 2. Run command: mmdc -i DefaultAzureCredentialAuthFlow.md -o DefaultAzureCredentialAuthFlow.svg
 
 flowchart LR;
-    A(Environment):::deployed ==> B(Managed Identity):::deployed ==> C(Azure CLI):::developer;
+    A(Environment):::deployed ==> B(Workload Identity):::deployed ==> C(Managed Identity):::deployed ==> D(Azure CLI):::developer;
 
     subgraph CREDENTIAL TYPES;
         direction LR;
         Deployed(Deployed service):::deployed ==> Developer(Developer):::developer;
 
         %% Hide links between boxes in the legend by setting width to 0. The integers after "linkStyle" represent link indices.
-        linkStyle 2 stroke-width:0px;
+        linkStyle 3 stroke-width:0px;
     end;
 
     %% Define styles for credential type boxes
@@ -21,6 +21,7 @@ flowchart LR;
 
     %% Add API ref links to credential type boxes
     click A "https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#EnvironmentCredential" _blank;
-    click B "https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#ManagedIdentityCredential" _blank;
-    click C "https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#AzureCLICredential" _blank;
+    click B "https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#WorkloadIdentityCredential" _blank;
+    click C "https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#ManagedIdentityCredential" _blank;
+    click D "https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#AzureCLICredential" _blank;
 ```