Customer HubCalendar (CalDAV)
The Calendar policy hands a CalDAV account to the native Calendar app of iOS and iPadOS via a configuration profile, which removes the need for manual setup by the end user. On current iOS versions, the calendar paths belonging to the account are discovered automatically according to RFC 6764 through a redirect at /.well-known/caldav. A correctly configured server-side /.well-known/caldav redirect is therefore mandatory on current iOS versions; specifying a principal URL alone is no longer sufficient there.
Configuration options
The following fields are available for the CalDAV account. They correspond to the keys of the Apple CalDAV payload (com.apple.caldav.account).
Account settings
- Account description — display name of the account on the device.
- Host — server address without scheme and without path (e.g.
calendar.example.com). - Port — usually
443. - Use SSL — mandatory when the server is reachable via HTTPS. Without SSL enabled, an unencrypted connection is attempted on port
443, which fails. - User name — entered manually or via the placeholders
${user.name}or${user.email}. - Password — if left empty, the device prompts for it during profile installation.
- Principal URL (optional) — the path to the user principal (e.g.
/remote.php/dav/principals/users/${user.name}/).
https://host/...). Host, port and encryption are derived from Host, Port and Use SSL. On current iOS versions, however, a configured principal URL no longer replaces automatic discovery — what counts is a correctly configured /.well-known/caldav redirect. The field can therefore be left empty.Automatic discovery via .well-known
Current iOS versions set up CalDAV accounts according to RFC 6764. The sequence is:
- A
PROPFIND /.well-known/caldavrequest to the server configured under Host. - The server responds with a redirect (
301) to its DAV endpoint (/remote.php/davfor ownCloud/Nextcloud). - The DAV endpoint is used to determine the
current-user-principaland, from there, the user’s calendar area.
Reliable setup therefore depends entirely on a correct /.well-known redirect. On newer iOS versions, automatic discovery can no longer be bypassed by specifying a principal URL — without a working /.well-known redirect the setup fails, even if a principal URL is configured.
http:// instead of https://) that iOS 17 still tolerated causes discovery to abort on current versions. Accounts already set up under iOS 17 on older devices may continue to work while new setups fail.Server-side configuration of the redirect
/.well-known/caldav and /.well-known/carddav must redirect to the server’s DAV endpoint with a 301. The target address must begin with https:// and must not contain an internal port.
For nginx:
location = /.well-known/caldav { return 301 https://$host/remote.php/dav; }
location = /.well-known/carddav { return 301 https://$host/remote.php/dav; }
For Apache (in the vHost):
Redirect 301 /.well-known/caldav https://calendar.example.com/remote.php/dav
Redirect 301 /.well-known/carddav https://calendar.example.com/remote.php/dav
8080), the web server often only knows its public address as http on the internal port. A redirect generated from this is then incorrect, for example http://calendar.example.com:8080/remote.php/dav. Since current iOS versions do not follow a switch from https to http, discovery fails. In this case the redirect must be set with a full https:// target address — either directly on the TLS-terminating proxy or as an absolute target URL as in the Apache example.Verification
The redirect can be checked with curl:
curl -sI https://calendar.example.com/.well-known/caldav
The response must contain a redirect with a correct location header:
HTTP/2 301
location: https://calendar.example.com/remote.php/dav
The location header must begin with https:// and must not contain an internal port (e.g. :8080).
Troubleshooting
| Symptom | Cause | Solution |
|---|---|---|
| Setup fails only on newer iOS versions; older devices keep working | The redirect points to http:// (downgrade); older iOS versions tolerated this | Correct the redirect to https:// |
301 points to an internal port (e.g. :8080) | Reverse proxy/TLS termination, the web server does not know its public address | Set the redirect with the full https:// address on the proxy or web server |
405 Method Not Allowed on paths such as / or /principals/ | Automatic discovery does not take effect and falls back to default paths that do not exist on the server | Configure the /.well-known redirect correctly (mandatory on newer iOS versions) |
| The discovered path is obviously wrong | Principal URL configured as a full URL instead of a plain path, or Use SSL not enabled | Enter the principal URL as a plain path and enable Use SSL |
Isolating the problem on the device
For isolation, a CalDAV account can be set up directly on the device as a test under Settings → Calendar → Accounts. If the manually configured account connects while the account distributed via profile fails, the cause lies in automatic discovery (/.well-known) or in the principal URL distributed through the profile — not in the server itself.
Use on macOS
The CalDAV configuration and the server-side /.well-known requirement apply to macOS unchanged: