Merge pull request #350 from terraform-providers/docs-fixes

Various documentation fixes and enable custom partner ID

internal/clients/builder.go

@@ -13,8 +13,10 @@ import (
 )
 
 type ClientBuilder struct {
-	AuthConfig       *authentication.Config
-	TerraformVersion string
+	AuthConfig                *authentication.Config
+	DisableTerraformPartnerID bool
+	PartnerID                 string
+	TerraformVersion          string
 }
 
 // Build is a helper method which returns a fully instantiated *AadClient based on the auth Config's current settings.
@@ -54,9 +56,11 @@ func (b *ClientBuilder) Build(ctx context.Context) (*AadClient, error) {
 	}
 
 	o := &services.ClientOptions{
-		TenantID:         b.AuthConfig.TenantID,
-		TerraformVersion: b.TerraformVersion,
-		Environment:      *env,
+		DisableTerraformPartnerID: b.DisableTerraformPartnerID,
+		PartnerID:                 b.PartnerID,
+		TenantID:                  b.AuthConfig.TenantID,
+		TerraformVersion:          b.TerraformVersion,
+		Environment:               *env,
 	}
 
 	// Graph Endpoints

internal/provider/provider.go

@@ -7,6 +7,7 @@ import (
 
 	"github.com/hashicorp/go-azure-helpers/authentication"
 	"github.com/hashicorp/terraform-plugin-sdk/helper/schema"
+	"github.com/hashicorp/terraform-plugin-sdk/helper/validation"
 	"github.com/hashicorp/terraform-plugin-sdk/terraform"
 
 	"github.com/terraform-providers/terraform-provider-azuread/internal/clients"
@@ -76,25 +77,28 @@ func AzureADProvider() terraform.ResourceProvider {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARM_CLIENT_ID", ""),
+				Description: "The Client ID which should be used for service principal authentication.",
 			},
 
 			"tenant_id": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARM_TENANT_ID", ""),
+				Description: "The Tenant ID which should be used. Works with all authentication methods except MSI.",
 			},
 
 			"metadata_host": {
 				Type:        schema.TypeString,
 				Required:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARM_METADATA_HOSTNAME", ""),
-				Description: "The Hostname which should be used to fetch environment metadata from.",
+				Description: "The Hostname which should be used for the Azure Metadata Service.",
 			},
 
 			"environment": {
 				Type:        schema.TypeString,
 				Required:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARM_ENVIRONMENT", "public"),
+				Description: "The Cloud Environment which should be used. Possible values are `public`, `usgovernment`, `german`, and `china`. Defaults to `public`.",
 			},
 
 			// Client Certificate specific fields
@@ -108,26 +112,46 @@ func AzureADProvider() terraform.ResourceProvider {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARM_CLIENT_CERTIFICATE_PATH", ""),
+				Description: "The path to the Client Certificate associated with the Service Principal for use when authenticating as a Service Principal using a Client Certificate.",
 			},
 
 			// Client Secret specific fields
 			"client_secret": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARM_CLIENT_SECRET", ""),
+				Description: "The password to decrypt the Client Certificate. For use when authenticating as a Service Principal using a Client Certificate",
 			},
 
 			// Managed Service Identity specific fields
 			"use_msi": {
 				Type:        schema.TypeBool,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARM_USE_MSI", false),
+				Description: "Allow Managed Service Identity to be used for Authentication.",
 			},
 
 			"msi_endpoint": {
 				Type:        schema.TypeString,
 				Optional:    true,
 				DefaultFunc: schema.EnvDefaultFunc("ARM_MSI_ENDPOINT", ""),
+				Description: "The path to a custom endpoint for Managed Service Identity - in most circumstances this should be detected automatically. ",
+			},
+
+			// Managed Tracking GUID for User-agent
+			"partner_id": {
+				Type:         schema.TypeString,
+				Optional:     true,
+				ValidateFunc: validation.Any(validation.IsUUID, validation.StringIsEmpty),
+				DefaultFunc:  schema.EnvDefaultFunc("ARM_PARTNER_ID", ""),
+				Description:  "A GUID/UUID that is registered with Microsoft to facilitate partner resource usage attribution.",
+			},
+
+			"disable_terraform_partner_id": {
+				Type:        schema.TypeBool,
+				Optional:    true,
+				DefaultFunc: schema.EnvDefaultFunc("ARM_DISABLE_TERRAFORM_PARTNER_ID", false),
+				Description: "Disable the Terraform Partner ID which is used if a custom `partner_id` isn't specified.",
 			},
 		},
 
