CalDAV and CardDAV: how to sync calendar and contacts

Module 5: Calendar and contacts · Reading time: 10 minutes

Learning objective: After this lesson, you can explain how CalDAV and CardDAV keep your calendar and contacts in sync between server and devices, why you only notice them when you set up an app, and what information you need to connect an app.

Key concepts: CalDAV, CardDAV, WebDAV, sync, server address, .well-known/caldav, .well-known/carddav, principal, app password, Exchange ActiveSync, default calendar

Calendar and contacts live on a server

With Google and Microsoft, you don't notice how your calendar gets onto your phone. You log in with your account, and the calendar and contacts are just there. Behind the scenes, they often use their own way of synchronising: Microsoft uses Exchange ActiveSync and its own connections, Google its own account syncing on Android.

With a European provider, it almost always works through two open standards:

• CalDAV (RFC 4791) for calendars and task lists;
• CardDAV (RFC 6352) for contacts.

Both build on WebDAV, an extension of ordinary web traffic (HTTPS) that lets you read and write files on a server. For CalDAV, an appointment is a small file in iCalendar format (lesson 5.2), and a contact is a small file in vCard format. The server stores these files in a folder per calendar or address book. Your phone, your laptop and the web calendar each ask every few minutes: "what's changed since last time?" and only fetch the changes.

iPhone  <--CalDAV/HTTPS-->  server: /calendars/anne/werk/  <--CalDAV-->  laptop (Thunderbird)
                                   ^
                                   |
                              web calendar in the browser

The great advantage of an open standard: you're not tied to a single app. The calendar app on your iPhone, DAVx5 on Android, Thunderbird, Calendar on the Mac, and many other apps all speak CalDAV. If you switch to another provider later that also supports CalDAV, you simply set up the same apps again.

Why you don't see it until you set up an app

After moving your calendar (lessons 5.2 and 5.3), everything sits neatly in the web calendar of your new service. Your phone doesn't know anything about that yet. No app appears automatically: you need to add an account on every device. For that you need three things:

The server address and .well-known

Every service has its own path where CalDAV and CardDAV live. For Nextcloud that's /remote.php/dav, for other servers it's something different. To avoid everyone needing to know that path, there's an agreed convention (RFC 6764): an app that's only given the domain name first checks a fixed location:

https://cloud.example.com/.well-known/caldav
https://cloud.example.com/.well-known/carddav

The server replies there with a redirect to the real path. If that redirect works correctly, you only need to enter cloud.example.com on your iPhone. If it doesn't work, the app says "unable to verify account" and you'll need to enter the full address. The same RFC also describes SRV records (_caldavs._tcp.example.com) that let an app find the server starting from your email domain. Not every app uses these.

After that, the app asks the server for your principal: the fixed location of your account on the server, with the list of your calendars and address books. This way the app automatically finds all your calendars, including any shared with you.

Why you need an app password

Most European cloud services ask for a second step when you log in via the browser: a code by email, an authenticator app, or a passkey. A calendar app on your phone can't complete that second step. It only has a field for username and password.

That's why you create an app password for such an app: a long, random password that only applies to that one app. You create it in your cloud's security settings, give it a recognisable name ("Calendar iPhone Anne"), and enter it in the app.

Benefits:

• Your real password isn't stored on your phone.
• If you lose your phone, you only revoke that one app password; everything else keeps working.
• If you change your regular password, your apps keep working.

Some apps can also log in via the browser: they open your cloud's login screen, you complete the second step there, and the app automatically receives an app password. DAVx5 on Android can do this with Nextcloud, for example.

The best-known error message for calendar apps is 401 Unauthorized. This almost always means: you used your regular password instead of an app password, or the app password has been revoked.

Exchange calendars and what you lose

If you're coming from Microsoft 365, you're used to a few things that work differently, or not at all, with CalDAV:

• Seeing colleagues' free/busy status when scheduling. Nextcloud and other CalDAV servers have their own version (availability within the same server), but it doesn't work between different services and not always in every app.
• Booking rooms and equipment (meeting room, projector). Some servers have resource calendars, others don't.
• Delegated access ("the secretary manages the director's calendar"). With CalDAV you arrange this by sharing with edit rights.

Add this to your list (module 3). It's rarely a reason not to switch, but colleagues do need to know about it in advance.

In practice: what it looks like with a provider

In a WebOké Nextcloud, you'll find the addresses in the Calendar app, at the bottom left under Calendar settings: the CalDAV URL and the Server Address for iOS and macOS, each with a copy button. The general address is https://<your-address>/remote.php/dav. You create an app password under Settings, Security, Devices & sessions. There you can also later see which device last made contact and when, and revoke an app password. Other Nextcloud providers work exactly the same way; with other European services (for example mailbox.org, Posteo, or an Open-Xchange environment), the CalDAV address is listed in the help pages or settings, and app passwords are sometimes called "device password" or "application password".

Summary

• CalDAV (calendar, tasks) and CardDAV (contacts) are open standards built on top of WebDAV and HTTPS; every change is a small file on the server.
• You need to add an account on every device yourself: server address, username and an app password.
• Via .well-known/caldav and .well-known/carddav, an app finds the real path from just the domain name; if that doesn't work, enter the full DAV address.
• An app password is needed because calendar apps can't do a second login step; a 401 error almost always means a wrong password.
• Exchange features like free/busy between colleagues, room booking and delegation work differently; add them to your list.

Quiz

Exercise

Exercise A5.1: Can an app find your calendar? Enter the address of your (new) cloud, for example cloud.example.com. The program checks whether /.well-known/caldav and /.well-known/carddav redirect correctly to a DAV path, and whether the server responds there as a DAV server. This tells you whether you can enter just the domain name on a phone.

Further reading

The steps in these articles apply to WebOké's services; with other providers it works in a similar way.

• Nextcloud manual 3.5: App passwords: when and how to use them
• Nextcloud manual 9.9: Calendar and contacts on the iPhone and iPad
• Nextcloud manual 9.10: Calendar and contacts on Android with DAVx5
• Nextcloud manual 15.6: Calendar or contacts don't show up on the phone
• Create app password (needed to connect with apps and devices)
• RFC 4791 (CalDAV), RFC 6352 (CardDAV), RFC 4918 (WebDAV), RFC 6764 (.well-known and SRV for CalDAV and CardDAV)