provider/azurerm: Updating the AzureRM Provider Guide (#15148)

* SSL all the things!

* Rewriting the AzureRM docs

website/source/docs/providers/azurerm/index.html.markdown

@@ -92,73 +92,117 @@ The following arguments are supported:
 
 Azure requires that an application is added to Azure Active Directory to generate the `client_id`, `client_secret`, and `tenant_id` needed by Terraform (`subscription_id` can be recovered from your Azure account details).
 
-There are two high-level tasks to complete.  The first is to create an App Registration with Azure Active Directory.  You can do this in either the New ARM portal (http://portal.azure.com) or the older 'Classic' portal (http://manage.windowsazure.com).
+It's possible to complete this task in either the [Azure CLI](#creating-credentials-using-the-azure-cli) or in the [Azure Portal](#creating-credentials-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.
 
-The second task is to grant permissions for the Application Registration in your Subscription.
+### Creating Credentials using the Azure CLI
 
-To create the App Registration using the New ARM portal:
+Firstly, login to the Azure CLI using:
 
-- Select **Azure Active Directory** from the left pane
-- Select the **App Registrations** tile from the Overview Section
-- Click **Endpoints** at the top of the App Registrations blade.  This will display a list of URIs. Extract the GUID from the bottom URI for **OAUTH 2.0 AUTHORIZATION ENDPOINT**. This is the `tenant_id`
-- Select **Add** from the top of the blade.
-- Add a friendly name for the application e.g. **Terraform**. Choose **Web App / API** for Application Type
-- Add a valid URI as the Sign-on URL. This isn't used and can be anything e.g. http://terra.form.
-- Click **Create** at the bottom to create the App Registration
-- Choose your new App Registration to show details
-- You should now be on the blade for your App Registration.  At the top, notice the "Application ID" GUID.  You'll use this as the `client_id`
-- If the Settings blade for your Application Registration is not showing, click on **All Settings**
-- Click on **Keys**. Enter a name for your key in **Key description** and choose an expiration duration.  When you click **Save** at the top of the blade, the key value will be displayed.  Once it is displayed, you then use this as the value for `client_secret`. This will disappear once you move off the page
-- Click **Required Permissions**.  Click **Add**.  This will allow us to add permission to use the Windows Azure Service Management API to the App Registration.  On Step 1, choose Windows Azure Service Management API.  Click **Select**.  On Step 2, check the box next to "Access Azure Service Management as organization users".  Click **Select**.  Click **Done** to finish adding the permission.
+```shell
+$ az login
+```
 
-To create the App Registration using the 'Classic' portal:
+Once logged in - it's possible to list the Subscriptions associated with the account via:
 
-- Select **Active Directory** from the left pane and select the directory you wish to use
-- Select **Applications** from the options at the top of the page
-- Select **Add** from the bottom of the page. Choose **Add an application my organization is developing**
-- Add a friendly name for the application e.g. **Terraform**. Leave **Web Application And/Or Web API** selected and click the arrow for the next page
-- Add two valid URIs. These aren't used an can be anything e.g. http://terra.form. Click the arrow to complete the wizard
-- You should now be on the page for the application. Click on **Configure** at the top of the page. Scroll down to the middle of the page where you will see the value for `client_id`
-- In the **Keys** section of the page, select a suitable duration and click **Save** at the bottom of the page. This will then display the value for `client_secret`. This will disappear once you move off the page
-- Click **View Endpoints** at the bottom of the page. This will display a list of URIs. Extract the GUID from the bottom URI for **OAUTH 2.0 AUTHORIZATION ENDPOINT**. This is the `tenant_id`
+```shell
+$ az account list
+```
 
-To grant permissions to the App Registration to your subscription, you now must to use to the 'ARM' Portal:
+The output (similar to below) will display one or more Subscriptions - with the `ID` field being the `subscription_id` field referenced above.
 
-- Select **Subscriptions** from the left panel. Select the subscription that you want to use. In the Subscription details pane, click **Access Control (IAM)**
-- Click **Add**.  For Step 1 select an appropriate role for the tasks you want to complete with Terraform. You can find details on the built in roles [here](https://azure.microsoft.com/en-gb/documentation/articles/role-based-access-built-in-roles/)
-- Type in the name of the application added in the search box. You need to type this as it won't be shown in the user list. Click on the appropriate user in the list and then click **Select**
-- Click **OK** in the **Add Access** panel. The changes will now be saved
+```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"
+    }
+  }
+]
+```
 
-## To create using [Azure CLI](https://github.com/Azure/azure-cli):
+Should you have more than one Subscription, you can specify the Subscription to use via the following command:
 
-   ```shell
-   az login
-   az account set --subscription="${SUBSCRIPTION_ID}"
-   az ad sp create-for-rbac --role="Contributor" --scopes="/subscriptions/${SUBSCRIPTION_ID}"
-   ```
+```shell
+$ az account set --subscription="SUBSCRIPTION_ID"
+```
 
-This will output your `client_id`, `client_secret` (password), `sp_name`, and `tenant`. The sp_name or client_id may be used for the `servicePrincipalProfile.servicePrincipalClientId` and the `client_secret` is used for `servicePrincipalProfile.servicePrincipalClientSecret`.
+We can now create the Service Principal, which will have permissions to manage resources in the specified Subscription using the following command:
 
-Confirm your service principal by opening a new shell and run the following commands substituting in `sp_name`, `client_secret`, and `tenant`:
+```shell
+$ az ad sp create-for-rbac --role="Contributor" --scopes="/subscriptions/SUBSCRIPTION_ID"
+```
 
-   ```shell
-   az login --service-principal -u NAME -p PASSWORD --tenant TENANT
-   az vm list-sizes --location westus
-   ```
+This command will output 5 values:
 
-* **With the legacy [Azure XPlat CLI](https://github.com/Azure/azure-xplat-cli)**
+```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"
+}
+```
 
-   Instructions: ["Use Azure CLI to create a service principal to access resources"](https://azure.microsoft.com/en-us/documentation/articles/resource-group-authenticate-service-principal-cli/)
+These values map to the Terraform variables like so:
 
-* **With [PowerShell](https://azure.microsoft.com/en-us/documentation/articles/resource-group-authenticate-service-principal/)**
+ - `appId` is the `client_id` defined above.
+ - `password` is the `client_secret` defined above.
+ - `tenant` is the `tenant_id` defined above.
 
-   Instructions: ["Use Azure PowerShell to create a service principal to access resources"](https://azure.microsoft.com/en-us/documentation/articles/resource-group-authenticate-service-principal/)
+---
 
-* **With the [Legacy Portal](https://azure.microsoft.com/en-us/documentation/articles/resource-group-create-service-principal-portal/)**
+Finally - it's possible to test these values work as expected by first logging in:
 
-   Instructions: ["Use portal to create Active Directory application and service principal that can access resources"](https://azure.microsoft.com/en-us/documentation/articles/resource-group-create-service-principal-portal/)
+```shell
+$ az login --service-principal -u CLIENT_ID -p CLIENT_SECRET --tenant TENANT_ID
+```
 
-This may be out of date and was based on: [https://github.com/Azure/acs-engine](https://github.com/Azure/acs-engine/blob/master/docs/serviceprincipal.md)
+Once logged in as the Service Principal - we should be able to list the VM Sizes in the `West US` region:
+
+```shell
+$ az vm list-sizes --location westus
+```
+
+### Creating Credentials in the Azure Portal
+
+There's a couple of phases to create Credentials via [the Azure Portal](https://portal.azure.com):
+
+ 1. Creating an Application in Azure Active Directory (which acts as a Service Principal)
+ 2. Granting 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 finally click **Endpoints** at the top of the **App Registration** blade. This will display a list of URIs, the URI for **OAUTH 2.0 AUTHORIZATION ENDPOINT** contains a GUID - which 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 **Add** 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)
+
+Once that's done - select the Application you just created in [the **App Registration** blade](https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps/RegisteredApps/Overview). At the top of this page, the "Application ID" GUID is the `client_id` you'll need.
+
+Finally, we can create the `client_secret` by selecting **Keys** and then generating a new key by entering a description, selecting how long the `client_secret` should be valid for - and finally pressing **Save**. This value will only be visible whilst on the page, so be sure to copy it now (otherwise you'll need to regenerate a new key).
+
+### 2. Granting the Application access to manage resources in your Azure Subscription
+
+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**.
+
+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](https://azure.microsoft.com/en-gb/documentation/articles/role-based-access-built-in-roles/) available here.
+
+Secondly, search for and select the name of the Application created in Azure Active Directory to assign it this role - then press **Save**.
+
+## Creating Credentials through the Legacy CLI's
+
+It's also possible to create credentials via [the legacy cross-platform CLI](https://azure.microsoft.com/en-us/documentation/articles/resource-group-authenticate-service-principal-cli/) and the [legacy PowerShell Commandlets](https://azure.microsoft.com/en-us/documentation/articles/resource-group-authenticate-service-principal/) - however we would highly recommend using the Azure CLI above.
 
 ## Testing