Talking to an OAuth2 API from the Notes Client (NO Xpages)

Introduction

Have you wondered if it is possible to talk to an OAuth2 SaaS API from the Notes Client without XPages? We did just that!

We were asked to develop a solution to create invoices and contact information from a standard HCL Domino CRM and Licence Tracking application to an OAuth2 api. The requirement was for a simple action button on a contact form that when clicked from the HCL Notes client, created a draft invoice on the client’s accounting SaaS and a new contact (if it didn’t already exist on the SaaS platform).

How we did it…

The above diagram show how this process works.

Oauth2 generally likes to show the user a login GUI where the user signs in with their credentials and then eventually receives an access token for use in later api requests.

Even though it may be possible to redirect user from the HCL Notes client to the web browser and write an agent for the callback I couldn’t find any information on how to achieve this (Please provide a resource in the comments if I’m wrong as I would really be interested to learn more on other peoples methods).

So we decided we needed to get rid of the login GUI altogether to make the process completely seamless to the user. But how? you may ask.

Below are the parameters needed to be sent in the authorization url.

https://YOUR_DOMAIN/authorize?
    response_type=code&
    client_id=YOUR_CLIENT_ID&
    redirect_uri=https://YOUR_APP/callback&
    scope=SCOPE&
    audience=API_AUDIENCE&
    state=STATE

Oauth2 provides a scope for offline_access. If this scope is sent in the scope parameter of the authorization url, when user logs in, a refresh_token will be included in the response. This refresh_token can then be used to request a new access_token. Refresh tokens expire a lot later than access tokens (in this case 60 days), while access_tokens were expiring after 30 minutes.

But doesn’t the login GUI need to show to the user so that they can log in and actually receive the response?

Postman comes to the rescue.

We only need to get one refresh_token with the GUI to generate new access_tokens. So we used Postman to “jump start” the refresh token process. Postman allowed us to login to the GUI of the OAuth2 so we could retrieve our first refresh_token.

We then took this refresh_token and saved it on a Notes document for retrieval later. The Notes document (which is hidden), looks like this:

We created an agent that sends the refresh_token to the refresh token api and retrieves a new access_token and a new refresh_token. Both of these new tokens are then saved to the Notes document for retrieval in the future. We have the agent scheduled to run once a month so that the refresh token never expires (expires every 60 days in this case but may be different depending on the SaaS accessed).

Conclusion

So, in short we successfully integrated an Oauth2 SaaS into a HCL Notes Client based application “GUILess” (if that’s a word) and without the use of XPages. It works from a simple Action button on a form and requires no additional interaction from the user.

I’m sure that there are many more use cases where this would be an extremely useful and powerful feature for many new (or existing) HCL Notes/Domino applications.

I hope you found this useful and I look forward to your comments.

Best regards,
Adrian Marikar – Domino People Ltd

Special thanks to my colleague Vitalijus who’s assistance was invaluable!