Association de comptes Google avec OAuth

Les comptes sont associés à l'aide des flux implicites et codes d'autorisation OAuth 2.0 standards dans l'industrie. Votre service doit prendre en charge les points de terminaison d'autorisation et d'échange de jetons conformes à OAuth 2.0.

Dans le flux implicite, Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. Une fois la connexion réussie, vous renvoyez un jeton d'accès à durée de vie prolongée à Google. Ce jeton d'accès est désormais inclus dans chaque requête envoyée par Google.

Dans le flux code d'autorisation, vous avez besoin de deux points de terminaison:

  • Le point de terminaison d'autorisation, qui présente l'UI de connexion à vos utilisateurs qui ne sont pas encore connectés. Le point de terminaison d'autorisation crée également un code d'autorisation de courte durée pour enregistrer le consentement des utilisateurs à l'accès demandé.

  • Le point de terminaison échange de jetons, qui est responsable de deux types d'échanges:

    1. Échange un code d'autorisation contre un jeton d'actualisation de longue durée et un jeton d'accès de courte durée. Cet échange se produit lorsque l'utilisateur suit le parcours d'association de compte.
    2. Échange un jeton d'actualisation à longue durée de vie contre un jeton d'accès à courte durée de vie. Cet échange se produit lorsque Google a besoin d'un nouveau jeton d'accès, car celui-ci a expiré.

Choisir un flux OAuth 2.0

Bien que le flux implicite soit plus simple à implémenter, Google recommande que les jetons d'accès émis par le flux implicite n'expirent jamais. En effet, l'utilisateur est obligé d'associer à nouveau son compte après l'expiration d'un jeton avec le flux implicite. Si vous avez besoin d'une expiration des jetons pour des raisons de sécurité, nous vous recommandons vivement d'utiliser plutôt le flux avec code d'autorisation.

Principes de conception

Cette section décrit les exigences de conception et les recommandations concernant l'écran utilisateur que vous hébergez pour les flux d'association OAuth. Une fois qu'elle est appelée par l'application Google, votre plate-forme affiche une page de connexion à Google et un écran de consentement pour l'association de compte à l'utilisateur. L'utilisateur est redirigé vers l'application Google après avoir donné son autorisation pour associer des comptes.

Cette figure montre comment un utilisateur peut associer son compte Google à votre système d'authentification. La première capture d'écran montre l'association lancée par l'utilisateur depuis votre plate-forme. La deuxième image montre la connexion de l'utilisateur à Google, tandis que la troisième montre le consentement et la confirmation de l'utilisateur pour associer son compte Google à votre application. La dernière capture d'écran montre un compte utilisateur associé avec succès dans l'application Google.
Figure 1 Connexion de l'utilisateur à Google pour l'association de compte et écrans de consentement

Conditions requises

  1. Vous devez indiquer que le compte de l'utilisateur sera associé à Google, et non à un produit Google spécifique tel que Google Home ou l'Assistant Google.

Recommandations

Nous vous recommandons d'effectuer les opérations suivantes :

  1. Afficher les règles de confidentialité de Google. Incluez un lien vers les Règles de confidentialité de Google sur l'écran de consentement.

  2. Données à partager. Utilisez un langage clair et concis pour indiquer à l'utilisateur quelles données Google exige et pourquoi.

  3. Incitation à l'action claire Énoncez une incitation à l'action claire sur votre écran de consentement, par exemple "Accepter et associer". En effet, les utilisateurs doivent comprendre quelles données ils doivent partager avec Google pour associer leurs comptes.

  4. Possibilité d'annuler. Proposez aux utilisateurs la possibilité de revenir en arrière ou d'annuler s'ils choisissent de ne pas associer leur compte.

  5. Procédure de connexion claire. Assurez-vous que les utilisateurs disposent d'une méthode claire pour se connecter à leur compte Google, comme des champs pour leur nom d'utilisateur et leur mot de passe ou Se connecter avec Google.

  6. Possibilité de dissocier : Offrez aux utilisateurs un mécanisme de dissociation, par exemple une URL vers les paramètres de leur compte sur votre plate-forme. Vous pouvez également inclure un lien vers le compte Google, où les utilisateurs peuvent gérer leur compte associé.

  7. Possibilité de changer de compte utilisateur Suggérez aux utilisateurs une méthode pour changer de compte. Cette fonctionnalité est particulièrement utile si les utilisateurs ont tendance à posséder plusieurs comptes.

    • Si un utilisateur doit fermer l'écran d'autorisation pour changer de compte, envoyez une erreur récupérable à Google afin qu'il puisse se connecter au compte souhaité avec l'association OAuth et le parcours implicite.

  8. Incluez votre logo. Afficher le logo de votre entreprise sur l'écran de consentement. Utilisez vos consignes de style pour placer votre logo. Si vous souhaitez également afficher le logo de Google, consultez la section Logos et marques.

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

