in Office 365, Office 365 API

Working with Office 365 APIs – The RAW Version

Many folks have asked me how Office 365 APIs work, how does it interact with Azure AD, authenticate users and authorize applications.

Well, to understand what is really going on, we need to get our hands dirty.

NOTE: This blog post does not use Office 365 API Tools for Visual Studio, ADAL authentication libraries or Office 365 client libraries.

This blog post assumes you have knowledge on constructing raw REST API calls.

Special Thanks to Rob Howard (Principal PM Lead in Office Developer Platform) as this blog post  is based on his session.

The Basics

Office 365 APIs are deployed to Azure Active Directory (AD). They are just like any other Web API applications deployed to your tenant that is available for directory applications to request permissions to access that applications.

The first step is to register and configure an Azure AD application in your tenant and then set the application permissions you want.

In this blog post, we will use a great tool called Fiddler to interact and get response from the services in the RAW fashion!

I promise, we will not open Visual Studio.

Below are the high level tasks we will be doing:

Refer to this blog post to get familiar with single-tenant and multi-tenant applications.

Register an Azure AD Application

Your Office 365 subscription comes with free access to Azure AD portal that provides access to the associated directory. Browse to the Azure AD portal:

  • Browse to your directory page
  • Click on Applications (in the top bar)
  • Click on ‘Add’ (in the bottom bar) to add your application
  • In the wizard:
    • Select  ‘Add an application my organization is developing’
    • Give it a unique name
    • Choose ‘Web Application And/Or Web API’register-app-1
    • Enter Sign-On URL and Application ID URI
    • For now, make sure they are uniqueregister-app-2

Your application is now registered and you will be redirected to the application’s page.

Configure the application

Click on Configure in the top menu bar to view and configure app settings

The key values we are interested in are the following:

  • Client Id
  • A key
    • AKA as Client Secret.
    • You will need to generate one in the Configure page.
    • To do so: In the keys section:Select a duration
      • Save the settings to view and copy the key
  • Reply URL
    • Make sure this is a valid web site.
    • This is where Azure AD will return the authorization code to.
    • It doesn’t matter what happens when Azure returns as we are using fiddler now.

Copy the values in a notepad or your favorite text editor. We will need them when we use fiddler.

Configure Office 365 Application Permissions

  • In the bottom, select Add application
  • In the Add application dialog, select:
    • Office 365 Exchange Online
    • Office 365 SharePoint Onlineazuread-add-applications
  • Select the following permissions for Office 365 Exchange Online:
    • Read users’ contacts
    • Have full access to users’ contacts
  • Select the following permissions for Office 365 SharePoint Online:
    • Read users’ files

Save the application settings.

OAuth Authentication Flow

Now that we have covered the basics and registered an Azure AD application, its time to understand the OAuth authentication flow required to authorize and access these APIs.

You will need to use the Authorization Grant Flow to interact with the APIs which is detailed here in this MSDN documentation.

In simple terms:

Your application requests an authorization code with which your application can then request the access token for the desired resource in Azure AD.

There are two parties involved:

  • OAuth Authorization Endpoint
    • For single-tenant apps (which is default configuration for an app):
      • https://login.windows.net/{tenant-id}/oauth2/authorize
    • For multi-tenant apps:
      • https://login.windows.net/common/oauth2/authorize
  • OAuth Token Endpoint
    • For single-tenant apps (which is default configuration for an app):
      • https://login.windows.net/{tenant-id}/oauth2/token
    • For multi-tenant apps:
      • https://login.windows.net/common/oauth2/token

When your app navigates to the authorization endpoint (for your application/tenant), it is when the user has to sign in and consent the application (only muti-tenant apps requires users to consent) to use the resources it is requesting.

For Office 365 APIs: consenting an app will allow the application to access the specified resources on behalf of the signed in user.

Once you have the access token, you can now access the resource’s endpoint and query data.

Azure AD Common Consent Framework

What is this common consent framework?

In Azure AD, your application requests access to one or more specific resources. So if your application is requesting access to say 3 resources, users will need to consent 3 times, one for each resource.

To simplify this, Azure AD has implemented this Common Consent Framework wherein the consent page will display all the resources your application is requesting so the user can consent once.

As mentioned before, the consent grant experience will depend on whether your application is a single-tenant or multi-tenant.

  • In single-tenant apps: There is no consent grant for single-tenant as you are deploying the app for your organization.
  • In multi-tenant apps: External directory users (meaning, not from your organization) will require to consent and grant the app the permissions it requires.

Get the Authorization Code

Now that we have covered the essentials, lets get our hands dirty!

  • The first step before you query your Office 365 data, you need an access token for that resource.
  • To get an access token for the resource, you need an authorization code to get the required access token.
  • To get authorization code, user needs to sign in and consent (authorize) the app.

Here is how you will construct the authorization endpoint Url for your application:

https://login.windows.net/{paste your tenant id or use common for multitenant app}/oauth2/authorize
?client_id={paste your client id here}
&resource=Microsoft.SharePoint
&redirect_uri={paste your reply url here}
&response_type=code

For example, here is my full authorization endpoint Url:

