CardDAV Contact Sync Developer Guide

CardDAV contact sync — developer guide

How FreeITSM reads a CardDAV address book and turns its contacts into rows in users. Shipped in 1.8.0, asked for in #133.

This page covers the transport and the mapping — connecting, reading, and turning a vCard into a person. The import itself, the scope rules and the run lifecycle are on CardDAV import internals.

🔑 Reading only. Sending a change the other way — surgical vCard editing, folding, escaping and the conflict rule — is a separate file (includes/carddav_write.php) and a separate page: CardDAV write-back internals. The split is deliberate, so that "the import issues PROPFIND and REPORT and nothing else" stays a fact about the code.

For the administrator's view, see CardDAV contact sync.

---

1. The shape of it, in one idea

Directory sync already knew how to bring people into users safely. What it did not know was how to speak anything but LDAP.

includes/directory_sync.php owns the policy: nobody is ever deleted, a run that returns far fewer people than last time changes nothing, missing once is noise. None of that is about LDAP — and none of it was rebuilt.

What is about LDAP is every extension point around it: the columns are named ldap_attr_*, paging uses LDAP_CONTROL_PAGEDRESULTS, identity is objectGUID or entryUUID, and a manager is a distinguished name. CardDAV is HTTP and vCard — no DNs, no paged controls, identity is a URL plus an ETag.

So this is a fetch-and-map layer bolted under an existing policy layer, deliberately narrow:

        ┌──────────────── CardDAV ────────────────┐   ┌──── LDAP ────┐
        │  includes/carddav.php      (transport)  │   │  ldap_*()    │
        │  includes/carddav_sync.php (map + run)  │   │              │
        └────────────────────┬────────────────────┘   └──────┬───────┘
                             │                              │
                             └──────────────┬───────────────┘
                                            ▼
                        includes/directory_sync.php  (the policy layer)
                        dsyncFindExisting / dsyncCreate / dsyncApplyToExisting
                        dsyncHandleMissing / syncBrakeTripped / dsyncGetRun
                                            ▼
                                    users, directory_sync_runs

🔑 The policy layer turned out to be genuinely transport-agnostic, which was not a given — it was written with only LDAP in mind. The import calls ten of its functions and nine are used exactly as the LDAP path uses them. The one change needed was cosmetic: syncBrakeTripped() gained an optional $words parameter so its message can say "the wrong address book, or a group renamed on the server" instead of naming a base DN. LDAP's defaults are untouched, so that path behaves identically.

---

2. Files

Colour key: 🗄️ schema · ⚙️ engine · 🔌 API · 🖥️ UI · 🌍 i18n · 🐳 test rig

	File	What it does
⚙️	includes/carddav.php	the transport. HTTP, auth, PROPFIND/REPORT, vCard tokenising. Knows nothing about users.
⚙️	includes/carddav_sync.php	the import. vCard → person, scope resolution, the run.
⚙️	includes/directory_sync.php	the policy layer, shared with LDAP. Touched once, additively.
🗄️	auth_providers	protocol gains 'carddav'; carddav_addressbook, carddav_scope, carddav_scope_value, carddav_auth
🔌	api/system/test_carddav_connection.php	connect, list books, and scan the chosen one
🔌	api/system/run_directory_sync.php	routes to the right engine by protocol
🔌	api/system/save_sso_provider.php	the third protocol branch
🖥️	system/sso/carddav.php	the config page — Connection / Contacts / History
🖥️	system/sso/index.php	the provider list, and the carddav type option
⚙️	scripts/directory_sync.php	--all filters protocol IN ('ldap','carddav') and routes
🌍	lang/en/system.php	field_carddav_*, carddav_*, and the sso_keywords that make it findable
⚙️	includes/carddav_write.php	the write half: editing an existing card, and the portal and analyst pushes - see write-back internals
⚙️	includes/carddav_create.php	adding a new contact and linking the person - write-back internals §17
🔌	api/tickets/address_book_add.php · 🖥️ assets/js/address-book-add.js	the Add to address book button on Tickets → Users and Assets → Users
🗄️	auth_providers.carddav_write_back · carddav_allow_create	write-back, and letting analysts add people (both default 0; the second is forced off without the first)
🐳	docker/carddav-test/	Baïkal 0.12.1 in a container, with a seed script

