Zimlet Developers Guide:Proxy Servlet Setup: Difference between revisions

(New page: {| cellspacing="0" cellpadding="5" style="border: 1px solid rgb(153, 153, 170); margin: 0pt 0.5em 0.5em 0pt; float: none; background-color: rgb(249, 249, 255);" |[[Image:zdg-6-menu-icon-zi...)
 
No edit summary
 
(33 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{BC|Community Sandbox}}
__FORCETOC__
<div class="col-md-12 ibox-content">
=Zimlet Developers Guide: Proxy Servlet Setup=
{{KB|{{Unsupported}}|{{ZCS 7.0}}|{{ZCS 6.0}}|}}
{{Archive}}
{| cellspacing="0" cellpadding="5" style="border: 1px solid rgb(153, 153, 170); margin: 0pt 0.5em 0.5em 0pt; float: none; background-color: rgb(249, 249, 255);"
{| cellspacing="0" cellpadding="5" style="border: 1px solid rgb(153, 153, 170); margin: 0pt 0.5em 0.5em 0pt; float: none; background-color: rgb(249, 249, 255);"
|[[Image:zdg-6-menu-icon-zimbra.jpg|20px]]
|[[Image:zdg-6-menu-icon-zimbra.jpg|20px]]
Line 15: Line 21:
     |-
     |-
     |[[ZCS 6.0:Zimlet Developers Guide:Firefox and Firebug|Firefox and Firebug]]
     |[[ZCS 6.0:Zimlet Developers Guide:Firefox and Firebug|Firefox and Firebug]]
    |-
    |[[ZCS 6.0:Zimlet Developers Guide:Troubleshooting|Troubleshooting]]
     |}
     |}


|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-advanced.jpg|20px]]
|[[ZCS 6.0:Zimlet Developers Guide:Advanced Concepts|Advanced Concepts]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-library.jpg|20px]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-library.jpg|20px]]
|[[ZCS 6.0:Zimlet Developers Guide:Zimlet API Specifications|API Specifications]]
|[[ZCS 6.0:Zimlet Developers Guide:Zimlet API Specifications|API Specifications]]
Line 22: Line 32:
|[[ZCS 6.0:Zimlet Developers Guide:Example Zimlets|Example Zimlets]]
|[[ZCS 6.0:Zimlet Developers Guide:Example Zimlets|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.
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.
Line 50: Line 59:
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 <code>allowedDomains</code> Zimbra COS allows you to configure what domains the Proxy Servlet will proxy. Using <code>allowedDomains</code>, you can prevent the Proxy Servet from making connections to servers and domains other than those you specify.
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 <code>allowedDomains</code> Zimbra COS allows you to configure what domains the Proxy Servlet will proxy. Using <code>allowedDomains</code>, 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 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 <code>zmprov</code> Command Line tool. The default allowed domains are:
 
<pre>
zimbraProxyAllowedDomains: *.ymg.com
zimbraProxyAllowedDomains: *.yahoo.com
zimbraProxyAllowedDomains: *.maxmind.com
zimbraProxyAllowedDomains: *.csgnetworks.com
zimbraProxyAllowedDomains: *.yahooapis.com
</pre>
 
To see the list of allowed domains, from a command line, run the following:
<pre>
zmprov gc {cos-name} | grep zimbraProxyAllowedDomains
</pre>
 
Note: <code>zmprov</code> 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:
<pre>
zmprov mc {cos-name} +zimbraProxyAllowedDomains {missing-domain-name}
</pre>
 
Where:
<ul>
<li>{cos-name} is the Class of Service</li>
<li>{missing-domain-name} is the omain name (such as *.google.com or *.myexternaldomain.com)</li>
</ul>
 
''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.
 
<ol>
<li>JXplorer is available at http://jxplorer.org/</li>
<li>Launch JXplorer and create a connection:
 
{| cellpadding="5" cellspacing="0" border="1" width="70%"
|style="background-color:#ffffcc;" width="25%" |'''Property'''
|style="background-color:#ffffcc;"|'''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
|}
</li>
<li>Browse to "zimbra > cos > default" and you will see a list of allowed domains COS attributes.</li>
</ol>


== Usage ==
== Usage ==


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.
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:  
This servlet takes accepts the following parameters:  
Line 69: Line 145:
|auth
|auth
|Optional
|Optional
|This is the authentication method. HTTP Basic Authentication is supported (<code>auth=basic</code>).
|This is the authentication method to use when the proxy servlet connects the external server. HTTP Basic Authentication is supported (<code>auth=basic</code>).
|-
|-
|user
|user
|Optional
|Optional
|The username to use for authentication.
|The username to use for authentication to the external server.
|-
|-
|password
|password
|Optional
|Optional
|The password to use for authentication.
|The password to use for authentication to the external server.
|}
|}


The default URL binding for Proxy Servlet is <code>http://your.zimbraserver.com/service/proxy</code>.
The default URL binding for Proxy Servlet is <code>http://your.zimbraserver.com/service/proxy</code>.
Line 86: Line 163:
http://your.zimbraserver.com/service/proxy?target=www.yahoo.com
http://your.zimbraserver.com/service/proxy?target=www.yahoo.com
</pre>
</pre>
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 [[ZCS_6.0:Zimlet_Developers_Guide:Dev_Environment_Setup#Accessing_Zimbra_Desktop_via_Browser|Accessing Zimbra Desktop via Browser]].
Example:
<pre>
http://127.0.0.1:7633/service/proxy?target=www.yahoo.com
</pre>
See the [[ZCS_6.0:Zimlet_Developers_Guide:Examples:HTTP_GET_and_POST|HTTP GET and POST with Proxy Servlet]] example for how to call the Proxy Servlet from a zimlet.


== Open All Domains Zimlet ==
== Open All Domains Zimlet ==
Line 108: Line 194:


This zimlet is provided in the [[ZCS 6.0:Zimlet Developers Guide:Example_Zimlets#Dev Utility Zimlets|Examples]] section.
This zimlet is provided in the [[ZCS 6.0:Zimlet Developers Guide:Example_Zimlets#Dev Utility Zimlets|Examples]] section.
{{Article Footer|Zimbra Collaboration Server 7.0|12/22/2009}}
[[Category:Developers]]
[[Category:Zimlets]]
[[Category:ZCS 7.0]]
[[Category:ZCS 6.0]]
[[Category:Proxy]]

Latest revision as of 12:18, 16 July 2015

Zimlet Developers Guide: Proxy Servlet Setup

   KB 3210        Last updated on 2015-07-16  




0.00
(0 votes)
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

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 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: 2015-07-16



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