diff --git a/website/docs/guides/azure_cli.html.markdown b/website/docs/guides/azure_cli.html.markdown index 3f3621830f..03a88702f3 100644 --- a/website/docs/guides/azure_cli.html.markdown +++ b/website/docs/guides/azure_cli.html.markdown @@ -22,8 +22,7 @@ We recommend using either a Service Principal or Managed Service Identity when r ## Important Notes about Authenticating using the Azure CLI -* Prior to version 1.20 the AzureAD Provider used a different method of authorizing via the Azure CLI where credentials reset after an hour - as such we'd recommend upgrading to version 1.20 or later of the AzureAD Provider. -* Terraform only supports authenticating using the `az` CLI (and this must be available on your PATH) - authenticating using the older `azure` CLI or PowerShell Cmdlets is not supported. +* 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)). --- @@ -44,13 +43,13 @@ Firstly, login to the Azure CLI using: $ az login ``` -Once logged in - it's possible to list the Subscriptions associated with the account via: +Once logged in - it's possible to list the Subscriptions and Tenants associated with the account via: ```shell $ az account list ``` -The output (similar to below) will display one or more Subscriptions - with the `id` field being the `subscription_id` field referenced above. +The output (similar to below) will display one or more Subscriptions - with the `tenantId` field being the `tenant_id` field referenced above. ```json [ @@ -69,59 +68,39 @@ The output (similar to below) will display one or more Subscriptions - with the ] ``` -Should you have more than one Subscription, you can specify the Subscription to use via the following command: +Should your account exist in more than one tenant (e.g. as a guest user), you can specify the tenant at login time: ```bash -$ az account set --subscription="SUBSCRIPTION_ID" +$ az login --tenant "TENANT_ID_OR_DOMAIN" ``` ---- - -## Configuring Azure CLI authentication in Terraform +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: -Now that we're logged into the Azure CLI - we can configure Terraform to use these credentials. - -To configure Terraform to use the Default Subscription defined in the Azure CLI - we can use the following 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.1.0" -} +```bash +$ az login --tenant "TENANT_ID_OR_DOMAIN" --allow-no-subscriptions ``` -More information on [the fields supported in the Provider block can be found here](../index.html#argument-reference). - -At this point running either `terraform plan` or `terraform apply` should allow Terraform to run using the Azure CLI to authenticate. - --- -It's also possible to configure Terraform to use a specific Subscription - for example: +## Configuring Azure CLI authentication in Terraform + +No specific configuration is required for the provider to use Azure CLI authentication. A Provider block is _technically_ optional, however we'd strongly recommend defining one to be able to pin the version of the Provider being used: ```hcl provider "azuread" { # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used - version = "=0.1.0" - - subscription_id = "00000000-0000-0000-0000-000000000000" + version = "=0.10.0" } ``` -More information on [the fields supported in the Provider block can be found here](../index.html#argument-reference). - -At this point running either `terraform plan` or `terraform apply` should allow Terraform to run using the Azure CLI to authenticate. - ---- - -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: +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.1.0" + version = "=0.10.0" - subscription_id = "00000000-0000-0000-0000-000000000000" - tenant_id = "11111111-1111-1111-1111-111111111111" + 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 28c83f0893..e58262f2ff 100644 --- a/website/docs/guides/managed_service_identity.html.markdown +++ b/website/docs/guides/managed_service_identity.html.markdown @@ -20,20 +20,24 @@ Terraform supports a number of different methods for authenticating to Azure: 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. +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? -Certain services within Azure (for example Virtual Machines and Virtual Machine Scale Sets) can be assigned an Azure Active Directory identity which can be used to access the Azure Subscription. This identity can then be assigned permissions to a Subscription, Resource Group or other resources using the Azure Identity and Access Management functionality - however by default no permissions are assigned. +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. Once a resource is configured with an identity, a local metadata service exposes credentials which can be used by applications such as Terraform. ## Configuring Managed Service Identity -The (simplified) Terraform Configuration below configures a Virtual Machine with Managed Service Identity, and then grants it Contributor access to the Subscription: +The (simplified) Terraform Configuration below configures a Virtual Machine with Managed Service Identity, and then outputs the Object ID of the corresponding Service Principal: ```hcl -data "azuread_subscription" "current" {} +data "azurerm_subscription" "current" {} + +resource "azurerm_linux_virtual_machine" "test" { + name = "test-vm" -resource "azuread_virtual_machine" "test" { # ... identity = { @@ -41,21 +45,18 @@ resource "azuread_virtual_machine" "test" { } } -data "azuread_builtin_role_definition" "contributor" { - name = "Contributor" -} - -resource "azuread_role_assignment" "test" { - name = "${azuread_virtual_machine.test.name}" - scope = "${data.azuread_subscription.primary.id}" - role_definition_id = "${data.azuread_subscription.subscription.id}${data.azuread_builtin_role_definition.contributor.id}" - principal_id = "${lookup(azuread_virtual_machine.test.identity[0], "principal_id")}" +output "test_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. + ## 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 permissions have been assigned via Azure's Identity and Access Management system. +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. 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. @@ -72,7 +73,7 @@ Whilst a Provider block is _technically_ optional when using Environment Variabl ```hcl provider "azuread" { # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used - version = "=0.1.0" + version = "=0.10.0" } ``` @@ -80,6 +81,8 @@ 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: @@ -87,7 +90,7 @@ It's also possible to configure Managed Service Identity within the Provider Blo ```hcl provider "azuread" { # Whilst version is optional, we /strongly recommend/ using it to pin the version of the Provider being used - version = "=0.1.0" + version = "=0.10.0" use_msi = true } @@ -98,3 +101,9 @@ provider "azuread" { More information on [the fields supported in the Provider block can be found here](../index.html#argument-reference). 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. + + +[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 67da830e6c..382d7df6cc 100644 --- a/website/docs/guides/service_principal_client_certificate.html.markdown +++ b/website/docs/guides/service_principal_client_certificate.html.markdown @@ -24,15 +24,15 @@ Further steps must be taken to grant a Service Principal permission to manage ob 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. -Beyond authentication and managing Azure AAD resources further steps are required to make so a Service principal can make changes to Azure Active Directory objects such as users and groups. The [Granting a Service Principal permission to manage AAD](service_principal_configuration.html) guide contains the required steps. +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. --- -## Creating a Service Principal +## Setting up an Application and Service Principal -A Service Principal is an application within Azure Active Directory which can be used as a means of authentication, either [using a Client Secret](service_principal_client_secret.html) or a Client Certificate (which is documented in this guide) and can be created though the Azure Portal. +A Service Principal is a security principal within Azure Active Directory which can be granted permissions to manage objects in Azure Active Directory. To authenticate with a Service Principal, you will need to create an Application object within Azure Active Directory, which you will use as a means of authentication, either [using a Client Secret](service_principal_client_secret.html) or a Client Certificate (which is documented in this guide). This can be done using the Azure Portal. -This guide will cover how to generate a client certificate, how to create a Service Principal and then how to assign the Client Certificate to the Service Principal so that it can be used for authentication. Once that's done finally we're going to grant the Service Principal permission to manage resources in the Subscription - to do this we're going to assign `Contributor` rights to the Subscription - however [it's possible to assign other permissions](https://azure.microsoft.com/en-gb/documentation/articles/role-based-access-built-in-roles/) depending on your configuration. +This guide will cover how to generate a client certificate, how to create an Application and linked Service Principal, and then how to assign the Client Certificate to the Application so that it can be used for authentication. --- @@ -58,37 +58,27 @@ Finally we can generate a PFX file which can be used to authenticate with Azure: $ openssl pkcs12 -export -out "service-principal.pfx" -inkey "service-principal.key" -in "service-principal.crt" ``` -Now that we've generated a certificate, we can create the Azure Active Directory application. +Now that we've generated a certificate, we can create the Azure Active Directory Application. --- -### Creating the Service Principal +### Creating the Application and Service Principal -We're going to create the Service Principal in the Azure Portal - to do this navigate to [the **Azure Active Directory** overview](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview) within the Azure Portal - [then select the **App Registration** blade](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps/RegisteredApps/Overview) and click **Endpoints** at the top of the **App Registration** blade. A list of URIs will be displayed and you need to locate the URI for **OAUTH 2.0 AUTHORIZATION ENDPOINT** which contains a GUID. This GUID is your Tenant ID (the `tenant_id` field mentioned above). - -Next, navigate back to [the **App Registration** blade](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps/RegisteredApps/Overview) - from here we'll create the Application in Azure Active Directory. To do this click **New application registration** at the top to add a new Application within Azure Active Directory. On this page, set the following values then press **Create**: +We're going to create the Application in the Azure Portal - to do this navigate to the [**Azure Active Directory** overview][azure-portal-aad-overview] within the [Azure Portal][azure-portal] - then select the [**App Registrations** blade][azure-portal-applications-blade]. Click the **New registration** button at the top to add a new Application within Azure Active Directory. On this page, set the following values then press **Create**: - **Name** - this is a friendly identifier and can be anything (e.g. "Terraform") -- **Application Type** - this should be set to "Web app / API" -- **Sign-on URL** - this can be anything, providing it's a valid URI (e.g. https://terra.form) - -At this point the newly created Azure Active Directory application should be visible on-screen - if it's not, navigate to the [the **App Registration** blade](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps/RegisteredApps/Overview) and select the Azure Active Directory application. At the top of this page, the "Application ID" GUID is the `client_id` you'll need. - -### Assigning the Client Certificate to the Service Principal - -To associate the public portion of the Client Certificate (the `*.crt` file) with the Azure Active Directory Application - to do this select **Settings** and then **Keys**. This screen displays the Passwords (Client Secrets) and Public Keys (Client Certificates) which are associated with this Azure Active Directory Application. +- **Supported Account Types** - this should be set to "Accounts in this organisational directory only (single tenant)" +- **Redirect URI** - you should choose "Web" in for the URI type. the actual value can be left blank -The Public Key associated with the generated Certificate can be uploaded by selecting **Upload Public Key**, selecting the file which should be uploaded (in the example above, this'd be `service-principal.crt`) - and then hitting **Save**. +At this point the newly created Azure Active Directory application should be visible on-screen - if it's not, navigate to the [**App Registration** blade][azure-portal-applications-blade] and select the newly created Azure Active Directory application. -### Allowing the Service Principal to manage the Subscription +At the top of this page, you'll need to take note of the "Application (client) ID" and the "Directory (tenant) ID", which you can use for the values of `client_id` and `tenant_id` respectively. -Now that we've created the Application within Azure Active Directory and assigned the certificate we're using for authentication, we can now grant the Application permissions to manage the Subscription. To do this, [navigate to the **Subscriptions** blade within the Azure Portal](https://portal.azure.com/#blade/Microsoft_Azure_Billing/SubscriptionsBlade), select the Subscription you wish to use, then click **Access Control (IAM)** and finally **Add role assignment**. +### Assigning the Client Certificate to the Azure Active Directory Application -Firstly, specify a Role which grants the appropriate permissions needed for the Service Principal (for example, `Contributor` will grant Read/Write on all resources in the Subscription). More information about [the built in roles can be found here](https://azure.microsoft.com/en-gb/documentation/articles/role-based-access-built-in-roles/). +To associate the public portion of the Client Certificate (the `*.crt` file) with the Azure Active Directory Application - to do this select **Certificates & secrets**. This screen displays the Certificates and Client Secrets (i.e. passwords) which are associated with this Azure Active Directory Application. -Secondly, search for and select the name of the Application created in Azure Active Directory to assign it this role - then press **Save**. - -At this point the newly created Azure Active Directory Application should be associated with the Certificate that we generated earlier (which can be used as a Client Certificate) - and should have permissions to the Azure Subscription. +The Public Key associated with the generated Certificate can be uploaded by selecting **Upload Certificate**, selecting the file which should be uploaded (in the example above, this'd be `service-principal.crt`) - and then hitting **Add**. --- @@ -102,16 +92,15 @@ When storing the credentials as Environment Variables, for example: $ export ARM_CLIENT_ID="00000000-0000-0000-0000-000000000000" $ export ARM_CLIENT_CERTIFICATE_PATH="/path/to/my/client/certificate.pfx" $ export ARM_CLIENT_CERTIFICATE_PASSWORD="Pa55w0rd123" -$ export ARM_SUBSCRIPTION_ID="00000000-0000-0000-0000-000000000000" -$ export ARM_TENANT_ID="00000000-0000-0000-0000-000000000000" +$ export ARM_TENANT_ID="10000000-2000-3000-4000-500000000000" ``` -The following Provider block can be specified - where `1.20.0` is the version of the Azure Provider that you'd like to use: +The following Provider block can be specified - where `0.10.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.1.0" + version = "=0.10.0" } ``` @@ -119,6 +108,8 @@ 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 the Service Principal to authenticate. +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 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: @@ -131,13 +122,12 @@ 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.1.0" + version = "=0.10.0" - subscription_id = "00000000-0000-0000-0000-000000000000" client_id = "00000000-0000-0000-0000-000000000000" client_certificate_path = "${var.client_certificate_path}" client_certificate_password = "${var.client_certificate_password}" - tenant_id = "00000000-0000-0000-0000-000000000000" + tenant_id = "10000000-2000-3000-4000-500000000000" } ``` @@ -145,4 +135,8 @@ 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 the Service Principal to authenticate. -Next you may want to follow the [Granting a Service Principal permission to manage AAD](service_principal_configuration.html) guide to grant the Service Ability permission to create and modify Azure Active Directory objects such as users and groups. +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-portal]: https://portal.azure.com/ +[azure-portal-aad-overview]: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview +[azure-portal-applications-blade]: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps/RegisteredApps/Overview diff --git a/website/docs/guides/service_principal_client_secret.html.markdown b/website/docs/guides/service_principal_client_secret.html.markdown index 59788d9467..4742f1e8b9 100644 --- a/website/docs/guides/service_principal_client_secret.html.markdown +++ b/website/docs/guides/service_principal_client_secret.html.markdown @@ -16,156 +16,35 @@ 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 (which is covered in this guide) -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. -Beyond authentication and managing Azure AAD resources further steps are required to make so a Service principal can make changes to Azure Active Directory objects such as users and groups. The [Granting a Service Principal permission to manage AAD](service_principal_configuration.html) guide contains the required steps. - -## Creating a Service Principal - -A Service Principal is an application within Azure Active Directory whose authentication tokens can be used as the `client_id`, `client_secret`, and `tenant_id` fields needed by Terraform (`subscription_id` can be independently recovered from your Azure account details). - -It's possible to complete this task in either the [Azure CLI](#creating-a-service-principal-using-the-azure-cli) or in the [Azure Portal](#creating-a-service-principal-in-the-azure-portal) - in both we'll create a Service Principal which has `Contributor` rights to the subscription. [It's also possible to assign other rights](https://azure.microsoft.com/en-gb/documentation/articles/role-based-access-built-in-roles/) depending on your configuration. - -### Creating a Service Principal using 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: - -```shell -$ az cloud set --name AzureChinaCloud|AzureGermanCloud|AzureUSGovernment -``` - ---- - -Firstly, login to the Azure CLI using: - -```shell -$ az login -``` - -Once logged in - it's possible to list the Subscriptions associated with the account via: - -```shell -$ az account list -``` - -The output (similar to below) will display one or more Subscriptions - with the `id` field being the `subscription_id` field referenced above. - -```json -[ - { - "cloudName": "AzureCloud", - "id": "00000000-0000-0000-0000-000000000000", - "isDefault": true, - "name": "PAYG Subscription", - "state": "Enabled", - "tenantId": "00000000-0000-0000-0000-000000000000", - "user": { - "name": "user@example.com", - "type": "user" - } - } -] -``` - -Should you have more than one Subscription, you can specify the Subscription to use via the following command: - -```shell -$ az account set --subscription="SUBSCRIPTION_ID" -``` - -We can now create the Service Principal which will have permissions to manage resources in the specified Subscription using the following command: - -```shell -$ az ad sp create-for-rbac --role="Contributor" --scopes="/subscriptions/SUBSCRIPTION_ID" -``` - -This command will output 5 values: - -```json -{ - "appId": "00000000-0000-0000-0000-000000000000", - "displayName": "azure-cli-2017-06-05-10-41-15", - "name": "http://azure-cli-2017-06-05-10-41-15", - "password": "0000-0000-0000-0000-000000000000", - "tenant": "00000000-0000-0000-0000-000000000000" -} -``` - -These values map to the Terraform variables like so: - - - `appId` is the `client_id` defined above. - - `password` is the `client_secret` defined above. - - `tenant` is the `tenant_id` defined above. - ---- - -Finally, it's possible to test these values work as expected by first logging in: - -```shell -$ az login --service-principal -u CLIENT_ID -p CLIENT_SECRET --tenant TENANT_ID -``` - -Once logged in as the Service Principal - we should be able to list the VM sizes by specifying an Azure region, for example here we use the `West US` region: +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. -```shell -$ az vm list-sizes --location westus -``` +## Setting up an Application and Service Principal -~> **Note**: If you're using the **China**, **German** or **Government** Azure Clouds - you will need to switch `westus` out for another region. You can find which regions are available by running: +A Service Principal is a security principal within Azure Active Directory which can be granted permissions to manage objects in Azure Active Directory. To authenticate with a Service Principal, you will need to create an Application object within Azure Active Directory, which you will use as a means of authentication, either [using a Client Secret](service_principal_client_secret.html) or a Client Certificate (which is documented in this guide). This can be done using the Azure Portal. -```shell -$ az account list-locations -``` +This guide will cover how to create an Application and linked Service Principal, and then how to generate a Client Secret for the Application so that it can be used for authentication. -Finally, since we're logged into the Azure CLI as a Service Principal we recommend logging out of the Azure CLI (but you can instead log in using your user account): - -```bash -$ az logout -``` +### Creating the Application and Service Principal -Information on how to configure the Provider block using the newly created Service Principal credentials can be found below. - ---- - -### Creating a Service Principal in the Azure Portal - -There are three tasks necessary to create a Service Principal using [the Azure Portal](https://portal.azure.com): - - 1. Create an Application in Azure Active Directory (which acts as a Service Principal) - 2. Generating a Client Secret for the Azure Active Directory Application (which can be used for authentication) - 3. Grant the Application access to manage resources in your Azure Subscription - -### 1. Creating an Application in Azure Active Directory - -Firstly navigate to [the **Azure Active Directory** overview](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview) within the Azure Portal - [then select the **App Registration** blade](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps/RegisteredApps/Overview) and click **Endpoints** at the top of the **App Registration** blade. A list of URIs will be displayed and you need to locate the URI for **OAUTH 2.0 AUTHORIZATION ENDPOINT** which contains a GUID. This GUID is your Tenant ID (the `tenant_id` field mentioned above). - -Next, navigate back to [the **App Registration** blade](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps/RegisteredApps/Overview) - from here we'll create the Application in Azure Active Directory. To do this click **New application registration** at the top to add a new Application within Azure Active Directory. On this page, set the following values then press **Create**: +We're going to create the Application in the Azure Portal - to do this navigate to the [**Azure Active Directory** overview][azure-portal-aad-overview] within the [Azure Portal][azure-portal] - then select the [**App Registrations** blade][azure-portal-applications-blade]. Click the **New registration** button at the top to add a new Application within Azure Active Directory. On this page, set the following values then press **Create**: - **Name** - this is a friendly identifier and can be anything (e.g. "Terraform") -- **Application Type** - this should be set to "Web app / API" -- **Sign-on URL** - this can be anything, providing it's a valid URI (e.g. https://terra.form) - -At this point the newly created Azure Active Directory application should be visible on-screen - if it's not, navigate to the [the **App Registration** blade](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps/RegisteredApps/Overview) and select the Azure Active Directory application. At the top of this page, the "Application ID" GUID is the `client_id` you'll need. - -### 2. Generating a Client Secret for the Azure Active Directory Application +- **Supported Account Types** - this should be set to "Accounts in this organisational directory only (single tenant)" +- **Redirect URI** - you should choose "Web" in for the URI type. the actual value can be left blank -Now that the Azure Active Directory Application exists we can create a Client Secret which can be used for authentication - to do this select **Settings** and then **Keys**. This screen displays the Passwords (Client Secrets) and Public Keys (Client Certificates) which are associated with this Azure Active Directory Application. +At this point the newly created Azure Active Directory application should be visible on-screen - if it's not, navigate to the [**App Registration** blade][azure-portal-applications-blade] and select the Azure Active Directory application. -On this screen we can generate a new Password by entering a Description and selecting an Expiry Date, and then pressing **Save**. Once the Password has been generated it will be displayed on screen - _the Password is only displayed once_ so **be sure to copy it now** (otherwise you will need to regenerate a new key). This newly generated Password is the `client_secret` you will need. +At the top of this page, you'll need to take note of the "Application (client) ID" and the "Directory (tenant) ID", which you can use for the values of `client_id` and `tenant_id` respectively. -### 3. Granting the Application access to manage resources in your Azure Subscription +### Generating a Client Secret for the Azure Active Directory Application -Once the Application exists in Azure Active Directory - we can grant it permissions to modify resources in the Subscription. To do this, [navigate to the **Subscriptions** blade within the Azure Portal](https://portal.azure.com/#blade/Microsoft_Azure_Billing/SubscriptionsBlade), then select the Subscription you wish to use, then click **Access Control (IAM)**, and finally **Add role assignment**. +Now that the Azure Active Directory Application exists we can create a Client Secret which can be used for authentication - to do this select **Certificates & secrets**. This screen displays the Certificates and Client Secrets (i.e. passwords) which are associated with this Azure Active Directory Application. -Firstly, specify a Role which grants the appropriate permissions needed for the Service Principal (for example, `Contributor` will grant Read/Write on all resources in the Subscription). There's more information about [the built in roles available here](https://azure.microsoft.com/en-gb/documentation/articles/role-based-access-built-in-roles/). - -Secondly, search for and select the name of the Application created in Azure Active Directory to assign it this role - then press **Save**. +Click the "New client secret" button, then enter a short description, choose an expiry period and click "Add". Once the Client Secret has been generated it will be displayed on screen - _the secret is only displayed once_ so **be sure to copy it now** (otherwise you will need to regenerate a new one). This is the `client_secret` you will need. --- @@ -178,16 +57,15 @@ When storing the credentials as Environment Variables, for example: ```bash $ export ARM_CLIENT_ID="00000000-0000-0000-0000-000000000000" $ export ARM_CLIENT_SECRET="00000000-0000-0000-0000-000000000000" -$ export ARM_SUBSCRIPTION_ID="00000000-0000-0000-0000-000000000000" -$ export ARM_TENANT_ID="00000000-0000-0000-0000-000000000000" +$ export ARM_TENANT_ID="10000000-2000-3000-4000-500000000000" ``` -The following Provider block can be specified - where `1.20.0` is the version of the Azure Provider that you'd like to use: +The following Provider block can be specified - where `0.10.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.1.0" + version = "=0.10.0" } ``` @@ -195,6 +73,8 @@ 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 the Service Principal to authenticate. +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 these variables either in-line or from using variables in Terraform (as the `client_secret` is in this example), like so: @@ -206,12 +86,11 @@ 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.1.0" + version = "=0.10.0" - subscription_id = "00000000-0000-0000-0000-000000000000" - client_id = "00000000-0000-0000-0000-000000000000" - client_secret = "${var.client_secret}" - tenant_id = "00000000-0000-0000-0000-000000000000" + client_id = "00000000-0000-0000-0000-000000000000" + client_secret = "${var.client_secret}" + tenant_id = "10000000-2000-3000-4000-500000000000" } ``` @@ -219,4 +98,8 @@ 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 the Service Principal to authenticate. -Next you may want to follow the [Granting a Service Principal permission to manage AAD](service_principal_configuration.html) guide to grant the Service Ability permission to create and modify Azure Active Directory objects such as users and groups. +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-portal]: https://portal.azure.com/ +[azure-portal-aad-overview]: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview +[azure-portal-applications-blade]: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps/RegisteredApps/Overview diff --git a/website/docs/guides/service_principal_configuration.html.markdown b/website/docs/guides/service_principal_configuration.html.markdown index cf8e354f76..bc5fb9d826 100644 --- a/website/docs/guides/service_principal_configuration.html.markdown +++ b/website/docs/guides/service_principal_configuration.html.markdown @@ -26,77 +26,55 @@ We recommend using either a Service Principal or Managed Service Identity when r ## Creating a Service Principal -A Service Principal is an application within Azure Active Directory whose authentication tokens can be used as the `client_id`, `client_secret`, and `tenant_id` fields needed by Terraform (`subscription_id` can be independently recovered from your Azure account details). +A Service Principal represents an application within Azure Active Directory whose authentication tokens can be used as the `client_id`, `client_secret`, and `tenant_id` fields needed by Terraform (`subscription_id` can be independently recovered from your Azure account details). Depending on how the service principal authenticates to azure it can be created in a number of different ways: * [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) -## Granting administrator permissions +## Azure Active Directory permissions -~> **Note**: This requires the use of powershell cmdlets and is easiest to run in CloudShell. +Now that you have created and authenticated an Application / Service Principal pair, you will need to grant some permissions to administer Azure Active Directory. You can choose either of the following methods to achieve similar results. +### Method 1: Directory Roles (recommended) -Firstly, connect to the directory using: +With this method, you will assign directory roles to the Service Principal you created, to grant the desired permissions to administer objects in your Azure Active Directory tenant. -```shell -Connect-AzureAD -TenantID "00000000-0000-0000-0000-000000000000" -``` +Navigate to the [**Azure Active Directory** overview][azure-portal-aad-overview] within the [Azure Portal][azure-portal]. Go to the [**Roles and Administrators** blade][azure-portal-aad-roles-blade]. -Next we want to get the correct role to assign, in this case `User Account Administrator`: +Locate the role you wish to assign and click on it. Consult the [documentation for administrator role permissions][admin-roles-docs] from Microsoft for more information about the available roles and the permissions they grant. -```shell -$role = Get-AzureADDirectoryRole | Where-Object {$_.displayName -eq 'User Account Administrator'} -Write-Host $role -``` +Click "Add assignments" and type the name of your Service Principal in the search box to locate it. If you know the Object ID of the Service Principal, verify that it is the same. Select it and click the "Add" button to assign the role. -Since this is a built-in Role, if this doesn't exist (returns `null` above) then we need to instantiate it from the Role Template: +The choice of which directory roles to assign will be specific to your organisations Commonly used roles include: -```shell -if ($role -eq $null) { - # Instantiate an instance of the role template - $roleTemplate = Get-AzureADDirectoryRoleTemplate | Where-Object {$_.displayName -eq 'User Account Administrator'} - Enable-AzureADDirectoryRole -RoleTemplateId $roleTemplate.ObjectId +- `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. - # Fetch User Account Administrator role instance again - $role = Get-AzureADDirectoryRole | Where-Object {$_.displayName -eq 'User Account Administrator'} -} -``` +### Method 2: API access with admin consent -Next we need the Client ID (sometimes referred to as the Application ID) of the Service Principal. We can look this up by it's display name: +This method involves granting API scopes to your Application, and then granting consent for your Application to access the APIs in its own capacity (i.e. not on behalf of a user). -```shell -$sp = Get-AzureADServicePrincipal -All $true | Where-Object {$_.displayName -eq 'Service Principal Name'} -$sp.ObjectId -``` +Navigate to the [**Azure Active Directory** overview][azure-portal-aad-overview] within the [Azure Portal][azure-portal] and select the [**App Registrations** blade][azure-portal-applications-blade]. Locate your registered Application and click on its display name to manage it. -Now that we have all the required information we can add the service principal to the role: +Go to the API Permissions blade for the Application and click the "Add a permission" button. In the pane that opens, select "Azure Active Directory Graph" (under the Supported Legacy APIs subheading). Do not select "Microsoft Graph", as the provider does not currently make use of this API. -```shell -Add-AzureADDirectoryRoleMember -ObjectId $role.ObjectId -RefObjectId $sp.ObjectId +Choose "Application Permissions" for the permission type, and check the permissions you would like to assign. The permissions you need will depend on which directory objects you are seeking to manage with Terraform. We suggest the following permissions: -``` +- `Application.ReadWrite.All` +- `Directory.ReadWrite.All` -Finally we can repeat this for the `Company Administrator` role: +Note that these permissions do not cover all use cases. Notable actions you cannot perform with permissions granted in this way include deleting groups and deleting users. -```shell -$role = Get-AzureADDirectoryRole | Where-Object {$_.displayName -eq 'Company Administrator'} -$role +Once you have assigned the permissions, you will need to grant admin consent. This requires that you are signed in to the Portal as a Global Administrator. Click the "Grant admin consent" button and confirm the action. -if ($role -eq $null) { - # Instantiate an instance of the role template - $roleTemplate = Get-AzureADDirectoryRoleTemplate | Where-Object {$_.displayName -eq 'Company Administrator'} - Enable-AzureADDirectoryRole -RoleTemplateId $roleTemplate.ObjectId +The Application now has permission to administer your Azure Active Directory tenant. - # Fetch User Account Administrator role instance again - $role = Get-AzureADDirectoryRole | Where-Object {$_.displayName -eq 'Company Administrator'} -} -$sp = Get-AzureADServicePrincipal | Where-Object {$_.displayName -eq 'Service Principal Name'} -$sp.ObjectId - -Add-AzureADDirectoryRoleMember -ObjectId $role.ObjectId -RefObjectId $sp.ObjectId - -``` - -At this point you should now be able to manage Users, Groups and other Azure Active Directory resources using Terraform. +[admin-roles-docs]: https://docs.microsoft.com/en-us/azure/active-directory/users-groups-roles/directory-assign-admin-roles +[azure-portal]: https://portal.azure.com/ +[azure-portal-aad-overview]: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/Overview +[azure-portal-aad-roles-blade]: https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RolesAndAdministrators \ No newline at end of file