diff --git a/Guide-CalDAV.-.md b/Guide-CalDAV.-.md new file mode 100644 index 0000000..6127ac8 --- /dev/null +++ b/Guide-CalDAV.-.md @@ -0,0 +1,172 @@ +# Guide-CalDAV + +Ce guide pratique vous accompagne dans la configuration des variables CalDAV pour synchroniser l'agenda **Pronote** vers un calendrier compatible CalDAV. +Pour consulter le tableau complet des variables disponibles, reportez-vous à la page [Configuration](Configuration). + +--- + +## Choisir un serveur CalDAV + +Plusieurs solutions existent pour héberger un serveur CalDAV. Voici les trois options principales, adaptées à différents besoins : + +- **Nextcloud / ownCloud** : Solution cloud auto-hébergée complète, avec un module calendrier intégré. Idéal pour une utilisation personnelle ou familiale. +- **Radicale** : Serveur CalDAV léger et minimaliste, parfait pour un auto-hébergement simple et performant. +- **Baïkal** : Serveur dédié CalDAV/CardDAV, conçu pour une intégration facile et une gestion centralisée des calendriers et contacts. + +--- + +## Nextcloud / ownCloud + +### Trouver l'URL CalDAV + +1. Connectez-vous à l'interface web de votre instance Nextcloud/ownCloud. +2. Ouvrez l'application **Calendrier** depuis le tableau de bord. +3. Dans le coin inférieur gauche de la barre latérale, cliquez sur l'icône **Réglages** (engrenage). +4. À côté du calendrier de votre choix, cliquez sur le menu **trois points (`...`)** puis sélectionnez **Copier le lien privé** ou **Copier le lien d'abonnement**. +5. Pour obtenir l'URL racine, descendez dans les réglages globaux (en bas de la page) et cherchez **Copier l'adresse CalDAV principale**. + +### Format d'URL + +- **URL de base (principale)** : + ```text + https:///remote.php/dav/principals/users// + ``` +- **URL d'un calendrier spécifique** : + ```text + https:///remote.php/dav/calendars/// + ``` + +> **Remarque** : `` correspond à votre identifiant Nextcloud, et `` est le nom technique du calendrier (ex. `personal`, `work`). + +### Créer un mot de passe d'application + +Si votre instance utilise une **authentification à deux facteurs (2FA)**, les mots de passe d'application sont **obligatoires** pour les connexions CalDAV. + +1. Cliquez sur votre **avatar utilisateur** (en haut à droite) puis sélectionnez **Paramètres personnels** (ou **Réglages**). +2. Dans la barre latérale gauche, sous la section *Personnel*, cliquez sur **Sécurité**. +3. Descendez jusqu'à la section **Appareils et sessions** ou **Mots de passe d'application**. +4. Saisissez un nom pour l'application (ex. `pronote-sync`) puis cliquez sur **Créer un nouveau mot de passe d'application**. +5. Nextcloud affiche alors votre **nom d'utilisateur** et un **jeton généré** (à usage unique). **Conservez ce jeton précieusement** : il servira de mot de passe pour la variable `CALDAV_PASSWORD`. + +--- + +## Radicale + +### Format d'URL + +- **URL de base** (accès racine) : + ```text + http://:5232/ + ``` + ou, si configuré derrière un reverse proxy avec HTTPS : + ```text + https:/// + ``` +- **URL d'un calendrier** : + ```text + http://:5232/// + ``` + +### Créer un calendrier + +Avec Radicale, les calendriers sont **créés automatiquement** à la première écriture par un client CalDAV compatible. Vous pouvez également les gérer manuellement via l'interface web si celle-ci est activée. + +### Identifiants + +Les identifiants sont configurés dans le fichier de configuration de Radicale, généralement sous la section `[auth]`. Par défaut, Radicale utilise souvent une authentification de type `htpasswd` (fichier Apache). + +Pour créer un utilisateur, utilisez la commande suivante : + +```bash +htpasswd -Bc /chemin/vers/users.htpasswd +``` + +> **Exemple** : +> ```bash +> htpasswd -Bc /etc/radicale/users.htpasswd pronote-sync +> ``` +> Vous serez invité à saisir un mot de passe pour l'utilisateur ``. + +--- + +## Baïkal + +### Format d'URL + +- **Point d'accès DAV** (racine) : + ```text + https:///dav.php + ``` +- **URL principale de l'utilisateur** : + ```text + https:///dav.php/principals// + ``` +- **URL d'un calendrier** : + ```text + https:///dav.php/calendars/// + ``` + +### Administration + +1. Accédez à l'interface d'administration de Baïkal à l'URL : + ```text + https:///admin/ + ``` +2. Rendez-vous dans la section **Users and address books** → **Users** → **Add User** pour créer un nouvel utilisateur. +3. Les calendriers peuvent être gérés sous **Users** → **Calendars** ou créés automatiquement par les clients CalDAV. + +--- + +## Distinction entre URL du serveur et chemin du calendrier + +Il est important de bien comprendre la différence entre ces deux variables pour une configuration correcte : + +- **`CALDAV_URL`** : + Il s'agit de l'**URL racine du serveur CalDAV** ou du **point d'accès de découverte** (ex. `https://cloud.example.com/remote.php/dav`). + Cette URL permet au client de découvrir les capacités du serveur et les collections disponibles. + +- **`CALDAV_CALENDAR_PATH`** : + Il s'agit du **chemin spécifique** identifiant la **collection de calendrier** où les événements (`VEVENT`) seront écrits. + Par exemple : `/remote.php/dav/calendars/john/personal/`. + +> **Astuce** : La plupart des serveurs CalDAV exposent l'**URL complète du calendrier** dans leur interface web, via un menu de partage ou de réglages (ex. « Copier l'URL CalDAV » ou « Copier le lien privé »). +> Vous pouvez extraire `CALDAV_URL` et `CALDAV_CALENDAR_PATH` à partir de cette URL complète. + +--- + +## Sécurité : HTTPS obligatoire + +Pour protéger vos identifiants et vos données en transit, les règles suivantes s'appliquent : + +- **HTTPS est obligatoire** par défaut pour la variable `CALDAV_URL`. +- **HTTP n'est toléré que pour les hôtes locaux** (`localhost`, `127.0.0.1`, `::1`) et **uniquement** si la variable `CALDAV_ALLOW_INSECURE_HTTP=true` est définie. +- Cette mesure garantit que vos identifiants ne sont pas transmis en clair sur le réseau. +- La variable `CALDAV_URL` est stockée sous forme de `SecretStr` et **masquée dans les logs** pour éviter toute fuite accidentelle. + +--- + +## Exemple de configuration + +Voici des exemples de configuration pour les serveurs présentés ci-dessus : + +```ini +# Exemple pour Nextcloud +CALDAV_URL=https://cloud.example.com/remote.php/dav +CALDAV_USERNAME=pronote-sync +CALDAV_PASSWORD=mot_de_passe_application +CALDAV_CALENDAR_PATH=/pronote-sync/ +``` + +```ini +# Exemple pour Radicale en local (développement uniquement) +# CALDAV_URL=http://localhost:5232 +# CALDAV_USERNAME=user +# CALDAV_PASSWORD=mot_de_passe +# CALDAV_CALENDAR_PATH=/user/pronote/ +# CALDAV_ALLOW_INSECURE_HTTP=true +``` + +--- + +→ [Configuration](Configuration) — tableau des variables +→ [Sécurité](Sécurité) — gestion des secrets \ No newline at end of file