Version de développement

Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.

Intégrations

Connexion Google via OAuth (Application Connectée)

Configurer une Application Connectée pour accéder aux API Google avec un accès hors ligne durable, et résoudre les erreurs de renouvellement de jeton.

Connexion Google via OAuth — Application Connectée

Cette page décrit la configuration d'une Application Connectée (Connected App) pour s'authentifier auprès des services Google via OAuth 2.0, notamment pour les comptes e-mail Gmail.

Cette méthode est distincte des Paramètres Google (Agenda, Drive, Contacts). Elle est utilisée par exemple pour connecter un compte Gmail via IMAP/SMTP avec OAuth, ou pour appeler une API Google personnalisée depuis un script.

Pourquoi une configuration spécifique pour Google ?

Google impose des conditions particulières pour délivrer un jeton de rafraîchissement (refresh_token) :

Le paramètre access_type=offline doit être présent dans l'URL d'autorisation.
Le paramètre prompt=consent doit forcer l'affichage de l'écran de consentement.

Sans ces deux paramètres, Google ne fournit qu'un jeton d'accès valable ~1 heure, sans possibilité de le renouveler automatiquement. Le compte se retrouve alors bloqué après expiration, avec un message « Veuillez autoriser OAuth ».

Depuis la version incluant ce correctif, Dodock ajoute automatiquement ces paramètres lorsque l'URI d'autorisation contient accounts.google.com.

Prérequis : créer un client OAuth sur Google Cloud

Rendez-vous sur https://console.cloud.google.com/.
Utilisez un projet existant ou créez-en un nouveau.
Dans API et services, cliquez sur Identifiants.
Cliquez sur Créer des identifiants → ID client OAuth.
Choisissez le type Application Web.

Dans URI de redirection autorisés, ajoutez :

https://{votresite}/api/method/frappe.integrations.doctype.connected_app.connected_app.oauth2_callback

Enregistrez et notez le Client ID et le Client Secret.

Créer l'Application Connectée dans Dodock

Accueil > Intégrations > Application Connectée

Cliquez sur Nouvelle Application Connectée.
Renseignez les champs suivants :

Champ	Valeur pour Google
Fournisseur	`google` (ou tout nom explicite)
URI d'autorisation	`https://accounts.google.com/o/oauth2/auth`
URI de jeton	`https://oauth2.googleapis.com/token`
Client ID	Valeur copiée depuis Google Cloud
Client Secret	Valeur copiée depuis Google Cloud
Périmètre (Scopes)	Selon l'usage (ex. `https://mail.google.com/` pour Gmail)

Enregistrez le document.

Dodock détecte automatiquement que l'URI contient accounts.google.com et ajoute access_type=offline et prompt=consent à l'URL d'autorisation. Vous n'avez pas à les saisir manuellement dans la table des paramètres.

Autoriser l'accès (flux d'autorisation)

Après enregistrement, vous devez autoriser l'accès une première fois pour que Google émette un refresh_token :

Ouvrez l'Application Connectée.
Cliquez sur le bouton Autoriser l'accès (ou accédez à l'URL générée).
Connectez-vous avec le compte Google souhaité.
Acceptez les autorisations demandées — l'écran de consentement doit s'afficher (grâce à prompt=consent).
Vous êtes redirigé vers Dodock ; le Cache de jeton est créé avec un refresh_token valide.

      
sequenceDiagram
    participant U as Utilisateur
    participant D as Dodock
    participant G as Google OAuth

Renouvellement automatique du jeton

Une fois autorisé, Dodock renouvelle le jeton d'accès automatiquement :

      
sequenceDiagram
    participant D as Dodock
    participant G as Google OAuth

Si le refresh_token est absent du cache (comptes configurés avant ce correctif), Dodock affiche désormais un message clair :

« Ce jeton est expiré et ne dispose pas de jeton de rafraîchissement. Veuillez ré-autoriser avec un accès hors ligne. »

Cela indique qu'une nouvelle autorisation est requise (voir section suivante).

Ré-autoriser un compte existant

Si votre compte Gmail (ou autre service Google) rencontrait des erreurs périodiques d'autorisation avant ce correctif, vous devez effectuer une ré-autorisation unique :

Ouvrez l'Application Connectée concernée.
Enregistrez le document (ce qui déclenche l'ajout automatique de access_type=offline).
Cliquez sur Autoriser l'accès et suivez le flux de consentement Google.
Vérifiez que le Cache de jeton associé contient bien un refresh_token.

Cette ré-autorisation unique est nécessaire même si le code a été mis à jour. Sans elle, Google ne peut pas émettre de nouveau refresh_token pour les sessions existantes.

Vérifier le Cache de jeton

Accueil > Intégrations > Cache de jeton

Le Cache de jeton stocke les jetons OAuth associés à chaque Application Connectée. Vous pouvez y vérifier :

La présence d'un Jeton de rafraîchissement (non vide = configuration correcte).
La date d'expiration du jeton d'accès en cours.

Le refresh_token n'est jamais écrasé par un renouvellement normal (Google ne le renvoie pas à chaque rafraîchissement). Dodock le préserve automatiquement.

Résolution des problèmes courants

Symptôme	Cause probable	Action
« Veuillez autoriser OAuth » répété	Pas de `refresh_token` stocké	Ré-autoriser via l'Application Connectée
« Ré-autoriser avec un accès hors ligne »	`refresh_token` absent du cache après expiration	Ré-autoriser (voir section ci-dessus)
Erreur Google `invalid_request: Missing required parameter: refresh_token`	Ancienne configuration sans `access_type=offline`	Enregistrer l'Application Connectée puis ré-autoriser
Le compte fonctionne pendant ~1h puis échoue	Idem	Idem