Skip to content

Latest commit

 

History

History
149 lines (133 loc) · 5.47 KB

ng-abq-soap.adoc

File metadata and controls

149 lines (133 loc) · 5.47 KB
Raw

ABQ - SOAP API

Table of Contents

Introduction

The "Allow/Block/Quarantine" feature allows for granular access control of mobile devices connecting to the server. For more details about the feature, refer to the ABQ Service documentation.

This appendix introduces the SOAP API support for the ABQ service.

Zimbra SOAP

Zimbra implements the Simple Object Access Protocol (SOAP) for integration with clients. For more information:

Zimbra’s SOAP implementation comprises a soap:Header and a soap:Body, as in this example of a SOAP request:

<?xml version="1.0" encoding="utf-8" ?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
    <soap:Header>
        <context xmlns="urn:zimbra">
            <authToken>$token</authToken>
            <format type="xml"/>
        </context>
    </soap:Header>
    <soap:Body>
        $xml
    </soap:Body>
</soap:Envelope>

Here $xml should replaced with the SOAP request that we want to issue, and $token should be a valid token granted by Zimbra after the client has successfully authenticated.

Login

To get access to Zimbra, first authenticate yourself and obtain a valid token. Here is the XML request to do so:

<AuthRequest xmlns="urn:zimbraAdmin">
    <account by="name">"user@example.com"</account>
    <password>password</password>
</AuthRequest>

Here an example of a reply:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
    <soap:Header>
        <context xmlns="urn:zimbra">
        <change token="699"/>
        </context>
    </soap:Header>
    <soap:Body>
        <AuthResponse xmlns="urn:zimbraAdmin">
            <authToken>0_2ebb6bdada2b1987c4fa625f95862d2a299b2e4c_69643d33363a34623065356237342d366135612d343435372d393032662d6630313833343131386666363b6578703d31333a313532393335333836373330303b61646d696e3d313a313b747970653d363a7a696d6272613b753d313a613b7469643d31303a313031323636373733383b76657273696f6e3d31333a382e382e385f47415f323030393b</authToken>
            <lifetime>43199998</lifetime>
        </AuthResponse>
    </soap:Body>
</soap:Envelope>

After we have a valid token we can use it in subsequent calls placing it into the <authToken>$token</authToken> of soap:Header.

ABQ API

All ABQ calls have a common XML:

<zextras xmlns="urn:zimbraAdmin">
    <module>ZxMobile</module>
    <action>$action</action>
</zextras>

where $action can be: getDeviceControlList, getDeviceStatus or setDeviceStatus followed by a parameter if needed. Here is an example of a reply:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope">
    <soap:Header>
        <context xmlns="urn:zimbra">
        <change token="699"/>
        </context>
    </soap:Header>
    <soap:Body>
        <response content="{"response":{"devices":[{"device_id":"device4","status":"device1=allowed;device2=quarantined;device3=Blocked"}]},
        "ok":true}"/>
    </soap:Body>
</soap:Envelope>

All ABQ replies are standard and they are placed into a <response> tag with a content attribute. Content is formatted as JSON with only one JSONObject: "response" and Boolean: "ok". The former contains the reply and the latter indicates if the request succeeded or not.

getDeviceControlList

Returns a list of all ABQ devices filtered by status: “all”, ”allowed”, ”quarantined” or ”blocked” (case insensitive)

<zextras xmlns="urn:zimbraAdmin">
    <module>ZxMobile</module>
    <action>getDeviceControlList</action>
    <status>all</status>
</zextras>

getDeviceStatus

Returns a list of ABQ devices status given a device list (semicolon separated)

<zextras xmlns="urn:zimbraAdmin">
    <module>ZxMobile</module>
    <action>getDeviceStatus</action>
    <device>device01;device02</device>
</zextras>

The reply contains a JSON array called devices, each with a pair of string attributes : "device_id" and "status". Here is an example:

{"response":{"devices":[{"device_id":"device1","status":"Allowed"}]},"ok":true}

If the requested device is not found in ABQ, it is simply omitted from the response.

setDeviceStatus

Sets the device status for a given device or list of devices. The list is semicolon separated and each element is composed of device_id = $status where $status can be Allowed, Quarantined or Blocked (case insensitive). Returns a list of failed devices.

<zextras xmlns="urn:zimbraAdmin">
    <module>ZxMobile</module>
    <action>setDeviceStatus</action>
    <deviceStatus>device01=allowed;device02=blocked</deviceStatus>
</zextras>

The reply contains a JSON array called devices, each with a pair of string attributes : "device_id" and "status". Here is an example:

    {"response":{"devices":[{"device_id":"device4","status":"wrong"}]},"ok":true}

Example

AbqClient is a simple java example to show access to ABQ api. It’s self contained and can be build with ant:

$ ant build

and executed by:

$ ant run