Skip to content

Latest commit

 

History

History
439 lines (318 loc) · 14.2 KB

ng-abq.adoc

File metadata and controls

439 lines (318 loc) · 14.2 KB

ABQ Service

The "Allow/Block/Quarantine" feature allows for granular access control of mobile devices connecting to the server. It’s a "pre-emptive" type of security feature, meaning that it acts upon the first connection to the server and it’s made to ensure that only authorized devices can finalize synchronization with server. This allows a full administrator to keep track of all mobile device used in their network. Presently only CLI tools are provided; a web GUI will be released in the future.

Components

The ABQ feature is composed of three main logical components:

  • a Device Control List

  • an Authorization Engine

  • a set of CLI tools

Device Control List

The Device Control List, also known as the "ABQ List", holds the information about allowed devices within the NG config engine. Devices can be added to the Device Control List via CLI based on their “Device ID” which can be obtained via CLI.

It is also possible to further limit access by limiting the accounts that can synchronise with the server on a specific device.

Note
On module startup, if the Device Control List is empty all mobile devices previously recognized by the Zimbra server will be imported as Allowed.

Authorization Engine

The Authorization Engine takes care of checking devices against the Device Control List and setting their ABQ status to the appropriate value.

Each rule is applied to all accounts connecting using a device it is a device id. It applies to a specific account connecting using that device if it has the format device_id/account_id or device_id/accountName

CLI Toolset.

The CLI Toolset allows administrators to interact with the device control list and with the synchronization status of a device, specifically to:

  • Display the Device Control List

  • Display all Quarantined and Blocked Devices

  • Add one or more devices to the Device Control List

  • Move a device from “Quarantine” to “Allowed” or “Blocked”

  • Change the synchronization status of a device

Every time the administrator changes a device’s status in an ABQ-enabled environment, depending on the issued state the device will be forced to re-sync folders with the server resulting in an immediate re-route to either a dummy virtual mailbox that will explain to the user what’s happened, or to the real mailbox to perform the re-sync.

ABQ Modes

The ABQ feature is triggered for every mobile device that tries to synchronize with server, and can be set to one of four possible modes: "Permissive", "Interactive", "Strict” and "Disabled". This attribute is Global for all the cluster.

"Permissive" mode:

The Authorization Engine is not active, so after authenticating the user and checking their account status for safety reasons, the synchronization will continue. It is still possible to block specific devices but non-blocked devices will always be allowed to sync.

"Interactive" mode:

After authenticating the user and checking their account status for safety reasons, the Device Control system will check the "Device ID" sent by the device against the list of allowed devices:

  • if the device/user couple is in the "allowed" list the synchronization will continue.

  • if the device/user couple is not in the device list but device is in the "allowed" list the synchronization will continue.

  • if the device is not in the “allowed” list the synchronization will be paused, a dummy email notifying the user of its "Quarantine" status will be sent and the connection will be set to "Quarantine" status.

Administrators can be notified at regular intervals, and every notification email will only include new Quarantined devices. They will then be able to allow or deny the synchronization for each device using the appropriate CLI tools.

"Strict" mode:

After authenticating the user and checking their account status for safety reasons, the Device Control system will check the "Device ID" sent by the device against the list of allowed devices:

  • if the device/user couple or the device by itself is in the "allowed" list the synchronization will continue.

  • if the device is not in the “allowed” list the synchronization will be put in "Blocked" state, no data will be synchronized and a dummy email notifying the user of the device’s "Blocked" status will be sent.

"Disabled" mode:

ABQ is disabled, no checks are triggered and no policies are enforced.

ABQ Mode Control

The current mode can be checked by running the following command:

zxsuite config global get attribute abqMode

The ABQ mode can be changed running the following command:

zxsuite config global set attribute abqMode value [Permissive|Interactive|Strict|Disabled]

Dummy data

The feature makes use of “Dummy emails” and a “Dummy mailbox” to put devices on hold while waiting for authorization (Interactive Mode) or to notify their “Blocked” status (Permissive Mode, Interactive Mode and Strict Mode).

