Cleanup based on acrolynx feedback.

Author: Stephen Tramer

azure-go-sdk-conceptual/azure-sdk-go-auth-aad-samples.md

@@ -4,7 +4,7 @@ description: Selected samples for working with Azure Active Directory (AAD) and
 author: sptramer
 ms.author: sttramer
 manager: carmonm
-ms.date: 03/21/2018
+ms.date: 09/05/2018
 ms.topic: sample
 ms.prod: azure
 ms.technology: azure-sdk-go
@@ -13,7 +13,7 @@ ms.devlang: go
 ---
 # Azure SDK for Go samples for authentication and AAD
 
-The following table links to selected samples of Go source code that you can use to authenticate with the Azure SDK for Go and work with Azure Active Directory (AAD) services.
+The following table links to selected samples that demonstrate authentication and use of Azure Active Directory from the Azure SDK for Go.
 
 All samples for the Azure SDK for Go are available on [GitHub](https://github.com/Azure-Samples/azure-sdk-for-go-samples).
 

azure-go-sdk-conceptual/azure-sdk-go-authorization.md

@@ -5,7 +5,7 @@ services: azure
 author: sptramer
 ms.author: sttramer
 manager: carmonm
-ms.date: 04/03/2018 
+ms.date: 09/05/2018 
 ms.topic: conceptual
 ms.prod: azure
 ms.technology: azure-sdk-go
@@ -15,19 +15,19 @@ ms.component: authentication
 ---
 # Authentication methods in the Azure SDK for Go
 
-The Azure SDK for Go offers a variety of authentication types and methods that your application can use. Supported authentication methods range from pulling information from environment variables to interactive web-based authentication. This article introduces you to the available types of authentication in the SDK, and the methods for using them. You'll also learn best practices for selecting which authentication type is right for your application.
+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 of these authentication types are 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.
+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 an Azure Active Directory (AAD) user or service principal. To learn more, see [Get started with certificate-based authentication in Azure Active Directory]. |
 | 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 Service Identity (MSI) | Your application is running on an Azure resource that has been configured with Managed Service Identity (MSI). To learn more, see [Managed Service Identity (MSI) for Azure resources]. |
-| Device token | Your application is meant to be used interactively __only__ and will have a variety of users, potentially from multiple AAD tenants. Users have access to a web browser to sign in. For more information, see [Use device token authentication](#use-device-token-authentication).|
-| Username/password | You have an interactive application that cannot use any other authentication method. Your users do not have multi-factor authentication enabled for their AAD sign in. |
+| Device token | Your application is meant to be used interactively __only__. Users may have multi-factor authentication enabled. Users have access to a web browser to sign in. For more information, see [Use device token authentication](#use-device-token-authentication).|
+| Username/password | You have an interactive application that can't use any other authentication method. Your users don't have multi-factor authentication enabled for their AAD sign-in. |
 
 > [!IMPORTANT]
 > If you use an authentication type other than client credentials, your application must be registered in Azure Active Directory. To learn how,
@@ -40,7 +40,12 @@ The Azure SDK for Go offers several different types of authentication, using dif
 [Create a service principal with Azure CLI]: /cli/azure/create-an-azure-service-principal-azure-cli
 [Managed Service Identity (MSI) for Azure resources]: /azure/active-directory/managed-service-identity/overview
 
-These authentication types are available through different methods. [_Environment-based authentication_](#use-environment-based-authentication) reads credentials directly from the program's environment. [_File-based authentication_](#use-file-based-authentication) loads a file containing service principal credentials. [_Client-based authentication_](#use-an-authentication-client) uses an object in Go code and makes you responsible for providing the credentials during program execution. Finally, [_Device token authentication_](#use-device-token-authentication) requires users to sign in interactively through a web browser with a token, and cannot be used with environment- or file-based authentication.
+These authentication types are available through different methods.
+
+* [_Environment-based authentication_](#use-environment-based-authentication) reads credentials directly from the program's environment.
+* [_File-based authentication_](#use-file-based-authentication) loads a file containing service principal credentials.
+* [_Client-based authentication_](#use-an-authentication-client) uses an object in code and makes you responsible for providing the credentials during program execution.
+* [_Device token authentication_](#use-device-token-authentication) requires users to sign in interactively through a web browser with a token.
 
 All authentication functions and types are available in the `github.com/Azure/go-autorest/autorest/azure/auth` package.
 
@@ -49,9 +54,17 @@ All authentication functions and types are available in the `github.com/Azure/go
 
 ## Use environment-based authentication
 
-If you're running your application in a tightly controlled environment such as in a container, environment-based authentication is a natural choice. You configure the shell environment before running your application and the Go SDK reads these environment variables at runtime to authenticate with Azure.
+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 methods except device tokens, evaluated in the following order:
 
-Environment-based authentication has support for all authentication methods except device tokens, evaluated in the following order: Client credentials, certificates, username/password, and Managed Service Identity (MSI). If a required environment variable is unset or the SDK gets a refusal from the authentication service, the next authentication type is tried. If the SDK cannot authenticate from the environment, it returns an error.
+* Client credentials
+* X509 certificates
+* Username/password
+* Managed Service Identity (MSI)
+
+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.
 
@@ -68,14 +81,14 @@ The following table details the environment variables that need to be set for ea
 | | `AZURE_CLIENT_ID` | The application client ID. |
 | | `AZURE_USERNAME` | The username to sign in with. |
 | | `AZURE_PASSWORD` | The password to sign in with. |
-| __MSI__ | | MSI does not require any credentials to be set. The application must be running on an Azure resource configured to use MSI. For details, see [Managed Service Identity (MSI) for Azure resources]. |
+| __MSI__ | | No credentials are needed for MSI authentication. The application must be running on an Azure resource configured to use MSI. For details, see [Managed Service Identity (MSI) for Azure resources]. |
 
-If you need to connect to a cloud or management endpoint other than the default Azure public cloud, you can also set the following environment variables. The most common reasons to set them are if you use Azure Stack, a cloud in a different geographic region, or the Azure Classic deployment model.
+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. This should be a URI pointing to your management endpoint. |
+| `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](https://godoc.org/github.com/Azure/go-autorest/autorest/azure/auth#NewAuthorizerFromEnvironment) function to get your authorizer object. This object is then set
 on the `Authorizer` property of clients to allow them access to Azure.
@@ -96,18 +109,18 @@ To authenticate on Azure Stack, you need to set the following variables:
 
 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:
+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 details on how to use Azure SDK for Go on Azure Stack see [Use API version profiles with Go in Azure Stack](https://docs.microsoft.com/azure/azure-stack/user/azure-stack-version-profiles-go)
+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](https://docs.microsoft.com/azure/azure-stack/user/azure-stack-version-profiles-go)
 
 ## Use file-based authentication
 
-File-based authentication only works with client credentials when they are stored in a local file format generated by [the Azure CLI](/cli/azure). 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.
+File-based authentication uses a file format generated by [the Azure CLI](/cli/azure). 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.
 
 ```azurecli
 az ad sp create-for-rbac --sdk-auth > azure.auth
@@ -126,7 +139,7 @@ For more on using service principals and managing their access permissions, see
 
 ## Use device token authentication
 
-If you want users to sign in interactively, the best way to offer that capability 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 an Azure Active Directory (AAD) account. This authentication method supports accounts that have multi-factor authentication enabled, unlike standard username/password 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 an Azure Active Directory (AAD) account. This authentication method supports accounts that have multi-factor authentication enabled, unlike standard username/password authentication.
 
 To use device token authentication, create a [DeviceFlowConfig](https://godoc.org/github.com/Azure/go-autorest/autorest/azure/auth#DeviceFlowConfig) authorizer with the [NewDeviceFlowConfig](https://godoc.org/github.com/Azure/go-autorest/autorest/azure/auth#NewDeviceFlowConfig) function. Call [Authorizer](https://godoc.org/github.com/Azure/go-autorest/autorest/azure/auth#DeviceFlowConfig.Authorizer) on the resulting object to start the authentication process. Device flow authentication blocks program execution until the whole authentication flow is complete.
 
@@ -138,7 +151,11 @@ 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](https://godoc.org/github.com/Azure/go-autorest/autorest/azure/auth#AuthorizerConfig) interface. Use a type that implements this interface when you want an interactive program, use specialized configuration files, or have a requirement that prevents you from using another authentication method.
+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](https://godoc.org/github.com/Azure/go-autorest/autorest/azure/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
@@ -159,7 +176,7 @@ The following table lists the types in the SDK that conform to the `AuthorizerCo
 [DeviceFlowConfig]: https://godoc.org/github.com/Azure/go-autorest/autorest/azure/auth#DeviceFlowConfig
 [UsernamePasswordConfig]: https://godoc.org/github.com/Azure/go-autorest/autorest/azure/auth#UsernamePasswordConfig
 
-Create an authenticator with its associated `New` function, and then call `Authorize` on the resulting object to perform authentication. For example, to use certificate-based authentication:
+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:
 
 ```go
 import "github.com/Azure/go-autorest/autorest/azure/auth"

azure-go-sdk-conceptual/azure-sdk-go-compute-networking-samples.md

@@ -4,7 +4,7 @@ description: Selected samples for working with compute resources like VMs and vi
 author: sptramer
 ms.author: sttramer
 manager: carmonm
-ms.date: 03/21/2018
+ms.date: 09/05/2018
 ms.topic: sample
 ms.prod: azure
 ms.technology: azure-sdk-go
@@ -14,14 +14,14 @@ ms.devlang: go
 
 # Azure SDK for Go samples for compute and networking
 
-The following table links to selected samples of Go source code that you can use to manage VMs, virtual networks, and subnets in Azure. 
+The following table links to selected samples that demonstrate the management of compute and virtual network resources in the Azure SDK for Go.
 
 All samples for the Azure SDK for Go are available on [GitHub](https://github.com/Azure-Samples/azure-sdk-for-go-samples).
 
 | Name | Description |
 |------|-------------|
 | [network/network](https://github.com/Azure-Samples/azure-sdk-for-go-samples/blob/master/network/network.go) | Create, update, delete, and query network resources including virtual networks, subnets, and network security groups. |
-| [compute/vm_disk](https://github.com/Azure-Samples/azure-sdk-for-go-samples/blob/master/compute/vm_disk.go) | Create, attach, detatch, update, and encrypt data disks for a VM. |
+| [compute/vm_disk](https://github.com/Azure-Samples/azure-sdk-for-go-samples/blob/master/compute/vm_disk.go) | Create, attach, detach, update, and encrypt data disks for a VM. |
 | [compute/vm](https://github.com/Azure-Samples/azure-sdk-for-go-samples/blob/master/compute/vm.go) | Create, update, deactivate, and manage VMs. |
 | [compute/vm_with_availabilityset](https://github.com/Azure-Samples/azure-sdk-for-go-samples/blob/master/compute/vm_with_availabilityset.go) | Create availability sets and load balancers for VMs. |
 | [compute/vm_with_identity](https://github.com/Azure-Samples/azure-sdk-for-go-samples/blob/master/compute/vm_with_identity.go) | Create and manage Managed Service Identities (MSIs) for VMs. |

azure-go-sdk-conceptual/azure-sdk-go-containers-samples.md

@@ -4,7 +4,7 @@ description: Selected samples for working with ACI and AKS from the Azure SDK fo
 author: sptramer
 ms.author: sttramer
 manager: carmonm
-ms.date: 03/21/2018
+ms.date: 09/05/2018
 ms.topic: sample
 ms.prod: azure
 ms.technology: azure-sdk-go
@@ -14,7 +14,7 @@ ms.devlang: go
 
 # Azure SDK for Go samples for containers
 
-The following table links to selected samples of Go source code that you can use to work with containers on Azure via Azure Container Instances (ACI) or Azure Kubernetes Service (AKS). 
+The following table links to selected samples that demonstrate the management of Azure Container Instances (ACI) and Azure Kubernetes Service (AKS) from the Azure SDK for Go.
 
 All samples for the Azure SDK for Go are available on [GitHub](https://github.com/Azure-Samples/azure-sdk-for-go-samples).