CalDAV Provider Guide

Overview

This guide provides comprehensive CalDAV configuration details for connecting SuiteCRM to CalDAV-compliant calendar servers. Use this as your authoritative reference for CalDAV setup, URL discovery, and provider-specific troubleshooting.

If you need general Calendar Account setup instructions, see User Guide. This guide focuses specifically on CalDAV configuration details.

What is CalDAV

CalDAV (Calendar Distributed Authoring and Versioning) is an open standard protocol that enables calendar access and synchronization over the internet. It’s based on WebDAV and HTTP, making it a widely supported, interoperable solution for calendar management.

Understanding CalDAV URLs

CalDAV URLs follow a specific structure that points directly to a calendar resource on the server. Understanding URL anatomy helps you construct valid URLs and troubleshoot connection issues.

URL Structure

A typical CalDAV URL has these components:

https://server.example.com/dav-path/username/calendar-name/

  • Protocol: Always https:// (or http:// for local testing, not recommended)

  • Server: The hostname or IP address of your CalDAV server

  • DAV Path: The path to the CalDAV service endpoint (varies by implementation)

  • Username: Your CalDAV account username

  • Calendar Name: The specific calendar identifier

  • Trailing Slash: Required by most CalDAV implementations

Trailing Slash Requirement

Most CalDAV servers require the URL to end with a trailing slash (/). Without it, you’ll encounter errors like "Calendar not found" or "Invalid URL".

Correct:

https://caldav.example.com/dav/calendars/john/personal/

Incorrect:

https://caldav.example.com/dav/calendars/john/personal

Always include the trailing slash unless your specific CalDAV provider documentation states otherwise.

Port Numbers

Some CalDAV servers run on non-standard ports. Include the port number in the URL when necessary:

http://localhost:5232/username/calendar/

Check your CalDAV server documentation for the correct port number.

Common URL Patterns

This table provides standard URL patterns for popular CalDAV providers. Replace placeholders with your actual values.

Provider URL Pattern Notes

Example Provider

https://caldav.example.com/dav/calendars/user/EMAIL/CALENDAR_ID/

EMAIL is your full email address (e.g., user@example.com)

These patterns are starting points. Always verify the exact URL format with your CalDAV provider’s documentation or administrator.

Finding Your CalDAV URL

Detailed instructions for discovering your CalDAV URL.

Example

Example provides CalDAV access with their email service. The URL structure is consistent across all Example accounts.

Steps to Find Your URL:

  1. Log into your Example account

  2. Navigate to Settings (gear icon)

  3. Click Calendars in the settings menu

  4. Locate the calendar you want to sync

  5. Click the three-dot menu or Actions next to the calendar name

  6. Select Export or CalDAV Settings

  7. Copy the displayed CalDAV URL

Expected URL Format:

https://caldav.example.com/dav/calendars/user/your-email@example.com/calendar-id/

Example:

https://caldav.example.com/dav/calendars/user/john@example.com/12345678-1234-5678-1234-000000000000/

Authentication Details:

  • Username: Your full Providers email address (e.g., john@example.com)

  • Password: Your Provider password or an app-specific password (recommended)

CalDAV Calendar Account with Example Server URL

Other CalDAV Providers

If your CalDAV provider is not listed above, follow these general discovery steps:

  1. Check Provider Documentation: Most CalDAV servers document their URL structure in setup guides

  2. Contact Your Administrator: If using a company-hosted CalDAV server, ask your IT department for the correct URL

  3. Use a CalDAV Client: Configure a desktop CalDAV client (Thunderbird Lightning, macOS Calendar, etc.) and inspect the connection settings

  4. Examine CalDAV Autodiscovery: Some servers support .well-known/caldav autodiscovery; try https://your-server/.well-known/caldav

CalDAV Troubleshooting

Provider-specific issues and solutions for CalDAV connections.

Connection Test Failures

"Calendar not found" or "Invalid URL"

Causes:

  • Incorrect CalDAV URL structure

  • Missing trailing slash

  • Wrong calendar name or identifier

  • Calendar has been deleted or renamed

Solutions:

  • Verify the URL ends with a trailing slash: https://server/path/calendar/

  • Check that the calendar name matches exactly (case-sensitive in some implementations)

  • Log into the CalDAV web interface and confirm the calendar exists

  • Re-copy the URL from the CalDAV provider’s settings page

"Authentication failed" or "Invalid credentials"

Causes:

  • Incorrect username or password

  • Username format mismatch (email vs username)

  • Password contains special characters not properly encoded

  • Account locked or disabled on CalDAV server

  • Two-factor authentication enabled without app password

