Merge pull request #12234 from andretms/andret-Docs-Guided-Setup

AAD Guided Setups - Android Windows, ASP.NET Web App
jhakulin · May 10, 2017 · bd9f32f · bd9f32f
2 parents 96c666d + 9890056
commit bd9f32f
Show file tree

Hide file tree

Showing 42 changed files with 1,843 additions and 20 deletions.
diff --git a/articles/active-directory/develop/GuidedSetups/active-directory-android.md b/articles/active-directory/develop/GuidedSetups/active-directory-android.md
@@ -0,0 +1,5 @@
+[!INCLUDE [1. Introduction](active-directory-mobileanddesktopapp-android-introduction.md)]
+[!INCLUDE [2. Setup](active-directory-mobileanddesktopapp-android-setup.md)]
+[!INCLUDE [3. Use](active-directory-mobileanddesktopapp-android-use.md)]
+[!INCLUDE [4. Configure](active-directory-mobileanddesktopapp-android-configure.md)]
+[!INCLUDE  [5. Test and Validate](active-directory-mobileanddesktopapp-android-test.md)]
diff --git a/articles/active-directory/develop/GuidedSetups/active-directory-aspnetwebapp.md b/articles/active-directory/develop/GuidedSetups/active-directory-aspnetwebapp.md
@@ -0,0 +1,6 @@
+[!INCLUDE [1. Introduction](active-directory-serversidewebapp-aspnetwebappowin-introduction.md)]
+[!INCLUDE [2. Setup](active-directory-serversidewebapp-aspnetwebappowin-setup.md)]
+[!INCLUDE [3. Use](active-directory-serversidewebapp-aspnetwebappowin-use.md)]
+[!INCLUDE [4. Configure](active-directory-serversidewebapp-aspnetwebappowin-configure.md)]
+[!INCLUDE  [5. Test and Validate](active-directory-serversidewebapp-aspnetwebappowin-test.md)]
+
diff --git a/...elop/GuidedSetups/active-directory-mobileanddesktopapp-android-configure-arp.md b/...elop/GuidedSetups/active-directory-mobileanddesktopapp-android-configure-arp.md
@@ -0,0 +1,52 @@
+---
+title: Azure AD v2 Android Getting Started - Configure | Microsoft Docs
+description: How an Android app can get an access token and call Microsoft Graph API or APIs that require access tokens from Azure Active Directory v2 endpoint
+services: active-directory
+documentationcenter: dev-center-name
+author: andretms
+manager: mbaldwin
+editor: ''
+
+ms.assetid: 820acdb7-d316-4c3b-8de9-79df48ba3b06
+ms.service: active-directory
+ms.devlang: na
+ms.topic: article
+ms.tgt_pltfrm: na
+ms.workload: identity
+ms.date: 05/09/2017
+ms.author: andret
+
+---
+
+## Add the application’s registration information to your app
+
+In this step, you need to add the Client ID to your project.
+
+1.	Open `MainActivity` (under `app` > `java` > *`{host}.{namespace}`*)
+2.	Replace the line starting with `final static String CLIENT_ID` with:
+```java
+final static String CLIENT_ID = "[Enter the application Id here]";
+```
+3. Open: `app` > `manifests` > `AndroidManifest.xml`
+4. Add the following activity to `manifest\application` node. This register a `BrowserTabActivity` to allow the OS to resume your application after completing the authentication:
+
+```xml
+<!--Intent filter to capture System Browser calling back to our app after Sign In-->
+<activity
+    android:name="com.microsoft.identity.client.BrowserTabActivity">
+    <intent-filter>
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+
+        <!--Add in your scheme/host from registered redirect URI-->
+        <!--By default, the scheme should be similar to 'msal[appId]' -->
+        <data android:scheme="msal[Enter the application Id here]"
+            android:host="auth" />
+    </intent-filter>
+</activity>
+```
+
+### What is Next
+
+[Test and Validate](active-directory-mobileanddesktopapp-android-test.md)
diff --git a/.../develop/GuidedSetups/active-directory-mobileanddesktopapp-android-configure.md b/.../develop/GuidedSetups/active-directory-mobileanddesktopapp-android-configure.md
@@ -0,0 +1,69 @@
+---
+title: Azure AD v2 Android Getting Started - Configure | Microsoft Docs
+description: How an Android app can get an access token and call Microsoft Graph API or APIs that require access tokens from Azure Active Directory v2 endpoint
+services: active-directory
+documentationcenter: dev-center-name
+author: andretms
+manager: mbaldwin
+editor: ''
+
+ms.assetid: 820acdb7-d316-4c3b-8de9-79df48ba3b06
+ms.service: active-directory
+ms.devlang: na
+ms.topic: article
+ms.tgt_pltfrm: na
+ms.workload: identity
+ms.date: 05/09/2017
+ms.author: andret
+
+---
+
+## Create an application (Express)
+Now you need to register your application in the *Microsoft Application Registration Portal*:
+1. Register your application via the [Microsoft Application Registration Portal](https://apps.dev.microsoft.com/portal/register-app?appType=mobileAndDesktopApp&appTech=android&step=configure)
+2.	Enter a name for your application and your email
+3.	Make sure the option for Guided Setup is checked
+4.	Follow the instructions to obtain the application ID and paste it into your code
+
+### Add your application registration information to your solution (Advanced)
+Now you need to register your application in the *Microsoft Application Registration Portal*:
+1. Go to the [Microsoft Application Registration Portal](https://apps.dev.microsoft.com/portal/register-app) to register an application
+2. Enter a name for your application and your email 
+3. Make sure the option for Guided Setup is unchecked
+4. Click `Add Platforms`, then select `Native Application` and hit Save
+5.	Open `MainActivity` (under `app` > `java` > *`{host}.{namespace}`*)
+6.	Replace the *[Enter the application Id here]* in the line starting with `final static String CLIENT_ID` with the application ID you just registered:
+
+```java
+final static String CLIENT_ID = "[Enter the application Id here]";
+```
+<!-- Workaround for Docs conversion bug -->
+<ol start="7">
+<li>
+Open `AndroidManifest.xml` (under `app` > `manifests`)
+Add the following activity to `manifest\application` node. This registers a `BrowserTabActivity` to allow the OS to resume your application after completing the authentication:
+</li>
+</ol>
+
+```xml
+<!--Intent filter to capture System Browser calling back to our app after Sign In-->
+<activity
+    android:name="com.microsoft.identity.client.BrowserTabActivity">
+    <intent-filter>
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+
+        <!--Add in your scheme/host from registered redirect URI-->
+        <!--By default, the scheme should be similar to 'msal[appId]' -->
+        <data android:scheme="msal[Enter the application Id here]"
+            android:host="auth" />
+    </intent-filter>
+</activity>
+```
+<!-- Workaround for Docs conversion bug -->
+<ol start="8">
+<li>
+In the `BrowserTabActivity`, replace `[Enter the application Id here]` with the application ID.
+</li>
+</ol>
diff --git a/...tory/develop/GuidedSetups/active-directory-mobileanddesktopapp-android-intro.md b/...tory/develop/GuidedSetups/active-directory-mobileanddesktopapp-android-intro.md
@@ -0,0 +1,3 @@
+---
+redirect_url: active-directory-android 
+---
diff --git a/...velop/GuidedSetups/active-directory-mobileanddesktopapp-android-introduction.md b/...velop/GuidedSetups/active-directory-mobileanddesktopapp-android-introduction.md
@@ -0,0 +1,54 @@
+---
+title: Azure AD v2 Android Getting Started - Intro | Microsoft Docs
+description: How an Android app can get an access token and call Microsoft Graph API or APIs that require access tokens from Azure Active Directory v2 endpoint
+services: active-directory
+documentationcenter: dev-center-name
+author: andretms
+manager: mbaldwin
+editor: ''
+
+ms.assetid: 820acdb7-d316-4c3b-8de9-79df48ba3b06
+ms.service: active-directory
+ms.devlang: na
+ms.topic: article
+ms.tgt_pltfrm: na
+ms.workload: identity
+ms.date: 05/09/2017
+ms.author: andret
+
+---
+
+# Call the Microsoft Graph API from an Android app
+
+This guide demonstrates how a native Android application can get an access token and call Microsoft Graph API or other APIs that require access tokens from Azure Active Directory v2 endpoint.
+
+At the end of this guide, your application will be able to call a protected API using personal accounts (including outlook.com, live.com, and others) as well as work and school accounts from any company or organization that has Azure Active Directory.  
+
+### How this sample works
+![How this sample works](media/active-directory-mobileanddesktopapp-android-intro/android-intro.png)
+
+The sample created by this guide is based on a scenario where an Android application is used to query a Web API that accepts tokens from Azure Active Directory v2 endpoint – in this case, Microsoft Graph API. For this scenario, a token is added to HTTP requests via the Authorization header. Token acquisition and renewal is handled by the Microsoft Authentication Library (MSAL).
+
+### Pre-requisites
+* This guided setup is focused on Android Studio, but any other Android application development environment is also acceptable. 
+* Android SDK 21 or newer is required (SDK 25 is recommended).
+* Google Chrome or a web browser using Custom Tabs is required for this release of Microsoft Authentication Library (MSAL) for Android.
+
+> Note: Google Chrome is not included on Visual Studio Emulator for Android. We recommend you to test this code on an Emulator with API 25 or an image with API 21 or newer that has with Google Chrome installed.
+
+
+### How to handle token acquisition to access a protected Web API
+
+After the user authenticates, the sample application receives a token that can be used to query Microsoft Graph API or a Web API secured by Microsoft Azure Active Directory v2.
+
+APIs such as Microsoft Graph require an access token to allow accessing specific resources – for example, to read a user’s profile, access user’s calendar or send an email. Your application can request an access token using MSAL to access these resources by specifying API scopes. This access token is then added to the HTTP Authorization header for every call made against the protected resource. 
+
+MSAL manages caching and refreshing access tokens for you, so your application doesn't need to.
+
+### Libraries
+
+This guide uses the following libraries:
+
+|Library|Description|
+|---|---|
+|[com.microsoft.identity.client](http://javadoc.io/doc/com.microsoft.identity.client/msal)|Microsoft Authentication Library (MSAL)|
diff --git a/...tory/develop/GuidedSetups/active-directory-mobileanddesktopapp-android-setup.md b/...tory/develop/GuidedSetups/active-directory-mobileanddesktopapp-android-setup.md
@@ -0,0 +1,154 @@
+---
+title: Azure AD v2 Android Getting Started - Setup | Microsoft Docs
+description: How an Android ap can get an access token and call Microsoft Graph API or APIs that require access tokens from Azure Active Directory v2 endpoint
+services: active-directory
+documentationcenter: dev-center-name
+author: andretms
+manager: mbaldwin
+editor: ''
+
+ms.assetid: 820acdb7-d316-4c3b-8de9-79df48ba3b06
+ms.service: active-directory
+ms.devlang: na
+ms.topic: article
+ms.tgt_pltfrm: na
+ms.workload: identity
+ms.date: 05/09/2017
+ms.author: andret
+
+---
+
+## Set up your project
+
+> Prefer to download this sample's Android Studio project instead? [Download a project](https://github.com/Azure-Samples/active-directory-android-native-v2/archive/master.zip) and skip to the [Configuration](#create-an-application-express) step to configure the code sample before executing    .
+
+
+### Create a new project 
+1.	Open Android Studio, go to: `File` > `New` > `New Project`
+2.	Name your application and click `Next`
+3.	Make sure to select *API 21 or newer (Android 5.0)* and click `Next`
+4.	Leave `Empty Activity`, click `Next`, then `Finish`
+
+
+### Add the Microsoft Authentication Library (MSAL) to your project
+1.	In Android Studio, go to: `Gradle Scripts` > `build.gradle (Module: app)`
+2.	Copy and paste the following code under `Dependencies`:
+
+```ruby  
+compile ('com.microsoft.identity.client:msal:0.1.+') {
+    exclude group: 'com.android.support', module: 'appcompat-v7'
+}
+compile 'com.android.volley:volley:1.0.0'
+```
+
+<!--start-collapse-->
+### About this package
+
+The package above installs the Microsoft Authentication Library (MSAL). MSAL handles acquiring, caching and refreshing user tokens used to access APIs protected by Azure Active Directory v2 endpoint.
+<!--end-collapse-->
+
+## Create your application’s UI
+
+1.	Open: `activity_main.xml` under `res` > `layout`
+2.	Change the activity layout from `android.support.constraint.ConstraintLayout` or other to `LinearLayout`
+3.	Add `android:orientation="vertical"` property to `LinearLayout` node
+4.	Copy and paste the following code into the `LinearLayout` node, replacing the current content:
+
+```xml
+<TextView
+    android:text="Welcome, "
+    android:textColor="#3f3f3f"
+    android:textSize="50px"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:layout_marginLeft="10dp"
+    android:layout_marginTop="15dp"
+    android:id="@+id/welcome"
+    android:visibility="invisible"/>
+
+<Button
+    android:id="@+id/callGraph"
+    android:text="Call Microsoft Graph"
+    android:textColor="#FFFFFF"
+    android:background="#00a1f1"
+    android:layout_width="match_parent"
+    android:layout_height="wrap_content"
+    android:layout_marginTop="200dp"
+    android:textAllCaps="false" />
+
+<TextView
+    android:text="Getting Graph Data..."
+    android:textColor="#3f3f3f"
+    android:layout_width="match_parent"
+    android:layout_height="wrap_content"
+    android:layout_marginLeft="5dp"
+    android:id="@+id/graphData"
+    android:visibility="invisible"/>
+
+<LinearLayout
+    android:layout_width="match_parent"
+    android:layout_height="0dip"
+    android:layout_weight="1"
+    android:gravity="center|bottom"
+    android:orientation="vertical" >
+
+    <Button
+        android:text="Sign Out"
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:layout_marginBottom="15dp"
+        android:textColor="#FFFFFF"
+        android:background="#00a1f1"
+        android:textAllCaps="false"
+        android:id="@+id/clearCache"
+        android:visibility="invisible" />
+</LinearLayout>    <TextView
+    android:text="Welcome, "
+    android:textColor="#3f3f3f"
+    android:textSize="50px"
+    android:layout_width="wrap_content"
+    android:layout_height="wrap_content"
+    android:layout_marginLeft="10dp"
+    android:layout_marginTop="15dp"
+    android:id="@+id/welcome"
+    android:visibility="invisible"/>
+
+<Button
+    android:id="@+id/callGraph"
+    android:text="Call Microsoft Graph"
+    android:textColor="#FFFFFF"
+    android:background="#00a1f1"
+    android:layout_width="match_parent"
+    android:layout_height="wrap_content"
+    android:layout_marginTop="200dp"
+    android:textAllCaps="false" />
+
+<TextView
+    android:text="Getting Graph Data..."
+    android:textColor="#3f3f3f"
+    android:layout_width="match_parent"
+    android:layout_height="wrap_content"
+    android:layout_marginLeft="5dp"
+    android:id="@+id/graphData"
+    android:visibility="invisible"/>
+
+<LinearLayout
+    android:layout_width="match_parent"
+    android:layout_height="0dip"
+    android:layout_weight="1"
+    android:gravity="center|bottom"
+    android:orientation="vertical" >
+
+    <Button
+        android:text="Sign Out"
+        android:layout_width="match_parent"
+        android:layout_height="wrap_content"
+        android:layout_marginBottom="15dp"
+        android:textColor="#FFFFFF"
+        android:background="#00a1f1"
+        android:textAllCaps="false"
+        android:id="@+id/clearCache"
+        android:visibility="invisible" />
+</LinearLayout>
+```
+
diff --git a/...ctory/develop/GuidedSetups/active-directory-mobileanddesktopapp-android-test.md b/...ctory/develop/GuidedSetups/active-directory-mobileanddesktopapp-android-test.md
@@ -0,0 +1,43 @@
+---
+title: Azure AD v2 Android Getting Started - Test | Microsoft Docs
+description: How an Android app can get an access token and call Microsoft Graph API or APIs that require access tokens from Azure Active Directory v2 endpoint
+services: active-directory
+documentationcenter: dev-center-name
+author: andretms
+manager: mbaldwin
+editor: ''
+
+ms.assetid: 820acdb7-d316-4c3b-8de9-79df48ba3b06
+ms.service: active-directory
+ms.devlang: na
+ms.topic: article
+ms.tgt_pltfrm: na
+ms.workload: identity
+ms.date: 05/09/2017
+ms.author: andret
+
+---
+## Test your code
+
+1. Deploy your code to your device/emulator.
+2. When you're ready to test, use a Microsoft Azure Active Directory (organizational account) or a Microsoft Account (live.com, outlook.com) account to sign in. 
+
+![Sample screen shot](media/active-directory-mobileanddesktopapp-android-test/mainwindow.png)
+<br/><br/>
+![Sign-in](media/active-directory-mobileanddesktopapp-android-test/usernameandpassword.png)
+
+### Consent
+The first time a user signs in to your application, they will be presented with a consent screen similar to the below, where they need to explicitly accept: 
+
+![Consent](media/active-directory-mobileanddesktopapp-android-test/androidconsent.png)
+
+
+### Expected results
+You should see the results of a call to Microsoft Graph API ‘me’ endpoint used to to obtain the user profile - https://graph.microsoft.com/v1.0/me. For a list of common Microsoft Graph endpoints, please see this [article](https://developer.microsoft.com/graph/docs#common-microsoft-graph-queries).
+
+<!--start-collapse-->
+### More information about scopes and delegated permissions
+Graph API requires the `user.read` scope to read user profile. This scope is added by default to every application registered through our registration portal. Some other Graph APIs as well as custom APIs for your backend server require additional scopes. For example, for Graph, `Calendars.Read` is required to list user’s calendars. In order to access the user’s calendar in the context of an application, you need to add this delegated application registration’s information and then add `Calendars.Read` to the `AcquireTokenAsync` call. The user may be prompted for additional consent as you increase the number of scopes.
+
+If a backend API does not require a scope (not recommended), you can use the `ClientId` as the scope in the `AcquireTokenAsync` call.
+<!--end-collapse-->