acceso soap a zimbra

Hace ya muchas versiones que Zimbra soporta operaciones SOAP. Eso quiere decir que podemos crear una aplicación externa a Zimbra y comunicarnos con él a través de llamadas Soap. Podemos hacer cosas como: crear una cuenta, borrarla, crear una alias, crear un dominio, modificar un password, hacer una búsqueda por la GAL, modificar parámentros del server, crear volúmenes de disco, crear/modificar listas de distribución, deshabilitar un zimlet, crear una nota en el calendario, crear un cita en el calendario, etc, etc.

Para quien no sepa lo que es SOAP (Simple Object Access Protocol), se trata protocolo diseñado para la comunicación a través de la red entre dos procesos. Toda la comunicación se basa en el intercambio de mensajes en formato XML. Es decir, si yo quiero que Zimbra haga algo; construyo un mensaje XML, se lo envío, el lo hace y me devuelve (o no) un resultado también en formato XML.

SOAP es uno de los principales protocolos para construir "web services" a través de Internet, pero hay más. Existen otros protocolos para la comunicación a través de la red como pueden ser Corba o DCOM. Ninguno de ellos es tan extendido y fácil de usar como SOAP. SOAP utiliza HTTP para ser transportado y por tanto puede hacer uso SSL (HTTPs) para añadirle una capa de seguridad de forma que todos los mensajes XMLs van cifrados. Además es posible programar llamadas SOAP con cualquier tipo de lenguaje. Al ser un protocolo sobre HTTP la mayoría de firewals lo tienen abierto y es de fácil implementación.

Para hacer este ejemplo de conexión SOAP contra Zimbra utilizaré un programa escrito en PHP. Para saber exactamente el formato de los mensajes XML que se deben construir es necesario que leáis los documentos de texto que hay dentro de /opt/zimbra/doc/soap*.txt. Todos estos archivos de texto explican como se forman los mensajes y que resultado producen.

Los mensajes SOAP en PHP se puede construir de dos maneras diferentes. Una es utilizando una librería SOAP para PHP como NuSoap o PHP:Soap. Ellas facilitan la creación de los mensajes y la lectura de las respuesta. La otra forma (que es la que yo utilizaré) es contruir los mensajes XML "a mano". Esta solución es más laboriosa pero es la mejor para entender como funciona este protocolo.

Lo primero que haremos es saber cual es la dirección URL donde está publicado el web service de Zimbra. Este web service de Zimbra esta esperando a que nosotros le enviemos peticiones XML para él ejecutarlas.

La URL que nos interesa (hay dos) en este momento es:

https://mizimbra.miempresa.com:7071/service/admin/soap/

Como veis al ser https todos los mensajes XML irán cifrados.

Ahora lo que necesitamos, antes de pedir al Zimbra que haga algo, es identificarnos. Para ello Zimbra nos proporciona la función SOAP AuthRequest que nos permite validarnos. Si miramos el archivo /opt/zimbra/doc/soap-admin.txt vemos que la petición XML tiene que tener este formato:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Header>
      <context xmlns="urn:zimbra"/>
   </soap:Header>
   <soap:Body>
      <AuthRequest xmlns="urn:zimbraAdmin">
         <name>admin@miempresa.com</name>
         <password>mi_contraseña</password>
    </AuthRequest>
   </soap:Body>
</soap:Envelope>

Lo que hacemos es una llamada a la función AuthRequest pasándole el nombre de usuario y la contraseña del usuario administrador.

Una vez enviado este XML al web service de Zimbra, este nos contesta con otro XML:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:Header>
      <context xmlns="urn:zimbra">
      <sessionId id="2260" type="admin">2260</sessionId>
      <change token="119977"/></context>
   </soap:Header>
   <soap:Body>
      <AuthResponse xmlns="urn:zimbraAdmin">
         <authToken>0_fd180...313b</authToken>   
         <lifetime>43199999</lifetime>
         <a n="zimbraIsDomainAdminAccount">false</a>
         <sessionId id="2260" type="admin">2260</sessionId>
      </AuthResponse>
   </soap:Body>
</soap:Envelope>

De esta respuesta nos tendremos que apuntar dos datos importante como son el authToken y el sessionId que nos permitirán hacer otro tipo de peticiones a Zimbra, pero esta vez ya logeados.

Es importante comprender el formato de una petición SOAP. Toda petición SOAP va dentro de tags <envelope>...</envelope>. Luego la petición tiene una cabecera <header>...</header> y un cuerpo <body>...</body>. El resto de tags vienen especificados por el tipo de web service y debemos conocer previamente su estructura antes de hacer una petición.

Veamos ahora como se crea un mailbox o dirección de correo. Para ello primero consultamos /opt/zimbra/doc/soap-admin.txt y vemos que existe una función SOAP llamada CreateAccountRequest. Por tanto para crear un mailbox tenemos que enviar al web service esta petición:

<soap:envelope soap="http://www.w3.org/2003/05/soap-envelope">
   <soap:header>
      <context xmlns="urn:zimbra">
      <authtoken>0_fd180...313b</authtoken>
      <sessionid id="2260">2260</sessionid>
   </context>
   </soap:header>
   <soap:body>
      <createaccountrequest xmlns="urn:zimbraAdmin">
         <name>soyunusuario@miempresa.com</name>
         <password>123456789</password>
         <a n="givenName">Francisco</a>
         <a n="sn">Rebollo</a>
      </createaccountrequest>
   </soap:body>
</soap:envelope>

Es importante que noteis como dentro del header hemos añadido los valores del authToken y del sessionId que hemos obtenido anteriormente. Esto es necesario ya que solo podemos utilizar la función CreateAccountRequest si anteriormente nos hemos identificado. El resto de parámentros que pasamos por el body son: dirección de correo, contraseña, nombre y apellido. Dentro del body podemos pasar muchos más parámetros utilizantdo el tag <a> y el atributo "n=".

Para quien no domine de PHP la manera de enviar estas peticiones XML por Internet a Zimbra es programando las funciones curl. Estas funciones lo que hacen es poder abrir conexiones con servidores http, ftp, telnet, etc.
Estos son los archivos fuentes de pruebas.

zimbraAdmin.class.php