distribution/vendor/github.com/Azure/azure-sdk-for-go/sdk/azidentity/README.md

Azure Identity Client Module for Go

The Azure Identity module provides Azure Active Directory (Azure AD) token authentication support across the Azure SDK. It includes a set of TokenCredential implementations, which can be used with Azure SDK clients supporting token authentication.

| Azure Active Directory documentation | Source code

Getting started

Install the module

This project uses Go modules for versioning and dependency management.

Install the Azure Identity module:

go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity

Prerequisites

• an Azure subscription
• Go 1.18

Authenticating during local development

When debugging and executing code locally, developers typically use their own accounts to authenticate calls to Azure services. The azidentity module supports authenticating through developer tools to simplify local development.

Authenticating via the Azure CLI

DefaultAzureCredential and AzureCLICredential can authenticate as the user signed in to the Azure CLI. To sign in to the Azure CLI, run az login. On a system with a default web browser, the Azure CLI will launch the browser to authenticate a user.

When no default browser is available, az login will use the device code authentication flow. This can also be selected manually by running az login --use-device-code.

Key concepts

Credentials

A credential is a type which contains or can obtain the data needed for a service client to authenticate requests. Service clients across the Azure SDK accept a credential instance when they are constructed, and use that credential to authenticate requests.

The azidentity module focuses on OAuth authentication with Azure Active Directory (AAD). It offers a variety of credential types capable of acquiring an Azure AD access token. See Credential Types for a list of this module's credential types.

DefaultAzureCredential

DefaultAzureCredential is appropriate for most apps that will be deployed to Azure. It combines common production credentials with development credentials. It attempts to authenticate via the following mechanisms in this order, stopping when one succeeds:

1. Environment - DefaultAzureCredential will read account information specified via environment variables and use it to authenticate.
2. Workload Identity - If the app is deployed on Kubernetes with environment variables set by the workload identity webhook, DefaultAzureCredential will authenticate the configured identity.
3. Managed Identity - If the app is deployed to an Azure host with managed identity enabled, DefaultAzureCredential will authenticate with it.
4. 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.

Managed Identity

DefaultAzureCredential and ManagedIdentityCredential support managed identity authentication in any hosting environment which supports managed identities, such as (this list is not exhaustive):

• Azure App Service
• Azure Arc
• Azure Cloud Shell
• Azure Kubernetes Service
• Azure Service Fabric
• Azure Virtual Machines

Examples

• Authenticate with DefaultAzureCredential
• Define a custom authentication flow with ChainedTokenCredential
• Specify a user-assigned managed identity for DefaultAzureCredential

Authenticate with DefaultAzureCredential

This example demonstrates authenticating a client from the armresources module with DefaultAzureCredential.

cred, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
  // handle error
}

client := armresources.NewResourceGroupsClient("subscription ID", cred, nil)

Specify a user-assigned managed identity for DefaultAzureCredential

To configure DefaultAzureCredential to authenticate a user-assigned managed identity, set the environment variable AZURE_CLIENT_ID to the identity's client ID.

Define a custom authentication flow with ChainedTokenCredential

DefaultAzureCredential is generally the quickest way to get started developing apps for Azure. For more advanced scenarios, ChainedTokenCredential links multiple credential instances to be tried sequentially when authenticating. It will try each chained credential in turn until one provides a token or fails to authenticate due to an error.

The following example demonstrates creating a credential, which will attempt to authenticate using managed identity. It will fall back to authenticating via the Azure CLI when a managed identity is unavailable.

managed, err := azidentity.NewManagedIdentityCredential(nil)
if err != nil {
  // handle error
}
azCLI, err := azidentity.NewAzureCLICredential(nil)
if err != nil {
  // handle error
}
chain, err := azidentity.NewChainedTokenCredential([]azcore.TokenCredential{managed, azCLI}, nil)
if err != nil {
  // handle error
}

client := armresources.NewResourceGroupsClient("subscription ID", chain, nil)

Credential Types

Authenticating Azure Hosted Applications

Credential	Usage
DefaultAzureCredential	Simplified authentication experience for getting started developing Azure apps
ChainedTokenCredential	Define custom authentication flows, composing multiple credentials
EnvironmentCredential	Authenticate a service principal or user configured by environment variables
ManagedIdentityCredential	Authenticate the managed identity of an Azure resource
WorkloadIdentityCredential	Authenticate a workload identity on Kubernetes

Authenticating Service Principals

Credential	Usage
ClientAssertionCredential	Authenticate a service principal with a signed client assertion
ClientCertificateCredential	Authenticate a service principal with a certificate
ClientSecretCredential	Authenticate a service principal with a secret

Authenticating Users

Credential	Usage
InteractiveBrowserCredential	Interactively authenticate a user with the default web browser
DeviceCodeCredential	Interactively authenticate a user on a device with limited UI
UsernamePasswordCredential	Authenticate a user with a username and password

Authenticating via Development Tools

Credential	Usage
AzureCLICredential	Authenticate as the user signed in to the Azure CLI

Environment Variables

DefaultAzureCredential and EnvironmentCredential can be configured with environment variables. Each type of authentication requires values for specific variables:

Service principal with secret

variable name	value
AZURE_CLIENT_ID	ID of an Azure Active Directory application
AZURE_TENANT_ID	ID of the application's Azure Active Directory tenant
AZURE_CLIENT_SECRET	one of the application's client secrets

Service principal with certificate

variable name	value
AZURE_CLIENT_ID	ID of an Azure Active Directory application
AZURE_TENANT_ID	ID of the application's Azure Active Directory tenant
AZURE_CLIENT_CERTIFICATE_PATH	path to a certificate file including private key
AZURE_CLIENT_CERTIFICATE_PASSWORD	password of the certificate file, if any

Username and password

variable name	value
AZURE_CLIENT_ID	ID of an Azure Active Directory application
AZURE_USERNAME	a username (usually an email address)
AZURE_PASSWORD	that user's password

Configuration is attempted in the above order. For example, if values for a client secret and certificate are both present, the client secret will be used.

Troubleshooting

Error Handling

Credentials return an error when they fail to authenticate or lack data they require to authenticate. For guidance on resolving errors from specific credential types, see the troubleshooting guide.

For more details on handling specific Azure Active Directory errors please refer to the Azure Active Directory error code documentation.

Logging

This module uses the classification-based logging implementation in azcore. To enable console logging for all SDK modules, set AZURE_SDK_GO_LOGGING to all. Use the azcore/log package to control log event output or to enable logs for azidentity only. For example:

import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"

// print log output to stdout
azlog.SetListener(func(event azlog.Event, s string) {
    fmt.Println(s)
})

// include only azidentity credential logs
azlog.SetEvents(azidentity.EventAuthentication)

Credentials log basic information only, such as GetToken success or failure and errors. These log entries don't contain authentication secrets but may contain sensitive information.

Next steps

Client and management modules listed on the Azure SDK releases page support authenticating with azidentity credential types. You can learn more about using these libraries in their documentation, which is linked from the release page.

Provide Feedback

If you encounter bugs or have suggestions, please open an issue.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.