The Dummy Mailbox is a virtual mailbox consisting of only an “Inbox” folder that will be synchronized to the device while this is in either Quarantine or Block status. Dummy Emails are predefined email messages that are synchronized to a device in Quarantine or Block status to alert the user. For now these messages aren’t customizable, and will be localized in the future. Whenever the ABQ status of a device is changed, the device’s sync state will be reset.

This was designed to make sure the user knows what’s happening, the alternative being forcing the synchronization to fail with no descriptive response for the user itself – which would likely cause a significant overhead on support calls.

Custom ABQ emails

Quarantine and block dummy emails can be customized by using the zxsuite mobile setABQMessage message command.

Messages can be customized globally or by domain, and multiple languages can be set.

The zxsuite mobile setABQMessage command accepts the following parameters:

Parameter Type Value Default

configLevel

string

global,domain

global

domain

string

only if config != global

messageClass

enum

blocked,quarantined

language

enum

locale (e.g. "en-us")

system default

from

string

Admin Address

reply_to

string

N/A

subject

string

Built-in default

body_plain

string

Built-in default

body_plain_file

path

Path to the file to use as plain text body

N/A

body_html

string

Built-in default

body_html_file

path

Path to the file to use as html body

N/A

Setup Example

Given two files, /tmp/quarantine_body.txt and /tmp/quarantine_body.html containing the French language plaintext and html message bodies and the [email protected] support email address, the following command will set the quarantine message for the domain.com domain without affecting other domains or users:

zxsuite mobile setABQMessage domain domain.com quarantined fr from [email protected] body_plain_file /tmp/quarantine_body.txt body_html_file /tmp/quarantine_body.html

Warning
Before being able to customize the ABQ messages, a default must be set using default as the language in the command, e.g.

zxsuite mobile setABQMessage global quarantined default […​]

Notifications

Administrators can be notified via email of quarantined devices at a specific interval defined by the abqNotificationsInterval NG configuration attribute, expressed in milliseconds:

The interval can be checked by running the following command:

zxsuite config global get attribute abqNotificationsInterval

The interval can be changed running the following command:

zxsuite config global set attribute abqNotificationsInterval value [delay in milliseconds]

By default, the abqNotificationsInterval is set to 0 - meaning that no notifications will be delivered.

ABQ Service Status

The ABQ service status can be checked running the following command:

zxsuite mobile getServices

The service can be stopped or started using the default service control of the Mobile NG module:

zxsuite mobile doStartService abq
zxsuite mobile doStopService abq

When mode is Disabled ABQ service won’t automatically start and devices are always allowed to sync.

ABQ CLI

A list of all ABQ CLI commands can be displayed running:

$ zxsuite mobile abq

Allow/Block/Quarantine mobile devices management

    list                    - List devices.
                              zxsuite mobile ABQ list [attr1 value1 [attr2 value2...] ]

    add                     - add/import devices
                              zxsuite mobile ABQ add [attr1 value1 [attr2 value2...] ]

    allow                   - Allow synchronization for a quarantined device
                              zxsuite mobile ABQ allow {device_id}

    block                   - Deny synchronization for a quarantined device
                              zxsuite mobile ABQ block {device_id}

    set                     - Set synchronization status for a device
                              zxsuite mobile ABQ set {device_id} {Allowed|Blocked|Quarantined}

    delete                  - Delete device from ABQ
                              zxsuite mobile ABQ delete {device_id}

    setNotificationInterval - Set the notification interval for new quarantined devices
                              zxsuite mobile ABQ setNotificationInterval {45m|6h|1d|0}

ABQ "list" Command

List all devices ABQ status. The "status" argument will filter the list in order to only show devices in that specific status.

$ zxsuite mobile abq list
List devices.

Syntax:
   zxsuite mobile ABQ list [attr1 value1 [attr2 value2...] ]


PARAMETER LIST

NAME        TYPE    EXPECTED VALUES
status(O)   String  Allowed|Blocked|Quarantined

(M) == mandatory parameter, (O) == optional parameter

Example:

[zimbra@mail ~]$ zxsuite mobile abq list

        devices

                device_id   androidc133785981
                status      Quarantined

                device_id   androidc1024711770
                status      Blocked

                device_id   SAMSUNG1239862958
                status      Allowed

