1# Azure Identity Client Module for Go
2
3The Azure Identity module provides Microsoft Entra ID ([formerly Azure Active Directory](https://learn.microsoft.com/entra/fundamentals/new-name)) 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.
4
5[](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity)
6| [Microsoft Entra ID documentation](https://learn.microsoft.com/entra/identity/)
7| [Source code](https://github.com/Azure/azure-sdk-for-go/tree/main/sdk/azidentity)
8
9# Getting started
10
11## Install the module
12
13This project uses [Go modules](https://github.com/golang/go/wiki/Modules) for versioning and dependency management.
14
15Install the Azure Identity module:
16
17```sh
18go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity
19```
20
21## Prerequisites
22
23- an [Azure subscription](https://azure.microsoft.com/free/)
24- Go 1.18
25
26### Authenticating during local development
27
28When 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.
29
30#### Authenticating via the Azure CLI
31
32`DefaultAzureCredential` and `AzureCLICredential` can authenticate as the user
33signed in to the [Azure CLI](https://learn.microsoft.com/cli/azure). 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.
34
35When no default browser is available, `az login` will use the device code
36authentication flow. This can also be selected manually by running `az login --use-device-code`.
37
38#### Authenticate via the Azure Developer CLI
39
40Developers coding outside of an IDE can also use the [Azure Developer CLI](https://aka.ms/azure-dev) to authenticate. Applications using the `DefaultAzureCredential` or the `AzureDeveloperCLICredential` can use the account logged in to the Azure Developer CLI to authenticate calls in their application when running locally.
41
42To authenticate with the Azure Developer CLI, run `azd auth login`. On a system with a default web browser, `azd` will launch the browser to authenticate. On systems without a default web browser, run `azd auth login --use-device-code` to use the device code authentication flow.
43
44## Key concepts
45
46### Credentials
47
48A credential is a type which contains or can obtain the data needed for a
49service client to authenticate requests. Service clients across the Azure SDK
50accept a credential instance when they are constructed, and use that credential
51to authenticate requests.
52
53The `azidentity` module focuses on OAuth authentication with Microsoft Entra ID. It offers a variety of credential types capable of acquiring a Microsoft Entra access token. See [Credential Types](#credential-types "Credential Types") for a list of this module's credential types.
54
55### DefaultAzureCredential
56
57`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:
58
59
60
611. **Environment** - `DefaultAzureCredential` will read account information specified via [environment variables](#environment-variables) and use it to authenticate.
621. **Workload Identity** - If the app is deployed on Kubernetes with environment variables set by the workload identity webhook, `DefaultAzureCredential` will authenticate the configured identity.
631. **Managed Identity** - If the app is deployed to an Azure host with managed identity enabled, `DefaultAzureCredential` will authenticate with it.
641. **Azure CLI** - If a user or service principal has authenticated via the Azure CLI `az login` command, `DefaultAzureCredential` will authenticate that identity.
651. **Azure Developer CLI** - If the developer has authenticated via the Azure Developer CLI `azd auth login` command, the `DefaultAzureCredential` will authenticate with that account.
66
67> 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.
68
69## Managed Identity
70
71`DefaultAzureCredential` and `ManagedIdentityCredential` support
72[managed identity authentication](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/overview)
73in any hosting environment which supports managed identities, such as (this list is not exhaustive):
74* [Azure App Service](https://learn.microsoft.com/azure/app-service/overview-managed-identity)
75* [Azure Arc](https://learn.microsoft.com/azure/azure-arc/servers/managed-identity-authentication)
76* [Azure Cloud Shell](https://learn.microsoft.com/azure/cloud-shell/msi-authorization)
77* [Azure Kubernetes Service](https://learn.microsoft.com/azure/aks/use-managed-identity)
78* [Azure Service Fabric](https://learn.microsoft.com/azure/service-fabric/concepts-managed-identity)
79* [Azure Virtual Machines](https://learn.microsoft.com/entra/identity/managed-identities-azure-resources/how-to-use-vm-token)
80
81## Examples
82
83- [Authenticate with DefaultAzureCredential](#authenticate-with-defaultazurecredential "Authenticate with DefaultAzureCredential")
84- [Define a custom authentication flow with ChainedTokenCredential](#define-a-custom-authentication-flow-with-chainedtokencredential "Define a custom authentication flow with ChainedTokenCredential")
85- [Specify a user-assigned managed identity for DefaultAzureCredential](#specify-a-user-assigned-managed-identity-for-defaultazurecredential)
86
87### Authenticate with DefaultAzureCredential
88
89This example demonstrates authenticating a client from the `armresources` module with `DefaultAzureCredential`.
90
91```go
92cred, err := azidentity.NewDefaultAzureCredential(nil)
93if err != nil {
94 // handle error
95}
96
97client := armresources.NewResourceGroupsClient("subscription ID", cred, nil)
98```
99
100### Specify a user-assigned managed identity for DefaultAzureCredential
101
102To configure `DefaultAzureCredential` to authenticate a user-assigned managed identity, set the environment variable `AZURE_CLIENT_ID` to the identity's client ID.
103
104### Define a custom authentication flow with `ChainedTokenCredential`
105
106`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.
107
108The 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.
109
110```go
111managed, err := azidentity.NewManagedIdentityCredential(nil)
112if err != nil {
113 // handle error
114}
115azCLI, err := azidentity.NewAzureCLICredential(nil)
116if err != nil {
117 // handle error
118}
119chain, err := azidentity.NewChainedTokenCredential([]azcore.TokenCredential{managed, azCLI}, nil)
120if err != nil {
121 // handle error
122}
123
124client := armresources.NewResourceGroupsClient("subscription ID", chain, nil)
125```
126
127## Credential Types
128
129### Authenticating Azure Hosted Applications
130
131|Credential|Usage
132|-|-
133|[DefaultAzureCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#DefaultAzureCredential)|Simplified authentication experience for getting started developing Azure apps
134|[ChainedTokenCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#ChainedTokenCredential)|Define custom authentication flows, composing multiple credentials
135|[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
136|[ManagedIdentityCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#ManagedIdentityCredential)|Authenticate the managed identity of an Azure resource
137|[WorkloadIdentityCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#WorkloadIdentityCredential)|Authenticate a workload identity on Kubernetes
138
139### Authenticating Service Principals
140
141|Credential|Usage
142|-|-
143|[AzurePipelinesCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#AzurePipelinesCredential)|Authenticate an Azure Pipelines [service connection](https://learn.microsoft.com/azure/devops/pipelines/library/service-endpoints?view=azure-devops&tabs=yaml)
144|[ClientAssertionCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#ClientAssertionCredential)|Authenticate a service principal with a signed client assertion
145|[ClientCertificateCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#ClientCertificateCredential)|Authenticate a service principal with a certificate
146|[ClientSecretCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#ClientSecretCredential)|Authenticate a service principal with a secret
147
148### Authenticating Users
149
150|Credential|Usage
151|-|-
152|[InteractiveBrowserCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#InteractiveBrowserCredential)|Interactively authenticate a user with the default web browser
153|[DeviceCodeCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#DeviceCodeCredential)|Interactively authenticate a user on a device with limited UI
154|[UsernamePasswordCredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#UsernamePasswordCredential)|Authenticate a user with a username and password
155
156### Authenticating via Development Tools
157
158|Credential|Usage
159|-|-
160|[AzureCLICredential](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#AzureCLICredential)|Authenticate as the user signed in to the Azure CLI
161|[`AzureDeveloperCLICredential`](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity#AzureDeveloperCLICredential)|Authenticates as the user signed in to the Azure Developer CLI
162
163## Environment Variables
164
165`DefaultAzureCredential` and `EnvironmentCredential` can be configured with environment variables. Each type of authentication requires values for specific variables:
166
167#### Service principal with secret
168
169|variable name|value
170|-|-
171|`AZURE_CLIENT_ID`|ID of a Microsoft Entra application
172|`AZURE_TENANT_ID`|ID of the application's Microsoft Entra tenant
173|`AZURE_CLIENT_SECRET`|one of the application's client secrets
174
175#### Service principal with certificate
176
177|variable name|value
178|-|-
179|`AZURE_CLIENT_ID`|ID of a Microsoft Entra application
180|`AZURE_TENANT_ID`|ID of the application's Microsoft Entra tenant
181|`AZURE_CLIENT_CERTIFICATE_PATH`|path to a certificate file including private key
182|`AZURE_CLIENT_CERTIFICATE_PASSWORD`|password of the certificate file, if any
183
184#### Username and password
185
186|variable name|value
187|-|-
188|`AZURE_CLIENT_ID`|ID of a Microsoft Entra application
189|`AZURE_USERNAME`|a username (usually an email address)
190|`AZURE_PASSWORD`|that user's password
191
192Configuration is attempted in the above order. For example, if values for a
193client secret and certificate are both present, the client secret will be used.
194
195## Token caching
196
197Token caching is an `azidentity` feature that allows apps to:
198
199* Cache tokens in memory (default) or on disk (opt-in).
200* Improve resilience and performance.
201* Reduce the number of requests made to Microsoft Entra ID to obtain access tokens.
202
203For more details, see the [token caching documentation](https://aka.ms/azsdk/go/identity/caching).
204
205## Troubleshooting
206
207### Error Handling
208
209Credentials 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](https://aka.ms/azsdk/go/identity/troubleshoot).
210
211For more details on handling specific Microsoft Entra errors, see the Microsoft Entra [error code documentation](https://learn.microsoft.com/entra/identity-platform/reference-error-codes).
212
213### Logging
214
215This 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:
216```go
217import azlog "github.com/Azure/azure-sdk-for-go/sdk/azcore/log"
218
219// print log output to stdout
220azlog.SetListener(func(event azlog.Event, s string) {
221 fmt.Println(s)
222})
223
224// include only azidentity credential logs
225azlog.SetEvents(azidentity.EventAuthentication)
226```
227
228Credentials 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.
229
230## Next steps
231
232Client and management modules listed on the [Azure SDK releases page](https://azure.github.io/azure-sdk/releases/latest/go.html) support authenticating with `azidentity` credential types. You can learn more about using these libraries in their documentation, which is linked from the release page.
233
234## Provide Feedback
235
236If you encounter bugs or have suggestions, please
237[open an issue](https://github.com/Azure/azure-sdk-for-go/issues).
238
239## Contributing
240
241This project welcomes contributions and suggestions. Most contributions require
242you to agree to a Contributor License Agreement (CLA) declaring that you have
243the right to, and actually do, grant us the rights to use your contribution.
244For details, visit [https://cla.microsoft.com](https://cla.microsoft.com).
245
246When you submit a pull request, a CLA-bot will automatically determine whether
247you need to provide a CLA and decorate the PR appropriately (e.g., label,
248comment). Simply follow the instructions provided by the bot. You will only
249need to do this once across all repos using our CLA.
250
251This project has adopted the
252[Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
253For more information, see the
254[Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/)
255or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any
256additional questions or comments.
257
258