Solutions:

  • Verify username format (some providers require full email address)

  • For Example Provider, create an app password in Security settings

  • Check if your CalDAV account is active and not locked

  • Disable two-factor authentication temporarily for testing, then use app passwords

"SSL certificate problem" or "Certificate verification failed"

Causes:

  • Self-signed certificate on CalDAV server

  • Expired SSL certificate

  • Certificate hostname mismatch

  • Missing intermediate certificates

Solutions:

  • For self-signed certificates, add the certificate to your SuiteCRM server’s trusted certificates

  • Verify the CalDAV server’s SSL certificate is valid and not expired

  • Ensure the certificate hostname matches the URL you’re using

  • For testing only, you can disable SSL verification in SuiteCRM (not recommended for production)

"Connection timeout" or "Failed to connect"

Causes:

  • CalDAV server is not accessible from SuiteCRM server

  • Firewall blocking outbound connections

  • Incorrect port number

  • Server is down or unreachable

Solutions:

  • Test connectivity from SuiteCRM server: curl -X PROPFIND -u "USERNAME:PASSWORD" https://your-caldav-server/

  • Verify the CalDAV server is running and accessible

  • Check firewall rules allow outbound HTTPS connections

  • Confirm the port number is correct (5232, 443, etc.)

  • If using a local network, ensure SuiteCRM server can reach the internal hostname/IP

Provider Specific Issues

"Authentication required" despite correct credentials

Cause:

Provider requires username as full email address, not just the local part.

Solution:

  • Use full email address as username: john@example.com (not just john)

  • Verify the email address is correct in Calendar Account settings

"Calendar list is empty"

Cause:

No calendars exist in your Providers account, or permissions issue.

Solution:

  • Log into Providers web interface and create a calendar

  • Verify the calendar is not hidden or archived

  • Ensure the calendar is set to "Active"

General Debugging Tips

Enable SuiteCRM Logging

  1. Go to Administration > System Settings

  2. Set Log Level to Info or Debug

  3. Reproduce the connection issue

  4. Review suitecrm.log for entries tagged [CalendarSync] or [CalDAV]

Test CalDAV Access Independently

Use curl from your SuiteCRM server to verify CalDAV connectivity:

# Test CalDAV connectivity with PROPFIND method (replace USERNAME and PASSWORD)
curl -X PROPFIND -u "USERNAME:PASSWORD" https://your-caldav-server/path/to/calendar/

# With depth header to list calendar contents
curl -X PROPFIND -u "USERNAME:PASSWORD" -H "Depth: 1" https://your-caldav-server/path/to/calendar/

# For servers with self-signed certificates, add -k flag
curl -k -X PROPFIND -u "USERNAME:PASSWORD" https://your-caldav-server/path/to/calendar/

Possible responses:

  • 207 Multi-Status - Success, CalDAV is working

  • 401 Unauthorized - Invalid credentials

  • 404 Not Found - Incorrect URL path

Verify URL in Desktop Client

Configure the same CalDAV URL in a desktop calendar client (Thunderbird, macOS Calendar, GNOME Evolution):

  1. If the desktop client connects successfully, the URL is correct

  2. If the desktop client also fails, the issue is with the CalDAV server or URL

  3. Compare the URL format used by the desktop client with your SuiteCRM configuration

Security Best Practices

Use App Passwords

When available, always use app-specific passwords instead of your main account password. For Example, create app passwords in Settings > Security > App Passwords.

App passwords provide:

  • Limited scope (calendar access only)

  • Easy revocation without changing main password

  • Better security audit trail

Prefer HTTPS

Always use HTTPS for CalDAV connections to encrypt credentials and calendar data in transit:

  • Production: HTTPS is mandatory

  • Development/Testing: HTTP on local network only

  • Self-Hosted: Use Let’s Encrypt for free SSL certificates

Restrict CalDAV User Permissions

Grant CalDAV accounts only the necessary permissions:

  • Read/write access to calendars only

  • No admin or file access

  • Limited to specific calendars if possible

Monitor Calendar Account Activity

Regularly review Calendar Accounts in SuiteCRM:

  • Check Last Sync Date for unusual activity

  • Verify Test Successful status periodically

  • Audit active accounts and remove unused ones

Next Steps

Now that you understand CalDAV configuration:

If you encounter persistent CalDAV issues not covered in this guide, check your CalDAV provider’s documentation or contact their support team for provider-specific assistance.

Content is available under GNU Free Documentation License 1.3 or later unless otherwise noted.