Integrating webMethods IS and the office 365 outlook REST API

As more companies are adopting Office 365, the need to integrate with the provided apis is growing. In this guide I’ll investigate an integration between the outlook REST apis and the webMethods integration server. This will allow our integration environment to have acces to the mail, calendar and contact apis.
The article consist of three parts. First part is the necessary configuration in the azure portal. Next we’ll look into the Oauth2 authorization flow. Finally I’ll discuss a basic webMethods integration.

Azure active directory configuration

First we need to do some configuration in the azure portal. The link to this portal is https://manage.windowazure.com. There is also a new portal available at https://portal.azure.com . But at the moment of writing not all required functionality was added to the new interface. In the Azure active directory configuration page we need to add a new application. This application will be the representation of our webMethods client in azure. Make sure to select the “Add an application my organisation is developing” and the “Web application and/or web api” options in the wizard.

Go to your newly create active directory app to do further configuration. Both the sign-on url and the App id uri do not have to be urls to real resources. In this setup, they only function as a logical identifier.

Creating the certificates

For this article we will create a new self-signed certificate using the openssl command line. Generating a certificate can also be done with other tools. This blog describes the steps for the windows-tool MakeCert. Let’s get started!

“Client credential grant” authorization flow

In a conventional Oauth2 log in procedure, the application has to get an acces token for each user. To acquire this, the end user has to log-on and give the received acces token to the application. In our setup this scenario is not possible because the webMethods client needs acces without a specific user signing in. For this type of use case Oauth2 describes another flow called “Client credential grant”.

The webMethods client will request an acces token from the Oauth2 token issuing endpoint by providing it’s own client credentials. In this scenario the token is also referred to as an “app only” token. Oauth2 describes in this flow two ways to authenticate the daemon client, by providing the client_id and client_secret http parameters or by providing a signed JSON web token (JWT). However Azure does only allow the more secure second method. The reason for this is that the received acces token can represent a great amount of rights over the api.

In the first postman image below is an example of requesting the acces token from the token issuing endpoint (https://login.microsoftonline.com<your tenand id>/oauth2/token). The client_assertion parameter contains the JSON web token. In the webMethods implementation (see last screenshot) is a java code example of creating such a token using the open source jjwt-library. The second postman image displays a call to the outlook mail api to receive the last mails of a particular account.

The sample project depends on the Tundra package. This is an open source utilities packages which can be found on GitHub. When you are creating a office365 integration, you should also think about caching the received access token. The access token is only valid during a 60 minute interval and therefore you should implement a mechanism to request a new token when it expires. And off course … add some error handling code 😉