Edit

Authentication with the Azure SDK for Go (legacy)

  • Article

Important

This article applies to the legacy version of the Azure SDK for Go. For authenticating to the latest modules use the Azure Identity package.

The Azure SDK for Go offers multiple ways to authenticate with Azure. These authentication types are invoked through different authentication methods. This article covers the available types, methods, and how to choose which are best for your application.

Available authentication types and methods

The Azure SDK for Go offers several different types of authentication, using different credentials sets. Each authentication type is available through different authentication methods, which are how the SDK takes these credentials as input. The following table describes the available types of authentication and situations in which they're recommended for use by your application.

Authentication type Recommended when...
Certificate-based authentication You have an X509 certificate that was configured for a Microsoft Entra user or service principal. To learn more, see Get started with certificate-based authentication in Microsoft Entra ID.
Client credentials You have a configured service principal that is set up for this application or a class of applications it belongs to. To learn more, see Create a service principal with Azure CLI.
Managed identities for Azure resources Your application is running on an Azure resource that has been configured with a managed identity. To learn more, see Managed identities for Azure resources.
Device token Your application is meant to be used interactively only. Users may have multifactor authentication enabled. Users have access to a web browser to sign in. For more information, see Use device token authentication.
Username/password You have an interactive application that can't use any other authentication method. Your users don't have multifactor authentication enabled for their Microsoft Entra sign-in.

Key points

  • If you use an authentication type other than client credentials, your application must be registered in Microsoft Entra ID. To learn how, see Integrating applications with Microsoft Entra ID.
  • Unless you have special requirements, avoid username/password authentication. In situations where user-based sign-in is appropriate, device token authentication can usually be used instead.

These authentication types are available through different methods.

All authentication functions and types are available in the github.com/Azure/go-autorest/autorest/azure/auth package.

Note

Unless you have special requirements, avoid client-based authentication. This method of authentication encourages bad practices. In particular, using client-based authentication makes it tempting to hard-code credentials. Writing custom code for authentication may also break under future SDK releases if authentication requirements change.

Use environment-based authentication

If you're running your application in a controlled setting, environment-based authentication is a natural choice. With this authentication method, you configure the shell environment before running your application. At runtime, the Go SDK reads these environment variables to authenticate with Azure.

Environment-based authentication has support for all authentication types except device tokens, evaluated in the following order:

  • Client credentials
  • Certificate-based authentication
  • Username/password
  • Managed identities for Azure resources

If an authentication type has unset values or is refused, the SDK automatically tries the next authentication type. When no more types are available to try, the SDK returns an error.

The following table details the environment variables that need to be set for each authentication type supported by environment-based authentication.

Authentication type Environment variable Description
Client credentials AZURE_TENANT_ID The ID for the Active Directory tenant that the service principal belongs to.
AZURE_CLIENT_ID The name or ID of the service principal.
AZURE_CLIENT_SECRET The secret associated with the service principal.
Certificate AZURE_TENANT_ID The ID for the Active Directory tenant that the certificate is registered with.
AZURE_CLIENT_ID The application client ID associated with the certificate.
AZURE_CERTIFICATE_PATH The path to the client certificate file.
AZURE_CERTIFICATE_PASSWORD The password for the client certificate.
Username/Password AZURE_TENANT_ID The ID for the Active Directory tenant that the user belongs to.
AZURE_CLIENT_ID The application client ID.
AZURE_USERNAME The username to sign in with.
AZURE_PASSWORD The password to sign in with.
Managed identity No credentials are needed for managed identity authentication. The application must be running on an Azure resource configured to use managed identities. For details, see Managed identities for Azure resources.

To connect to a cloud or management endpoint other than the default Azure public cloud, set the following environment variables. The most common reasons are if you use Azure Stack, a cloud in a different geographic region, or the classic deployment model.

Environment variable Description
AZURE_ENVIRONMENT The name of the cloud environment to connect to.
AZURE_AD_RESOURCE The Active Directory resource ID to use when connecting, as a URI to your management endpoint.

