KB 1907        Last updated on 2015-07-13  

(0 votes)

Sometimes it makes sense to integrate a application into the Zimbra server directly rather then in the Web Interface. A good example of this is an application that uses Zimbra for Authentication. The code is from the test source code in the zimbrastore.jar. Additionally, please include zimbracommon.jar, json.jar, and commons-httpclient-3.1.jar

package org.technicaldetails.zimbra.authenticator;
import java.io.IOException;
import com.zimbra.common.soap.AccountConstants;
import com.zimbra.common.soap.SoapFaultException;
import com.zimbra.cs.account.Account;
import com.zimbra.cs.account.auth.AuthContext.Protocol;
import com.zimbra.cs.account.soap.SoapProvisioning;

So how do we use this?

First let's connect to the server:

                SoapProvisioning sp;
			sp = new SoapProvisioning();
			sp.soapSetURI("https://someurl.com:7071" + com.zimbra.common.soap.AdminConstants.ADMIN_SERVICE_URI);
			sp.soapAdminAuthenticate("aUsername", "aPassword");
                catch (Exception e)


This code tries to connect up to the server someurl.com with the ZimbraServlet.USER_SERVICE_URI path. (/server/soap iirc). We also could be connecting to the Admin service if we wanted to access the admin functionality or to use the auth-token to connect into other mailboxes.

Trans.invoke takes the Soap Element and sends it across the wire to the server. If it doesn't work for network reasons it will exception out.

If it works, you can get at the auth token by doing the following:

           // get the auth token out, no default, must be present or a service exception is thrown
            String authToken = response.getAttribute(AccountConstants.E_AUTH_TOKEN);
            // get the session id, if not present, default to null
            String sessionId = response.getAttribute(ZimbraSoapContext.E_SESSION_ID, null);

The getAttributeCode here will bail if there is no Auth_Token returned. Since Zimbra sets back a message without one if the token is null, then obviously this will crash if it fails to log in to the server.

Now that we have a working authentication token, we can add it to every soap request that is passed back and forth. Remember that HTTP is stateless. This token is how Zimbra knows that who you are, and that you arn't a evil mean hacker out to steal people's email.

            // set the auth token and session id in the transport for future requests to use
           if (sessionId != null)

Fair enough. This is enough for some really basic things where you are just trying to authenticate if a user exists or not. But what if you wanted to do something a bit more advanced. What if you wanted to know what tags a user uses so you can synchronize your tagging system with Zimbras?

Like everything else, we create a message to pass to the Zimbra Server.

            Element tagsRequest = Element.XMLElement.mFactory.createElement(MailService.GET_TAG_REQUEST);
            Element tagsResponse = trans.invoke(tagsRequest);

<GetTagResponse xmlns="urn:zimbraMail">

 <tag color="3" u="7" name="Work" id="71"/>
 <tag color="5" u="5" name="Bank" id="68"/>
 <tag color="3" name="Softball" id="70"/>
 <tag color="6" name="Friends" id="69"/>
 <tag color="4" u="26" name="Firefly" id="67"/>
 <tag color="1" name="Aviation" id="66"/>
 <tag color="2" name="Java" id="65"/>

congrats, you have connected to your Zimbra Server for the First Time, and gotten something useful out of it. Of course, while SOAP is the way to communicate with the Zimbra Server, we are basically twiddling with the wire format here. That's not something we want to do long term, we would prefer to encapsulate it with higher level logic that isolates us from wire format changes. That's where Zclient comes in... Next time.

Verified Against: Unknown Date Created: 4/4/2007
Article ID: https://wiki.zimbra.com/index.php?title=ZClient Date Modified: 2015-07-13

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