This sample demonstrates the usage of the AAD Graph plugin for Apache Cordova to build an Apache Cordova app for managing an Azure Active Directory via AAD Graph API.

This sample solution demonstrates the usage of the AAD Graph plugin for Apache Cordova to build an Apache Cordova app, targeting several different platforms with a single code base. The application signs users in with Azure Active Directory (AAD), using the Active Directory Authentication Library (ADAL) plugin for Cordova to obtain a JWT access token through the OAuth 2.0 protocol. The access token is sent to AAD's Graph API to authenticate the user and obtain information about users, groups and applications. For more information about how the protocols work in this scenario and other scenarios, see Authentication Scenarios for Azure AD.

AAD Graph plugin for Apache Cordova is an open source library. For distribution options, source code, and contributions, check out the AAD Graph Cordova repo at https://github.com/Azure-Samples/active-directory-cordova-graphapi.

If you would like to get started immediately, skip this section and jump to How To Run The Sample. This sample demonstrates a simple application, which allows a user to retrieve and manage directory users, groups and applications. Available actions include CRUD and some specific operations like Reset user password and Restore deleted application. Supported platforms: iOS, Android, Windows Store and Windows Phone.

NOTE: You should login as a Global Administrator in order to all sample functionality to work; you may get "Insufficient privileges" error otherwise.

To run this sample you will need:

• An Internet connection
• A Windows 8.1 64-bit machine with minimum 4 GB of RAM if you want to run Windows Table/PC apps. Processor that supports Client Hyper-V and Second Level Address Translation (SLAT) is also required if you want to run Windows Phone 8.1 app on emulator.
• A Mac OSX 10.8.5/Mountain Lion or higher machine with 4 GB of RAM if you want to run iOS app.
• To run Android app you can choose among
  • Mac OSX 10.8.5/Mountain Lion or higher machine with 4 GB of RAM
  • Linux machine (GNOME or KDE desktop) with 4 GB of RAM (tested on Ubuntu® 14.04)
  • Windows 8 or higher machine with 4 GB of RAM
• Git
• NodeJS
• Cordova CLI (can be easily installed via NPM package manager: npm install -g cordova)

Platform specific development tools depending on platform(s) you want to run sample application on:

• To build and run Windows Tablet/PC or Phone app version

  Visual Studio 2013 for Windows with Update 2 or later (Express or another version).

• To build and run for iOS

  Xcode 5.x or greater. Download it at http://developer.apple.com/downloads or the Mac App Store

  ios-sim – allows you to launch iOS apps into the iOS Simulator from the command line (can be easily installed via the terminal: npm install -g ios-sim)

• To build and run application for Android

  Install Java Development Kit (JDK) 7 or later. Make sure JAVA_HOME (Environment Variable) is correctly set according to JDK installation path (for example C:\Program Files\Java\jdk1.7.0_75).

  Install Android SDK and add <android-sdk-location>\tools location (for example, C:\tools\Android\android-sdk\tools) to your PATH Environment Variable.

  Open Android SDK Manager (for example, via terminal: android) and install

  • Android 5.1.1 (API 22) platform SDK
  • Android SDK Build-tools version 19.1.0 or higher
  • Android Support Repository (Extras)

  Android sdk doesn't provide any default emulator instance. Create a new one by running android avd from terminal and then selecting Create... if you want to run Android app on emulator. Recommended Api Level is 19 or higher, see AVD Manager for more information about Android emulator and creation options.

To use this sample you will need a Microsoft Azure Active Directory Tenant. If you're not sure what a tenant is or how you would get one, read What is a Azure AD tenant? or Sign up for Azure as an organization. These docs should get you started on your way to using Azure AD.

1. Sign in to the Azure management portal.
2. Click on Active Directory in the left hand nav.
3. Click the directory tenant where you wish to register the sample application.
4. Click the Applications tab.
5. In the drawer, click Add.
6. Click "Add an application my organization is developing".
7. Enter a friendly name for the application, for example "AADGraphClient", select "Native Client Application", and click next.
8. Enter a Redirect Uri value of your choosing and of form http://AADGraphClient. NOTE: there are certain platform specific features that can only be leveraged by using Redirect Uri values in specific formats. We will add guidance about this soon.
9. While still in the Azure portal, click the Configure tab of your application.
10. Find the Client ID value and copy it aside, you will need this later when configuring your application.
11. In the Permissions to Other Applications configuration section, ensure that "Access your organization's directory" and "Enable sign-on and read user's profiles" are selected under "Delegated permissions" for Azure Active Directory. Save the configuration.

