1# NOTE: This module will go out of support by March 31, 2023. For authenticating with Azure AD, use module [azidentity](https://pkg.go.dev/github.com/Azure/azure-sdk-for-go/sdk/azidentity) instead. For help migrating from `auth` to `azidentiy` please consult the [migration guide](https://aka.ms/azsdk/go/identity/migration). General information about the retirement of this and other legacy modules can be found [here](https://azure.microsoft.com/updates/support-for-azure-sdk-libraries-that-do-not-conform-to-our-current-azure-sdk-guidelines-will-be-retired-as-of-31-march-2023/).
2
3## Authentication
4
5Typical SDK operations must be authenticated and authorized. The `autorest.Authorizer`
6interface allows use of any auth style in requests, such as inserting an OAuth2
7Authorization header and bearer token received from Azure AD.
8
9The SDK itself provides a simple way to get an authorizer which first checks
10for OAuth client credentials in environment variables and then falls back to
11Azure's [Managed Service Identity]() when available, e.g. when on an Azure
12VM. The following snippet from [the previous section](#use) demonstrates
13this helper.
14
15```go
16import "github.com/Azure/go-autorest/autorest/azure/auth"
17
18// create a VirtualNetworks client
19vnetClient := network.NewVirtualNetworksClient("<subscriptionID>")
20
21// create an authorizer from env vars or Azure Managed Service Idenity
22authorizer, err := auth.NewAuthorizerFromEnvironment()
23if err != nil {
24 handle(err)
25}
26
27vnetClient.Authorizer = authorizer
28
29// call the VirtualNetworks CreateOrUpdate API
30vnetClient.CreateOrUpdate(context.Background(),
31// ...
32```
33
34The following environment variables help determine authentication configuration:
35
36- `AZURE_ENVIRONMENT`: Specifies the Azure Environment to use. If not set, it
37 defaults to `AzurePublicCloud`. Not applicable to authentication with Managed
38 Service Identity (MSI).
39- `AZURE_AD_RESOURCE`: Specifies the AAD resource ID to use. If not set, it
40 defaults to `ResourceManagerEndpoint` for operations with Azure Resource
41 Manager. You can also choose an alternate resource programmatically with
42 `auth.NewAuthorizerFromEnvironmentWithResource(resource string)`.
43
44### More Authentication Details
45
46The previous is the first and most recommended of several authentication
47options offered by the SDK because it allows seamless use of both service
48principals and [Azure Managed Service Identity][]. Other options are listed
49below.
50
51> Note: If you need to create a new service principal, run `az ad sp create-for-rbac -n "<app_name>"` in the
52> [azure-cli](https://github.com/Azure/azure-cli). See [these
53> docs](https://docs.microsoft.com/cli/azure/create-an-azure-service-principal-azure-cli?view=azure-cli-latest)
54> for more info. Copy the new principal's ID, secret, and tenant ID for use in
55> your app, or consider the `--sdk-auth` parameter for serialized output.
56
57[azure managed service identity]: https://docs.microsoft.com/azure/active-directory/msi-overview
58
59- The `auth.NewAuthorizerFromEnvironment()` described above creates an authorizer
60 from the first available of the following configuration:
61
62 1. **Client Credentials**: Azure AD Application ID and Secret.
63
64 - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate.
65 - `AZURE_CLIENT_ID`: Specifies the app client ID to use.
66 - `AZURE_CLIENT_SECRET`: Specifies the app secret to use.
67
68 2. **Client Certificate**: Azure AD Application ID and X.509 Certificate.
69
70 - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate.
71 - `AZURE_CLIENT_ID`: Specifies the app client ID to use.
72 - `AZURE_CERTIFICATE_PATH`: Specifies the certificate Path to use.
73 - `AZURE_CERTIFICATE_PASSWORD`: Specifies the certificate password to use.
74
75 3. **Resource Owner Password**: Azure AD User and Password. This grant type is *not
76 recommended*, use device login instead if you need interactive login.
77
78 - `AZURE_TENANT_ID`: Specifies the Tenant to which to authenticate.
79 - `AZURE_CLIENT_ID`: Specifies the app client ID to use.
80 - `AZURE_USERNAME`: Specifies the username to use.
81 - `AZURE_PASSWORD`: Specifies the password to use.
82
83 4. **Azure Managed Service Identity**: Delegate credential management to the
84 platform. Requires that code is running in Azure, e.g. on a VM. All
85 configuration is handled by Azure. See [Azure Managed Service
86 Identity](https://docs.microsoft.com/azure/active-directory/msi-overview)
87 for more details.
88
89- The `auth.NewAuthorizerFromFile()` method creates an authorizer using
90 credentials from an auth file created by the [Azure CLI][]. Follow these
91 steps to utilize:
92
93 1. Create a service principal and output an auth file using `az ad sp create-for-rbac --sdk-auth > client_credentials.json`.
94 2. Set environment variable `AZURE_AUTH_LOCATION` to the path of the saved
95 output file.
96 3. Use the authorizer returned by `auth.NewAuthorizerFromFile()` in your
97 client as described above.
98
99- The `auth.NewAuthorizerFromCLI()` method creates an authorizer which
100 uses [Azure CLI][] to obtain its credentials.
101
102 The default audience being requested is `https://management.azure.com` (Azure ARM API).
103 To specify your own audience, export `AZURE_AD_RESOURCE` as an evironment variable.
104 This is read by `auth.NewAuthorizerFromCLI()` and passed to Azure CLI to acquire the access token.
105
106 For example, to request an access token for Azure Key Vault, export
107 ```
108 AZURE_AD_RESOURCE="https://vault.azure.net"
109 ```
110
111- `auth.NewAuthorizerFromCLIWithResource(AUDIENCE_URL_OR_APPLICATION_ID)` - this method is self contained and does
112 not require exporting environment variables. For example, to request an access token for Azure Key Vault:
113 ```
114 auth.NewAuthorizerFromCLIWithResource("https://vault.azure.net")
115 ```
116
117 To use `NewAuthorizerFromCLI()` or `NewAuthorizerFromCLIWithResource()`, follow these steps:
118
119 1. Install [Azure CLI v2.0.12](https://docs.microsoft.com/cli/azure/install-azure-cli) or later. Upgrade earlier versions.
120 2. Use `az login` to sign in to Azure.
121
122 If you receive an error, use `az account get-access-token` to verify access.
123
124 If Azure CLI is not installed to the default directory, you may receive an error
125 reporting that `az` cannot be found.
126 Use the `AzureCLIPath` environment variable to define the Azure CLI installation folder.
127
128 If you are signed in to Azure CLI using multiple accounts or your account has
129 access to multiple subscriptions, you need to specify the specific subscription
130 to be used. To do so, use:
131
132 ```
133 az account set --subscription <subscription-id>
134 ```
135
136 To verify the current account settings, use:
137
138 ```
139 az account list
140 ```
141
142[azure cli]: https://github.com/Azure/azure-cli
143
144- Finally, you can use OAuth's [Device Flow][] by calling
145 `auth.NewDeviceFlowConfig()` and extracting the Authorizer as follows:
146
147 ```go
148 config := auth.NewDeviceFlowConfig(clientID, tenantID)
149 a, err := config.Authorizer()
150 ```
151
152[device flow]: https://oauth.net/2/device-flow/
View as plain text