services	platforms	author
active-directory	dotnet, xamarin	jmprieur

Integrating Azure AD into a cross platform Xamarin application

This sample solution shows how to build a native application that uses Xamarin to target several different platforms with a single shared C# code base. The application signs users in with Azure Active Directory (AAD), using the Active Directory Authentication Library (ADAL) 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 other users in their organization.

Looking for previous versions of this code sample? Check out the tags on the releases GitHub page.

About The Sample

If you would like to get started immediately, skip this section and jump to How To Run The Sample.

This sample solution is a "Directory Searcher" that contains five projects, implementing a common component and apps for four different target platforms: iOS, Android, Windows Store 8.1, and WPF. The solution is built using the Xamarin Platform, which allows all four applications to be written in C# and ported to the corresponding platform. Each application contains two major portions: a platform specific project that is used primarily for UI, and a shared portable class library (PCL) that contains the application logic.

In this application, the platform specific projects are effectively only responsible from presenting the UI. Each application receives an input search term from the user, and calls a method SearchByAlias in the application's DirectorySearcherLib PCL. SearchByAlias returns a User object, which is used to present information about the search results such as the user's name, user principal name, and phone number.

The DirectorySearcherLib PCL is the application's shared C# code base, which contains both the identity related logic and the search related logic. It leverages ADAL.NET v3, which is also a PCL, to automatically sign users in with the OAuth 2.0 protocol, acquire an access token for the AAD Graph API, cache tokens, maintain user sessions, and so on. It then queries AAD's Graph API for information about a user in the authenticated user's tenant with a matching alias, and returns results to the platform specific UI code. By writing both the identity and search logic in the DirectorySearcherLib PCL, the code only needs to be written once and can be reused across each platform.

How To Run The Sample

To run this entire sample you will need:

An Internet connection
A Windows machine (necessary if you want to run the Windows Store or WPF apps)
An OS X machine (necessary if you want to run the iOS app)
Visual Studio 2017 (recommended) which comes with Xamarin for iOS, Android, and Universal platform;
An Azure subscription (a free trial is sufficient)

Every Azure subscription has an associated Azure Active Directory tenant. If you don't already have an Azure subscription, you can get a free subscription by signing up at https://azure.microsoft.com. All of the Azure AD features used by this sample are available free of charge.

Step 1: Setup your Xamarin development environment

We recommend you begin with the Xamarin Download Page, installing Xamarin on both your Mac and PC. If you don't have both machines available, you can still run the sample, but certain projects will have to be omitted. Follow the detailed installation guides for iOS and Android, and if you would like to understand more about the options available to you for development, have a look at the Building Cross Platform Applications guide. You do not need to setup a device for development at this time, nor do you need a Apple Developer Program subscription (unless, of course, you want to run the iOS app on a device).

For this sample, we recommend that you use the Visual Studio Integration to run the sample in Visual Studio, and connect to your OS X machine by pairing via the Xamarin Build Host, which comes as part of your Xamarin for OS X installation.

Step 2: Clone or download this repository

Once you have completed your IDE setup, from your shell or command line run:

git clone https://github.com/Azure-Samples/active-directory-dotnet-native-multitarget.git

or download and exact the repository .zip file.

Step 3: Create user(s) in your Azure Active Directory tenant

For this sample, you must have at least one user homed in the AAD tenant in which you will register the application. That is to say that you can not run the sample with your Microsoft Account, so create a new user with the same domain as your tenant if necessary.

Step 4: Register the sample with your Azure Active Directory tenant

This step and the following are actually optional - the sample is configured to run with any tenant out of the box. But for best understanding, we recommend completing these two steps and registering the application in your own tenant.

Sign in to the Azure management portal.
Click on Active Directory in the left hand nav.
Click the directory tenant where you wish to register the sample application.
Click the Applications tab.
In the drawer, click Add.
Click "Add an application my organization is developing".
Enter a friendly name for the application, for example "DirectorySearcherClient", select "Native Client Application", and click next.
Enter a Redirect Uri value of your choosing and of form http://MyDirectorySearcherApp.
While still in the Azure portal, click the Configure tab of your application.
Find the Client ID value and copy it aside, you will need this later when configuring your application.
In the Permissions to Other Applications configuration section, ensure that "Access your organization's directory" and "Sign in and read user profile" are selected under "Delegated permissions" for Azure Active Directory. Save the configuration.

Step 5: Configure the sample to use your Azure AD tenant

Open the solution in Visual Studio 2015.
Open the DirectorySearcher.cs file in the DirectorySearcherLib (Portable) project.
Find the clientId member variable and replace its value with the Client Id you copied from the Azure portal.
Find the returnUri member variable and replace the value with the redirect Uri you registerd in the Azure portal.

Step 6: Run the sample(s)

Clean the solution, rebuild the solution, and run it! Explore each different platform by running each project, searching for users by their alias, logging in with users in your tenant, and viewing results. You'll notice that the user needs to consent to the app on first login - this is because the app is configured to work with any tenant. If you would like to remove this consent flow, see the comments in the Directory Searcher class.

How to Recreate this Sample

Coming soon.

andrewchungxam/active-directory-dotnet-native-multitarget