From private repo

articles/active-directory/pp/TOC.yml

@@ -23,6 +23,10 @@
       items:
       - name: From a Linux VM
         href: msi-tutorial-linux-vm-access-arm.md
+    - name: Use a VM MSI to access Azure Cosmos DB
+      items:
+      - name: From a Linux VM
+        href: msi-tutorial-linux-vm-access-cosmosdb.md
     - name: Use a VM MSI to access Azure storage
       items:
       - name: From a Linux VM using access key

articles/active-directory/pp/msi-tutorial-linux-vm-access-cosmosdb.md

@@ -0,0 +1,265 @@
+---
+title: Use a user-assigned Managed Service Identity (MSI) on a Linux VM to access Azure Cosmos DB
+description: A tutorial that walks you through the process of using a User-Assigned Managed Service Identity (MSI) on a Linux VM, to access Azure Cosmos DB.
+services: active-directory
+documentationcenter: 
+author: daveba
+manager: mtillman
+editor: 
+
+ms.service: active-directory
+ms.devlang: na
+ms.topic: article
+ms.tgt_pltfrm: na
+ms.workload: identity
+ms.date: 02/14/2018
+ms.author: skwan
+ROBOTS: NOINDEX,NOFOLLOW
+---
+# Use a user-assigned Managed Service Identity (MSI) on a Linux VM to access Azure Cosmos DB 
+
+[!INCLUDE[preview-notice](~/includes/active-directory-msi-preview-notice-ua.md)]
+
+This tutorial shows you how to create and use a user-assigned Managed Service Identity (MSI) from a Linux Virtual Machine, then use it to access Azure Cosmos DB. You learn how to:
+
+> [!div class="checklist"]
+> * Create a User Assigned Managed Service Identity (MSI)
+> * Assign the user-assigned MSI to a Linux Virtual Machine
+> * Grant the MSI access to an Azure Cosmos DB instance
+> * Get an access token using the user-assigned MSI identity, and use it to access Azure Cosmos DB
+
+## Prerequisites
+
+[!INCLUDE [msi-core-prereqs](~/includes/active-directory-msi-core-prereqs-ua.md)]
+
+[!INCLUDE [msi-tut-prereqs](~/includes/active-directory-msi-tut-prereqs.md)]
+
+To run the CLI script examples in this tutorial, you have two options:
+
+- Use [Azure Cloud Shell](~/articles/cloud-shell/overview.md) either from the Azure portal, or via the **Try It** button, located in the top right corner of each code block.
+- [Install the latest version of CLI 2.0](https://docs.microsoft.com/cli/azure/install-azure-cli) (2.0.23 or later) if you prefer to use a local CLI console.
+
+## Sign in to Azure
+
+Sign in to the Azure portal at [https://portal.azure.com](https://portal.azure.com).
+
+## Create a Linux virtual machine in a new resource group
+
+For this tutorial, we create a new Linux VM. You can also enable MSI on an existing VM.
+
+1. Click the **+ Create a resource** found on the upper left-hand corner of the Azure portal.
+2. Select **Compute**, and then select **Ubuntu Server 16.04 LTS VM**.
+3. Enter the virtual machine information. For **Authentication type**, select **SSH public key** or **Password**. The created credentials allow you to log in to the VM.
+
+    ![MSI Linux VM](~/articles/active-directory/media/msi-tutorial-linux-vm-access-arm/msi-linux-vm.png)
+
+4. Choose a **Subscription** for the virtual machine in the dropdown.
+5. Under **Resource Group**, choose **Create New** and type the name of the resource group for this VM. When complete, click **OK**.
+6. Select the size for the VM. To see more sizes, select **View all** or change the Supported disk type filter. In the **Settings** blade, keep the defaults and click **OK**.
+
+## Create a user-assigned MSI
+
+1. If you are using the CLI console (instead of an Azure Cloud Shell session), start by signing in to Azure. Use an account that is associated with the Azure subscription under which you would like to create the new MSI:
+
+    ```azurecli
+    az login
+    ```
+
+2. Create a user-assigned MSI using [az identity create](/cli/azure/identity#az_identity_create). The `-g` parameter specifies the resource group where the MSI is created, and the `-n` parameter specifies its name. Be sure to replace the `<RESOURCE GROUP>` and `<MSI NAME>` parameter values with your own values:
+
+    ```azurecli-interactive
+    az identity create -g <RESOURCE GROUP> -n <MSI NAME>
+    ```
+
+    The response contains details for the user-assigned MSI created, similar to the following example (note the `clientId` and `id` values for your MSI, as they are used in later steps):
+
+    ```json
+    {
+    "clientId": "73444643-8088-4d70-9532-c3a0fdc190fz",
+    "clientSecretUrl": "https://control-westcentralus.identity.azure.net/subscriptions/<SUBSCRIPTON ID>/resourcegroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<MSI NAME>/credentials?tid=5678&oid=9012&aid=123444643-8088-4d70-9532-c3a0fdc190fz",
+    "id": "/subscriptions/<SUBSCRIPTON ID>/resourcegroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<MSI NAME>",
+    "location": "westcentralus",
+    "name": "<MSI NAME>",
+    "principalId": "c0833082-6cc3-4a26-a1b1-c4b5f90a981f",
+    "resourceGroup": "<RESOURCE GROUP>",
+    "tags": {},
+    "tenantId": "733a8f0e-ec41-4e69-8ad8-971fc4b533bl",
+    "type": "Microsoft.ManagedIdentity/userAssignedIdentities"
+    }
+    ```
+
+## Assign your user-assigned MSI to your Linux VM
+
+Unlike a system-assigned MSI, a user-assigned MSI can be used by clients on multiple Azure resources. For this tutorial, you assign it to a single VM. You can also assign it to more than one VM.
+
+Assign the user-assigned MSI to your Linux VM using [az vm assign-identity](/cli/azure/vm#az_vm_assign_identity). Be sure to replace the `<RESOURCE GROUP>` and `<VM NAME>` parameter values with your own values. Use the `id` property returned in the previous step for the `--identities` parameter value:
+
+```azurecli-interactive
+az vm assign-identity -g <RESOURCE GROUP> -n <VM NAME> --identities "/subscriptions/<SUBSCRIPTION ID>/resourcegroups/<RESOURCE GROUP>/providers/Microsoft.ManagedIdentity/userAssignedIdentities/<MSI NAME>"
+```
+
+## Create a Cosmos DB account 
+
+If you don't already have one, now create a Cosmos DB account. You can also skip this step and use an existing Cosmos DB account, if you prefer. 
+
+1. Click the **+/Create new service** button found on the upper left-hand corner of the Azure portal.
+2. Click **Databases**, then **Azure Cosmos DB**, and a new "New account" panel  displays.
+3. Enter an **ID** for the Cosmos DB account, which you use later.  
+4. **API** should be set to "SQL." The approach described in this tutorial can be used with the other available API types, but the steps in this tutorial are for the SQL API.
+5. Ensure the **Subscription** and **Resource Group** match the ones you specified when you created your VM in the previous step.  Select a **Location** where Cosmos DB is available.
+6. Click **Create**.
+
+## Create a collection in the Cosmos DB account
+
+Next, add a data collection in the Cosmos DB account that you can query in later steps.
+
+1. Navigate to your newly created Cosmos DB account.
+2. On the **Overview** tab click the **+/Add Collection** button, and an "Add Collection" panel slides out.
+3. Give the collection a database ID, collection ID, select a storage capacity, enter a partition key, enter a throughput value, then click **OK**.  For this tutorial, it is sufficient to use "Test" as the database ID and collection ID, select a fixed storage capacity and lowest throughput (400 RU/s).
+
+## Grant your User Assigned MSI access to the Cosmos DB account access keys
+
+Cosmos DB does not natively support Azure AD authentication.  However, you can use an MSI to retrieve a Cosmos DB access key from the Resource Manager, then use the key to access Cosmos DB.  In this step, you grant your user assigned MSI access to the keys to the Cosmos DB account.
+
+First grant the MSI identity access to the Cosmos DB account in Azure Resource Manager using the Azure CLI. Update the values for `<SUBSCRIPTION ID>`, `<RESOURCE GROUP>`, and `<COSMOS DB ACCOUNT NAME>` for your environment. Replace `<MSI PRINCIPALID>` with the `principalId` property returned by the `az identity create` command in [Create a user-assigned MSI](#create-a-user-assigned-msi).  Cosmos DB supports two levels of granularity when using access keys:  read/write access to the account, and read-only access to the account.  Assign the `DocumentDB Account Contributor` role if you want to get read/write keys for the account, or assign the `Cosmos DB Account Reader Role` role if you want to get read-only keys for the account:
+
+```azurecli-interactive
+az role assignment create --assignee <MSI PRINCIPALID> --role '<ROLE NAME>' --scope "/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.DocumentDB/databaseAccounts/<COSMODS DB ACCOUNT NAME>"
+```
+
+The response includes the details for the role assignment created:
+
+```
+{
+  "id": "/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.DocumentDB/databaseAccounts/<COSMOS DB ACCOUNT>/providers/Microsoft.Authorization/roleAssignments/5b44e628-394e-4e7b-bbc3-d6cd4f28f15b",
+  "name": "5b44e628-394e-4e7b-bbc3-d6cd4f28f15b",
+  "properties": {
+    "principalId": "c0833082-6cc3-4a26-a1b1-c4b5f90a981f",
+    "roleDefinitionId": "/subscriptions/<SUBSCRIPTION ID>/providers/Microsoft.Authorization/roleDefinitions/fbdf93bf-df7d-467e-a4d2-9458aa1360c8",
+    "scope": "/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.DocumentDB/databaseAccounts/<COSMOS DB ACCOUNT>"
+  },
+  "resourceGroup": "<RESOURCE GROUP>",
+  "type": "Microsoft.Authorization/roleAssignments"
+}
+```
+
+## Get an access token using the User Assigned MSI and use it to call Azure Resource Manager
+
+For the remainder of the tutorial, work from the VM created earlier.
+
+To complete these steps, you need an SSH client. If you are using Windows, you can use the SSH client in the [Windows Subsystem for Linux](https://msdn.microsoft.com/commandline/wsl/install_guide). If you need assistance configuring your SSH client's keys, see [How to Use SSH keys with Windows on Azure](../../virtual-machines/linux/ssh-from-windows.md), or [How to create and use an SSH public and private key pair for Linux VMs in Azure](../../virtual-machines/linux/mac-create-ssh-keys.md).
+
+1. In the Azure portal, navigate to **Virtual Machines**, go to your Linux virtual machine, then from the **Overview** page click **Connect** at the top. Copy the string to connect to your VM. 
+2. Connect to your VM using your SSH client.  
+3. Next, you are prompted to enter in your **Password** you added when creating the **Linux VM**. You should then be successfully signed in.  
+4. Use CURL to get an access token for Azure Resource Manager.  
+
+    The CURL request and response for the access token is below.  Replace <CLIENT ID> with the clientId value of your user assigned MSI:
+
+    ```bash
+    curl 'http://localhost:50342/oauth2/token?resource=https://management.azure.com/&client_id=<CLIENT ID>' -H "Metadata:true"
+    ```
+
+    > [!NOTE]
+    > In the previous request, the value of the "resource" parameter must be an exact match for what is expected by Azure AD. When using the Azure Resource Manager resource ID, you must include the trailing slash on the URI.
+    > In the following response, the access_token element as been shortened for brevity.
+
+    ```bash
+    {"access_token":"eyJ0eXAiOi...",
+     "expires_in":"3599",
+     "expires_on":"1518503375",
+     "not_before":"1518499475",
+     "resource":"https://management.azure.com/",
+     "token_type":"Bearer",
+     "client_id":"1ef89848-e14b-465f-8780-bf541d325cd5"}
+     ```
+
+## Get access keys from Azure Resource Manager to make Cosmos DB calls  
+
+Now use CURL to call Resource Manager using the access token we retrieved in the previous section, to retrieve the Cosmos DB account access key. Once we have the access key, we can query Cosmos DB. Be sure to replace the `<SUBSCRIPTION ID>`, `<RESOURCE GROUP>`, and `<COSMOS DB ACCOUNT NAME>` parameter values with your own values. Replace the `<ACCESS TOKEN>` value with the access token you retrieved earlier.  If you want to retrieve read/write keys, use key operation type `listKeys`.  If you want to retrieve read-only keys, use the key operation type `readonlykeys`:
+
+```bash 
+curl 'https://management.azure.com/subscriptions/<SUBSCRIPTION ID>/resourceGroups/<RESOURCE GROUP>/providers/Microsoft.DocumentDB/databaseAccounts/<COSMOS DB ACCOUNT NAME>/<KEY OPERATION TYPE>?api-version=2016-03-31' -X POST -d "" -H "Authorization: Bearer <ACCESS TOKEN>" 
+```
+
+> [!NOTE]
+> The text in the prior URL is case-sensitive, so ensure if you are using upper-lowercase for your Resource Groups to reflect it accordingly. Additionally, it’s important to know that this is a POST request not a GET request and ensure you pass a value to capture a length limit with -d that can be NULL.  
+
+The CURL response gives you the list of Keys.  For example, if you get the read-only keys:  
+
+```bash 
+{"primaryReadonlyMasterKey":"bWpDxS...dzQ==",
+"secondaryReadonlyMasterKey":"38v5ns...7bA=="}
+```
+
+Now that you have the access key for the Cosmos DB account you can pass it to a Cosmos DB SDK and make calls to access the account.  For a quick example, you can pass the access key to the Azure CLI.  You can get the <COSMOS DB CONNECTION URL> from the **Overview** tab on the Cosmos DB account blade in the Azure portal.  Replace the <ACCESS KEY> with the value you obtained above:
+
+```bash
+az cosmosdb collection show -c <COLLECTION ID> -d <DATABASE ID> --url-connection "<COSMOS DB CONNECTION URL>" --key <ACCESS KEY>
+```
+
+This CLI command returns details about the collection:
+
+```bash
+{
+  "collection": {
+    "_conflicts": "conflicts/",
+    "_docs": "docs/",
+    "_etag": "\"00006700-0000-0000-0000-5a8271e90000\"",
+    "_rid": "Es5SAM2FDwA=",
+    "_self": "dbs/Es5SAA==/colls/Es5SAM2FDwA=/",
+    "_sprocs": "sprocs/",
+    "_triggers": "triggers/",
+    "_ts": 1518498281,
+    "_udfs": "udfs/",
+    "id": "Test",
+    "indexingPolicy": {
+      "automatic": true,
+      "excludedPaths": [],
+      "includedPaths": [
+        {
+          "indexes": [
+            {
+              "dataType": "Number",
+              "kind": "Range",
+              "precision": -1
+            },
+            {
+              "dataType": "String",
+              "kind": "Range",
+              "precision": -1
+            },
+            {
+              "dataType": "Point",
+              "kind": "Spatial"
+            }
+          ],
+          "path": "/*"
+        }
+      ],
+      "indexingMode": "consistent"
+    }
+  },
+  "offer": {
+    "_etag": "\"00006800-0000-0000-0000-5a8271ea0000\"",
+    "_rid": "f4V+",
+    "_self": "offers/f4V+/",
+    "_ts": 1518498282,
+    "content": {
+      "offerIsRUPerMinuteThroughputEnabled": false,
+      "offerThroughput": 400
+    },
+    "id": "f4V+",
+    "offerResourceId": "Es5SAM2FDwA=",
+    "offerType": "Invalid",
+    "offerVersion": "V2",
+    "resource": "dbs/Es5SAA==/colls/Es5SAM2FDwA=/"
+  }
+}
+```
+
+## Next steps
+
+- For an overview of MSI, see [Managed Service Identity (MSI) for Azure resources](msi-overview.md).
+
+Use the following comments section to provide feedback and help us refine and shape our content.

articles/api-management/api-management-modify-content-layout.md

@@ -22,7 +22,7 @@ There are three fundamental ways to customize the developer portal in Azure API
 
 * [Edit the contents of static pages and page layout elements][modify-content-layout] (explained in this guide)
 * [Update the styles used for page elements across the developer portal][customize-styles]
-* [Modify the templates used for pages generated by the portal][portal-templates] (e.g. API docs, products, user authentication, etc.)
+* [Modify the templates used for pages generated by the portal][portal-templates] (for example, API docs, products, user authentication, etc.)
 
 ## <a name="page-structure"> </a>Structure of developer portal pages
 
@@ -32,43 +32,26 @@ The developer portal is based on a content management system. The layout of ever
 
 All widgets are editable. 
 * The core contents specific to each individual page reside in the "Contents" widget. Editing a page means editing the contents of this widget.
-* All page layout elements are contained with the remaining widgets. Changes made to these widgets will apply to all pages. They will be referred to as "layout widgets".
+* All page layout elements are contained with the remaining widgets. Changes made to these widgets are applied to all pages. They are referred to as "layout widgets."
 
-In day-to-day page editing one usually only modifies the Content widget which will have different content for each individual page.
+In day-to-day page editing one would often modify just the Content widget, which will have different content for each individual page.
 
 ## <a name="modify-layout-widget"> </a>Modifying the contents of a layout widget
 
-Content within the developer portal is modified via the publisher portal which is accessible from the Azure Portal. To reach it, click **Publisher portal** from the service toolbar of your API Management instance.
+The Developer portal is accessible from the Azure Portal. 
 
-![Publisher portal][api-management-management-console]
-
-To edit the contents of that widget, click **Widgets** from the **Developer Portal** menu on the left. For this example lets modify the contents of the Header widget. Select the **Header** widget from the list.
-
-![Widgets header][api-management-widgets-header]
-
-The contents of the header is editable from within the **Body** field. Change the text as desired and then click **Save** at the bottom of the page.
+1. Click **Developer Portal** from the toolbar of your API Management instance.
+2. To edit the contents of widgets, click the icon comprised of two paint brushes from the **Developer** portal menu on the left. 
+3. To modify the contents of the header, scroll to the **Header** section in the list on the left.
+
+    The widgets are editable from within the fields.
+4. Once you are ready to publish your changes, click **Publish** at the bottom of the page.
 
 Now you should be able to see the new header on every page within the developer portal.
 
-> To open the developer portal while in the publisher portal, click **Developer portal** in the top bar.
-> 
-> 
-
-## <a name="edit-page-contents"> </a>Edit the contents of a page
-
-To see the list of all existing content pages, click **Content** from the **Developer portal** menu in the publisher portal.
-
-![Manage content][api-management-customization-manage-content]
-
-Click the **Welcome** page to edit what is displayed on the home page of the developer portal. Make the changes you want, preview them if necessary, and then click **Publish Now** to make them visible to everyone.
-
-> The home page uses a special layout that allows it to display a banner at the top. This banner is not editable from the **Content** section. To edit this banner, click **Widgets** from the **Developer portal** menu, select **Home page** from the **Current Layer** drop-down list, and then open the **Banner** item under the **Featured section**. The contents of this widget are editable just like any other page.
-> 
-> 
-
 ## <a name="next-steps"> </a>Next steps
 * [Update the styles used for page elements across the developer portal][customize-styles]
-* [Modify the templates used for pages generated by the portal][portal-templates] (e.g. API docs, products, user authentication, etc.)
+* [Modify the templates used for pages generated by the portal][portal-templates] (for example, API docs, products, user authentication, etc.)
 
 [Structure of developer portal pages]: #page-structure
 [Modifying the contents of a layout widget]: #modify-layout-widget