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.

创建项目

如需创建项目以使用账号关联功能,请执行以下操作:

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

  1. 打开 Google API 控制台的 OAuth 同意屏幕页面。
  2. 如果出现提示,请选择您刚刚创建的项目。
  3. 在“OAuth 同意屏幕”页面上,填写表单,然后点击“保存”按钮。

    应用名称:征求用户同意的应用的名称。该名称应准确反映您的应用,并与用户在其他地方看到的应用名称一致。应用名称将显示在账号关联意见征求界面上。

    应用徽标:权限请求页面上显示的一张图片,用以让用户认出您的应用。该徽标会显示在账号关联意见征求页面和账号设置

    支持电子邮件:供用户就其是否同意的问题与您联系。

    Google API 的范围:借助范围,您的应用可以访问用户的私密 Google 数据。对于 Google 账号关联用例,默认范围(电子邮件地址、个人资料、openid)已足够,您无需添加任何敏感范围。通常,最佳做法是在需要访问权限时逐步请求相应权限范围,而不是提前请求。了解详情

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

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

    应用隐私权政策链接:显示在 Google 账号关联意见征求界面上。必须托管在已获授权的网域上。

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

    图 1. 虚构应用 Tunery 的 Google 账号关联意见征求界面

  4. 查看“验证状态”,如果您的应用需要验证,请点击“提交以供验证”按钮,以提交您的应用以供验证。如需了解详情,请参阅 OAuth 验证要求

Implémenter votre serveur OAuth

Pour prendre en charge le flux implicite OAuth 2.0, votre service accorde une autorisation un point de terminaison unique disponible via HTTPS. Ce point de terminaison est responsable de l'authentification l'obtention du consentement des utilisateurs pour l'accès aux données. Le point de terminaison d'autorisation présente une interface utilisateur de connexion aux utilisateurs qui ne sont pas déjà connectés et enregistre autoriser l'accès demandé.

Lorsqu'une application Google doit appeler l'une des API autorisées de votre service, Google utilise ce point de terminaison pour obtenir l'autorisation de vos utilisateurs d'appeler ces API en son nom.

Une session de flux implicite OAuth 2.0 typique lancée par Google possède le flux suivant:

  1. Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. La se connecte (s'il ne l'est pas déjà) et autorise Google à accéder à leurs données avec votre API, s'ils ne l'ont pas déjà accordé.
  2. Votre service crée un jeton d'accès et le renvoie à Google Pour ce faire, redirigez le navigateur de l'utilisateur vers Google associé à la requête.
  3. Google appelle les API de votre service et associe le jeton d'accès chaque requête. Votre service vérifie que le jeton d'accès accorde à Google l'autorisation d'accès à l'API, puis termine l'appel d'API.

Gérer les requêtes d'autorisation

Lorsqu'une application Google doit associer un compte via une méthode OAuth 2.0 flux implicite, Google redirige l'utilisateur vers votre point de terminaison d'autorisation qui inclut les paramètres suivants:

Paramètres du point de terminaison de l'autorisation
client_id ID client que vous avez attribué à Google.
redirect_uri URL à laquelle vous envoyez la réponse à cette requête.
state Une valeur de tenue de registre renvoyée à Google telle quelle dans le l'URI de redirection.
response_type Type de valeur à renvoyer dans la réponse. Pour l'authentification OAuth 2.0 le type de réponse est toujours token.
user_locale Le paramètre linguistique du compte Google RFC5646 format utilisé pour localiser votre contenu dans la langue préférée de l'utilisateur.

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

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

Pour que votre point de terminaison d'autorisation traite les requêtes de connexion, procédez comme suit : étapes:

  1. Vérifiez les valeurs client_id et redirect_uri pour pour empêcher l'octroi d'accès à des applications clientes non intentionnelles ou mal configurées:

    • Vérifiez que client_id correspond à l'ID client que vous attribué à Google.
    • Vérifiez que l'URL spécifiée par redirect_uri a la forme suivante:
      https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
      https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
      
  2. Vérifiez si l'utilisateur est connecté à votre service. Si l'utilisateur n'est pas signé suivez la procédure de connexion ou d'inscription de votre service.

  3. Générez un jeton d'accès que Google utilisera pour accéder à votre API. La Le jeton d'accès peut correspondre à n'importe quelle valeur de chaîne, mais il doit représenter de manière unique le user et le client pour lequel le jeton est destiné et ne doit pas être devinable.

  4. Envoyer une réponse HTTP qui redirige le navigateur de l'utilisateur vers l'URL spécifiée par le paramètre redirect_uri. Incluez tous les les paramètres suivants dans le fragment d'URL:

    • access_token: jeton d'accès que vous venez de générer
    • token_type: chaîne bearer
    • state: valeur de l'état non modifié de l'original demander

    Voici un exemple de l'URL obtenue:

    https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID#access_token=ACCESS_TOKEN&token_type=bearer&state=STATE_STRING

Le gestionnaire de redirection OAuth 2.0 de Google reçoit le jeton d'accès et confirme que la valeur state n'a pas changé. Une fois que Google a obtenu pour votre service, le jeton est associé aux appels suivants à vos API de service.

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

您可以使用 OAuth 2.0 Playground 工具验证您的实现。

在该工具中,执行以下步骤:

  1. 点击配置 以打开 OAuth 2.0 配置窗口。
  2. OAuth flow 字段中,选择 Client-side(客户端)。
  3. OAuth 端点字段中,选择自定义
  4. 在相应字段中指定您的 OAuth 2.0 端点和您分配给 Google 的客户端 ID。
  5. 第 1 步部分,不要选择任何 Google 范围。请将此字段留空或输入对服务器有效的范围(如果您不使用 OAuth 范围,则可以输入任意字符串)。完成后,点击授权 API
  6. Step 2Step 3 部分中,完成 OAuth 2.0 流程,并验证每个步骤是否按预期运行。

您可以使用 Google 账号关联演示版工具验证您的实现。

在该工具中,执行以下步骤:

  1. 点击使用 Google 账号登录按钮。
  2. 选择您要关联的账号。
  3. 输入服务 ID。
  4. (可选)输入您要请求访问权限的一个或多个范围。
  5. 点击开始演示
  6. 当系统提示时,请确认您同意或拒绝关联请求。
  7. 确认您已被重定向到您的平台。