Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Association de comptes Google avec OAuth

Les comptes sont associés à l'aide du flux de code d'autorisation OAuth 2.0, qui est une norme du secteur.

OAuth 2.1 et PKCE pour les agents

Pour les agents d'IA sans état et les pipelines multimodaux, l'application d'OAuth 2.1 est recommandée.

PKCE (Proof Key for Code Exchange) : doit être utilisé pour sécuriser le flux avec code d'autorisation et éviter les attaques par interception.
Pas de flux implicite : le flux implicite expose les jetons d'accès dans l'URL, ce qui constitue un risque de sécurité pour les environnements d'agent.

Votre service doit être compatible avec les points de terminaison d'autorisation et d'échange de jetons conformes à OAuth 2.0/2.1.

创建项目

如需创建项目以使用账号关联，请执行以下操作：

前往 Google API 控制台。
点击 Create project 。
输入名称或接受生成的建议。
确认或修改任何剩余字段。
点击创建。

如需查看项目 ID，请执行以下操作：

前往 Google API 控制台。
在着陆页的表格中找到您的项目。项目 ID 会显示在 ID 列中。

配置 OAuth 权限请求页面

Google 账号关联过程包含一个权限请求页面，该页面会告知用户请求访问其数据的应用、应用请求的数据类型以及适用的条款。您需要先配置 OAuth 权限请求页面，然后才能生成 Google API 客户端 ID。

打开 Google API 控制台的 OAuth 权限请求页面页面。
如果系统提示您选择项目，请选择您刚刚创建的项目。
在“OAuth 权限请求页面”上，填写表单，然后点击“保存”按钮。

应用名称 ：向用户征求同意的应用的名称。该名称应准确反映您的应用，并且与用户在其他位置看到的应用名称保持一致。应用名称将显示在账号关联权限请求页面上。

应用徽标：权限请求页面上显示的一张图片，用以让用户认出您的应用。徽标会显示在账号关联权限请求页面和账号设置中

支持邮箱 ：用户用于针对其同意问题与您联系的邮箱。

Google API 的范围 ：范围允许您的应用访问用户的私有 Google 数据。对于 Google 账号关联用例，默认范围（邮箱、个人资料、openid）就足够了，您无需添加任何敏感范围。通常，最佳做法是在需要访问权限时逐步请求范围，而不是提前请求。了解详情。

已获授权的网域 ：为了保护您和您的用户，Google 只允许使用 OAuth 进行身份验证的应用使用已获授权的网域。您应用的链接必须托管在已获授权的网域上。了解详情。

应用首页链接 ：应用的首页。必须托管在已获授权的网域上。

应用隐私权政策链接 ：显示在 Google 账号关联权限请求页面上。必须托管在已获授权的网域上。

应用服务条款链接（可选） ：必须托管在已获授权的网域上。

图 1. 虚构应用 Tunery 的 Google 账号关联权限请求页面
查看“验证状态”，如果您的应用需要验证，请点击“提交以进行验证”按钮，提交应用以进行验证。如需了解详情，请参阅 OAuth 验证要求。

Implémenter votre serveur OAuth

Une implémentation de serveur OAuth 2.0 du flux de code d'autorisation se compose de deux points de terminaison que votre service met à disposition par HTTPS. Le premier point de terminaison est le point de terminaison d'autorisation, qui est chargé de trouver ou d'obtenir le consentement des utilisateurs pour l'accès aux données. Le point de terminaison d'autorisation présente une interface utilisateur de connexion à vos utilisateurs qui ne sont pas encore connectés et enregistre le consentement à l'accès demandé. Le deuxième point de terminaison est le point de terminaison d'échange de jetons, qui est utilisé pour obtenir des chaînes chiffrées, appelées jetons, qui autorisent un utilisateur à accéder à votre service.

Lorsqu'une application Google doit appeler l'une des API de votre service, Google utilise ces points de terminaison ensemble pour obtenir l'autorisation de vos utilisateurs d'appeler ces API en leur nom.

Association de compte Google : flux avec code d'autorisation OAuth

Le diagramme de séquence suivant détaille les interactions entre l'utilisateur, Google et les points de terminaison de votre service.

Figure 1. Séquence d'événements dans le flux avec code d'autorisation OAuth 2.0 pour l'association du compte Google.

Rôles et responsabilités

