Managed DAVdroid

With Managed DAVdroid, you can configure DAVdroid centrally for a whole organization.

Managed configuration

Managed DAVdroid allows you to manage DAVdroid clients centrally by using these configuration methods (in order of precedence):

  1. EMM restrictions (recommended)
  2. network configuration: fixed URL (QR code)
  3. network configuration: unicast DNS
  4. network configuration: Zeroconf (DNS-SD)
  5. local configuration file

This configuration is used in the Managed DAVdroid UI and for new Managed DAVdroid accounts.

Existing Managed DAVdroid accounts on your devices won't be modified when the managed configuration is changed.

Configuration by EMM restrictions (Android Enterprise)

Android Enterprise is the recommended method to configure Managed DAVdroid. With Android Enterprise, IT departments can deploy apps to managed devices and configure them in a standardized way using EMM software. Apps are configured by restrictions which can be set in the EMM software for every deployed app.

Network configuration

There are three methods of network configuration:

  • fixed URL
  • unicast DNS
  • Zeroconf (DNS-SD)

Network configuration requires managed Android devices to be connected to the network where the configuration file can be found. Usually, this is a WiFi and/or VPN connection. The following paragraphs apply to all network configuration methods:

Certificates

When accessing the configuration file, PKI is used to verify the TLS certificate, so a self-signed certificate won't work without adding it to the Android device first. We recommend to put the configuration file to a location which is accessible over a trusted certificate. You can then define custom trusted certificates in the configuration file.

Caching

Two types of caching are used to cache Managed DAVdroid configuration when it's taken from the network:

  1. configuration cache and
  2. HTTP cache.

Configuration cache: Managed DAVdroid caches the configuration file which is fetched from the network so that Managed DAVdroid configuration is available when there is no network access (and for the time when Managed DAVdroid has been started, but the new network configuration is not ready yet). The cache will be overwritten when a new configuration file is downloaded. To reset the cache without a new configuration file, use: Managed DAVdroid / About/License / Managed configuration / Reload configuration.

HTTP cache: The configuration file is cached when it has been downloaded from the network according to the rules of the HTTP protocol. For instance, if the Web server which hosts the configuration file returns a freshness period of one hour, Managed DAVdroid will always use the cached version for one hour. However, the configuration file will be downloaded at least once a day (max-age: 1 day) to avoid problems caused by obsolete configuration files. If there is no Expires, the cache will use If-Match and If-Unmodified-Since.

It's advisable to set an expiration time for the configuration file on the Web server (for instance, one hour) explicitly to avoid unnecessary network traffic every time Managed DAVdroid is started on a device.

Configuration by fixed URL/QR code

The simplest method to configure Managed DAVdroid over the network is to use a fixed configuration file URL, which can for example be provided as a QR code. This method can be used if you don't want to use automatic discovery of the Managed DAVdroid configuration file.

To set a network configuration URL, an ACTION_VIEW Intent with the configuration file URL (ending in davdroid-config.json) has to be called on the Android device. To do so, you can

  • scan the QR code of the configuration file URL, then open it with Managed DAVdroid (not your browser)
  • link to the configuration file on some page in your Intranet, and use your browser to open it with Managed DAVdroid

You can see and reset the current configuration file URL in Managed DAVdroid / About/License / Managed configuration.

Summary: To get Managed DAVdroid running with a fixed configuration URL, you need to

  1. upload the Managed DAVdroid configuration file to a HTTPS server in the network (file name: davdroid-config.json),
  2. generate a QR code for this URL,
  3. scan the QR code on the Android device (you may have to install a QR code scanner app first),
  4. start Managed DAVdroid and make sure everything works as expected.

Configuration by unicast DNS

Managed DAVdroid tries to resolve the SRV and TXT path records of davdroid-configs.local in the local network. In case of success, the resulting URL (https scheme, domain and host taken from SRV, path taken from TXT path, or / else) is used to fetch Managed DAVdroid configuration.

An example DNS configuration could look like this:

 

davdroid-configs.local   IN SRV 1 0 443 internal.example.com
davdroid-configs.local   IN TXT "path=/davdroid/davdroid-config.json"

 

In this case, Managed DAVdroid would try to access the configuration file at https://internal.example.com:443/davdroid/davdroid-config.json.

Summary: to get Managed DAVdroid running with unicast DNS, you need to

  1. upload the Managed DAVdroid configuration file to a HTTPS server in the network,
  2. add SRV and TXT DNS records for davdroid-configs.local in your network DNS server/forwarder,
  3. start Managed DAVdroid and make sure everything works as expected.

Configuration by Zeroconf (DNS-SD)

Managed DAVdroid can discover a service called davdroid-configs._tcp using DNS-SD. The network configuration file URL (https scheme) will be built from the host and path parts of TXT records (the SRV record is not used because the discovery service is not the same as the referenced configuration). If no host is specified, the host name of the host running the avahi service is used. If no path is specified, / will be used.