授权代码流程的 OAuth 2.0 服务器实现包括 两个端点，您的服务会通过 HTTPS 提供这两个端点。第一个端点 是授权端点，负责查找或获取 就数据访问征求用户意见。授权端点会提供一个 尚未登录的用户的登录界面，并记录同意情况 请求的访问权限。第二个端点是令牌交换端点， 用于获取加密字符串（称为令牌），以授权用户 访问您的服务。

当 Google 应用需要调用您的某个服务的 API 时，Google 会使用 将这些端点组合在一起，以获取用户调用这些 API 的权限 。

由 Google 发起的 OAuth 2.0 授权代码流程会话包含 以下流程：

  1. Google 会在用户的浏览器中打开您的授权端点。如果流 在用户通过纯语音设备上针对某个 Action 启动，Google 会将 将代码执行到手机上
  2. 用户登录（如果尚未登录），并授予 Google 以下权限： 访问您的 API 访问其数据（如果尚未授权）。
  3. 您的服务会创建授权代码并将其返回给 Google。待办事项 因此，请使用授权代码将用户的浏览器重定向回 Google。 附件。
  4. Google 会将授权代码发送到您的令牌交换端点， 验证代码的真实性并返回访问令牌和 刷新令牌。访问令牌是一个短期有效的令牌 作为访问 API 的凭据。刷新令牌长期有效 Google 可以存储该令牌，以便在用户首次访问该令牌时， 过期。
  5. 在用户完成账号关联流程后， 从 Google 发送的请求中包含访问令牌。

处理授权请求

需要使用 OAuth 2.0 授权代码执行账号关联的情况 流程中，Google 会通过请求将用户发送到您的授权端点 包含以下参数：

授权端点参数
client_id 您分配给 Google 的客户 ID。
redirect_uri 此请求的响应发送到的网址。
state 将一个在 重定向 URI。
scope 可选：一组以空格分隔的范围字符串，用于指定 Google 请求授权的数据
response_type 要在响应中返回的值的类型。对于 OAuth 2.0 授权代码流程中，响应类型始终为 code。
user_locale “Google 账号语言设置” RFC5646 格式，用于将您的内容本地化为用户首选语言。

例如，如果您的授权端点位于 https://myservice.example.com/auth 时，请求可能如下所示：

GET https://myservice.example.com/auth?client_id=GOOGLE_CLIENT_ID&redirect_uri=REDIRECT_URI&state=STATE_STRING&scope=REQUESTED_SCOPES&response_type=code&user_locale=LOCALE

为了让授权端点能够处理登录请求，请执行以下操作 步骤：

  1. 验证 client_id 是否与您分配给 Google 的 Client ID 匹配，以及 redirect_uri 与 Google 为您的服务提供的重定向网址是否匹配。这些检查对于防止 访问意外或配置错误的客户端应用。如果你支持多种 OAuth 2.0 流程，还应确认 response_type 是否为 code。
  2. 检查用户是否已登录您的服务。如果用户没有登录， 完成服务的登录或注册流程。
  3. 生成授权代码，以供 Google 用于访问您的 API。 授权代码可以是任何字符串值，但它必须是唯一的 代表用户、令牌对应的客户端以及代码的有效期 而且不可猜测出来。您通常需要进行授权 会在大约 10 分钟后过期。
  4. 确认 redirect_uri 参数指定的网址包含 以下表单： 
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
  https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
  5. 将用户的浏览器重定向到 redirect_uri 参数。添加您在 以及您在重定向时返回未经修改的原始状态值 方法是附加 code 和 state 参数。以下是 生成的网址示例： 
    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

处理令牌交换请求

您的服务的令牌交换端点负责处理两种令牌 广告交易平台：

  • 交换访问令牌和刷新令牌的授权代码
  • 用刷新令牌换取访问令牌

令牌交换请求包含以下参数：

令牌交换端点参数
client_id 用于将请求来源标识为 Google 的字符串。此字符串必须 在您的系统中注册为 Google 的唯一标识符。
client_secret 您在 Google 中为您的服务注册的密钥字符串。
grant_type 所交换的令牌的类型。是 authorization_code 或 refresh_token。
code 如果值为 grant_type=authorization_code，则此参数为 Google 通过您的登录或令牌交换收到的代码 端点。
redirect_uri 如果值为 grant_type=authorization_code，则此参数为 初始授权请求中使用的网址。
refresh_token 如果值为 grant_type=refresh_token，则此参数为 刷新令牌 Google 从您的令牌交换端点收到的令牌。
交换访问令牌和刷新令牌的授权代码

用户登录且您的授权端点返回一个短期有效的 授权代码发送给 Google，Google 会向您的令牌交换发送请求 端点使用授权代码交换访问令牌和刷新 令牌。

