Zimlet Developers Guide:Proxy Servlet Setup
|Introduction||Getting Started||Dev Environment Setup||
|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.
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.
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.
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.
You will not be required to directly call the Proxy Servlet. When your zimlet accesses external sites (either through the use of the XML API to execute action urls with data 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.
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 (|
|user||Optional||The username to use for authentication.|
|password||Optional||The password to use for authentication.|
The default URL binding for Proxy Servlet is
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
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.
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.