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 will 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://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. Make a note of the Client ID, we will need this id in the authentication process. Now we have to consent permission to the office 365 outlook api. This can be done in the “Permissions to other applications” section. Add the office 365 Exchange online application and configure the required application permissions.





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!
1. Create self-signed certificate and the associated private key:
openssl-create-key-cert:

2. Package the public certificate and the private key into one p12 container:
openssl-p12-container:

3. Azure requires a base64 encoded fingerprint of the certificate:
openssl-fingerprint:

4. We will also need the base64 value of the public key. This can be found between the begin and end certificate tags:

Uploading the public key using the azure web interface is not yet possible thus we’ll need to download the manifest file. This manifest file contains all the information about our active directory application.  Simply add the public key value and thumbprint to it and upload the file again. You can download and upload the manifest json file as depicted in the image below.

Open the downloaded file and search for the “keyCredentials” json key and add following fields:
* customKeyIdentifier, the base64 encoded thumbprint of the certificate
* keyId, a new universally unique identifier (uuid)
* type, this should be “AsymmetricX509Cert”
* usage, this should be “Verify”
* value, this is the base64 encoded value of the public key

“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/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.

My simple webMethods implementation

Azure has been configured and we understand the Oauth2 authentication process. Finally it is time to go back to our familiar environment, the webMethods IS! First configure a new keystore with the p12 container file we created earlier (step 2 in the creating the certificates section of this post). Store this office365KeyStore.p12 file somewhere on the server. In the webMethods Admin UI go to Security > KeyStore > Create Keystore Alias and provide the necessary properties. You will also need to enter the password again which you used to create this file.

I’ve made a simple webMethods implementation to showcase an api call to the office365 outlook api. It consist of tree services.
* flows.oauth.getSignedJWT, creates and signs a JWT token using the open source jjwt-library.
* flows.oauth.getAccessToken, calls the office 365 token issuing endpoint with the signed JWT.
* pub.getMessages, calls the messages endpoint which gets the last mails from the specified user.

To run this tutorial package you’ll need to configure the java properties file located at “packages/tutorialOffice365/config/package.properties”. You will need to provide following parameters:
* client_id, the client id found in the azure active directory application configuration.
* tokenEndpoint, the token issuing endpoint
* certificateThumbprint, the base64 encoded fingerprint of the public key.
* keyStoreAlias, the alias you created in the webMethods Admin UI ( In this example: OFFICE365_KEYSTORE).
* keyAlias, the alias of the private key (webMethods Admin UI > KeyStore >OFFICE365_KEYSTORE)

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.

Get webMethods IS package. (This is not production ready and only intended as a very simple example).