Edit online

Implementing a CMS Authentication Mechanism

Suppose you want to impose an authentication step for all users who want to edit documents in the Oxygen XML Web Author. This is usually required when the CMS needs authentication before granting access to a file. The Oxygen XML Web Author provides both a server-side and client-side API that allows you to implement such a mechanism.

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 Oxygen XML Web Author, the getURLStreamHandler method should return an instance of the ro.sync.ecss.extensions.api.webapp.plugin.URLStreamHandlerWithContext class.

By default, this class identifies the users based on the session cookie, so contextId is the value of the session cookie. This class can use the SessionStore API to store the user credentials.
Note: The user identification mechanism relies on the fact that URLs that are present in the XML document (for example, the source of an image, target of a link, or a DITA content reference) are relative URLs. If your documents contain absolute URLs, you need to implement an extra interface.
If the CMS denies 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 and save them to the SessionStore. For this part, you will need to implement a secure way to transmit the credentials. This can range from a simple ro.sync.ecss.extensions.api.webapp.plugin.WebappServletPluginExtension to an OAuth implementation.
4. Retry the operation that triggered the authentication procedure.