Outlook Entra — SKILL.md#

Microsoft Outlook via OAuth 2.0 (device code flow) et Microsoft Graph API. Lecture seule — seules les permissions Mail.Read, Calendars.Read, Contacts.Read sont utilisées.

Prérequis#

• App enregistrée sur Entra (Azure AD) avec permissions :

  • Mail.Read, Calendars.Read, Contacts.Read
  • OAuth 2.0 device code flow activé

• Python 3.8+ avec requests, html2text, cryptography

• Python 3.8+ avec un .venv créé dans le répertoire du skill ( uv venv .venv && uv pip install html2text requests cryptography)

• Fichier .env configuré (voir .env.example)

Installation#

bash

# Créer l'environnement virtuel (obligatoire)
cd ~/.openclaw/workspace/skills/outlook-entra
uv venv .venv
uv pip install html2text requests cryptography

# Copier et éditer la config
cp .env.example .env
# ⚠️ Remplir client_id, client_secret, tenant_id dans .env

Authentification (Flow)#

Le device code flow (RFC 8628) nécessite une intervention utilisateur unique.

Étape 1 — Lancer le script d'auth#

bash

.venv/bin/python scripts/outlook_auth.py

Le script va :

1. Demander un device code à Microsoft
2. Afficher un code utilisateur et une URL de vérification

Étape 2 — S'authentifier#

Aller sur https://login.microsoft.com/device et entrer le code affiché. Délai : 15 minutes maximum.

Étape 3 — Attendre la confirmation#

Le script poll automatiquement le endpoint Microsoft jusqu'à obtention du token. Une fois confirmé, les tokens sont sauvegardés localement.

Fonctionnement des tokens#

• L' access_token expire après ~1h
• Le refresh_token permet d'obtenir un nouvel access_token sans intervention
• Le refresh est automatisé par cron toutes les heures (voir section Cron)
• Si le refresh_token expire aussi (plusieurs mois d'inactivité) → relancer le flow complet

---

Commandes utiles#

bash

# Vérifier le statut du token
.venv/bin/python scripts/outlook_auth.py --status

# Rafraîchir le token manuellement
.venv/bin/python scripts/outlook_refresh.py

# Révoquer et supprimer les tokens
.venv/bin/python scripts/outlook_auth.py --revoke

Commandes (lecture seule)#

bash

# Statut de connexion
.venv/bin/python scripts/outlook_auth.py --status

# Lire les derniers messages
.venv/bin/python scripts/outlook_graph.py messages --folder Inbox --top 10

# Détail d'un message (corps complet, Markdown par défaut)
.venv/bin/python scripts/outlook_graph.py message <messageId>

# Détail en HTML brut (pour extraction/collage)
.venv/bin/python scripts/outlook_graph.py message <messageId> --raw

# Lister les dossiers mail
.venv/bin/python scripts/outlook_graph.py folders

# Pièces jointes d'un message
.venv/bin/python scripts/outlook_graph.py attachments <messageId>

# Télécharger une pièce jointe
.venv/bin/python scripts/outlook_graph.py download <messageId> --attach-id <attachmentId> --output /path/to/file

# Événements calendrier
.venv/bin/python scripts/outlook_graph.py events --top 10

# Contacts
.venv/bin/python scripts/outlook_graph.py contacts --top 20

# Rechercher dans les mails
.venv/bin/python scripts/outlook_graph.py search "mot-clé"

# Profil utilisateur
.venv/bin/python scripts/outlook_graph.py profile

Variables d'environnement (.env)#

VariableDescriptionExempleAZURE_TENANT_IDGUID du tenant Entra52ffb8b9-…``AZURE_CLIENT_IDID de l'app (Application ID)xxxxxxxx-…``AZURE_CLIENT_SECRETSecret de l'app~``AZURE_REDIRECT_URIRedirect URI (device flow : tout fait)http://localhost``OAUTH_TOKEN_URLURL token endpointhttps://login.microsoftonline.com/{tenant}/oauth2/v2.0/token``OAUTH_DEVICE_CODE_URLURL device code endpointhttps://login.microsoftonline.com/{tenant}/oauth2/v2.0/devicecode``MS_GRAPH_BASE_URLBase URL Microsoft Graphhttps://graph.microsoft.com/v1.0``TOKEN_FILEChemin du fichier de stockage des tokens~/.openclaw/outlook_tokens.json``TOKEN_FILE_KEYClé de chiffrement (optionnel)(vide par défaut)

Structure du skill#

text

outlook-entra/
├── SKILL.md
├── README.md
├── .env.example
├── .gitignore
├── .venv/                   # Environnement virtuel Python (créé via uv venv)
├── scripts/
│   ├── outlook_auth.py      # OAuth device code flow + status/revoke
│   ├── outlook_graph.py     # Appels Graph API (lecture seule)
│   ├── outlook_refresh.py   # Refresh token automatisé (pour cron)
│   └── outlook_token.py     # Module partagé (lecture/refresh tokens)
└── tests/
    └── test_outlook.py      # Tests unitaires

Notes#

• Le device code flow (RFC 8628) : l'utilisateur authentifie via https://microsoft.com/devicelogin. Une seule fois.
• Les refresh tokens sont automatiquement utilisés quand l'access token expire.
• Si TOKEN_FILE_KEY est défini, les tokens sont chiffrés AES-GCM avant stockage.
• Les erreurs 401 du Graph API déclenchent un refresh automatique.

Cron — Refresh automatique du token#

Le script outlook_refresh.py vérifie si le token expire bientôt et le rafraîchit automatiquement.

Crontab — refresh toutes les heures à HH:55 :

cron

55 * * * * /home/fred-ghilini/.openclaw/workspace/skills/outlook-entra/.venv/bin/python /home/fred-ghilini/.openclaw/workspace/skills/outlook-entra/scripts/outlook_refresh.py >> /home/fred-ghilini/.openclaw/outlook_refresh.log 2>&1

Installation :

bash

SKILL_DIR="/home/fred-ghilini/.openclaw/workspace/skills/outlook-entra"
( crontab -l 2>/dev/null | grep -v outlook_refresh; echo "55 * * * * ${SKILL_DIR}/.venv/bin/python ${SKILL_DIR}/scripts/outlook_refresh.py >> ~/.openclaw/outlook_refresh.log 2>&1" ) | crontab -

Vérification :

bash

crontab -l | grep outlook_refresh

Ressources#

• OAuth 2.0 Device Code Flow — Microsoft
• Microsoft Graph — Mail API
• Microsoft Graph — Calendar API