ABQ "import" Command

This command imports a list of device ids from a file, and always requires two parameters: an Input File with a list of Device IDs separated by a newline and the "status" the imported device(s) will be set to.

[zimbra@mail ~]$ zxsuite mobile abq import
command import requires more parameters

Syntax:
    zxsuite mobile ABQ import {Path to file} {Allowed|Blocked|Quarantined}

PARAMETER LIST

NAME            TYPE        EXPECTED VALUES
input_file(M)   String      Path to file
status(M)       String      Allowed|Blocked|Quarantined

(M) == mandatory parameter, (O) == optional parameter

Usage example:

zxsuite mobile ABQ import /path/to/file Allowed

Example:

[zimbra@mail ~]$ zxsuite mobile abq import /tmp/list Allowed
3 devices added

[zimbra@mail ~]$ cat /tmp/list
androidc133785981
androidc1024711770
SAMSUNG1239862958/[email protected]

In the example above, devices androidc133785981 and androidc1024711770 are allowed to sync entirely regardless of the account, while device SAMSUNG1239862958 can only synchronize the [email protected] account

ABQ "allow" Command

This is a specific command for quarantined device, and sets device status to Allowed.

$ zxsuite mobile abq allow
Allow synchronization for a quarantined device

Syntax:
   zxsuite mobile ABQ allow {device_id} [attr1 value1 [attr2 value2...]]

PARAMETER LIST

NAME            TYPE      EXPECTED VALUES
device_id(M)    String
account(O)      String    27ee8dd9-d813-4ca7-a988-580df0027a58|[email protected]


(M) == mandatory parameter, (O) == optional parameter

ABQ "block" Command

This is a specific command for quarantined device, and sets device status to Blocked.

$ zxsuite mobile abq block
Deny synchronization for a quarantined device

Syntax:
   zxsuite mobile ABQ block {device_id} [attr1 value1 [attr2 value2...]]

PARAMETER LIST

NAME            TYPE      EXPECTED VALUES
device_id(M)    String
account(O)      String    27ee8dd9-d813-4ca7-a988-580df0027a58|[email protected]

(M) == mandatory parameter, (O) == optional parameter

ABQ "set" Command

Set any status for any single device (either known or unknown).

$ zxsuite mobile abq set
Set synchronization status for a device

Syntax:
   zxsuite mobile ABQ set {device_id} {Allowed|Blocked|Quarantined} [attr1 value1 [attr2 value2...]]

PARAMETER LIST

NAME            TYPE      EXPECTED VALUES
device_id(M)    String
status(M)       String    Allowed|Blocked|Quarantined
account(O)      String    27ee8dd9-d813-4ca7-a988-580df0027a58|[email protected]

(M) == mandatory parameter, (O) == optional parameter

ABQ "delete" Command

Delete a device from all lists.

$ zxsuite help mobile abq delete
Delete device from ABQ

Syntax:
   zxsuite mobile ABQ delete {device_id} [attr1 value1 [attr2 value2...]]

PARAMETER LIST

NAME            TYPE      EXPECTED VALUES
device_id(M)    String
account(O)      String    27ee8dd9-d813-4ca7-a988-580df0027a58|[email protected]

(M) == mandatory parameter, (O) == optional parameter

ABQ "setNotificationInterval" Command

Set notification interval for new quarantined devices.

$ zxsuite mobile abq setNotificationInterval
command setNotificationInterval requires more parameters

Syntax:
    zxsuite mobile ABQ setNotificationInterval {45m|6h|1d}

PARAMETER LIST

NAME            TYPE        EXPECTED VALUES
interval(M)     String      45m|6h|1d

(M) == mandatory parameter, (O) == optional parameter

Usage example:

Set notification of new quarantined devices every 45 minutes
    zxsuite mobile abq setNotificationInterval 45m
Set notification of new quarantined devices every 6 hours
    zxsuite mobile abq setNotificationInterval 6h
Set notification of new quarantined devices once every day
    zxsuite mobile abq setNotificationInterval 1d
Disable notifications of new quarantined devices
    zxsuite mobile abq setNotificationInterval 0