How To Make WebApp Use the CMS Authentication Mechanism

This topic covers the case when you want to impose an authentication step to all users who want to edit documents in Oxygen XML WebApp. This is usually required when the CMS needs authentication before granting access to a file.

Oxygen XML WebApp provides both server-side and client-side API that allows you to implement such a mechanism. Following is a list of basic building blocks of the authentication mechanism:

Develop a plugin that implements the ro.sync.exml.plugin.urlstreamhandler.URLStreamHandlerPluginExtension interface. Considering the multi-user context of the WebApp, the getURLStreamHandler method should return an instance of the ro.sync.ecss.extensions.api.webapp.plugin.URLStreamHandlerWithContext class. This class tracks the user on behalf of which the URL connection will be made.
If the CMS rejects the connection attempt complaining that the user is not authenticated, you should throw a ro.sync.ecss.extensions.api.webapp.plugin.UserActionRequiredException exception. This exception is automatically relayed to the client-side as a sync.api.WebappMessage JavaScript object.
On the client side
- use the sync.api.Editor.EventTypes.CUSTOM_MESSAGE_RECEIVED event to intercept the messages sent from the server-side.
- display a dialog in order to collect more authentication information from the user.
- send the credentials to the server, more specifically to the ro.sync.ecss.extensions.api.webapp.plugin.URLStreamHandlerWithContext instance defined at step 1. For this part, you will need to implement a secure way to transmit the credentials. This can range from a simple servlet that runs in the WebApp to an OAuth implementation.
- retry the operation that triggered the authentication procedure