Extending Zimbra with Server Extensions

Zimlets and the ability to extend the Zimbra Web Client is a pretty widely known capability. But did you know that Zimbra also has a framework that allows developers to extend Zimbra server-side functionality?

Zimbra Server Extensions provide a mechanism to add functionality to the server in lieu of modifying web.xml and other web server configuration files. By implementing a Server Extension, you can inject or in some cases, intercept, server-side functionality. Some examples include:

• Handling authentication requests against a user store different than the built-in Zimbra LDAP user store. Server Extensions provide a way to “plug-in” your custom authentication mechanism.
• Creating custom SOAP requests to augment the current Zimbra SOAP API.
• Registering custom mime handlers for the processing of message mime components (i.e. body, message and multipart nodes).
• Performing registration or “bootstrapping” of server-side components, such as the Microsoft Exchange Free/Busy resolver.

Getting Started

Writing an extension starts by implementing the com.zimbra.cs.extension.ZimbraExtension interface:

public interface ZimbraExtension {

    /**
     * Defines a name for the extension. It must be an identifier.
     * @return the extension name
     */
    public String getName();

    /**
     * Initializes the extension. Called when the extension is loaded.
     *
     * @throws ServiceException
     */
    public void init() throws ServiceException;

    /**
     * Terminates the extension. Called when the server is shut down.
     *
     */
    public void destroy();
}

To create your Extension:

1. Write a MyZimbraExtension class that implements the ZimbraExtension interface.
2. Create a JAR file (for example: myext.jar) and include the following attribute in the JAR manifest file:
   • Zimbra-Extension-Class: com.example.MyZimbraExtension
3. Place the myext.jar into the {zimbra_install-dir}/lib/ext/{my-ext-dir} directory.

Below are a few examples, though not an exhaustive list, of how the Server Extension framework can be used:

Custom HTTP Handlers

A Server Extension can process HTTP GET/POST/OPTIONS requests by extending the com.zimbra.cs.extension.ExtensionHttpHandler abstract class and registering the subclass in the Extension init() method.

public class MyHttpHandler implements ExtensionHttpHandler {

    // the path under which MyHandler is registered
    public String getPath() {
        return "/myext/myhandler";
    }

    // override doGet/doPost/ doOptions as needed
    ...
}

and in MyZimbraExtension.init(), do the following:

com.zimbra.cs.extension.ExtensionDispatcherServlet.register(this, new MyHttpHandler());

This would result in processing of requests at http://{my-zimbra-server-url}/service/extension/myext/myhandler being delegated to the MyHttpHandler class.

Custom SOAP Requests

If an Extension needs to support extra SOAP requests, it can do so by implementing the com.zimbra.soap.DocumentService interface and registering custom SOAP requests & operations handlers from it.

public class MyDocumentService implements DocumentService {

    /**
     * Registers <code>DocumentHandler<code> instance with document dispatcher.
     */
    public void registerHandlers(DocumentDispatcher dispatcher) {
        dispatcher.registerHandler(HelloWorldOp.REQUEST_QNAME, new HelloWorldOp());
    }
}

and in MyZimbraExtension.init(), do the following:

com.zimbra.soap.SoapServlet.addService("SoapServlet", new MyDocumentService());

Custom Authentication

If your Zimbra deployment needs to authenticate user passwords from, for example, a “home grown” authentication system and not from LDAP (which is the out-of-the-box Zimbra solution), the Extension can do so by extending the com.zimbra.cs.account.auth.ZimbraCustomAuth abstract class.  The subclass would have to implement an authenticate() method to which the plain-text password is passed as one of the arguments.

Learn More

A detailed implementation document is available at ZimbraServer/docs/extensions.txt. Now that we’ve introduced the topic, stay tuned for more information on specific Server Extension implementation examples.