https://login.windows.net/ce1db01df-3f5d-43f4-b16c-8946f37c9709/oauth2/authorize?client_id=b71113a181-039e-462b-a8f6-f69ad7b9a286&resource=Microsoft.SharePoint&redirect_uri=http://www.chakkaradeep.com/&response_type=code

Its time now to open fiddler.

  • Open fiddler and start capturing the traffic
  • If you are not familiar with fiddler, I would highly encourage you to watch this getting-started video.

Paste the constructed authorization endpoint Url in a browser:

  • It should redirect you to sign in.
  • Sign in to your tenant where you registered your app (remember, this is a single tenant app)
  • After successful sign in, you should get redirected to the address you set in Reply Url
  • You will see the consent screen:
    • If this was a multi-tenant app and signing in from a different tenant:
  • There is no consent screen for single-tenant apps
    • Remember single-tenant apps target enterprise scenarios where you don’t want every user in the organization to consent for an app deployed for the organization.
  • Switch to fiddler:
    • You should be able to locate a HTTP 200 result with your Reply Url as the Host:fiddler-auth-code
    • In the Inspector window, click on WebForms tab to get a clear view of the authorization code returned:fiddler-auth-code-webforms-view
    • Copy the authorization code

Get an Access Token for Office 365 Resource

Now that we have the authorization code, we can request an access token for the resource.

This will be a POST request and we will use the fiddler’s Composer feature to construct and execute the request.

Here is how you will construct the token endpoint query:

Host:
https://login.windows.net/{paste tenant id or use common for multitenant app}/oauth2/token
Request Body:
grant_type=authorization_code
&redirect_uri={paste your reply url}
&client_id={paste your client id}
&client_secret={paste your encoded client secret}
&code={paste authorization code from previous step}
&resource={enter your resource}

In fiddler, switch to Composer tab:

  • Select POST for the method
  • Enter the following for host:
    • https://login.windows.net/{paste tenant id or use common for multitenant app}/oauth2/token
  • Enter the following for header:
    • Content-Type: application/x-www-form-urlencoded
  • In the request body, paste the constructed token endpoint’s request body
    • Make sure you have encoded your client secret
    • Enter the following for the resource:
      • https://outlook.office365.com (this is the Outlook resource which is required to access users’ mail, calendar, contacts)composer-get-access-token
  • Hit Execute to execute the request

This is where the Office 365 Discovery Service becomes useful with which you can discover your app’s capabilities and its endpoints and resource Ids.

If the operation was successful, you should see a HTTP 200 result with login.windows.net as the host:

Hit the response tab and click on the JSON tab to view the result where you will see the granted access token and other properties.

Copy the access token!

get-access-token

Query Office 365 Data

Now that we have an access token for Office 365 Exchange Contacts, lets construct a simple API query to get contacts.

You can refer to this Contacts API Reference to learn how to construct the API queries against Office 365 Exchange REST API.

In the Composer tab:

  • Select GET as the method
  • Enter the following as the host:
    • https://outlook.office365.com/api/v1.0/me/contacts
  • Enter the following for headers:
Accept:application/json
Authorization: Bearer {paste your access token}
  • Hit Execute to execute the request

If you did everything right, you should see a HTTP 200 result with your contacts in the result:

get-contacts

Post Office 365 Data

Lets now create a new contact.

This will be a POST request.

In the compose window:

  • Select POST as the method
  • Enter the following as the host:
    • https://outlook.office365.com/api/v1.0/me/contacts
  • Enter the following for headers:
Accept:application/json
Content-Type:application/json
Authorization: Bearer {paste access token}
  • Enter the following JSON as the Request Body for your new contact entity:
{
 "GivenName": "Oliver",
 "Surname": "Queen",
 "EmailAddresses": [
 {
 "Address": "olicity@arrow.com",
 "Name": "Oliver Queen"
 }
 ],
 "BusinessPhones": [
 "+1 732 555 0102"
 ]
}
  • Hit Execute to execute the request

If everything was successful, you should see a HTTP 201 Created result.

create-contact

Browse to your Office 365 Exchange Contacts portal and you should see your new contact!

contact-created

Feel free to leave a comment below if you have any questions!

If you have a product/feature request, make sure you post your idea here!

Happy Coding!

Write a Comment

Comment

Time limit is exhausted. Please reload the CAPTCHA.

  1. Hi,
    Thanks for this detailed example. I’m trying to follow along , but when i compose the Post to https://login.windows.net/{paste tenant id or use common for multitenant app}/oauth2/token i am getting a 401.
    You mentioned I should ‘ Make sure you have encoded your client secret’. What did you mean by that?

    Thanks,
    Russell

  2. Hi. Followed your information exactly. All is well except when trying to do the GET to /contacts api endpoint.

    I get 401 Unauthorized every time, No way around it. Have tried everything. Read your article several times, to no avail.

    I have double checked that the API endpoints are usable and deliver data because I have another project from github (node app) that can successfully access contacts and mail, so there is not a problem with me setup in Azure AD with the application and its configuration of those API endpoints.

    Was there something specific to the way you setup Fiddler perhaps with the composer options, or did you do something special when copying the access_code, converting it to another type, and then putting that in your get request to your contacts endpoint?

    Really cant figure this out. Any help would be appreciated.

  3. Hi, Very nice article.
    This REST end point gives only items in contacts, but how to get details of any users under the directory?