| 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 |
|
| 5 |
Typical SDK operations must be authenticated and authorized. The `autorest.Authorizer` |
| 6 |
interface allows use of any auth style in requests, such as inserting an OAuth2 |
| 7 |
Authorization header and bearer token received from Azure AD. |
| 8 |
|
| 9 |
The SDK itself provides a simple way to get an authorizer which first checks |
| 10 |
for OAuth client credentials in environment variables and then falls back to |
| 11 |
Azure's [Managed Service Identity]() when available, e.g. when on an Azure |
| 12 |
VM. The following snippet from [the previous section](#use) demonstrates |
| 13 |
this helper. |
| 14 |
|
| 15 |
```go |
| 16 |
import "github.com/Azure/go-autorest/autorest/azure/auth" |
| 17 |
|
| 18 |
// create a VirtualNetworks client |
| 19 |
vnetClient := network.NewVirtualNetworksClient("<subscriptionID>") |
| 20 |
|
| 21 |
// create an authorizer from env vars or Azure Managed Service Idenity |
| 22 |
authorizer, err := auth.NewAuthorizerFromEnvironment() |
| 23 |
if err != nil { |
| 24 |
handle(err) |
| 25 |
} |
| 26 |
|
| 27 |
vnetClient.Authorizer = authorizer |
| 28 |
|
| 29 |
// call the VirtualNetworks CreateOrUpdate API |
| 30 |
vnetClient.CreateOrUpdate(context.Background(), |
| 31 |
// ... |
| 32 |
``` |
| 33 |
|
| 34 |
The 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 |
|
| 46 |
The previous is the first and most recommended of several authentication |
| 47 |
options offered by the SDK because it allows seamless use of both service |
| 48 |
principals and [Azure Managed Service Identity][]. Other options are listed |
| 49 |
below. |
| 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/ |