26 Jul Integrating webMethods IS and the office 365 outlook REST API
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!
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<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.
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)