Zimlet Developers Guide:Proxy Servlet Setup

Introduction

Getting Started

Dev Environment Setup

Developing Zimlets Proxy Servlet Setup Firefox and Firebug

API Specifications

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.

Background

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.

Configuration

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

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}

Where:

• {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.

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

zmprov gc {cos-name} | grep zimbraProxyAllowedDomains

Using LDAP Utility

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.

http://jxplorer.org/

Launch JXplorer and create a connection:

Property	Value
Host	localhost
Port	389
Base DN	dc=localhost
Security > Level	Select "User + Password"
Security > User DN	uid=zimbra,cn=admins,cn=zimbra
Security > Password	zimbra

Usage

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. HTTP Basic Authentication is supported (auth=basic).
user	Optional	The username to use for authentication.
password	Optional	The password to use for authentication.

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

Example:

http://your.zimbraserver.com/service/proxy?target=www.yahoo.com

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">
    <global>
        <property name="allowedDomains">*</property>
    </global>
</zimletConfig>

This zimlet is provided in the Examples section.