Posted by on Mar 9, 2016 in #iOSDev, #Office365Dev | 0 comments

If you haven’t heard, there is an easy way to call a great amount of Microsoft APIs – using one single endpoint. This endpoint, so called the Microsoft Graph (https://graph.microsoft.io/) lets you access everything from data, to intelligence and insights powered by the Microsoft cloud.

No longer will you need to keep track of different endpoints and separate tokens in your solutions – how great is that? This post is an introductory part of getting started with the Microsoft Graph. For changes in the Microsoft Graph, head to: https://graph.microsoft.io/changelog

This blog post demonstrates how to register your application in Azure AD, which is needed when calling the Microsoft Graph. We will use the Microsoft Graph SDK for iOS (https://github.com/OfficeDev/Microsoft-Graph-SDK-iOS) and build a simple iOS application using the Objective-C language (https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/ProgrammingWithObjectiveC/Introduction/Introduction.html). In the application we will send ourselves a mail. The objective is to get familiar with the Microsoft Graph and its possibilities.

app

Are you more interested in the Swift programming language? Check out the Swift version of this blog post at: http://simonjaeger.com/get-going-swiftly-with-the-microsoft-sdk-for-ios/

Be aware, the Microsoft Graph SDK for iOS is still in preview. Read more about the conditions at: https://github.com/OfficeDev/Microsoft-Graph-SDK-iOS

The blog post is divided into multiple steps and should be followed in a chronological order. These are the included steps:

1.1 Register the application in Azure AD
1.2 Configure the application in Azure AD
2.1 Create the project
2.2 Add the dependencies
3.1 Add the MailClient class
3.2 Implement the initializer
3.3 Implement the getGraphServiceUrl method
3.4 Implement the signInWithCallback method
3.5 Implement the getUserWithCallback method
3.6 Implement the createRecipientWithAddress method
3.7 Implement the createBodyWithContent method
3.8 Implement the createMessageWithSubject method
3.9 Implement the sendMailWithMessage method
3.10 Implement the sendMeWithCallback method
3.11 Configure ADAL with your Azure AD application
4.1 Update the UI

Short of time and just want the final sample? Clone this repository (https://github.com/simonjaeger/PnP/tree/msgraph-ios-samples) and open the Xcode workspace file: /Samples/MicrosoftGraph.iOS.Objective-C.SendMail/MSGraph.MailClient.xcworkspace.

Prerequisites

Xcode 7: https://developer.apple.com/xcode/
CocoaPods: https://cocoapods.org/
Office 365 Developer Tenant: http://dev.office.com/devprogram/
Azure subscription for the Office 365 Developer Tenant (a trial is sufficient)

Step 1.1: Register the application in Azure AD

The first thing that we need to do is to register our application in Azure AD. This is how can acquire an access token for the Microsoft Graph (on behalf of the user).

Make sure that you have all of the required prerequisites before getting into this step.

1. Head to the current Azure portal and sign in with a user in your Office 365 Developer Tenant at: https://manage.windowsazure.com/
2. In the left menu, choose on Active Directory to list your Azure AD.

3. Click on your Azure AD in the Directory tab section.

4. Click on Applications in the tab menu.
5. Click on the Add button at the bottom to register a new Azure AD application.

6. Choose on Add an application my organization is developing in the dialog that shows up.
7. Name your application “MicrosoftGraph.iOS.Objective-C.SendMail” and select Native Client Application. Proceed by clicking the continue button down at the bottom.

8. Enter “https://MicrosoftGraph.iOS.Objective-C.SendMail/” as the Redirect URI. Click on the check button down below to complete the wizard.

Step 1.2: Configure the application in Azure AD

We need to configure the application in Azure AD to be able to request the Microsoft Graph as a resource. This is done by adding the Microsoft Graph as an application, along with a set of permissions.

1. Click on the Configure tab in the Azure AD application page.


2. Scroll down to the bottom to the Permissions to other applications section and click on the Add application button.
3. Show Microsoft Apps and add the Microsoft Graph.
4. Save your changes by clicking the check button at the bottom.

5. Click on Delegated permissions and pick the Send mail as a user permission.

6. Save your configuration by clicking the Save button at the bottom.

Step 2.1: Create the project

Now let’s create the iOS application project in Xcode.

1. Open the File menu. Select New and finally click on the Project… button.
2. In the iOS tab, select the Application to display the available templates for iOS.
3. Click on Single View Application and finally the Next button.

projecttype

4. Enter “MSGraph.MailClient” as the Product Name.
5. Set the Organization Name and Organization Identifier to anything of your liking.
6. Choose Objective-C as the Language of your project.
7. Finalize the options by pressing the Next button.

8. Choose a location for your project. Xcode will now create everything you need. Have a look in the Project Navigator and find your new iOS application project.

Step 2.2: Add the dependencies

We will use the popular dependency manager called CocoaPods in our project. This is a great way for us to bring the Microsoft SDK for iOS and its own dependencies into the project.

Before continuing, make sure that you have CocoaPods installed. You can read more about CocoaPods at: https://cocoapods.org/

A simple way of installing CocoaPods is to run the following command in the terminal (using the default Ruby install):

1. Ctrl + Click on your project MSGraph.MailClient and choose New File…

2. In Other, select Empty and click on the Next button.

newemptyfile

3. Name the file “Podfile” and leave the rest as it is. Click on the Create button to create the empty file.

newpodfile

4. Locate the Podfile in the Project Navigator and open it. Add the following lines to the Podfile.

5. Save the Podfile and close Xcode.
6. Open the Terminal and navigate to the folder containing the Podfile (if you run the command ls you should be able to see the Podfile).
7. Enter and run the following command in the Terminal. This will read the Podfile and install the dependencies.

8. If you follow the output, you should be able to see the Microsoft Graph SDK for iOS being installed (along with its own dependencies).

terminal

9. Now let’s reopen the project. Instead of opening the project with the MSGraph.MailClient.xcodeproj file, we should now use the MSGraph.MailClient.xcworkspace file. You can use the following command in the Terminal.

Step 3.1: Add the MailClient class

Now let’s create the class that is going to use the Microsoft Graph SDK for iOS. This class will take care of signing in the user, getting the user profile and finally send the mail with a message.

1. Ctrl + Click on the project folder MSGraph.MailClient and choose New File…

2. In Source, select Cocoa Touch Class and click on the Next button.

3. Name the file MailClient and leave the rest as it is. Click on the Create button to create the Cocoa Touch Class file.

4. In MailClient.h, add the following import statements. This will reference the Microsoft Graph SDK for iOS and ADAL.

5. In MailClient.h, add the following properties inside the interface of the class.

ADALDependencyResolver: The authentication resolver used by the Microsoft Graph SDK for iOS. This object comes from ADAL (Active Directory Authentication Library) and will be using the configuration that you created earlier in this post using Azure AD. We will copy the configuration from Azure AD into a property list file.
MSGraphServiceClient: This is the Microsoft Graph client from the Microsoft Graph SDK for iOS. This client allows us to perform operations towards the Microsoft Graph using an object model.
Ready: This variable will signal if a user has been signed in and the MailClient is ready to be used.

6. In MailClient.h, add the following method declarations inside the interface of the class (below the properties).

Your MailClient.h file should now look like this: https://github.com/simonjaeger/PnP/blob/msgraph-ios-samples/Samples/MicrosoftGraph.iOS.Objective-C.SendMail/MSGraph.MailClient/MailClient.h

7. In MailClient.m, add the following constants to the top of the implementation. These will be used in the initialization logic of the class.

Step 3.2: Implement the initializer

Inside the MailClient class (MailClient.m), add the following init method below the three variables. This method will initialize the three variables whenever an object of type MailClient is instantiated.

Step 3.3: Implement the getGraphServiceUrl method

Inside the MailClient class (MailClient.m), add the following method below init method. This method will combine the Microsoft Graph endpoint URL and the version parameter.

Step 3.4: Implement the signInWithCallback method

Inside the MailClient class (MailClient.m), add the following method below the getGraphServiceUrl method. This method requests ADAL to trigger an interactive logon session (with UI). Depending on the result of the session, the MailClient may or may not be put in a ready state.

Step 3.5: Implement the getUserWithCallback method

Inside the MailClient class (MailClient.m), add the following method below the signInWithCallback method. This method uses the Microsoft Graph client to read the signed in user profile. This is how we will extract the mail address of the signed in user.

Step 3.6: Implement the createRecipientWithAddress method

Inside the MailClient class (MailClient.m), add the following method below the getUserWithCallback method. This method creates a recipient object that we can use when engaging with the Microsoft Graph.

Step 3.7: Implement the createBodyWithContent method

Inside the MailClient class (MailClient.m), add the following method below the createRecipientWithAddress method. This method creates a body object that we can use when engaging with the Microsoft Graph. We will default to creating an HTML body.

Step 3.8: Implement the createMessageWithSubject method

Inside the MailClient class (MailClient.m), add the following method below the createBodyWithCallback method. This method creates a message object that we can use when engaging with the Microsoft Graph. It uses the createRecipientWithAddress method and createBodyWithContent method to build the completed message object.

Step 3.9: Implement the sendMailWithMessage method

Inside the MailClient class (MailClient.m), add the following method below the createMessageWithSubject method. This method takes a completed message object and sends it (on behalf of the signed in user) using the Microsoft Graph client.

Step 3.10: Implement the sendMeWithCallback method

Inside the MailClient class (MailClient.m), add the following method below the sendMailWithMessage method. This method aggregates the above logic to create the following flow:

  1. Let a user sign in.
  2. Get the user profile (mail address).
  3. Create the message.
  4. Send the message to the current user (on behalf of the current user).

In addition, we pass a logging mechanism to the method. This way we can let those status messages surface to the application interface, and follow the different steps as they execute.

Your MailClient.m file should now look like this: https://github.com/simonjaeger/PnP/blob/msgraph-ios-samples/Samples/MicrosoftGraph.iOS.Objective-C.SendMail/MSGraph.MailClient/MailClient.m

Build the project using the ⌘B shortcut, or by pressing the Build button in the Product menu.

Step 3.11: Configure ADAL with your Azure AD application

We need to get back into our Azure AD application configuration page to extract a few properties and put them into the project. The ADALDependencyResolver will try to initialize with a Property List file names adal_settings.plist – so we need to create that.

1. Ctrl + Click on the project folder MSGraph.MailClient and choose New File…

2. In Resource, select Property List and click on the Next button.

newplist

3. Name the file “adal_settings” and leave the rest as it is. Click on the Create button to create the property list file.

adal_settings

4. Head back into the current Azure portal (https://manage.windowsazure.com/), to the configuration page of your Azure AD application.
5. Locate the Client ID property and the Redirect URIs property.

6. In adal_settings.plist, add the following String items (rows) to the Root item.

ClientId: The ClientId of your Azure AD application.
ResourceId: The resource identifier of the Microsoft Graph, which is “https://graph.microsoft.com/”.
RedirectUri: One of the Redirect URIs listed in your Azure AD application, which is “https://MicrosoftGraph.iOS.Objective-C.SendMail/”.
AuthorityUrl: This is “https://login.microsoftonline.com/” combined with the name of your Azure AD tenant. In example, this would be “https://login.microsoftonline.com/contoso.onmicrosoft.com/” for the Azure AD tenant “contoso.onmicrosoft.com”.

7. Save your work using the ⌘S shortcut.

Step 4.1: Update the UI

In order to test everything, let’s hook up some UI. This is not going to be specific to the Microsoft Graph SDK for iOS. So I will only cover this briefly. You can learn more about UIKit at: https://developer.apple.com/library/ios/documentation/UIKit/Reference/UIKit_Framework/

1. In ViewController.m, add the following import statement at the top of the file. This will import the MailClient so that we can use it within the class.

2. In ViewController.m, add the following properties in the interface. The @IBOutlet properties will be references to a few UI elements that we will add to the Storyboard.

3. In ViewController.m, add the following line inside the viewDidLoad method (below the super call). This will make sure that the MailClient object is instantiated whenever the UI has been loaded.

4. In ViewController.m, add the following methods inside the class. This is the logging method and event handler for when a button is pressed. When the button is pressed we will trigger the MailClient go through the steps for sending ourselves a mail.

5. Your ViewController.m file should now look like this (apart from some styling specifics): https://github.com/simonjaeger/PnP/blob/msgraph-ios-samples/Samples/MicrosoftGraph.iOS.Objective-C.SendMail/MSGraph.MailClient/ViewController.m

6. In Main.storyboard, use the Object Library to drag three items onto the View Controller surface. A Label, a Button and an Activity Indicator View.

uiitems

7. [OPTIONAL] In Main.storyboard, layout and style everything as you please. You can learn more about Storyboards here: https://developer.apple.com/library/ios/documentation/General/Conceptual/Devpedia-CocoaApp/Storyboard.html
8. Connect the Storyboard outlets and actions to the @IBOutlet variables and the @IBAction method in the ViewController. In Main.storyboard, Ctrl + Click on the View Controller item in the View Controller Scene. This will show a list of the @IBOutlet variables and the @IBActions methods in the View Controller.

  1. Drag from “button” to the button in the Storyboard.
  2. Drag from “label” to the button in the Storyboard.
  3. Drag from “spinner” to the activity indicator view in the Storyboard.
  4. Drag from “sendMe:” to the button in the Storyboard, choose Touch Up Inside in order to trigger the sendMe method inside the View Controller when the button is tapped.

storyboard

Now – run the project using the ⌘R shortcut, or by pressing the Run button in the Product menu.

This should generate a mail in the iOS application and send it to yourself. At this point, go ahead and check your mailbox!

app

Wrap up

View the source code files included in this blog post (https://github.com/simonjaeger/PnP/tree/msgraph-ios-samples/Samples/MicrosoftGraph.iOS.Objective-C.SendMail) for a final reference of how your code should be structured (if needed). You should now have grasped an understanding of a few possibilities of interacting (and authenticating) with the Microsoft Graph.

-Simon Jaeger