Office365 Integration

Learn how to integrate Office365 services with you WEM application, using OAuth 2.0

Office365 offers many services that we can integrate with. E.g.:

  1. Outlook

  2. Calendar

  3. OneDrive

We’ve created a template project where you can begin using the Office365 API. In this guide we’ll show you how to set it up.

The OAuth 2.0 authentication protocol

To be able to safely make use of external providers there’s always some authentication procedure involved. The WEM Modeler already supports the two main standard industry protocols, SAML 2.0 and OAuth 2.0.

In this guide we’ll be using the OAuth 2.0 protocol. Below is a little bit of technical protocol information that helps you understand the actual integration. The OAuth 2.0 protocol requires 5 pieces of information to work properly:

  1. An Authorization Endpoint, a link where we’ll redirect to when we start the authentication procedure.

  2. A Token Endpoint, a link which will give us an access token after we’ve successfully validated ourselves with the ‘Authorization Endpoint’.

  3. A Client ID, this will validate our application to the external service provider.

  4. A Client Secret, this will also validate our application to the external service provider.

After retrieving the access token we’ll be able to use the external service provider’s API.

(An API, application programming interface, is like a toolbox that grants us access to a bunch of useful functions. For example, Outlook’s API allows you to retrieve all your unread mails.)

Step 1 – Copy the example project

Log into your WEM account at https://my.wem.io and scroll down to ‘WEM Example projects’. There you’ll find the example project ‘Office 365 Template’, click on the Copy button. Afterwards go to https://modeler.wem.io, and open the newly copied project.

Step 2 – Setting up the project (optional)

Let’s say we end up working on our project for a long time. Then it would be nice if we could publish the project right? To be able to do this we first need to link a domain address with our project.

Go to the ‘Project settings’ and configure the hostnames for the staging and live environment. (If the hostname isn’t taken, you can generally use the name of your project and the postfix “.staging.wem.io” or “.live.wem.io” as hostnames.) And with that our hostnames are set up. Don’t forget to save the changes you’ve made!

Step 3 – Getting your redirect URLs

Click on the authentication provider Office 365.

Copy and write all the Redirect URLs down somewhere. The redirect URLs in our case are:

Step 4 – Creating your Microsoft Azure App

Go to https://portal.azure.com and log into your Office365 account. (If you do not have an Office365 account you can get a free trial at https://products.office.com/en/try)

Click on Azure Active Directory and after that click on App registrations.

Click on the button New application registration and fill in the form that pops up.

In the text field Name you can enter any name you prefer. In the field Application type you need to select the option Web app / API. In the field Sign-on URL you can enter any URL you prefer, it doesn’t matter which URL you enter.

In the next screen you can see some of the settings of your application. Write down the ‘Application ID’, that will be your client id. After that’s done click on the Settings button.

Step 5 – Entering the Redirect URLs

Afterwards click on the Reply URLs button.

Enter the Redirect URLs you’ve written down before, and press the Save button afterwards.

Step 6 – Creating a client secret

Click on the ‘Keys’ button.

Enter a new password. Write in the Description field any name you prefer, we choose Client Secret. Select in the Expires field the option Never expires.

After that’s done click on the Save button. The actual key will now appear in the Value field.

Write the key down somewhere, that is our client secret.

Step 7 – Selecting the permissions of the app

Click on the required permissions button.

Click on the Add button.

Select the Microsoft Graph API.

Select all the permissions, this way we aren’t restricted in the way we’ll use the app.

After that’s done, do not forget to click the Grant Permissions button.

Step 8 – Get the OAuth2.0 endpoints

Go to the App registrations overview.

Click on the Endpoints button.

Write down the OAuth 2.0 endpoints somewhere.

For our purposes we need to change the endpoints a little bit, since we’ll be using the 2.0 version of the API. In both URLs add after ‘oauth2/’ the text ‘v2.0/’. The URLs will now look like this:

Step 9 – Setting up the authentication provider

Click on the ‘Office 365’ Authentication provider.

Write your Client ID and Client Secret in these fields. You’ve written them down in step 4 and step 6.

Write down the appropriate URLs in the ‘Authorization Endpoint’ field and the ‘Token Endpoint’ field. You’ve written them down in step 8. Under the ‘Scope’ field you need to write down ‘mail.read’, what you write down in this field is not that important as long as we do not leave it empty. And with that your authentication provider is done!

Step 10 – Trying out the template project

The template project can now be used.

Click on the highlighted ‘Preview’ button to try out the template project! It’s recommended to look through all the flowcharts in the project to see how it all works.

If you want to know more about the Office 365 API visit https://developer.microsoft.com/en-us/graph/docs.

Last updated