Zimlet Developers Guide:Proxy Servlet Setup

Zimlet Developers Guide: Proxy Servlet Setup

   KB 3210        Last updated on 07/16/2015  

(0 votes)
 - This article is a Community contribution and may include unsupported customizations.
 - This is archive documentation, which means it is not supported or valid for recent versions of Zimbra Collaboration.
Zdg-6-menu-icon-zimbra.jpg Introduction Zdg-6-menu-icon-green-flag.png Getting Started Zdg-6-menu-icon-terminal.png Dev Environment Setup Zdg-6-menu-icon-gear.png
Developing Zimlets
Proxy Servlet Setup
Firefox and Firebug
Zdg-6-menu-icon-advanced.jpg Advanced Concepts Zdg-6-menu-icon-library.jpg API Specifications Zdg-6-menu-icon-checkbox.jpg Example Zimlets

Using Ajax within a web application can be tricky given restrictions imposed by web browsers on network connections across domains (i.e. "cross-domains"). The Zimbra Web Client relies heavily on the use of Ajax to create a very rich, dynamic application experience within a web browser. And writing zimlets that will leverage the Zimbra Ajax objects to access external servers will fall under this same restriction.

This section will provide information on the Zimbra Proxy Servlet and how it is used by zimlets to avoid the cross-domain restriction.


An Ajax client running in a web browser is not permitted to directly make requests to servers other than the originating server. All modern web browsers impose a security restriction on network connections from the browser client, which includes calls via Ajax.

This restriction prevents a script or application in the browser from making a connection to any web server other than the one the web page originally came from. If your web application and the services that application uses come directly from the same server, then you do not run into this "cross-domain" restriction.


If your zimlets will request data from an external server via Ajax -- other than from the originating Zimbra server -- then the browser prevents the connection to that external from being made.


Proxy Servlet

The most common approach to work around this browser "cross-domain" limitation is to use a proxy on your Zimbra server. Instead of making your Ajax calls directly to the external service, you make your calls to the Zimbra Proxy Servlet. The proxy passes the request onto the external server and in return passes the response back to your zimlet. Because the Ajax connection is made to your server, and the data comes back from your server to the browser, the "cross-domain" restriction is avoided.


Allowed Domains

For security reasons, the Proxy Servlet be limited to only allow certain domains. An open proxy that passes any and all connections to any external server is open to abuse. The allowedDomains Zimbra COS allows you to configure what domains the Proxy Servlet will proxy. Using allowedDomains, you can prevent the Proxy Servet from making connections to servers and domains other than those you specify.

The Proxy Servlet checks the target URL against the list of allowed domains that are listed in Zimbra COS. When the proxy request target does not appear in the allowed domain list, the Proxy Servlet will return HTTP error 403 forbidden.


The allowed domains list is stored as a COS called "zimbraProxyAllowedDomains". You can configure this COS using the zmprov Command Line tool. The default allowed domains are:

zimbraProxyAllowedDomains: *.ymg.com
zimbraProxyAllowedDomains: *.yahoo.com
zimbraProxyAllowedDomains: *.maxmind.com
zimbraProxyAllowedDomains: *.csgnetworks.com
zimbraProxyAllowedDomains: *.yahooapis.com

To see the list of allowed domains, from a command line, run the following:

zmprov gc {cos-name} | grep zimbraProxyAllowedDomains

Note: zmprov is only available when using Zimbra Collaboration Suite (ZCS), not Zimbra Desktop (ZD).

To add a domain to the allowed domains list, from a command line, run the following:

zmprov mc {cos-name} +zimbraProxyAllowedDomains {missing-domain-name}


  • {cos-name} is the Class of Service
  • {missing-domain-name} is the omain name (such as *.google.com or *.myexternaldomain.com)

Note: Be sure to incude the "+" symbol in-front of the "zimbraProxyAllowedDomains" COS name. The "+" symbol indicates to append the new domain domain to the existing domain list; otherwise, you will overwrite all domains. Alternatively, use "-" symbol in-front of the "zimbraProxyAllowedDomains" to remove a particular instance of an attribute.

When using ZCS, the COS attributes are stored in LDAP. You can browse the ZCS LDAP by using an LDAP utility browser, such as JXplorer.

  1. JXplorer is available at http://jxplorer.org/
  2. Launch JXplorer and create a connection:
    Property Value
    Host localhost
    Port 389
    Base DN dc=localhost
    Protocol LDAP v3
    Security > Level Select "User + Password"
    Security > User DN uid=zimbra,cn=admins,cn=zimbra
    Security > Password zimbra
  3. Browse to "zimbra > cos > default" and you will see a list of allowed domains COS attributes.


When your zimlet accesses external sites (either through the use of the XML API to execute action urls or via the Ajax object to submit requests), the Zimlet framework will leverage the Proxy Servlet. The following information is useful when doing development to help with debugging and troubleshooting. You will not be required to directly call the Proxy Servlet.

This servlet takes accepts the following parameters:

Parameter Required / Optional Description
target Required This is the external server or service target URL.
auth Optional This is the authentication method to use when the proxy servlet connects the external server. HTTP Basic Authentication is supported (auth=basic).
user Optional The username to use for authentication to the external server.
password Optional The password to use for authentication to the external server.

The default URL binding for Proxy Servlet is http://your.zimbraserver.com/service/proxy.



When testing the proxy via Zimbra Desktop, be sure to use the proper server and port. Information on accessing Zimbra Desktop via a browser can be found at Accessing Zimbra Desktop via Browser.


See the HTTP GET and POST with Proxy Servlet example for how to call the Proxy Servlet from a zimlet.

Open All Domains Zimlet

When your zimlet accesses an external site (for example, *.yahoo.com) from Ajax, that zimlet need to tell (i.e. register in LDAP) the server that yahoo.com is an allowed domain to access. This setting is defined in the Zimlet Configuration File (config_template.xml) and is set in the allowedDomains parameter.

If you are using the Development Directory for your zimlet, this allowedDomains setting on the Configuration File is not picked-up by the server. You still need to include this file in your Zimlet Package but for zimlet development in the Development Directory, this configuration setting is not read.

An approach is to open all domains when doing development. This can be done by deploying an "Open All Domains" zimlet. This zimlet is an empty zimlet that just opens all domains so you can do your development and access external sites from your zimlet JavaScript without issue. Then when deploying your zimlet to production, be sure to include the Zimlet Configuration File that sets the correct allowedDomains. And do not deploy the "openAllDomains" zimlet in production.

Note: you should open allowed domains when doing development ONLY. Opening all domains in productions is a risk for abuse because the proxy will pass any and all connections to any external server. Therefore, do not deploy this zimlet in production and be sure to use the Zimlet Configuration File setting allowedDomains in your Zimlet Package.

The "openAllDomains" zimlet config_template.xml file is:

<zimletConfig name="com_zimbra_openalldomains" version="1.0">
        <property name="allowedDomains">*</property>

This zimlet is provided in the Examples section.

Verified Against: Zimbra Collaboration Server 7.0 Date Created: 12/22/2009
Article ID: https://wiki.zimbra.com/index.php?title=Zimlet_Developers_Guide:Proxy_Servlet_Setup Date Modified: 07/16/2015

Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search