对于这些请求，grant_type 的值为 authorization_code， 的 code 值是您先前授予的授权代码的值 。以下是发送 访问令牌和刷新令牌的授权代码：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=authorization_code&code=AUTHORIZATION_CODE&redirect_uri=REDIRECT_URI

要将授权代码交换为访问令牌和刷新令牌，您的 令牌交换端点通过执行以下命令来响应 POST 请求： 步骤：

  1. 验证 client_id 是否将请求来源标识为已获授权的请求来源 来源，并且 client_secret 与预期值匹配。
  2. 请确认授权代码有效且未过期， 请求中指定的客户端 ID 与 授权代码。
  3. 确认 redirect_uri 参数指定的网址完全相同 初始授权请求中使用的值。
  4. 如果您无法验证上述所有条件，则返回 HTTP 正文为 {"error": "invalid_grant"} 的 400 Bad Request 错误。
  5. 否则，使用授权代码中的用户 ID 来生成刷新 令牌和访问令牌。这些标记可以是任何字符串值， 必须唯一地代表用户和令牌对应的客户端， 不得被猜到对于访问令牌，请记录 令牌，通常是在您发出令牌一个小时后。 刷新令牌不会过期。
  6. 在 HTTPS 响应的正文中返回以下 JSON 对象： 
    {
"token_type": "Bearer",
"access_token": "ACCESS_TOKEN",
"refresh_token": "REFRESH_TOKEN",
"expires_in": SECONDS_TO_EXPIRATION
}

Google 会存储用户的访问令牌和刷新令牌，并存储相关记录 访问令牌的有效期。访问令牌过期后，Google 会使用 刷新令牌，以从令牌交换端点获取新的访问令牌。

用刷新令牌换取访问令牌

访问令牌过期后，Google 会向您的令牌交换发送请求 端点将刷新令牌交换为新的访问令牌。

对于这些请求，grant_type 的值为 refresh_token，值 “refresh_token”是您之前授予的刷新令牌的值 Google。以下是交换刷新令牌的请求示例 获取访问令牌：

POST /token HTTP/1.1
Host: oauth2.example.com
Content-Type: application/x-www-form-urlencoded

client_id=GOOGLE_CLIENT_ID&client_secret=GOOGLE_CLIENT_SECRET&grant_type=refresh_token&refresh_token=REFRESH_TOKEN

如需将刷新令牌交换为访问令牌，令牌交换端点 来响应 POST 请求：

  1. 验证 client_id 是否将请求来源标识为 Google，并 client_secret 与预期值一致。
  2. 请确认刷新令牌有效，以及在 请求与刷新令牌所关联的客户端 ID 相匹配。
  3. 如果您无法验证上述所有条件，则返回 HTTP 400 正文为 {"error": "invalid_grant"} 的 Bad Request 错误。
  4. 否则，请使用刷新令牌中的用户 ID 来生成访问权限 令牌。这些标记可以是任何字符串值，但它们必须是唯一的 代表用户和客户端，而不得 猜测。对于访问令牌，请记录令牌的到期时间， 通常在您发出令牌一小时后发送
  5. 在 HTTPS 的正文中返回以下 JSON 对象 回答：
    {
"token_type": "不记名",
"access_token": "ACCESS_TOKEN",
“expires_in”：SECONDS_TO_EXPIRATION
}
。
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:

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:

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

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

  1. Cliquez sur Configuration pour ouvrir la fenêtre de configuration OAuth 2.0.
  2. Dans le champ OAuth flow (Flux OAuth), sélectionnez Client-side (Côté client).
  3. Dans le champ Points de terminaison OAuth, sélectionnez Personnalisé.
  4. Indiquez votre point de terminaison OAuth 2.0 et l'ID client que vous avez attribué à Google dans les champs correspondants.
  5. Dans la section Étape 1, ne sélectionnez aucun champ d'application Google. Laissez plutôt ce champ vide ou saisissez une portée valide pour votre serveur (ou une chaîne arbitraire si vous n'utilisez pas de portées OAuth). Lorsque vous avez terminé, cliquez sur Autoriser les API.
  6. Dans les sections Étape 2 et Étape 3, suivez 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 Démo d'association de comptes Google.

Dans l'outil, procédez comme suit:

  1. Cliquez sur le bouton Se connecter avec Google.
  2. Sélectionnez le compte que vous souhaitez associer.
  3. Saisissez l'ID du service.
  4. Saisissez éventuellement un ou plusieurs champs d'application pour lesquels vous demanderez l'accès.
  5. Cliquez sur Démarrer la démo.
  6. Lorsque vous y êtes invité, confirmez que vous pouvez accepter ou refuser la demande d'association.
  7. Vérifiez que vous êtes redirigé vers votre plate-forme.