How to Make Oxygen XML WebApp Component 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 the Oxygen XML WebApp Component. This is usually required when the CMS needs authentication before granting access to a file.

The Oxygen XML WebApp Component provides both a server-side and client-side API that allows you to implement such a mechanism.

Implement CMS Authentication Mechanism

The following is a list of the basic building blocks of the authentication mechanism:

Develop a plugin that implements the ro.sync.exml.plugin.urlstreamhandler.URLStreamHandlerPluginExtension interface. Considering the multiple user context of the Oxygen XML WebApp Component, the getURLStreamHandler method should return an instance of the ro.sync.ecss.extensions.api.webapp.plugin.URLStreamHandlerWithContext class. This class tracks the user, based on the URL connection that will be made.
If the CMS rejects the connection attempt with a message 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, follow these steps:
1. Use the sync.api.Editor.EventTypes.CUSTOM_MESSAGE_RECEIVED event to intercept the messages sent from the server-side.
2. Display a dialog box to collect more authentication information from the user.
3. 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 Oxygen XML WebApp Component to an OAuth implementation.
4. Retry the operation that triggered the authentication procedure.