guide to using arm and its authentication

docs/arm.rst

@@ -0,0 +1,183 @@
+Quick Start: Azure Resource Manager Mode
+===============================================================================
+
+Azure Resource Template (JSON based Infrastructure as Code) runs with Azure
+Resource Manager which Azure Python SDK 2.0.0+ supports with new packages and
+functions, and SimpleAzure uses new version of Azure Python SDK to deploy
+software stacks under Azure Resource Templates.
+
+Previous development is now called 'legacy' or 'classic' mode of Azure Python
+SDK with limited features (although it still works to start or terminate Azure
+Virtual Machines).
+
+This document explains a few changes of using ARM mode and describes how to
+setup account credentials differently compared to the classic mode. It is also
+worth to mention that guidelines and instructions from Azure official document
+or other online articles are insufficient to follow, this is understandable
+because ARM supports with Azure Python SDK is fairly new (as of September 2016)
+and some Azure services are in 'preview' mode.
+
+Installation
+-------------------------------------------------------------------------------
+
+From Pypi::
+
+        pip install --pre azure
+
+If you already have the azure package but need to upgrade then add ``-U``
+option::
+
+        pip install --pre azure -U
+
+If you are looking for the latest development, probably downloading code from
+github.com would be best::
+
+        git clone git://github.com/Azure/azure-sdk-for-python.git
+        cd azure-sdk-for-python
+        python setup.py install
+
+
+Additional Packages
+-------------------------------------------------------------------------------
+
+You may encounter some errors like this, if you don't install additiona packages::
+
+   Traceback (most recent call last):
+   File "<stdin>", line 1, in <module>
+   File "/usr/local/lib/python2.7/site-packages/azure/common/credentials.py", line 25, in <module>
+   raise ImportError("You need to install 'msrest' to use this feature")
+   ImportError: You need to install 'msrest' to use this feature
+
+
+From Pypi::
+
+        pip install msrest
+        pip install msrestazure
+
+From github.com repository::
+
+        pip install -r requirements.txt
+
+Authentication with Service Principal Credentials (ServicePrincipalCredentials)
+-------------------------------------------------------------------------------
+
+Similar to AWS IAM service, Azure allows users to have resource access through
+Active Directory and Service Principal credentials which only require
+(encrypted) key strings such as clientID, secretKey or tenantID instead of
+certificate files generated by openssl e.g. .pem. Let's walk through SDK
+functions to see how it works.
+
+``ServicePrincipalCredentials()`` from ``azure.common.credentials`` requires
+three arguments: ``client_id``, ``secret``, and ``tenant`` to authenticate.
+
+``client_id`` is an unique application id, ``secret`` is a encrypted key string
+registered to the application and ``tenant`` is an unique user id.
+
+Getting these values is explained from here: https://azure.microsoft.com/en-us/documentation/articles/resource-group-create-service-principal-portal/
+but app registrations are not described entirely because Admin consent needs to
+be done additionally. Otherwise, registered apps are not visible in the
+subscriptions page to add access with Roles.
+
+Reconsent Step
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Follow the steps below:
+
+- Go to classic portal
+- Select 'Active Directory' and find 'applications' tab at the top of the page
+- Search apps by selecting 'Applications my company owns' in the search box
+- Select your application and find 'Users and Groups' tab at the top of the
+  page 
+- ``Reconsent`` if the page asks like ``Admin consent is required prior to
+  assigning users and groups. You can consent via the application by clicking
+  here:``
+
+With Azure CLI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is easier to create a new app and a service principal with access to your
+subscriptions via Azure CLI. The official documentation is here:
+https://azure.microsoft.com/en-us/documentation/articles/resource-group-authenticate-service-principal-cli/
+
+The two commands complete this step like::
+
+  $ azure ad sp create -n <app name> -p <password> --home-page <http or https url> --identifier-uris <http or https url>
+  $ azure role assignment create --objectId <uuid returned from previous command> -o <Role e.g. Owner or Reader> -c /subscriptions/<subscription ID>/
+
+ServicePrincipalCredentials()
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Try to authenticate with the ``client_id``, ``secret`` and ``tenant`` in Python
+like ::
+
+  from azure.common.credentials import ServicePrincipalCredentials as spc
+  cred = spc(client_id = 'abcdefghi-1234-4555-8173-jklmnopqrstu',secret='abcdEFGHIJ//klmnopqrSTU/',tenant='1234567-abcd-7890-ABCD-1234567890')
+
+If your credentials are invalid, you may see errors like this::
+
+        Traceback (most recent call last):
+          File "<stdin>", line 1, in <module>
+          File "/usr/local/lib/python2.7/site-packages/msrestazure/azure_active_directory.py", line 403, in __init__
+            self.set_token()
+          File "/usr/local/lib/python2.7/site-packages/msrestazure/azure_active_directory.py", line 434, in set_token
+            raise_with_traceback(AuthenticationError, "", err)
+          File "/usr/local/lib/python2.7/site-packages/msrest/exceptions.py", line 50, in raise_with_traceback
+            raise error
+        msrest.exceptions.AuthenticationError: , InvalidClientIdError: (invalid_request) AADSTS90002: No service namespace named '<wrong id>' was found in the data store.
+        Trace ID: <UUID>
+        Correlation ID: <UUID>
+        Timestamp: 2016-10-04 15:41:24Z
+
+ or ::
+
+        Traceback (most recent call last):
+          File "<stdin>", line 1, in <module>
+          File "/usr/local/lib/python2.7/site-packages/msrestazure/azure_active_directory.py", line 403, in __init__
+            self.set_token()
+          File "/usr/local/lib/python2.7/site-packages/msrestazure/azure_active_directory.py", line 434, in set_token           
+            raise_with_traceback(AuthenticationError, "", err)
+          File "/usr/local/lib/python2.7/site-packages/msrest/exceptions.py", line 50, in raise_with_traceback
+            raise error
+          msrest.exceptions.AuthenticationError: , InvalidClientError: (invalid_client) AADSTS70002: Error validating credentials. AADSTS50012: Invalid client secret is provided.
+          Trace ID: <UUID>
+          Correlation ID: <UUID>
+          Timestamp: 2016-10-04 15:41:33Z
+
+This may occur because your secret is not registered properly or client_id or tenant is not found.
+
+Create a new Resource Group
+-------------------------------------------------------------------------------
+
+The first step prior to any deployment would be creating a new resource group
+and it can be done via ``ResourceManagmentClient()`` from
+``azure.mgmt.resource``
+
+Let's try to create a sample group named 'quickstart-rg-1' by the following code::
+
+  from azure.mgmt.resource import ResourceManagementClient as rmc
+  client = rmc(cred, 'subscription_id')
+  client.resource_groups.create_or_update(
+            'quickstart-rg-1',
+            {
+                        'location':'eastus'
+            }
+        )
+
+Replace the 'subscription_id' with a real value.
+
+If you do not have proper permissions, error message looks like::
+
+        Traceback (most recent call last):
+          File "<stdin>", line 1, in <module>
+          File "/usr/local/lib/python2.7/site-packages/azure/mgmt/resource/resources/operations/resource_groups_operations.py", line 223, in create_or_update
+            raise exp
+        msrestazure.azure_exceptions.CloudError: The client '<uuid>' with object id '<uuid>' does not have authorization to perform action 'Microsoft.Resources/subscriptions/resourcegroups/write' over scope '/subscriptions/<subscription_id>/resourcegroups/quickstart-rg-1'.
+
+If your subscription principal is not consent::
+
+     Traceback (most recent call last):
+       File "<stdin>", line 1, in <module>
+       File "/usr/local/lib/python2.7/site-packages/azure/mgmt/resource/resources/operations/resource_groups_operations.py", line 223, in create_or_update
+         raise exp
+       msrestazure.azure_exceptions.CloudError: The received access token is not valid: at least one of the claims 'puid' or 'altsecid' or 'oid' should be present. If you are accessing as application please make sure service principal is properly created in the tenant.
+