Merge pull request #56888 from KingdomOfEnds/digital-twins-oauth

Digital Twins Postman and OAuth

Author: ktoliver

articles/digital-twins/TOC.yml

@@ -52,6 +52,8 @@
     href: how-to-user-defined-functions.md
   - name: How to route events and messages via endpoints
     href: how-to-egress-endpoints.md
+  - name: How to configure Postman
+    href: how-to-configure-postman.md
   - name: How to add blobs to objects
     href: how-to-add-blobs.md
   - name: How to use Digital Twins Swagger

articles/digital-twins/how-to-configure-postman.md

@@ -0,0 +1,90 @@
+---
+title: How to configure Postman for Azure Digital Twins | Microsoft Docs
+description: How to configure Postman for Azure Digital Twins
+author: kingdomofends
+manager: alinast
+ms.service: digital-twins
+services: digital-twins
+ms.topic: conceptual
+ms.date: 11/13/2018
+ms.author: adgera
+---
+
+# How to configure Postman for Azure Digital Twins
+
+This article describes how to configure an Azure Active Directory (Azure AD) application to use the OAuth 2.0 implicit grant flow. Then, it discusses how to configure the Postman REST client to make token-bearing HTTP requests to your Management APIs.
+
+## Postman summary
+
+Get started on Azure Digital Twins by using a REST client tool such as [Postman](https://www.getpostman.com/) to prepare your local testing environment. The Postman client helps to quickly create complex HTTP requests. Download the desktop version of the Postman client by going to [www.getpostman.com/apps](https://www.getpostman.com/apps).
+
+[Postman](https://www.getpostman.com/) is a REST testing tool that locates key HTTP request functionalities into a useful desktop and plugin-based GUI. Through the Postman client, solutions developers can specify the kind of HTTP request (POST, GET, UPDATE, PATCH, and DELETE), API endpoint to call, and use of SSL. Postman also supports adding HTTP request headers, parameters, form-data, and bodies.
+
+## Configure Azure Active Directory to use the OAuth 2.0 implicit grant flow
+
+Configure your Azure AD app to use the OAuth 2.0 implicit grant flow.
+
+1. Follow the steps in [this quickstart](https://docs.microsoft.com/azure/active-directory/develop/quickstart-v1-integrate-apps-with-azure-ad) to create an Azure AD application of type Native. Or you can reuse an existing Native app registration.
+
+1. Under **Required permissions**, enter `Azure Digital Twins` and select **Delegated Permissions**. Then select **Grant Permissions**.
+
+    ![Azure AD app registrations add api](../../includes/media/digital-twins-permissions/aad-app-req-permissions.png)
+
+1. Click **Manifest** to open the application manifest for your app. Set *oauth2AllowImplicitFlow* to `true`.
+
+      ![Azure AD implicit flow][1]
+
+1. Configure a **Reply URL** to [`https://www.getpostman.com/oauth2/callback`](https://www.getpostman.com/oauth2/callback).
+
+      ![Azure AD Reply URL][2]
+
+1. Copy and keep the **Application ID** of your Azure AD app. It is used below.
+
+## Configure the Postman client
+
+Next, set up and configure Postman to obtain an Azure AD token. Afterwards, make an authenticated HTTP request to Azure Digital Twins using the acquired token:
+
+1. Go to [www.getpostman.com]([https://www.getpostman.com/) to download the app.
+1. Ensure that your **Authorization URL** is correct. It should take the format:
+
+    ```plaintext
+    https://login.microsoftonline.com/YOUR_AZURE_TENANT.onmicrosoft.com/oauth2/authorize?resource=YOUR_RESOURCE_ID
+    ```
+
+    | Name  | Replace with | Example |
+    |---------|---------|---------|
+    | YOUR_AZURE_TENANT | The name of your tenant or organization | `microsoft` |
+    | YOUR_RESOURCE_ID | The resource ID | `10b07f429-9f4b-4714-9392-cc5e8e80c8b0` |
+
+1. Select the **Authorization** tab, select **OAuth 2.0**, and then select **Get New Access Token**.
+
+    | Field  | Value |
+    |---------|---------|
+    | Grant Type | `Implicit` |
+    | Callback URL | [`https://www.getpostman.com/oauth2/callback`](https://www.getpostman.com/oauth2/callback) |
+    | Auth URL | Use the **Authorization URL** from step 2 above |
+    | Client ID | Use the **Application ID** for the Azure AD app that was created or repurposed from the previous section |
+    | Scope | leave blank |
+    | State | leave blank |
+    | Client Authentication | `Send as Basic Auth header` |
+
+1. The client should now look like:
+
+   ![Postman client example][3]
+
+1. Select **Request Token**.
+
+    >[!NOTE]
+    >If you receive the error message "OAuth 2 couldn’t be completed," try the following:
+    > * Close Postman, and reopen it and try again.
+  
+1. Scroll down, and select **Use Token**.
+
+## Next steps
+
+To learn about authenticating with the Management APIs, read [Authenticate with APIs](./security-authenticating-apis.md).
+
+<!-- Images -->
+[1]: media/how-to-configure-postman/implicit-flow.png
+[2]: media/how-to-configure-postman/reply-url.png
+[3]: media/how-to-configure-postman/postman-oauth-token.png

articles/digital-twins/media/how-to-configure-postman/implicit-flow.png

@@ -6,7 +6,7 @@ manager: alinast
 ms.service: digital-twins
 services: digital-twins
 ms.topic: conceptual
-ms.date: 10/02/2018
+ms.date: 11/13/2018
 ms.author: lyrana
 ---
 
@@ -30,39 +30,16 @@ The Windows Azure Authentication Library offers many ways to acquire Active Dire
 
 ## Call Digital Twins from a middle-tier web API
 
-When developers architect Digital Twins solutions, they typically create a middle-tier application or API. The app or API then calls the Digital Twins API downstream. Users first authenticate to the mid-tier application, and then an on-behalf-of token flow is used to call downstream. For instructions about how to orchestrate the on-behalf-of flow, see [this page](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow). You also can view code samples on [this page](https://azure.microsoft.com/resources/samples/active-directory-dotnet-webapi-onbehalfof/).
+When developers architect Digital Twins solutions, they typically create a middle-tier application or API. The app or API then calls the Digital Twins API downstream. To support this standard web solution architecture, make sure that users first:
 
+1. Authenticate with the middle-tier application
+1. An OAuth 2.0 On-Behalf-Of token is acquired during authentication
+1. The acquired token is then used to authenticate with or call APIs that are further downstream using the On-Behalf-Of flow
 
-## Test with the Postman client
-
-To get up and running with the Digital Twins APIs, you can use a client such as Postman as an API environment. Postman helps you create complex HTTP requests quickly. The following steps show how to get an Azure AD token that's needed to call Digital Twins within the Postman UI.
-
-
-1. Go to https://www.getpostman.com/ to download the app.
-1. Follow the steps in [this quickstart](https://docs.microsoft.com/azure/active-directory/develop/quickstart-v1-integrate-apps-with-azure-ad) to create an Azure AD application. Or you can reuse an existing registration. 
-1. Under **Required permissions**, enter “Azure Digital Twins” and select **Delegated Permissions**. Then select **Grant Permissions**.
-1. Open the application manifest, and set **oauth2AllowImplicitFlow** to true.
-1. Configure a reply URL to [https://www.getpostman.com/oauth2/callback](https://www.getpostman.com/oauth2/callback).
-1. Select the **Authorization** tab, select **OAuth 2.0**, and then select **Get New Access Token**.
-
-    |**Field**  |**Value** |
-    |---------|---------|
-    | Grant type | Implicit |
-    | Callback URL | [https://www.getpostman.com/oauth2/callback](https://www.getpostman.com/oauth2/callback) |
-    | Auth URL | https://login.microsoftonline.com/<Your Azure AD Tenant e.g. Contoso>.onmicrosoft.com/oauth2/authorize?resource=0b07f429-9f4b-4714-9392-cc5e8e80c8b0 |
-    | Client ID | Use the application ID for the Azure AD app that was created or repurposed from Step 2. |
-    | Scope | Leave blank. |
-    | State | Leave blank. |
-    | Client authentication | Send as a Basic Auth header. |
-
-1. Select **Request Token**.
-
-    >[!NOTE]
-    >If you receive the error message "OAuth 2 couldn’t be completed," try the following:
-    > * Close Postman, and reopen it and try again.
-   
-1. Scroll down, and select **Use Token**.
+    For instructions about how to orchestrate the on-behalf-of flow, see [OAuth 2.0 On-Behalf-Of flow](https://docs.microsoft.com/azure/active-directory/develop/v2-oauth2-on-behalf-of-flow). You also can view code samples in [Calling a downstream web API](https://azure.microsoft.com/resources/samples/active-directory-dotnet-webapi-onbehalfof/).
 
 ## Next steps
 
-To learn about Azure Digital Twins security, read [Create and manage role assignments](./security-create-manage-role-assignments.md).
+To configure and test Azure Digital Twins using the OAuth 2.0 implicit grant flow, read [Configure Postman](./how-to-configure-postman.md).
+
+To learn about Azure Digital Twins security, read [Create and manage role assignments](./security-create-manage-role-assignments.md).