---

3. 🔴 Auth is the thing that will bite you

Read this before changing anything in carddav.php.

A stock Baïkal — the standard sabre/dav server, and what the reporter runs — ships dav_auth_type: Digest. Measured against 0.12.1:

Scheme	Result
Basic	401
Digest	207
CURLAUTH_ANY	207

Basic is the obvious choice and what almost every REST integration reaches for, and against a default install it fails outright. The operator then sees "authentication failed", checks a password that is correct, and concludes FreeITSM is broken.

$authMode = CURLAUTH_ANY;
if (($cfg['auth'] ?? 'auto') === 'digest') $authMode = CURLAUTH_DIGEST;
if (($cfg['auth'] ?? 'auto') === 'basic')  $authMode = CURLAUTH_BASIC;

So: CURLAUTH_ANY by default, an explicit override for the rare server that needs one, and the connection test reports which scheme actually won — because that is the one thing the operator cannot discover for themselves.

Three smaller things in cardDavRequest() that exist for a reason:

• It sends a real User-Agent. PHP's cURL sends none by default, and something in front of a server will read that as a bot and block it. That exact mistake once cost an afternoon of chasing a phantom WAF.
• It follows redirects. http:// → https://, or a path gaining a trailing slash, are both routine.
• cardDavExplainStatus() turns a status code into a sentence. 405 in particular is worth a real explanation: it means the address is reachable but is not a CardDAV endpoint — almost always a web page rather than the DAV path. A bare "HTTP 405" sends somebody to check their password.

---

4. Two requests, and only two

Listing address books — PROPFIND, Depth: 1

$body = '<?xml version="1.0" encoding="utf-8"?>' .
        '<d:propfind xmlns:d="DAV:" xmlns:card="urn:ietf:params:xml:ns:carddav" …>' .
        '<d:prop><d:displayname/><d:resourcetype/><cs:getctag/></d:prop>' .
        '</d:propfind>';

A collection carrying the {urn:ietf:params:xml:ns:carddav}addressbook resource type is an address book. Everything else in the response — including the container you asked about — is not, which is how the parent gets excluded without special-casing it by URL.

⚠️ Namespaces are not optional. Servers use different prefixes for the same namespaces: Baïkal answers with d: and card:, others with D: and C:. Anything matching on prefixes works against one server and silently finds nothing against the next. cardDavParseAddressBooks() registers the URIs and queries those:

$xp->registerNamespace('d', 'DAV:');
$xp->registerNamespace('card', 'urn:ietf:params:xml:ns:carddav');

🔑 null and [] are different answers and must not be collapsed. cardDavParseAddressBooks() returns null when the body will not parse as DAV at all, and [] when it parsed fine and held no address books. The first is a wrong URL; the second is an empty account. Merging them produces "no address books found" for somebody who typed their web interface by mistake, and they will check their address books rather than their URL.

Fetching cards — addressbook-query REPORT, with address-data

$body = '<?xml version="1.0" encoding="utf-8"?>' .
        '<card:addressbook-query xmlns:d="DAV:" xmlns:card="urn:ietf:params:xml:ns:carddav">' .
        '<d:prop><d:getetag/><card:address-data/></d:prop>' .
        '</card:addressbook-query>';

address-data returns the vCards inline, so this is one round trip. The obvious alternative — PROPFIND for the hrefs then a GET per card — is, on an address book of a few thousand contacts, the difference between one request and a few thousand.

Relative hrefs

⚠️ A server may answer with an absolute URL, a root-relative path, or a bare segment, and all three are legal. Concatenating blindly gives you https://host/dav.php/addressbooks/jsmith//dav.php/addressbooks/jsmith/itsm/ — a 404 that reads like a missing address book rather than a client bug. cardDavAbsoluteUrl() handles the three cases.

---

5. 🔴 vCard parsing: unfolding is load-bearing

RFC 6350 folds any line longer than 75 octets by inserting CRLF followed by a single space or tab. Servers really do this, and a long CATEGORIES list is exactly the kind of property that gets folded.

Parse the raw text line by line and you read:

CATEGORIES:customer,supplier,pa
 rtner