When using environment-based authentication, call the NewAuthorizerFromEnvironment function to get your authorizer object. This object is then set on the Authorizer property of clients to allow them access to Azure.

import "github.com/Azure/go-autorest/autorest/azure/auth"
authorizer, err := auth.NewAuthorizerFromEnvironment()

Authentication on Azure Stack

To authenticate on Azure Stack, you need to set the following variables:

Environment variable Description
AZURE_AD_ENDPOINT The Active Directory endpoint.
AZURE_AD_RESOURCE The Active Directory resource ID.

These variables can be retrieved from Azure Stack metadata information. To retrieve the metadata, open a web browser in your Azure Stack environment and use the url: (ResourceManagerURL)/metadata/endpoints?api-version=1.0

The ResourceManagerURL varies based on the region name, machine name, and external fully qualified domain name (FQDN) of your Azure Stack deployment:

Environment ResourceManagerURL
Development Kit https://management.local.azurestack.external/
Integrated Systems https://management.(region).ext-(machine-name).(FQDN)

For more information on how to use the Azure SDK for Go on Azure Stack, see Use API version profiles with Go in Azure Stack

Use file-based authentication

File-based authentication uses a file format generated by the Azure CLI. You can easily create this file when creating a new service principal with the --sdk-auth parameter. If you plan on using file-based authentication, make sure that this argument is provided when creating a service principal. Since the CLI prints output to stdout, redirect output to a file.

az ad sp create-for-rbac --role Contributor \
    --scopes /subscriptions/<subscription_id> \
    --sdk-auth > azure.auth

Set the AZURE_AUTH_LOCATION environment variable to where the authorization file is located. This environment variable is read by the application, and the credentials within it are parsed. If you need to select the authorization file at runtime, manipulate the program's environment using the os.Setenv function.

To load the authentication information, call the NewAuthorizerFromFile function. Unlike environment-based authorization, file-based authorization requires a resource endpoint.

import "github.com/Azure/go-autorest/autorest/azure/auth"
authorizer, err := NewAuthorizerFromFile(azure.PublicCloud.ResourceManagerEndpoint)

For more on using service principals and managing their access permissions, see Create a service principal with Azure CLI.

Use device token authentication

If you want users to sign in interactively, the best way is through device token authentication. This authentication flow passes the user a token to paste into a Microsoft sign-in site, where they then authenticate with a Microsoft Entra account. This authentication method supports accounts that have multifactor authentication enabled, unlike standard username/password authentication.

To use device token authentication, create a DeviceFlowConfig authorizer with the NewDeviceFlowConfig function. Call Authorizer on the resulting object to start the authentication process. Device flow authentication blocks program execution until the whole authentication flow is complete.

import "github.com/Azure/go-autorest/autorest/azure/auth"
deviceConfig := auth.NewDeviceFlowConfig(applicationID, tenantID)
authorizer, err := deviceConfig.Authorizer()

Use an authentication client

If you require a specific type of authentication and are willing to have your program do the work to load authentication information from the user, you can use any client that conforms to the auth.AuthorizerConfig interface. Use a type that implements this interface when you:

  • Write an interactive program
  • Use specialized configuration files
  • Have a requirement that prevents using a built-in authentication method

Warning

Never hard-code Azure credentials into an application. Putting secrets into an application binary makes it easier for an attacker to extract them, whether the application is running or not. This puts all Azure resources the credentials are authorized for at risk!

The following table lists the types in the SDK that conform to the AuthorizerConfig interface.

Authentication type Authorizer type
Certificate-based authentication ClientCertificateConfig
Client credentials ClientCredentialsConfig
Managed identities for Azure resources MSIConfig
Username/password UsernamePasswordConfig

Create an authenticator with its associated New function, and then call Authorize on the resulting object to authenticate. For example, to use certificate-based authentication:

import "github.com/Azure/go-autorest/autorest/azure/auth"
certificateAuthorizer := auth.NewClientCertificateConfig(certificatePath, certificatePassword, clientID, tenantID)
authorizerToken, err := certificateAuthorizer.Authorizer()

Next steps

Deploy an Azure virtual machine from Go