diff --git a/internal/clients/builder.go b/internal/clients/builder.go index f4d882e1e0..2b3a65b9a4 100644 --- a/internal/clients/builder.go +++ b/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 diff --git a/internal/provider/provider.go b/internal/provider/provider.go index a0f64a69fb..73fb4ee9b0 100644 --- a/internal/provider/provider.go +++ b/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,6 +112,7 @@ 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 @@ -115,6 +120,7 @@ func AzureADProvider() terraform.ResourceProvider { 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 @@ -122,12 +128,30 @@ func AzureADProvider() terraform.ResourceProvider { 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()) diff --git a/internal/services/configure_client.go b/internal/services/configure_client.go index 82e0832839..1c1b2eb55c 100644 --- a/internal/services/configure_client.go +++ b/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 != "" { diff --git a/website/docs/d/application.html.markdown b/website/docs/d/application.html.markdown index 0ce1a92a34..ed9f62966b 100644 --- a/website/docs/d/application.html.markdown +++ b/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 diff --git a/website/docs/d/client_config.html.markdown b/website/docs/d/client_config.html.markdown index 940d2f6fb2..0df9bce8fd 100644 --- a/website/docs/d/client_config.html.markdown +++ b/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. diff --git a/website/docs/d/domains.html.markdown b/website/docs/d/domains.html.markdown index ff946e1bec..ef377c7803 100644 --- a/website/docs/d/domains.html.markdown +++ b/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. diff --git a/website/docs/d/group.html.markdown b/website/docs/d/group.html.markdown index 4b72e4ebb0..fb2d9ca752 100644 --- a/website/docs/d/group.html.markdown +++ b/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 diff --git a/website/docs/d/groups.html.markdown b/website/docs/d/groups.html.markdown index de20286638..0be1ee4c09 100644 --- a/website/docs/d/groups.html.markdown +++ b/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 diff --git a/website/docs/d/service_principal.html.markdown b/website/docs/d/service_principal.html.markdown index 825f290467..d262688b4b 100644 --- a/website/docs/d/service_principal.html.markdown +++ b/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 diff --git a/website/docs/d/users.html.markdown b/website/docs/d/users.html.markdown index f3c5766281..b921f15331 100644 --- a/website/docs/d/users.html.markdown +++ b/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. diff --git a/website/docs/guides/azure_cli.html.markdown b/website/docs/guides/azure_cli.html.markdown index 03a88702f3..17b37c29fd 100644 --- a/website/docs/guides/azure_cli.html.markdown +++ b/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,8 +101,8 @@ 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" } ``` @@ -97,8 +110,8 @@ If you're looking to use Terraform across Tenants - it's possible to do this by ```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" } diff --git a/website/docs/guides/managed_service_identity.html.markdown b/website/docs/guides/managed_service_identity.html.markdown index e58262f2ff..6d455ae5fa 100644 --- a/website/docs/guides/managed_service_identity.html.markdown +++ b/website/docs/guides/managed_service_identity.html.markdown @@ -12,7 +12,7 @@ description: |- Terraform supports a number of different methods for authenticating to Azure: * [Authenticating to Azure using the Azure CLI](azure_cli.html) -* Authenticating to Azure using Managed Service Identity (which is covered in this guide) +* Authenticating to Azure using Managed Service Identity (covered in this guide) * [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) @@ -22,20 +22,26 @@ We recommend using either a Service Principal or Managed Service Identity when r Once you have configured a Service Principal as described in this guide, you should follow the [Configuring a Service Principal for managing Azure Active Directory](service_principal_configuration.html) guide to grant the Service Principal necessary permissions to create and modify Azure Active Directory objects such as users and groups. -## What is Managed Service Identity? +## What is a managed identity? -Certain services within Azure (for example Virtual Machines and Virtual Machine Scale Sets) can be assigned an Azure Active Directory identity. This identity can then be granted permissions to manage objects in Azure Active Directory. +[Managed identities][azure-managed-identities] for Azure resources can be used to authenticate to Azure Active Directory. There are two types of managed identities: system-assigned and user-assigned. This article is based on system-assigned managed identities. -Once a resource is configured with an identity, a local metadata service exposes credentials which can be used by applications such as Terraform. +Managed identities work in conjunction with Azure Resource Manager (ARM), Azure AD, and the Azure Instance Metadata Service (IMDS). Azure resources that support managed identities expose an internal IMDS endpoint that the client can use to request an access token. No credentials are stored on the VM, and the only additional information needed to bootstrap the Terraform connection to Azure is the Tenant ID. -## Configuring Managed Service Identity +Azure AD creates an AD identity when you configure an Azure resource to use a system-assigned managed identity. The configuration process is described in more detail below. Azure AD then creates a service principal to represent the resource. The lifecycle of a system-assigned identity is tied to the resource it is enabled for: it is created when the resource is created and it is automatically removed when the resource is deleted. -The (simplified) Terraform Configuration below configures a Virtual Machine with Managed Service Identity, and then outputs the Object ID of the corresponding Service Principal: +Not all Azure services support managed identities, and availability varies by region. Configuration details vary slightly among services. For more information, see [Services that support managed identities for Azure resources][azure-managed-identities-services]. + +When using a managed identity, you can only manage resources in the tenant where the corresponding service principal is homed. If you need to manage multiple tenants from the same location, we suggest using Service Principal Authentication with a [client certificate](service_principal_client_certificate.html) or [client secret](service_principal_client_secret.html) so that you can specify different credentials for each tenant. + +## Configuring a VM to use a Managed system-assigned managed identity + +The (simplified) Terraform configuration below configures a Virtual Machine with a system-assigned identity, and then outputs the Object ID of the corresponding Service Principal: ```hcl data "azurerm_subscription" "current" {} -resource "azurerm_linux_virtual_machine" "test" { +resource "azurerm_linux_virtual_machine" "example" { name = "test-vm" # ... @@ -45,35 +51,37 @@ resource "azurerm_linux_virtual_machine" "test" { } } -output "test_msi_object_id" { +output "example_msi_object_id" { value = azurerm_linux_virtual_machine.test.identity.0.principal_id } ``` -The implicitly created Service Principal should have the same or similar name as your virtual machine. - Refer to the [azurerm_linux_virtual_machine][azurerm_linux_virtual_machine] and [azurerm_windows_virtual_machine][azurerm_windows_virtual_machine] documentation for more information on how to use these resources to launch a new virtual machine. +The implicitly created Service Principal should have the same or similar name as your virtual machine. At this point you will need to assign permissions to access Azure Active Directory to create and modify Azure Active Directory objects such as users and groups. We recommend the Directory Roles method. See the [Configuring a Service Principal for managing Azure Active Directory](service_principal_configuration.html#method-1-directory-roles-recommended) guide for more information. + ## Configuring Managed Service Identity in Terraform -At this point we assume that Managed Service Identity is configured on the resource (e.g. Virtual Machine) being used - and that you are running Terraform on that resource. +At this point we assume that managed identity is configured on the resource (e.g. virtual machine) being used, that permissions have been granted, and that you are running Terraform on that resource. -Terraform can be configured to use Managed Service Identity for authentication in one of two ways: using Environment Variables or by defining the fields within the Provider block. +Terraform can be configured to use managed identity for authentication in one of two ways: using Environment Variables or by defining the fields within the Provider block. You can configure Terraform to use Managed Service Identity by setting the Environment Variable `ARM_USE_MSI` to `true`; as shown below: ```shell -$ export ARM_USE_MSI=true +$ export ARM_USE_MSI=true ARM_TENANT_ID=00000000-0000-0000-0000-000000000000 ``` +Note that when using managed identity for authentication, the tenant ID must also be specified. + -> **Using a Custom MSI Endpoint?** In the unlikely event you're using a custom endpoint for Managed Service Identity - this can be configured using the `ARM_MSI_ENDPOINT` Environment Variable - however this shouldn't need to be configured in regular use. -Whilst a Provider block is _technically_ optional when using Environment Variables - we'd strongly recommend defining one to be able to pin the version of the Provider being used: +Whilst a Provider block is _technically_ optional when using Environment Variables - we'd strongly recommend defining one to be able to pin the version of the Provider to be used: ```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" } ``` @@ -81,21 +89,22 @@ More information on [the fields supported in the Provider block can be found her At this point running either `terraform plan` or `terraform apply` should allow Terraform to run using Managed Service Identity. -Next you should follow the [Configuring a Service Principal for managing Azure Active Directory](service_principal_configuration.html) guide to grant the Service Principal necessary permissions to create and modify Azure Active Directory objects such as users and groups. - --- -It's also possible to configure Managed Service Identity within the Provider Block: +It's also possible to enable Managed Service Identity 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 = "=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" - use_msi = true + use_msi = true + tenant_id = "00000000-0000-0000-0000-000000000000" } ``` +Note that when using managed identity for authentication, the tenant ID must also be specified. + -> **Using a Custom MSI Endpoint?** In the unlikely event you're using a custom endpoint for Managed Service Identity - this can be configured using the `msi_endpoint` field - however this shouldn't need to be configured in regular use. More information on [the fields supported in the Provider block can be found here](../index.html#argument-reference). @@ -105,5 +114,7 @@ At this point running either `terraform plan` or `terraform apply` should allow Next you should follow the [Configuring a Service Principal for managing Azure Active Directory](service_principal_configuration.html) guide to grant the Service Principal necessary permissions to create and modify Azure Active Directory objects such as users and groups. +[azure-managed-identities]: https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview +[azure-managed-identities-services]: https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/services-support-managed-identities [azurerm_linux_virtual_machine]: https://www.terraform.io/docs/providers/azurerm/r/linux_virtual_machine.html [azurerm_windows_virtual_machine]: https://www.terraform.io/docs/providers/azurerm/r/windows_virtual_machine.html diff --git a/website/docs/guides/service_principal_client_certificate.html.markdown b/website/docs/guides/service_principal_client_certificate.html.markdown index 382d7df6cc..c585460e97 100644 --- a/website/docs/guides/service_principal_client_certificate.html.markdown +++ b/website/docs/guides/service_principal_client_certificate.html.markdown @@ -13,13 +13,9 @@ Terraform supports a number of different methods for authenticating to Azure: * [Authenticating to Azure using the Azure CLI](azure_cli.html) * [Authenticating to Azure using Managed Service Identity](managed_service_identity.html) -* Authenticating to Azure using a Service Principal and a Client Certificate (which is covered in this guide) +* Authenticating to Azure using a Service Principal and a Client Certificate (covered in this guide) * [Authenticating to Azure using a Service Principal and a Client Secret](service_principal_client_secret.html) -Further steps must be taken to grant a Service Principal permission to manage objects in an Azure Active Directory: - -[Granting a Service Principal permission to manage AAD](service_principal_configuration.html) - --- We recommend using either a Service Principal or Managed Service Identity when running Terraform non-interactively (such as when running Terraform in a CI server) - and authenticating using the Azure CLI when running Terraform locally. @@ -95,12 +91,12 @@ $ export ARM_CLIENT_CERTIFICATE_PASSWORD="Pa55w0rd123" $ export ARM_TENANT_ID="10000000-2000-3000-4000-500000000000" ``` -The following Provider block can be specified - where `0.10.0` is the version of the AzureAD Provider that you'd like to use: +The following Provider block can be specified - where `1.1.0` is the version of the AzureAD Provider that you'd like to use: ```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" } ``` @@ -114,19 +110,19 @@ Next you should follow the [Configuring a Service Principal for managing Azure A It's also possible to configure these variables either in-line or from using variables in Terraform (as the `client_certificate_path` and `client_certificate_password` are in this example), like so: -~> **NOTE:** We'd recommend not defining these variables in-line since they could easily be checked into Source Control. +~> We recommend not defining these variables in-line since they could easily be checked into Source Control. ```hcl variable "client_certificate_path" {} variable "client_certificate_password" {} 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" client_id = "00000000-0000-0000-0000-000000000000" - client_certificate_path = "${var.client_certificate_path}" - client_certificate_password = "${var.client_certificate_password}" + client_certificate_path = var.client_certificate_path + client_certificate_password = var.client_certificate_password tenant_id = "10000000-2000-3000-4000-500000000000" } ``` diff --git a/website/docs/guides/service_principal_client_secret.html.markdown b/website/docs/guides/service_principal_client_secret.html.markdown index 4742f1e8b9..4d780a2fbf 100644 --- a/website/docs/guides/service_principal_client_secret.html.markdown +++ b/website/docs/guides/service_principal_client_secret.html.markdown @@ -14,7 +14,7 @@ Terraform supports a number of different methods for authenticating to Azure: * [Authenticating to Azure using the Azure CLI](azure_cli.html) * [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 (which is covered in this guide) +* Authenticating to Azure using a Service Principal and a Client Secret (covered in this guide) --- @@ -60,12 +60,12 @@ $ export ARM_CLIENT_SECRET="00000000-0000-0000-0000-000000000000" $ export ARM_TENANT_ID="10000000-2000-3000-4000-500000000000" ``` -The following Provider block can be specified - where `0.10.0` is the version of the AzureAD Provider that you'd like to use: +The following Provider block can be specified - where `1.1.0` is the version of the AzureAD Provider that you'd like to use: ```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" } ``` @@ -79,17 +79,17 @@ Next you should follow the [Configuring a Service Principal for managing Azure A It's also possible to configure these variables either in-line or from using variables in Terraform (as the `client_secret` is in this example), like so: -~> **NOTE:** We'd recommend not defining these variables in-line since they could easily be checked into Source Control. +~> We recommend not defining these variables in-line since they could easily be checked into Source Control. ```hcl variable "client_secret" {} 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" client_id = "00000000-0000-0000-0000-000000000000" - client_secret = "${var.client_secret}" + client_secret = var.client_secret tenant_id = "10000000-2000-3000-4000-500000000000" } ``` diff --git a/website/docs/guides/service_principal_configuration.html.markdown b/website/docs/guides/service_principal_configuration.html.markdown index ba193e5b0b..07173845d8 100644 --- a/website/docs/guides/service_principal_configuration.html.markdown +++ b/website/docs/guides/service_principal_configuration.html.markdown @@ -16,10 +16,6 @@ Terraform supports a number of different methods for authenticating to Azure: * [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) -Further steps must be taken to grant a Service Principal permission to manage objects in an Azure Active Directory: - -* Granting a Service Principal permission to manage AAD (which is covered in this guide) - --- We recommend using either a Service Principal or Managed Service Identity when running Terraform non-interactively (such as when running Terraform in a CI server) - and authenticating using the Azure CLI when running Terraform locally. @@ -48,11 +44,13 @@ Click "Add assignments" and type the name of your Service Principal in the searc The choice of which directory roles to assign will be specific to your organisations Commonly used roles include: -- `Global Administrator` - Effective superuser permissions to administer any object in your AAD tenant. Sometimes called `Company Administrator`. -- `Global Reader` - Commonly used in conjunction with other roles to allow reading, but not writing, of directory data. -- `Application Administrator` - Create and manage applications, service principals (enterprise applications) and application proxy. -- `Groups Administrator` - Create and manage groups. -- `User Administrator` - Create and manage users _and_ groups. +Role | Description +--------------------------- | ----------------------------------------------------------------------------------------------------------------------- +`Global Administrator` | Effective superuser permissions to administer any object in your AAD tenant. Sometimes called `Company Administrator`. +`Global Reader` | Commonly used in conjunction with other roles to allow reading, but not writing, of directory data. +`Application Administrator` | Create and manage applications, service principals (enterprise applications) and application proxy. +`Groups Administrator` | Create and manage groups. +`User Administrator` | Create and manage users _and_ groups. ### Method 2: API access with admin consent diff --git a/website/docs/index.html.markdown b/website/docs/index.html.markdown index ebc54d9dba..dd6ecc5a45 100644 --- a/website/docs/index.html.markdown +++ b/website/docs/index.html.markdown @@ -79,7 +79,7 @@ If you have configuration questions, or general questions about using the provid The following arguments are supported: -* `client_id` - (Optional) The Client ID which should be used. This can also be sourced from the `ARM_CLIENT_ID` Environment Variable. +* `client_id` - (Optional) The Client ID which should be used when authenticating as a service principal. This can also be sourced from the `ARM_CLIENT_ID` Environment Variable. * `environment` - (Optional) The Cloud Environment which be used. Possible values are `public`, `usgovernment`, `german` and `china`. Defaults to `public`. This can also be sourced from the `ARM_ENVIRONMENT` environment variable. @@ -115,4 +115,16 @@ More information on [how to configure a Service Principal using Managed Service --- +## Advanced Usage + +For more advanced scenarios, the following additional arguments are supported: + +* `disable_terraform_partner_id` - (Optional) Disable sending the Terraform Partner ID if a custom `partner_id` isn't specified. The default Partner ID allows Microsoft to better understand the usage of Terraform and does not give HashiCorp any direct access to usage information. This can also be sourced from the `ARM_DISABLE_TERRAFORM_PARTNER_ID` environment variable. Defaults to `false`. + +* `metadata_host` - (Optional) The Hostname of the Azure Metadata Service (for example `management.azure.com`), used to obtain the Cloud Environment when using a Custom Azure Environment. This can also be sourced from the `ARM_METADATA_HOST` Environment Variable. + +~> **Note:** `environment` must be set to the requested environment name in the list of available environments held in the `metadata_host`. + +* `partner_id` - (Optional) A GUID/UUID that is [registered](https://docs.microsoft.com/azure/marketplace/azure-partner-customer-usage-attribution#register-guids-and-offers) with Microsoft to facilitate partner resource usage attribution. This can also be sourced from the `ARM_PARTNER_ID` Environment Variable. + It's also possible to use multiple Provider blocks within a single Terraform configuration, for example to work with resources across multiple Azure Active Directory Environments - more information can be found [in the documentation for Providers](https://www.terraform.io/docs/configuration/providers.html#multiple-provider-instances). diff --git a/website/docs/r/application_certificate.html.markdown b/website/docs/r/application_certificate.html.markdown index 7f38533c9a..5f890f813c 100644 --- a/website/docs/r/application_certificate.html.markdown +++ b/website/docs/r/application_certificate.html.markdown @@ -42,7 +42,7 @@ The following arguments are supported: * `end_date_relative` - (Optional) A relative duration for which the Certificate is valid until, for example `240h` (10 days) or `2400h30m`. Changing this field forces a new resource to be created. --> **NOTE:** One of `end_date` or `end_date_relative` must be set. The maximum duration is one year. +~> **NOTE:** One of `end_date` or `end_date_relative` must be set. The maximum duration is one year. * `key_id` - (Optional) A GUID used to uniquely identify this Certificate. If not specified a GUID will be created. Changing this field forces a new resource to be created. diff --git a/website/docs/r/application_password.html.markdown b/website/docs/r/application_password.html.markdown index becc268e00..252b892ffa 100644 --- a/website/docs/r/application_password.html.markdown +++ b/website/docs/r/application_password.html.markdown @@ -44,7 +44,7 @@ The following arguments are supported: * `end_date_relative` - (Optional) A relative duration for which the Password is valid until, for example `240h` (10 days) or `2400h30m`. Changing this field forces a new resource to be created. --> **NOTE:** One of `end_date` or `end_date_relative` must be set. +~> **NOTE:** One of `end_date` or `end_date_relative` must be set. * `key_id` - (Optional) A GUID used to uniquely identify this Password. If not specified a GUID will be created. Changing this field forces a new resource to be created. diff --git a/website/docs/r/group.markdown b/website/docs/r/group.markdown index 45fe78ed7d..cc58836a78 100644 --- a/website/docs/r/group.markdown +++ b/website/docs/r/group.markdown @@ -53,9 +53,7 @@ The following arguments are supported: -> **NOTE:** Group names are not unique within Azure Active Directory. --> **NOTE:** Do not use `azuread_group_member` at the same time as the `members` argument. - --> **NOTE:** Do not use `azuread_group_owner` at the same time as the `owners` argument. +~> **NOTE:** Do not use the `azuread_group_member` resource at the same time as the `members` argument. ## Attributes Reference diff --git a/website/docs/r/service_principal_certificate.html.markdown b/website/docs/r/service_principal_certificate.html.markdown index abb77e6844..ce076991c8 100644 --- a/website/docs/r/service_principal_certificate.html.markdown +++ b/website/docs/r/service_principal_certificate.html.markdown @@ -46,7 +46,7 @@ The following arguments are supported: * `end_date_relative` - (Optional) A relative duration for which the Certificate is valid until, for example `240h` (10 days) or `2400h30m`. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Changing this field forces a new resource to be created. --> **NOTE:** One of `end_date` or `end_date_relative` must be set. The maximum duration is one year. +~> **NOTE:** One of `end_date` or `end_date_relative` must be set. The maximum duration is one year. * `key_id` - (Optional) A GUID used to uniquely identify this Certificate. If not specified a GUID will be created. Changing this field forces a new resource to be created. diff --git a/website/docs/r/service_principal_password.html.markdown b/website/docs/r/service_principal_password.html.markdown index 52459f0a1e..5c90fbace9 100644 --- a/website/docs/r/service_principal_password.html.markdown +++ b/website/docs/r/service_principal_password.html.markdown @@ -48,7 +48,7 @@ The following arguments are supported: * `end_date_relative` - (Optional) A relative duration for which the Password is valid until, for example `240h` (10 days) or `2400h30m`. Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h". Changing this field forces a new resource to be created. --> **NOTE:** One of `end_date` or `end_date_relative` must be set. +~> **NOTE:** One of `end_date` or `end_date_relative` must be set. * `key_id` - (Optional) A GUID used to uniquely identify this Key. If not specified a GUID will be created. Changing this field forces a new resource to be created. @@ -63,7 +63,7 @@ The following attributes are exported: ## Import -PPasswords can be imported using the `object id` of a Service Principal and the `key id` of the password, e.g. +Passwords can be imported using the `object id` of a Service Principal and the `key id` of the password, e.g. ```shell terraform import azuread_service_principal_password.test 00000000-0000-0000-0000-000000000000/11111111-1111-1111-1111-111111111111