@@ -174,8 +198,10 @@ func providerConfigure(p *schema.Provider) schema.ConfigureFunc {
 		}
 
 		clientBuilder := clients.ClientBuilder{
-			AuthConfig:       config,
-			TerraformVersion: terraformVersion,
+			AuthConfig:                config,
+			PartnerID:                 d.Get("partner_id").(string),
+			DisableTerraformPartnerID: d.Get("disable_terraform_partner_id").(bool),
+			TerraformVersion:          terraformVersion,
 		}
 
 		client, err := clientBuilder.Build(p.StopContext())

internal/services/configure_client.go

@@ -14,6 +14,8 @@ import (
 	"github.com/terraform-providers/terraform-provider-azuread/version"
 )
 
+const terraformPartnerID = "222c6c49-1b0a-5959-a213-6608f9eb8820"
+
 type ClientOptions struct {
 	TenantID    string
 	Environment azure.Environment
@@ -48,7 +50,7 @@ func setUserAgent(client *autorest.Client, tfVersion, partnerID string, disableT
 	// unless users have opted out
 	if partnerID == "" && !disableTerraformPartnerID {
 		// Microsoft’s Terraform Partner ID is this specific GUID
-		partnerID = "222c6c49-1b0a-5959-a213-6608f9eb8820"
+		partnerID = terraformPartnerID
 	}
 
 	if partnerID != "" {

website/docs/d/application.html.markdown

@@ -32,7 +32,7 @@ output "azure_ad_object_id" {
 
 * `name` - (Optional) Specifies the name of the Application within Azure Active Directory.
 
--> **NOTE:** One of `object_id`, `application_id` or `name` must be specified.
+~> **NOTE:** One of `object_id`, `application_id` or `name` must be specified.
 
 ## Attributes Reference
 

website/docs/d/client_config.html.markdown

@@ -3,12 +3,12 @@ subcategory: "Base"
 layout: "azuread"
 page_title: "Azure Active Directory: azuread_client_config"
 description: |-
-  Gets information about the configuration of the azuread provider.
+  Gets information about the configuration of the AzureAD provider.
 ---
 
 # Data Source: azuread_client_config
 
-Use this data source to access the configuration of the AzureRM provider.
+Use this data source to access the configuration of the AzureAD provider.
 
 ## Example Usage
 
@@ -27,7 +27,6 @@ There are no arguments available for this data source.
 
 ## Attributes Reference
 
-* `client_id` is set to the Azure Client ID (Application Object ID).
-* `tenant_id` is set to the Azure Tenant ID.
-* `subscription_id` is set to the Azure Subscription ID.
-* `object_id` is set to the Azure Object ID.
+* `client_id` is set to the Client ID (Application ID).
+* `tenant_id` is set to the Tenant ID.
+* `object_id` is set to the Object ID of the authenticated principal.

website/docs/d/domains.html.markdown

@@ -3,12 +3,12 @@ subcategory: "Domains"
 layout: "azuread"
 page_title: "Azure Active Directory: azuread_domains"
 description: |-
-  Gets information about an existing Domains within Azure Active Directory.
+  Gets information about existing Domains within Azure Active Directory.
 ---
 
 # Data Source: azuread_domains
 
-Use this data source to access information about an existing Domains within Azure Active Directory.
+Use this data source to access information about existing Domains within Azure Active Directory.
 
 -> **NOTE:** If you're authenticating using a Service Principal then it must have permissions to `Directory.Read.All` within the `Windows Azure Active Directory` API.
 
@@ -24,11 +24,11 @@ output "domains" {
 
 ## Argument Reference
 
-* `include_unverified` - (Optional) Set to `true` if unverified Azure AD Domains should be included. Defaults to `false`.
+* `include_unverified` - (Optional) Set to `true` if unverified Azure AD domains should be included. Defaults to `false`.
 * `only_default` - (Optional) Set to `true` to only return the default domain.
 * `only_initial` - (Optional) Set to `true` to only return the initial domain, which is your primary Azure Active Directory tenant domain. Defaults to `false`.
 
--> **NOTE:** If `include_unverified` is set to `true` you cannot specify `only_default` or `only_initial`. Additionally you cannot combine `only_default` with `only_initial`.
+~> **NOTE:** If `include_unverified` is set to `true` you cannot specify `only_default` or `only_initial`. Additionally, you cannot combine `only_default` with `only_initial`.
 
 ## Attributes Reference
 
@@ -39,5 +39,5 @@ The `domain` block contains:
 * `domain_name` - The name of the domain.
 * `authentication_type` - The authentication type of the domain (Managed or Federated).
 * `is_default` - `True` if this is the default domain that is used for user creation.
-* `is_initial` - `True` if this is the initial domain created by Azure Activie Directory.
+* `is_initial` - `True` if this is the initial domain created by Azure Active Directory.
 * `is_verified` - `True` if the domain has completed domain ownership verification.

website/docs/d/group.html.markdown

@@ -29,7 +29,7 @@ The following arguments are supported:
 
 * `object_id` - (Optional) Specifies the Object ID of the AD Group within Azure Active Directory.
 
--> **NOTE:** Either a `name` or an `object_id` must be specified.
+~> **NOTE:** One of `name` or an `object_id` must be specified.
 
 ## Attributes Reference
 

website/docs/d/groups.html.markdown

@@ -29,7 +29,7 @@ The following arguments are supported:
 
 * `object_ids` - (Optional) The Object IDs of the Azure AD Groups.
 
--> **NOTE:** Either `names` or `object_ids` should be specified. Either of these _may_ be specified as an empty list, in which case no results will be returned.
+~> **NOTE:** Either `names` or `object_ids` should be specified. Either of these _may_ be specified as an empty list, in which case no results will be returned.
 
 ## Attributes Reference
 

website/docs/d/service_principal.html.markdown

@@ -47,7 +47,7 @@ The following arguments are supported:
 
 * `display_name` - (Optional) The Display Name of the Azure AD Application associated with this Service Principal.
 
--> **NOTE:** At least one of `application_id`, `display_name` or `object_id` must be specified.
+~> **NOTE:** At least one of `application_id`, `display_name` or `object_id` must be specified.
 
 * `app_roles` - A collection of `app_role` blocks as documented below. For more information https://docs.microsoft.com/en-us/azure/architecture/multitenant-identity/app-roles
 

website/docs/d/users.html.markdown

@@ -7,7 +7,7 @@ description: |-
 
 ---
 
-# Data Source: azuread_user
+# Data Source: azuread_users
 
 Gets Object IDs or UPNs for multiple Azure Active Directory users.
 
@@ -31,7 +31,7 @@ The following arguments are supported:
 
 * `mail_nicknames` - (Optional) The email aliases of the Azure AD Users.
 
--> **NOTE:** Either `user_principal_names`, `object_ids` or `mail_nicknames` should be specified. These _may_ be specified as an empty list, in which case no results will be returned.
+~> **NOTE:** Either `user_principal_names`, `object_ids` or `mail_nicknames` should be specified. These _may_ be specified as an empty list, in which case no results will be returned.
 
 * `ignore_missing` - (Optional) Ignore missing users and return users that were found. The data source will still fail if no users are found. Defaults to false.
 
@@ -48,13 +48,13 @@ ___
 
 The `user` object consists of:
 
-* `id` - The Object ID of the Azure AD User.
+* `object_id` - The Object ID of the Azure AD User.
 * `user_principal_name` - The User Principal Name of the Azure AD User.
 * `account_enabled` - `True` if the account is enabled; otherwise `False`.
 * `display_name` - The Display Name of the Azure AD User.
 * `mail` - The primary email address of the Azure AD User.
 * `mail_nickname` - The email alias of the Azure AD User.
-* `onpremises_sam_account_name` - The on premise sam account name of the Azure AD User.
-* `onpremises_user_principal_name` - The on premise user principal name of the Azure AD User.
+* `onpremises_sam_account_name` - The on-premise SAM account name of the Azure AD User.
+* `onpremises_user_principal_name` - The on-premise user principal name of the Azure AD User.
 * `usage_location` - The usage location of the Azure AD User.
 * `immutable_id` - The value used to associate an on-premises Active Directory user account with their Azure AD user object.

website/docs/guides/azure_cli.html.markdown

@@ -11,7 +11,7 @@ description: |-
 
 Terraform supports a number of different methods for authenticating to Azure:
 
-* Authenticating to Azure using the Azure CLI (which is covered in this guide)
+* Authenticating to Azure using the Azure CLI (covered in this guide)
 * [Authenticating to Azure using Managed Service Identity](managed_service_identity.html)
 * [Authenticating to Azure using a Service Principal and a Client Certificate](service_principal_client_certificate.html)
 * [Authenticating to Azure using a Service Principal and a Client Secret](service_principal_client_secret.html)
@@ -23,13 +23,13 @@ We recommend using either a Service Principal or Managed Service Identity when r
 ## Important Notes about Authenticating using the Azure CLI
 
 * Terraform only supports authenticating using the `az` CLI (and this must be available on your PATH) - authenticating using the older `azure` CLI or PowerShell Az / AzureRM Cmdlets is not supported.
-* Authenticating via the Azure CLI is only supported when using a User Account. If you're using a Service Principal (for example via `az login --service-principal`) you should instead authenticate via the Service Principal directly (either using a [Client Secret](service_principal_client_secret.html) or a [Client Certificate](service_principal_client_certificate.html)).
+* Authenticating via the Azure CLI is only supported when using a User Account. If you're using a Service Principal (for example via `az login --service-principal`) you should instead authenticate via the Service Principal directly, either using a [Client Certificate](service_principal_client_certificate.html) or a [Client Secret](service_principal_client_secret.html).
 
 ---
 
 ## Logging into the Azure CLI
 
-~> **Note**: If you're using the **China**, **German** or **Government** Azure Clouds - you'll need to first configure the Azure CLI to work with that Cloud.  You can do this by running:
+~> **Using other clouds** If you're using the **China**, **German** or **Government** Azure Clouds - you'll need to first configure the Azure CLI to work with that Cloud.  You can do this by running:
 
 ```shell
 $ az cloud set --name AzureChinaCloud|AzureGermanCloud|AzureUSGovernment
@@ -40,7 +40,7 @@ $ az cloud set --name AzureChinaCloud|AzureGermanCloud|AzureUSGovernment
 Firstly, login to the Azure CLI using:
 
 ```shell
-$ az login
+$ az login --allow-no-subscriptions
 ```
 
 Once logged in - it's possible to list the Subscriptions and Tenants associated with the account via:
@@ -49,7 +49,7 @@ Once logged in - it's possible to list the Subscriptions and Tenants associated
 $ az account list
 ```
 
-The output (similar to below) will display one or more Subscriptions - with the `tenantId` field being the `tenant_id` field referenced above.
+The output (similar to below) will display one or more Tenants and/or Subscriptions.
 
 ```json
 [
@@ -68,18 +68,31 @@ The output (similar to below) will display one or more Subscriptions - with the
 ]
 ```
 
-Should your account exist in more than one tenant (e.g. as a guest user), you can specify the tenant at login time:
+The provider will select the tenant ID from your default Azure CLI account. If you have more than one tenant listed in the output of `az account list`, for example if you are a guest user in other tenants, you can specify the tenant to use.
 
-```bash
-$ az login --tenant "TENANT_ID_OR_DOMAIN"
+```shell
+$ export ARM_TENANT_ID=00000000-0000-0000-0000-000000000000
 ```
 
-If your tenant does not have any subscriptions associated with it, for example if you are administering an Azure Active Directory B2C tenant, you will need to inform the CLI tools to permit signing in without one:
+You can also configure the tenant ID from within the provider block.
+
+```hcl
+provider "azuread" {
+  # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used
+  version = "=1.1.0"
+
+  tenant_id = "00000000-0000-0000-0000-000000000000"
+}
+```
+
+Alternatively, you can configure the Azure CLI to authenticate against the tenant you are managing with Terraform.
 
 ```bash
-$ az login --tenant "TENANT_ID_OR_DOMAIN" --allow-no-subscriptions
+$ az login --allow-no-subscriptions --tenant "TENANT_ID_OR_DOMAIN"
 ```
 
+-> **Tenants and Subscriptions** The AzureAD provider operates on tenants and not on subscriptions. We recommend always specifying `az login --allow-no-subscription` as it will force the Azure CLI to report tenants with no associated subscriptions, or if your user account does not have any roles assigned against your subscriptions.
+
 ---
 
 ## Configuring Azure CLI authentication in Terraform
@@ -88,17 +101,17 @@ No specific configuration is required for the provider to use Azure CLI authenti
 
 ```hcl
 provider "azuread" {
-  # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used
-  version = "=0.10.0"
+  # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider to be used
+  version = "=1.1.0"
 }
 ```
 
 If you're looking to use Terraform across Tenants - it's possible to do this by configuring the `tenant_id` field in the Provider block, as shown below:
 
 ```hcl
 provider "azuread" {
-  # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used
-  version = "=0.10.0"
+  # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider to be used
+  version = "=1.1.0"
 
   tenant_id = "10000000-2000-3000-4000-500000000000"
 }