Customer HubCalendar (CalDAV)
The Calendar configuration 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.
The configuration is also available for devices with User Enrollment →.
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.
- Hostname (required) — server address as a DNS name without scheme, port and path (e.g.
calendar.example.com). Plain IP addresses are not accepted. - Port — usually
443. The field has no preset value. - Use SSL — enabled by default; leave it enabled when the server is reachable via HTTPS. Without SSL enabled, an unencrypted connection is attempted on port
443, which fails. - Username (required) — entered manually or via placeholders such as
${user.name}or${user.email}. Further placeholders are listed in the Available placeholders section below the form. - Password — if left empty, the device prompts for it during profile installation.
- Principal URL (optional) — the full URL of the user principal including scheme and host (e.g.
https://calendar.example.com/remote.php/dav/principals/users/${user.name}/).
https://calendar.example.com/...). A plain path such as /remote.php/dav/... is marked as invalid (“has to be a valid URL”), and the configuration cannot be saved. Host and scheme of the URL should match Hostname 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.Per account VPN
The CalDAV account can be referenced in a VPN configuration in the Per account VPN section, so that the connection to the calendar server is established through this VPN. The form of the Calendar configuration then shows the notice “This configuration is referenced by a VPN configuration.” with the link Show the referenced configuration. Setting up the VPN is described in App to VPN Mapping →.
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 Hostname. - 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 with a different host or with http:// instead of https://, or Use SSL not enabled | Enter the Principal URL with https:// and the server configured under Hostname, or leave it empty, 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: