Votre API d'association de compte

Cette page de référence décrit les points de terminaison d'API que votre service doit implémenter pour prendre en charge l'association de compte avec Google. Cela inclut l'association de comptes basée sur OAuth, l'association de comptes simplifiée et l'échange d'applications.

Conditions préalables et normes

Pour implémenter correctement ces points de terminaison, votre service doit respecter les normes suivantes :

  • OAuth 2.0 : conforme à la RFC 6749.
  • Révocation de jeton : conforme à la norme RFC 7009.
  • Jetons Web JSON (JWT) : conformes à la norme RFC 7519 (obligatoire pour l'association simplifiée).
  • HTTPS : tous les points de terminaison doivent être diffusés via une connexion HTTPS sécurisée.

Point de terminaison Autorisation

Le point de terminaison d'autorisation est chargé d'authentifier les utilisateurs et d'obtenir leur consentement pour associer leurs comptes à Google.

  • URL : configurée dans la console Actions ou la console Google Cloud.
  • Méthode : GET

Paramètres de requête

Paramètres Description
client_id ID client que vous avez attribué à Google.
redirect_uri URL à laquelle vous envoyez la réponse à cette requête.
state Valeur de suivi retransmise telle quelle à Google dans l'URI de redirection.
response_type Doit être défini sur code pour le flux avec code d'autorisation.
scope (Facultatif) Liste des niveaux d'accès aux données demandés par Google, séparés par des espaces.
user_locale (Facultatif) Paramètre de langue du compte Google, spécifié à l'aide d'un tag de langue BCP-47 (par exemple, en-US).

Point de terminaison d'échange de jetons

Ce point de terminaison est chargé d'échanger les codes d'autorisation contre des jetons et d'actualiser les jetons d'accès expirés.

  • URL : configurée dans la console Actions ou la console Google Cloud.
  • Méthode : POST
  • Content-Type : application/x-www-form-urlencoded

Échanger le code d'autorisation contre des jetons

Les paramètres suivants sont utilisés dans la requête initiale d'échange de jetons.

Paramètres de requête

Paramètres Description
client_id ID client que vous avez attribué à Google.
client_secret Code secret du client que vous avez attribué à Google.
grant_type doit être authorization_code
code Code d'autorisation reçu du point de terminaison d'autorisation.
redirect_uri Le même URI de redirection que celui utilisé dans la requête initiale.

Échanger un jeton d'actualisation contre un jeton d'accès

Les paramètres suivants sont utilisés lors de l'actualisation d'un jeton d'accès.

Paramètres de requête

Paramètres Description
client_id ID client que vous avez attribué à Google.
client_secret Code secret du client que vous avez attribué à Google.
grant_type doit être refresh_token
refresh_token Jeton d'actualisation précédemment émis pour Google.

Réponse (JSON)

Renvoie une réponse positive avec un objet JSON dans le corps de la réponse HTTPS.

  • État HTTP : 200 OK
  • Content-Type : application/json;charset=UTF-8
Champs Description
token_type Obligatoire. Doit être bearer.
access_token Obligatoire. Jeton de courte durée utilisé pour accéder aux API de votre service.
refresh_token Obligatoire pour authorization_code grant_type. Jeton de longue durée utilisé pour obtenir de nouveaux jetons d'accès.
expires_in Obligatoire. Durée de vie restante du jeton d'accès, en secondes.

Réponses d'erreur

Si une requête envoyée au point de terminaison du jeton échoue, renvoyez une erreur HTTP 400 Bad Request ainsi qu'une réponse JSON contenant les champs suivants :

  • État HTTP : 400 Bad Request
  • Content-Type : application/json;charset=UTF-8
Champs d'erreur (JSON) Description
error Obligatoire. Doit être invalid_grant.
error_description (Facultatif) Texte lisible par l'utilisateur fournissant des informations supplémentaires.

Gérer les intents d'association simplifiée

Si votre service est compatible avec l'association de compte simplifiée (OAuth avec Se connecter avec Google), votre point de terminaison d'échange de jetons doit également être compatible avec les assertions de jeton Web JSON (JWT) et implémenter les intents check, create et get.

Les paramètres suivants sont utilisés dans ces requêtes :

Paramètres de requête

Paramètres Description
intent Intention de simplification spécifique demandée pour l'association : check, get ou create.
grant_type Pour ces requêtes, ce paramètre a toujours la valeur urn:ietf:params:oauth:grant-type:jwt-bearer.
assertion Jeton Web JSON (JWT) qui fournit une assertion signée de l'identité de l'utilisateur Google. Le JWT contient des informations telles que l'ID de compte Google, le nom et l'adresse e-mail de l'utilisateur.

 Votre serveur doit valider ce jeton JWT à l'aide des critères listés dans la section Validation JWT.
client_id ID client que vous avez attribué à Google.
client_secret Code secret du client que vous avez attribué à Google.
scope Facultatif : tous les niveaux d'accès que vous avez configurés pour que Google les demande aux utilisateurs. Généralement présent dans les intentions get et create.
response_type Obligatoire pour l'intention create : doit être défini sur token.

Validation JWT

Pour assurer la sécurité de l'association simplifiée, votre serveur doit valider le assertion (JWT) en fonction des critères suivants :

  • Signature : vérifiez la signature par rapport aux clés publiques de Google (disponibles au point de terminaison JWK de Google).
  • Émetteur (iss) : doit être défini sur https://accounts.google.com.
  • Audience (aud) : doit correspondre à l'ID client de l'API Google attribué à votre intégration.
  • Expiration (exp) : doit être dans le futur.

Réponse pour l'intention check

Une requête avec intent=check vérifie si le compte Google (identifié par la revendication sub ou email dans l'assertion JWT décodée) existe dans votre base de données utilisateur.

  • État HTTP : 200 OK (Compte trouvé) ou 404 Not Found (Compte introuvable)
  • Content-Type : application/json;charset=UTF-8
Champs Description
account_found Obligatoire. true si le compte existe, false dans le cas contraire.

Réponse pour l'intention get

Une requête avec intent=get demande un jeton d'accès pour un compte Google existant.

  • État HTTP : 200 OK
  • Content-Type : application/json;charset=UTF-8

L'objet JSON de réponse en cas de réussite utilise exactement la même structure qu'une réponse standard d'échange de jetons (renvoyant access_token, refresh_token, etc.).

Si le compte ne peut pas être associé, une erreur HTTP 401 est renvoyée.

  • État HTTP : 401 Unauthorized
  • Content-Type : application/json;charset=UTF-8
Champs d'erreur (JSON) Description
error Obligatoire. Doit être linking_error.
login_hint (Facultatif) Adresse e-mail de l'utilisateur à transmettre au flux d'association OAuth de secours.

Réponse pour l'intention create

Une requête avec intent=create demande la création d'un compte utilisateur avec les informations fournies dans le JWT.

  • État HTTP : 200 OK
  • Content-Type : application/json;charset=UTF-8

L'objet JSON de réponse en cas de réussite utilise exactement la même structure qu'une réponse standard d'échange de jetons (renvoyant access_token, refresh_token, etc.).

Si l'utilisateur existe déjà, une erreur HTTP 401 est renvoyée pour l'inviter à associer son compte existant.

  • État HTTP : 401 Unauthorized
  • Content-Type : application/json;charset=UTF-8
Champs d'erreur (JSON) Description
error Obligatoire. Doit être linking_error.
login_hint Adresse e-mail de l'utilisateur à transmettre au flux de connexion OAuth de secours.

Point de terminaison UserInfo (facultatif)

Utilisé pour récupérer les informations de profil de base de l'utilisateur associé, comme indiqué dans la spécification OpenID Connect Core 1.0. Ce partage est nécessaire pour des fonctionnalités telles que l'association simplifiée ou la connexion en un clic.

  • Méthode : GET
  • Authentification : Authorization: Bearer ACCESS_TOKEN

Réponse (JSON)

Renvoie une réponse positive avec un objet JSON dans le corps de la réponse HTTPS.

  • État HTTP : 200 OK
  • Content-Type : application/json;charset=UTF-8

Champs de réponse

Champs Description
sub Obligatoire. ID unique qui identifie l'utilisateur dans votre système.
email Obligatoire. Adresse e-mail de l'utilisateur.
email_verified Obligatoire. Valeur booléenne indiquant si l'adresse e-mail a été validée.
given_name (Facultatif) Prénom de l'utilisateur.
family_name (Facultatif) Nom de famille de l'utilisateur.
name (Facultatif) Nom complet de l'utilisateur.
picture (Facultatif) URL de la photo de profil de l'utilisateur.

Réponses d'erreur

Si le jeton d'accès n'est pas valide ou a expiré, renvoyez une erreur HTTP 401 Unauthorized. Vous devez également inclure l'en-tête de réponse WWW-Authenticate.

Toute réponse infructueuse (4xx ou 5xx) renvoyée lors du processus d'association est considérée comme irrécupérable. Dans ce cas, Google supprimera tous les jetons récupérés, et l'utilisateur devra recommencer le processus d'association de compte.

Point de terminaison de révocation du jeton (facultatif)

Permet à Google d'informer votre service lorsqu'un utilisateur dissocie son compte de la surface Google. Ce point de terminaison doit répondre aux exigences décrites dans la RFC 7009.

  • Méthode : POST
  • Content-Type : application/x-www-form-urlencoded

Paramètres de requête

Paramètres Description
client_id Chaîne qui identifie Google comme origine de la requête. Cette chaîne doit être enregistrée dans votre système en tant qu'identifiant unique de Google.
client_secret Chaîne secrète que vous avez enregistrée auprès de Google pour votre service.
token Jeton à révoquer.
token_type_hint (Facultatif) Indication sur le type de jeton révoqué (access_token ou refresh_token). Si aucune valeur n'est spécifiée, la valeur par défaut est access_token.

Réponses

Renvoie une réponse indiquant que l'opération a réussi lorsque le jeton a été supprimé ou s'il n'est plus valide.

  • État HTTP : 200 OK
  • Content-Type : application/json;charset=UTF-8

Réponses d'erreur

Si le jeton ne peut pas être supprimé pour une raison quelconque (par exemple, si la base de données n'est pas disponible), renvoyez une erreur HTTP 503. Google réessaiera d'envoyer la requête ultérieurement ou selon les indications de l'en-tête Retry-After.

  • État HTTP : 503 Service Unavailable
  • Content-Type : application/json;charset=UTF-8
  • En-têtes : Retry-After: <HTTP-date / delay-seconds>