From your shell or command line: git clone https://github.com/Azure-Samples/active-directory-cordova-graphapi.git

git clone https://github.com/AzureAD/azure-activedirectory-cordova-plugin-graph.git

cordova create AADGraphSample --copy-from="NativeClient-GraphAPI-Cordova/AADGraphClient"

cd AADGraphSample

cordova platform add android

cordova platform add ios

cordova platform add windows

Note: In case if you have a Visual Studio 2015 Preview installed you may have issues with project packaging for Windows related to MSBuild v.14 issue. You can workaround this issue by using patched cordova-windows with MSBuild reverted to v.12:

• Instead of cordova platform add windows use
• cd ..
• git clone -b msbuild14-issue https://github.com/MSOpenTech/cordova-windows
• cd AADGraphSample
• cordova platform add ..\cordova-windows

• cordova plugin add ../azure-activedirectory-cordova-plugin-graph
• cordova plugin add cordova-plugin-device
• cordova plugin add cordova-plugin-console
• cordova plugin add com.ionic.keyboard

1. Open the app.js file inside created AADGraphSample/www/js/ folder.
2. Find the tenantName variable and replace its value with the Tenant (Azure Active Directory) name from the Azure portal.
3. Find the authority variable and replace its value' part after https://login.windows.net/ with the Tenant (Azure Active Directory) name from the Azure portal.
4. Find the appId variable and replace its value with the Client Id assigned to your app from the Azure portal.
5. Find the redirectUrl variable and replace the value with the redirect Uri you registerd in the Azure portal.

    .value('tenantName', 'testlaboratory.onmicrosoft.com')
    .value('authority', 'https://login.windows.net/testlaboratory.onmicrosoft.com/')
    .value('resourceUrl', 'https://graph.windows.net/')
    .value('appId', '3cfa20df-bca4-4131-ab92-626fb800ebb5')
    .value('redirectUrl', 'http://test.com');

1. To build and run Windows Tablet/PC application version

cordova run windows

Note: During first run you may be asked to sign in for a developer license. See Developer license for more details.

To use ADFS/SSO on Windows Tablet/PC add the following preference into config.xml:

<preference name="adal-use-corporate-network" value="true" />

adal-use-corporate-network is false by default.

It will add all needed application capabilities and toggle authContext to support ADFS/SSO. You can change its value to false and back later, or remove it from config.xml - call cordova prepare after it to apply the changes.

Note: You should not normally use adal-use-corporate-network as it adds capabilities, which prevents an app from being published in the Windows Store.

2. To build and run application on Windows Phone 8.1

To run on connected device: cordova run windows --device -- --phone

To run on default emulator: cordova emulate windows -- --phone

Use cordova run windows --list -- --phone to see all available targets and cordova run windows --target=<target_name> -- --phone to run application on specific device or emulator (for example, cordova run windows --target="Emulator 8.1 720P 4.7 inch" -- --phone).

3. To build and run on Android device

To run on connected device: cordova run android --device

To run on default emulator: cordova emulate android

Note: Make sure you've created emulator instance using AVD Manager as it is showed in Prerequisites section.

Use cordova run android --list to see all available targets and cordova run android --target=<target_name> to run application on specific device or emulator (for example, cordova run android --target="Nexus4_emulator").

4. To build and run on iOS device

To run on connected device: cordova run ios --device

To run on default emulator: cordova emulate ios

Note: Make sure you have ios-sim package installed to run on emulator. See Prerequisites section for more details.

Use `cordova run ios --list` to see all available targets and `cordova run ios --target=<target_name>` to run application on specific device or emulator (for example,  `cordova run android --target="iPhone-6"`).

Use cordova run --help to see additional build and run options.