Guide d'implémentation d'OAuth 2.1

Ce guide explique comment autoriser de manière sécurisée la plate-forme Connected Apps à accéder à vos services. Pour les intégrations MCP d'applications connectées, nous vous recommandons vivement d'utiliser OAuth 2.1, la norme du secteur pour l'autorisation déléguée, avec clé de vérification pour l'échange de code (PKCE) afin de garantir une sécurité maximale des données utilisateur et une fiabilité optimale dans les flux "agentiques". La plate-forme Connected Apps est compatible avec le type d'autorisation par code d'autorisation avec les paramètres de clé de vérification pour l'échange de code (PKCE).

PKCE est obligatoire pour toutes les requêtes OAuth 2.1 et facultatif pour OAuth 2.0.

Pour activer la découverte automatique et simplifier le processus d'intégration, votre serveur d'autorisation doit être compatible avec l'extension de métadonnées du serveur d'autorisation, également appelée "découverte OAuth".

Comment Gemini MCP récupère le fichier JSON de configuration

La console Gemini MCP tente de récupérer votre fichier JSON de configuration à partir des URL suivantes, dans l'ordre indiqué dans cette section.

Si l'URL de votre serveur d'autorisation se trouve au niveau supérieur de votre domaine (par exemple, https://auth.example.com), Gemini ajoute des répertoires "bien connus" standards à votre domaine et recherche le serveur dans l'ordre suivant :

  1. https://auth.example.com/.well-known/oauth-authorization-server
  2. https://auth.example.com/.well-known/openid-configuration

Si l'URL de votre serveur d'autorisation se trouve dans un sous-répertoire ou un chemin d'accès spécifique de votre domaine, par exemple https://auth.example.com/realms/master, Gemini ajoute les mêmes chemins d'accès "well-known" directement à ce sous-répertoire, dans l'ordre suivant.

  1. .../realms/master/.well-known/oauth-authorization-server
  2. .../realms/master/.well-known/openid-configuration
  3. .../realms/master/.well-known/openid-configuration (compatibilité avec les chemins d'accès imbriqués)

Fonctionnalités JSON requises

Votre réponse de métadonnées doit inclure les champs suivants. L'intégration échoue si des champs obligatoires sont manquants ou si aucun type valide n'est trouvé.

authorization_endpoint
Doit être une URL de chaîne valide.
token_endpoint
Doit être une URL de chaîne valide.
response_types_supported
Doit contenir la chaîne code.
registration_endpoint

Pour l'instant, la Play Console s'appuie sur Dynamic Client.

Enregistrement (RFC 7591). Vous devez fournir un point de terminaison d'enregistrement dans vos métadonnées ou saisir l'ID client/le code secret directement dans l'interface utilisateur de la Play Console.

Si votre serveur d'autorisation n'est pas compatible avec l'enregistrement dynamique des clients, vous devez implémenter et renseigner manuellement les champs ID client et Code secret du client dans l'interface utilisateur de la Play Console pour finaliser l'intégration.

Si votre implémentation est compatible avec la clé de vérification pour l'échange de code (PKCE) ou les sessions persistantes, vous devez inclure les champs de capacité pertinents (tels que Challenge Methods et Grant Types) dans votre fichier JSON de découverte. Cela permet de garantir la compatibilité avec les normes de sécurité et de connectivité de Gemini. Si vous acceptez le champ d'application, vous devez inclure le champ scopes_supported.

Exemple de configuration

Voici une réponse JSON valide qui répond aux exigences de notre client.

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

Si vous incluez PKCE, l'extrait suivant montre un exemple de ce qui pourrait être inclus dans le bloc JSON.

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

Si vous incluez le champ scopes_supported, l'extrait suivant montre un exemple de ce qui pourrait être inclus dans le bloc JSON.

"scopes_supported": ["mcp", "cart.order"],

Flux avec code d'autorisation (version simplifiée)

Les étapes suivantes décrivent le flux de code d'autorisation standard. Cette séquence illustre exactement comment la plate-forme d'applications connectées obtient de manière sécurisée les jetons d'accès nécessaires auprès de votre serveur pour agir au nom d'un utilisateur.

  1. Demande d'autorisation : la surface Google détermine qu'elle doit appeler votre fonction, mais l'utilisateur n'est pas encore autorisé. Le chatbot lance le flux en redirigeant le navigateur de l'utilisateur (ou en affichant un lien) vers votre point de terminaison d'autorisation.

    Cette requête inclut votre ID client (ou généré automatiquement avec DCR), l'URI de redirection Gemini et les paramètres PKCE critiques (code_challenge et code_challenge_method).

    Ajoutez les URL suivantes à la liste d'autorisation pour la configuration d'OAuth :

    • https://oauth-redirect.googleusercontent.com/r/*
    • https://oauth-redirect-sandbox.googleusercontent.com/r/*
    • https://oauth-redirect-test.googleusercontent.com/r/*
    • https://oauth-redirect.googleusercontent.com/a/*
    • https://oauth-redirect-sandbox.googleusercontent.com/a/*
    • https://oauth-redirect-test.googleusercontent.com/a/*

  2. Consentement utilisateur : votre serveur d'autorisation valide la requête, authentifie l'utilisateur (connexion) et lui demande d'autoriser la surface Google à accéder à ses données ou à son service.

  3. Octroi de code : une fois que l'utilisateur a donné son consentement, votre serveur redirige le navigateur de l'utilisateur vers l'URI de redirection de Gemini, en ajoutant un code d'autorisation temporaire à l'URL.

  4. Échange de jetons : le backend derrière Gemini envoie une requête POST à votre point de terminaison de jeton, en échangeant le code d'autorisation contre un jeton d'accès.

  5. Accès accordé : votre point de terminaison de jeton vérifie le code et les paramètres PKCE, émet un jeton d'accès et, éventuellement, un jeton d'actualisation, puis les renvoie à Gemini.

Principales exigences de PKCE

PKCE ajoute une couche de sécurité pour empêcher l'interception non autorisée des codes d'autorisation.

  • code_verifier : chaîne aléatoire générée de manière cryptographique par Gemini au début du flux. Ces informations restent privées.
  • code_challenge : transformation de code_verifier, généralement le hachage SHA256. Il est envoyé publiquement, comme décrit à l'étape 1 du flux avec code d'autorisation.
  • Validation : votre point de terminaison de jeton (décrit à l'étape 4 du flux avec code d'autorisation) doit valider que le code_verifier reçu, une fois transformé, correspond au code_challenge d'origine.

Débogage

Des informations détaillées sur les erreurs d'association sont disponibles dans l'explorateur de journaux. Pour activer et afficher les erreurs, suivez les instructions de la section Surveiller les erreurs d'association de comptes dans votre projet de la console Google.

Exigences de configuration pour l'association de comptes Google

Pour en savoir plus sur la configuration de l'association de comptes Google, consultez les consignes suivantes concernant l'API.

Pour enregistrer votre intégration OAuth, vous devez configurer des détails spécifiques sur votre serveur d'autorisation. Assurez-vous d'avoir préparé les points de terminaison, les identifiants et les éléments suivants.

Champ de configuration

Description

Responsabilité du développeur

ID client et code secret du client

Identifiants uniques générés par votre serveur d'autorisation spécifiquement pour la plate-forme Connected Apps. Le code secret du client est l'identifiant de sécurité (mot de passe) associé à l'ID client.

Remarque : Si le développeur a émis l'ID client, il doit le fournir. Si Google a émis l'ID client, le développeur devra peut-être enregistrer ou valider un code secret.

Utilisez l'ID fourni par la plate-forme dans toutes les demandes d'autorisation.

Point de terminaison d'autorisation

URL vers laquelle rediriger les utilisateurs pour qu'ils s'authentifient et accordent leur autorisation

Hébergez le point de terminaison, par exemple https://yourdomain.com/oauth/authorize.

Point de terminaison du jeton

Point de terminaison du backend permettant d'échanger des codes d'autorisation contre des jetons d'accès/d'actualisation et d'actualiser les jetons arrivés à expiration.

Hébergez ce point de terminaison (par exemple, https://yourdomain.com/oauth/token).

Point de terminaison de révocation
Facultatif

URL permettant d'indiquer à votre système d'invalider un jeton lorsqu'un utilisateur se déconnecte.

Lorsqu'un utilisateur dissocie ou déconnecte votre intégration de la plate-forme Connected Apps, nous envoyons une requête POST au point de terminaison /revoke contenant le jeton d'accès ou d'actualisation.

Pour en savoir plus, consultez Dissocier des comptes.

Hébergez le point de terminaison, par exemple https://yourdomain.com/oauth/revoke.

Votre serveur doit traiter cette requête en invalidant définitivement le jeton fourni. Cela garantit que toute tentative ultérieure de la plate-forme d'applications connectées d'utiliser ce jeton échouera, ce qui protège les données de l'utilisateur après la déconnexion.

URI de redirection

URL de rappel spécifique fournie par la plate-forme vers laquelle le serveur d'autorisation renvoie le code après le consentement.

Configurez votre serveur d'autorisation pour qu'il n'accepte que l'URI de redirection officiel enregistré de la plate-forme.

Actualiser

/token avec grant_type=refresh_token

Mécanisme qui permet à la plate-forme d'applications connectées d'obtenir un nouveau jeton d'accès lorsque le jeton actuel expire, ce qui permet de maintenir l'intégration connectée de manière fluide sans que l'utilisateur ait à se connecter à plusieurs reprises.

Lorsqu'un jeton d'accès existant expire, la plate-forme Connected Apps envoie automatiquement une requête POST à votre point de terminaison /token. La charge utile de la requête inclura grant_type=refresh_token ainsi que le jeton d'actualisation précédemment émis par votre serveur.

Votre serveur doit valider le jeton d'actualisation fourni et renvoyer un nouveau jeton d'accès dans la réponse JSON. De plus, pour implémenter l'association persistante, vous devez éviter d'effectuer une rotation du jeton d'actualisation pendant cet échange. Au lieu d'en émettre un nouveau, renvoyez exactement le même jeton d'actualisation dans la réponse JSON et prolongez sa date d'expiration sur votre backend.

Type de réponse

Ce paramètre doit être défini sur CODE pour prendre en charge le flux avec code d'autorisation.

Champs d'application

Ensemble d'autorisations et de niveaux d'accès spécifiques qui définissent ce que le jeton est autorisé à faire. Ils doivent être prédéfinis dans votre configuration afin que Google puisse les demander lors de l'établissement de la liaison d'autorisation initiale.

Vous devrez fournir une liste de champs d'application par défaut (par exemple, openid, profile, email) que la plate-forme Connected Apps devra demander lors du lancement du flux.

Les champs d'application demandés doivent être aussi réduits que possible (principe du moindre privilège), mais entièrement suffisants pour les parcours utilisateur critiques (CUJ) pris en charge par votre intégration MCP.

UI Assets: Logo

Logo du développeur à afficher sur les écrans d'association de comptes et de consentement.

Il doit s'agir d'une image vectorielle (SVG) carrée d'au moins 500 x 500 pixels, avec une apparence circulaire. Par exemple, consultez https://[partner-domain]/assets/logo.svg ou le fichier SVG brut.

Association d'applications natives (App Flip)

Pour permettre l'association de comptes directement depuis vos applications Android ou iOS natives, nous vous déconseillons vivement d'utiliser des WebViews standards. À la place, nous vous recommandons vivement d'implémenter App Flip pour offrir une expérience utilisateur fluide.

Pour en savoir plus, consultez Association du compte Google avec App Flip basé sur OAuth.

Effectuez la validation sur le Play Store et l'App Store, et intégrez les URI de redirection de Google directement dans vos applications natives pour garantir un basculement d'autorisation sécurisé d'application à application.

Durée de vie des jetons

(Facultatif) Durée de validité d'un jeton d'accès avant qu'une actualisation ne soit requise. Utile pour configurer des règles de délai avant expiration dans GAL.

Les délais d'expiration courants vont de quelques minutes à quelques heures ou jours, selon les besoins de sécurité (par exemple, 30 days).

Erreurs d'intégration courantes

Voici une liste des erreurs courantes et des solutions potentielles applicables au processus d'intégration.

  • Autorisation "code" manquante : le système automatisé de la plate-forme Gemini vérifie explicitement la présence de la valeur "code" dans response_types_supported.
  • Point de terminaison d'enregistrement manquant : même si votre serveur est compatible avec les documents de métadonnées d'ID client, l'application Gemini (qui agit en tant que client OAuth se connectant à votre serveur) nécessite actuellement la présence d'un registration_endpoint dédié dans le fichier JSON de découverte.
  • Erreur non-200 : si le mécanisme de découverte automatique des métadonnées de Gemini accède à votre URL well-known et reçoit une erreur 404 ou 500, il ne tentera pas de deviner d'autres URL. Veuillez vous assurer que l'URL de découverte est accessible publiquement.