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.

Create the project

To create your project to use account linking:

  1. Go to the Google API Console.
  2. Click Create project.
  3. Enter a name or accept the generated suggestion.
  4. Confirm or edit any remaining fields.
  5. Click Create.

To view your project ID:

  1. Go to the Google API Console.
  2. Find your project in the table on the landing page. The project ID appears in the ID column.

The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.

  1. Open the OAuth consent screen page of the Google APIs console.
  2. If prompted, select the project you just created.

  3. On the "OAuth consent screen" page, fill out the form and click the “Save” button.

    Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.

    Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings

    Support email: For users to contact you with questions about their consent.

    Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.

    Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.

    Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.

    Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.

    Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.

    Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery

  4. Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.

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.

Utilisateur Application Google / Navigateur Serveur Google Votre point de terminaison d'authentification Votre point de terminaison de jeton 1. L'utilisateur lance l'association 2. Rediriger vers le point de terminaison d'authentification (GET) client_id, redirect_uri, state, scope 3. Afficher l'écran de connexion et de consentement 4. L'utilisateur s'authentifie et donne son consentement 5. Rediriger vers Google (GET) code, state 6. Gérer la redirection et transmettre le code/l'état 7. Échange de jetons (POST) grant_type=authorization_code, code 8. Jeton de retour (200 OK) access_token, refresh_token 9. Stocker des jetons utilisateur 10. Accéder aux ressources utilisateur
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 :

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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 :

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  1. 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"}.

  2. É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.

  1. 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"}.

  2. É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).
Handle userinfo requests

The userinfo endpoint is an OAuth 2.0 protected resource that return claims about the linked user. Implementing and hosting the userinfo endpoint is optional, except for the following use cases:

After the access token has been successfully retrieved from your token endpoint, Google sends a request to your userinfo endpoint to retrieve basic profile information about the linked user.

userinfo endpoint request headers
Authorization header The access token of type Bearer.

For example, if your userinfo endpoint is available at https://myservice.example.com/userinfo, a request might look like the following:

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

For your userinfo endpoint to handle requests, do the following steps:

  1. Extract access token from the Authorization header and return information for the user associated with the access token.
  2. If the access token is invalid, return an HTTP 401 Unauthorized error with using the WWW-Authenticate Response Header. Below is an example of a userinfo error response: 
    HTTP/1.1 401 Unauthorized
WWW-Authenticate: error="invalid_token",
error_description="The Access Token expired"
    If a 401 Unauthorized, or any other unsuccessful error response is returned during the linking process, the error will be non-recoverable, the retrieved token will be discarded and the user will have to initiate the linking process again.

  3. If the access token is valid, return and HTTP 200 response with the following JSON object in the body of the HTTPS response: 

    {
"sub": "USER_UUID",
"email": "EMAIL_ADDRESS",
"given_name": "FIRST_NAME",
"family_name": "LAST_NAME",
"name": "FULL_NAME",
"picture": "PROFILE_PICTURE",
}
     If your userinfo endpoint returns an HTTP 200 success response, the retrieved token and claims are registered against the user's Google account.

    userinfo endpoint response
    sub A unique ID that identifies the user in your system.
    email Email address of the user.
    given_name Optional: First name of the user.
    family_name Optional: Last name of the user.
    name Optional: Full name of the user.
    picture Optional: Profile picture of the user.

Valider votre implémentation

You can validate your implementation by using the OAuth 2.0 Playground tool.

In the tool, do the following steps:

  1. Click Configuration to open the OAuth 2.0 Configuration window.
  2. In the OAuth flow field, select Client-side.
  3. In the OAuth Endpoints field, select Custom.
  4. Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
  5. In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
  6. In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.

You can validate your implementation by using the Google Account Linking Demo tool.

In the tool, do the following steps:

  1. Click the Sign in with Google button.
  2. Choose the account you'd like to link.
  3. Enter the service ID.
  4. Optionally enter one or more scopes that you will request access for.
  5. Click Start Demo.
  6. When prompted, confirm that you may consent and deny the linking request.
  7. Confirm that you are redirected to your platform.