You can use any DNS-SD server. If you use avahi, the configuration file could be put into /etc/avahi/services and look like this:

 

<?xml version="1.0" standalone='no'?>
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
<service-group>
  <name>Managed DAVdroid configuration</name>
  <service protocol="ipv4">
    <type>_davdroid-configs._tcp</type>
    <port>443</port>
    <txt-record>host=internal.example.com</txt-record>
    <txt-record>path=/public/davdroid-config.json</txt-record>
  </service>
</service-group>

 

In this case, Managed DAVdroid would try to download the configuration file from https://internal.example.com/public/davdroid-config.json.

Summary: To get Managed DAVdroid running with DNS-SD, you need to

  1. upload the Managed DAVdroid configuration file to some Web server in the network,
  2. install and start a DNS-SD server like avahi on a server in the network (for instance, the Ubuntu avahi-daemon package),
  3. add the _davdroid-configs._tcp service with host and path TXT records,
  4. if necessary, allow DNS-SD in the firewall rules,
  5. start Managed DAVdroid and give it some time to detect and download the configuration.

Local configuration file

Managed DAVdroid watches the device for a file named davdroid-config.json in the app-private directory (package identifier: com.davdroid.managed) on the external storage, for instance /storage/emulated/0/Android/data/com.davdroid.managed/files/davdroid-config.json.

If no other configuration method is active, you can put a configuration file to this location (using a regular file manager app or adb). Changes in this file will be applied immediately. This method is only recommended for debugging/testing purposes, for instance if you want to test the configuration file without the influence of potential networking problems.

Configuration variables

Managed DAVdroid configuration variables
NameTypeDescription
licensetext*license data (JSON)
license_signaturetext*license signature (Base64)
organizationtextorganization display name; shown in app drawer and login activity
logo_urltext (URL)organization logo; shown in login activity; must be publicly accessible without authentication
support_homepage_urltext (URL)URL of intranet page with details on how to use Managed DAVdroid in this organization and how to get internal support; shown in app drawer
support_email_addresstext (email address)internal support email address – shown in app drawer and some notifications
support_phone_numbertext (phone number)internal support phone number – shown in app drawer and some notifications
login_base_urltext (URL)*

base URL for CalDAV/CardDAV service discovery when an account is added

example: https://server.example.com/dav/

login_user_nametextdefault user name when an account is added – only useful with EMM configuration when EMM can pre-fill restrictions from user details
login_certificate_aliastextif provided, client certificates will be used for authentication (instead of user name/password); value of this field will be pre-selected (if available)
max_accountsinteger*maximum number of accounts – no new accounts can be created when this number of accounts is reached
override_proxyboolean*false = system proxy settings are used
true = system proxy settings are ignored and override_proxy_host and override_proxy_port are used instead
override_proxy_hosttext (host name)HTTP proxy host name
override_proxy_portint (port number)HTTP proxy port number
wifi_onlyboolean

false = DAVdroid will only sync when a WiFi connection is active
true = DAVdroid will sync regardless of the connection type

wifi_only_ssidstext (comma-separated list)

when set, DAVdroid will only sync when device is connected to one of these WiFis

only used when wifi_only is true; example: wifi1,wifi2,wifi3

contact_group_methodstring: CATEGORIES or GROUP_VCARDS

CATEGORIES = contact groups are stored as per-contact category tags
GROUP_VCARDS = contact groups are separate VCards

set as required by your server and/or other clients

manage_calendar_colorsbooleanfalse = DAVdroid will copy detected calendar colors to the device at every sync
true = DAVdroid won't change local calendar colors at every sync
event_colorsboolean

false = DAVdroid won't synchronize event colors
true = DAVdroid will synchronize event colors

setting to true causes some default calendar apps; make sure that your preferred calendar app is working with this setting

*… required

Configuration file syntax

A Managed DAVdroid configuration file contains configuration variables in JSON format, like this:

 

{
  "license": "<escaped JSON, don't change this>",
  "license_signature": "<don't change this>",
  "organization": "bitfire",
  "logo_url": "https://intranet.example.com/your-logo.png",
  "support_homepage_url": "https://intranet.example.com/how-to-use-davdroid",
  "support_email_address": "it-support@example.com",
  "support_phone_number": "+1 234 56789",
  "login_base_url": "https://caldav+carddav.example.com/",
  "max_accounts": 1,
  "override_proxy": false,
  "wifi_only": true,
  "wifi_only_ssids": "wifi1,wifi2",
  "contact_group_method": "GROUP_VCARDS",
  "manage_calendar_colors": true,
  "event_colors": false
}

Last updated: 06 Feb 2018