Le tableau suivant définit les rôles et les responsabilités des acteurs du flux OAuth d'association de compte Google (GAL). Notez que dans GAL, Google agit en tant que client OAuth, tandis que votre service agit en tant que fournisseur d'identité/de services.

Acteur / Composant	Rôle dans la LAG	Responsabilités
Application / Serveur Google	Client OAuth	Lance le flux, reçoit le code d'autorisation, l'échange contre des jetons et les stocke de manière sécurisée pour accéder aux API de votre service.
Votre point de terminaison d'autorisation	Serveur d'autorisation	Authentifie vos utilisateurs et obtient leur consentement pour partager l'accès à leurs données avec Google.
Votre point de terminaison d'échange de jetons	Serveur d'autorisation	Valide les codes d'autorisation et les jetons d'actualisation, et émet des jetons d'accès au serveur Google.
URI de redirection Google	Point de terminaison de rappel	Reçoit la redirection de l'utilisateur depuis votre service d'autorisation avec les valeurs `code` et `state`.

Une session de flux avec code d'autorisation OAuth 2.0 initiée par Google se déroule comme suit :

Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. Si le flux a commencé sur un appareil vocal uniquement pour une Action, Google transfère l'exécution vers un téléphone.
L'utilisateur se connecte, s'il ne l'a pas déjà fait, et autorise Google à accéder à ses données avec votre API, s'il ne l'a pas déjà fait.
Votre service crée un code d'autorisation et le renvoie à Google. Pour ce faire, redirigez le navigateur de l'utilisateur vers Google en joignant le code d'autorisation à la requête.
Google envoie le code d'autorisation à votre point de terminaison d'échange de jetons, qui vérifie l'authenticité du code et renvoie un jeton d'accès et un jeton d'actualisation. Le jeton d'accès est un jeton de courte durée que votre service accepte comme identifiant pour accéder aux API. Le jeton d'actualisation est un jeton à longue durée de vie que Google peut stocker et utiliser pour acquérir de nouveaux jetons d'accès lorsqu'ils expirent.
Une fois que l'utilisateur a terminé le parcours d'association de compte, chaque requête ultérieure envoyée par Google contient un jeton d'accès.

Recette d'implémentation

Suivez ces étapes pour implémenter le flux avec code d'autorisation.

Étape 1 : Gérez les demandes d'autorisation

Lorsque Google lance l'association de compte, il redirige l'utilisateur vers votre point de terminaison d'autorisation. Pour en savoir plus sur les contrats de protocole et les exigences concernant les paramètres, consultez Point de terminaison d'autorisation.

Pour traiter la demande, procédez comme suit :

Validez la demande :
- Vérifiez que client_id correspond à l'ID client attribué à Google.
- Vérifiez que redirect_uri correspond à l'URL de redirection Google attendue : none https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
- Vérifiez que response_type est défini sur code.
Authentifiez l'utilisateur :
- Vérifiez si l'utilisateur est connecté à votre service.
- Si l'utilisateur n'est pas connecté, invitez-le à suivre votre procédure de connexion ou d'inscription.
Générez un code d'autorisation :
- Créez un code d'autorisation unique et difficile à deviner, associé à l'utilisateur et au client.
- Définissez le code pour qu'il expire dans environ 10 minutes.
Rediriger vers Google :
- Redirigez le navigateur vers l'URL fournie dans redirect_uri.
- Ajoutez les paramètres de requête suivants :
  - code : code d'autorisation que vous avez généré.
  - state : valeur d'état non modifiée reçue de Google.

Étape 2 : Gérez les demandes d'échange de jetons

Votre point de terminaison d'échange de jetons traite deux types de requêtes : l'échange de codes contre des jetons et l'actualisation des jetons d'accès expirés. Pour connaître les contrats de protocole détaillés et les exigences concernant les paramètres, consultez Point de terminaison d'échange de jetons.

A. Échanger des codes d'autorisation contre des jetons

Lorsque Google reçoit le code d'autorisation, il appelle votre point de terminaison d'échange de jetons (POST) pour récupérer les jetons.

Validez la demande :
- Validez client_id et client_secret.
- Vérifiez que le code d'autorisation est valide et qu'il n'a pas expiré.
- Vérifiez que redirect_uri correspond à la valeur utilisée à l'étape 1.
- Si la validation échoue, renvoyez un code HTTP 400 Bad Request avec {"error": "invalid_grant"}.
Émettre des jetons :
- Générez un refresh_token à longue durée de vie et un access_token à courte durée de vie (généralement une heure).
- Renvoyez un HTTP 200 OK avec la réponse standard du jeton JSON.