as two lines — so the last value in a long list silently goes missing and everything still looks like it worked. One line prevents it:

$norm = str_replace(["\r\n", "\r"], "\n", $vcard);
$norm = preg_replace("/\n[ \t]/", '', $norm);   // a continuation is \n + exactly one space or tab

Property names come before parameters

CATEGORIES:a,b and CATEGORIES;TYPE=x:a,b are the same property. An implementation looking for the literal CATEGORIES: misses the second. cardDavProperty() strips parameters, then compares case-insensitively because the spec says property names are case-insensitive:

$left = substr($line, 0, $colon);
$semi = strpos($left, ';');
$prop = strtoupper(trim($semi === false ? $left : substr($left, 0, $semi)));

Escaped separators

A comma inside a value is escaped, so splitting on a bare comma breaks it. Every split in this code uses a negative lookbehind:

preg_split('/(?<!\\\\),/', $rawCategories)   // commas, but not \,
preg_split('/(?<!\\\\);/', $rawOrg)          // semicolons, but not \;

---

6. vCard → person

cdsyncMapCard() returns the array the policy layer expects, or null to skip the card.

return [
    'guid'        => $uid,          // the policy layer's name; for LDAP it is objectGUID
    'username'    => '',            // a contact has no sign-in name
    'email'       => $email ?: null,
    'name'        => $name,
    'job_title'   => trim(cardDavProperty($lines, 'TITLE')[0] ?? '') ?: null,
    'department'  => $org['department'],
    'office'      => cdsyncLocality($lines),
    'phone'       => $phone,
    'mobile'      => $mobile,
    'employee_id' => null,          // vCard has nowhere to keep one
    'manager_dn'  => null,          // RELATED;TYPE=manager exists, almost nothing writes it
    'dn'          => $href,         // for logging: the display equivalent of a DN
];

Two reasons a card is skipped

// A KIND:group card is a container, not a person. "ITSM" is not somebody
// called ITSM, and importing one creates a contact nobody can explain.
if (strtolower(trim(cardDavProperty($lines, 'KIND')[0] ?? '')) === 'group') return null;

// ⚠️ The UID is the identity. Without one there is nothing stable to match on
// across runs — the next run would create a second copy of the same person.
if ($uid === '') return null;

🔑 Skipping on a missing UID rather than falling back to the name is the important one. A name is not unique and not stable, so matching on it would either merge two different people or duplicate one person every run. Skipping is visible and recoverable; a duplicate every night is neither.

The per-field decisions

Field	Source	The decision
name	FN, then N, then email, then UID	FN is mandatory in the spec and absent in the wild. The chain exists so nobody lands as a blank row in the people list.
email	first EMAIL passing FILTER_VALIDATE_EMAIL	also the match key for an existing person, so a malformed one must not be stored
phone / mobile	TEL by parameter	CELL/MOBILE → mobile. Otherwise WORK wins, then any untyped number — a single untyped number on a card is the number somebody wants rung.
department	ORG component 2	ORG:Acme Ltd;Finance. Component 1 is the organisation, which FreeITSM has nowhere to put: a person's company is users.tenant_id, a real relationship rather than a string.
office	ADR component 4	ADR has seven components — PO box, extended, street, locality, region, postcode, country. The fourth is the town, which is what answers "which site are they at".
employee_id	—	Left null. Filling it with something that merely looks like a payroll number is worse than leaving it empty.
manager_dn	—	Left null. RELATED;TYPE=manager is in RFC 6350 and almost nothing writes it, so the chain is not imported rather than half-imported.

Why username is '' and not the email. A contact has no sign-in. The policy layer already stores NULL rather than an empty string for it, so contacts do not pile up against a unique index.

---

7. What to read next

• CardDAV import internals — scope resolution, the run lifecycle, the counts bug, the CLI, and the Docker test rig
• Directory sync developer guide — the policy layer this sits under
• Extending directory sync — §2, the extension points this deliberately does NOT use
• CalDAV and CardDAV — §5 priced this work before it was done, and was right
• CardDAV contact sync — the administrator's view
• CardDAV write-back internals — the other direction, and the reason it is a separate file
• CalDAV and CardDAV — the original analysis, and CalDAV, which is still not built