Zimlet Developers Guide:Proxy Servlet Setup

Revision as of 22:37, 14 April 2010 by Cfremon (talk | contribs) (Adding Article Infobox)
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
Troubleshooting
Zdg-6-menu-icon-advanced.jpg Advanced Concepts Zdg-6-menu-icon-library.jpg API Specifications Zdg-6-menu-icon-checkbox.jpg Example Zimlets


Developer Article

Article Information

This article applies to the following ZCS versions.

ZCS 6.0 Article ZCS 6.0

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.

Proxy-servlet-nocrossdomain.png

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-crossdomain.png

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.

Proxy-servlet-crossdomainavoidviaproxy.png

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. 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}

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.

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.

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

Example:

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

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.

Example:

http://127.0.0.1:7633/service/proxy?target=www.yahoo.com

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

This zimlet is provided in the Examples section.


Verified Against: Zimbra Collaboration Suite 6.0 Date Created: 12/22/2009
Article ID: https://wiki.zimbra.com/index.php?title=Zimlet_Developers_Guide:Proxy_Servlet_Setup Date Modified: 2010-04-14



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