B. Actualiser les jetons d'accès

Lorsque le jeton d'accès expire, Google en demande un nouveau à l'aide du jeton d'actualisation.

Validez la demande :
- Validez client_id, client_secret et refresh_token.
- Si la validation échoue, renvoyez un code HTTP 400 Bad Request avec {"error": "invalid_grant"}.
Émettre un jeton d'accès :
- Générez un access_token éphémère.
- Renvoyez un 200 OK HTTP avec la réponse du jeton JSON (en incluant éventuellement un nouveau jeton d'actualisation).

Gérer les requêtes userinfo

Le point de terminaison userinfo est une ressource protégée par OAuth 2.0 qui renvoie les revendications concernant l'utilisateur associé. L'implémentation et l'hébergement du point de terminaison userinfo sont facultatifs, sauf dans les cas d'utilisation suivants:

Connexion à un compte associé avec Google One Tap.
Abonnement simplifié sur Android TV.

Une fois que le jeton d'accès a été récupéré avec succès à partir du point de terminaison de votre jeton, Google envoie une demande à ce point de terminaison pour récupérer les informations de base du profil sur l'utilisateur associé.

En-têtes de requête du point de terminaison userinfo
`Authorization header`	Jeton d'accès de type Bearer.

Par exemple, si votre point de terminaison userinfo est disponible à l'adresse https://myservice.example.com/userinfo, une requête peut se présenter comme suit:

GET /userinfo HTTP/1.1
Host: myservice.example.com
Authorization: Bearer ACCESS_TOKEN

Pour que votre point de terminaison userinfo traite les requêtes, procédez comme suit:

Extrayez le jeton d'accès de l'en-tête "Authorization" et renvoyez les informations concernant l'utilisateur associé au jeton d'accès.
Si le jeton d'accès n'est pas valide, renvoyez une erreur HTTP 401 Opération non autorisée à l'aide de l'en-tête de réponse WWW-Authenticate. Voici un exemple de réponse d'erreur userinfo:
```
HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
```
Si une erreur 401 (autorisation non autorisée) ou toute autre erreur est renvoyée pendant le processus d'association, l'erreur ne pourra pas être récupérée, le jeton récupéré sera supprimé et l'utilisateur devra recommencer le processus d'association.

Si le jeton d'accès est valide, renvoyez une réponse HTTP 200 avec l'objet JSON suivant dans le corps de la requête réponse:

{
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}

Si votre point de terminaison userinfo renvoie une réponse de réussite HTTP 200, le jeton et les revendications récupérés sont enregistrés sur le compte Google de l'utilisateur.

Réponse du point de terminaison userinfo
`sub`	Identifiant unique qui identifie l'utilisateur dans votre système.
`email`	Adresse e-mail de l'utilisateur.
`given_name`	Facultatif:prénom de l'utilisateur.
`family_name`	Facultatif:nom de l'utilisateur.
`name`	Facultatif:nom complet de l'utilisateur.
`picture`	Facultatif:photo de profil de l'utilisateur.

Valider votre implémentation

Vous pouvez valider votre implémentation à l'aide de l' outil OAuth 2.0 Playground.

Dans l'outil, procédez comme suit :

Cliquez sur Configuration pour ouvrir la fenêtre de configuration OAuth 2.0.
Dans le champ OAuth flow (Flux OAuth), sélectionnez Client-side (Côté client).
Dans le champ OAuth Endpoints (Points de terminaison OAuth), sélectionnez Custom (Personnalisé).
Spécifiez votre point de terminaison OAuth 2.0 et l'ID client que vous avez attribué à Google dans les champs correspondants.
Dans la section Step 1 (Étape 1), ne sélectionnez aucun champ d'application Google. Laissez plutôt ce champ vide ou saisissez un champ d'application valide pour votre serveur (ou une chaîne arbitraire si vous n'utilisez pas de champs d'application OAuth). Lorsque vous avez terminé, cliquez sur Authorize APIs (Autoriser les API).
Dans les sections Step 2 (Étape 2) et Step 3 (Étape 3), parcourez le flux OAuth 2.0 et vérifiez que chaque étape fonctionne comme prévu.

Vous pouvez valider votre implémentation à l'aide de l'outil de démonstration de l'association de comptes Google .