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.

Remarque :Utilisez les boutons suivants pour choisir le flux OAuth 2.0 que vous souhaitez implémenter. Si nécessaire, le contenu de ce guide sera actualisé en fonction de votre choix.

Flux implicite 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.

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.

Figure 2. Consignes de conception pour la connexion des utilisateurs à Google et les écrans de consentement.

Créer le projet

Remarque :Vous pouvez réutiliser un projet existant sans avoir à en créer un principalement pour l'association de comptes.

Pour créer votre projet afin d'utiliser l'association de comptes:

1. Go to the Google API Console.
2. Cliquez sur Créer un projet .
3. Saisissez un nom ou acceptez la suggestion générée.
4. Confirmez ou modifiez les champs restants.
5. Cliquez sur Créer .

Pour afficher votre ID de projet:

1. Go to the Google API Console.
2. Trouvez votre projet dans le tableau de la page de destination. L'ID du projet apparaît dans la colonne ID .

Configurer votre écran de consentement OAuth

Le processus d'association du compte Google comprend un écran de consentement qui indique aux utilisateurs l'application qui demande à accéder à leurs données, le type de données qu'ils demandent et les conditions applicables. Vous devez configurer votre écran de consentement OAuth avant de générer un ID client pour les API Google.

1. Ouvrez l'écran d'autorisation OAuth dans la console des API Google.
2. Si vous y êtes invité, sélectionnez le projet que vous venez de créer.

3. Sur la page "Écran d'autorisation OAuth", remplissez le formulaire, puis cliquez sur le bouton "Enregistrer".

   Nom de l'application:nom de l'application qui demande le consentement. Le nom doit refléter précisément votre application et être cohérent avec celui que les utilisateurs voient ailleurs. Le nom de l'application s'affiche sur l'écran d'autorisation de l'association de comptes.

   Logo de l'application:image affichée sur l'écran de consentement pour aider les utilisateurs à reconnaître votre application. Le logo s'affiche sur l'écran de consentement à l'association de comptes et dans les paramètres du compte.

   Adresse e-mail d'assistance:permet aux utilisateurs de vous contacter s'ils ont des questions concernant leur consentement.

   Champs d'application pour les API Google:les champs d'application permettent à votre application d'accéder aux données Google privées de vos utilisateurs. Pour le cas d'utilisation de l'association de compte Google, le champ d'application par défaut (adresse e-mail, profil, OpenID) est suffisant. Vous n'avez pas besoin d'ajouter de champ d'application sensible. Il est généralement recommandé de demander des portées de manière incrémentielle, au moment où l'accès est requis, plutôt que d'emblée. En savoir plus

   Domaines autorisés:pour vous protéger, vous et vos utilisateurs, Google n'autorise que les applications qui s'authentifient à l'aide d'OAuth à utiliser des domaines autorisés. Les liens de vos applications doivent être hébergés sur des domaines autorisés. En savoir plus

   Lien vers la page d'accueil de l'application:page d'accueil de votre application. Il doit être hébergé sur un domaine autorisé.

   Lien vers les règles de confidentialité de l'application:s'affiche sur l'écran d'autorisation de l'association de comptes Google. Il doit être hébergé sur un domaine autorisé.

   Lien vers les conditions d'utilisation de l'application (facultatif) : doit être hébergé sur un domaine autorisé.

   

   Figure 1 : Écran de consentement pour l'association d'un compte Google à une application fictive, Tunery

4. Vérifiez l'état de validation. Si votre application doit être validée, cliquez sur le bouton "Envoyer pour validation". Pour en savoir plus, consultez les Exigences de validation OAuth.

Implémenter votre serveur OAuth

Une mise en œuvre serveur OAuth 2.0 du flux de code d'autorisation comprend les éléments suivants : deux points de terminaison, que votre service met à disposition via HTTPS. Le premier point de terminaison est le point de terminaison d'autorisation 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 qui n'est pas déjà connectée et qui enregistre le consentement des utilisateurs. l'accès demandé. Le deuxième point de terminaison est le point de terminaison de l'échange de jetons, 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 pour obtenir l'autorisation de vos utilisateurs d'appeler ces API en son nom.

Une session de flux avec code d'autorisation OAuth 2.0 initiée par Google dispose du flux suivant:

1. Google ouvre votre point de terminaison d'autorisation dans le navigateur de l'utilisateur. Si le flux sur un appareil à commande vocale pour une action, Google transfère l'exécution sur un téléphone.
2. L'utilisateur se connecte, s'il n'est pas déjà connecté, et autorise Google à accéder à leurs données avec votre API, s'ils ne l'ont pas déjà accordé.
3. Votre service crée un code d'autorisation et le renvoie à Google. À faire Redirigez donc le navigateur de l'utilisateur vers Google avec le code d'autorisation joint à la demande.
4. Google envoie le code d'autorisation au point de terminaison de votre échange de jetons, qui vérifie l'authenticité du code et renvoie un jeton d'accès et une jeton d'actualisation. Le jeton d'accès est un jeton de courte durée que votre service accepte comme identifiants d'accès aux API. Le jeton d'actualisation est un jeton que Google peut stocker et utiliser pour obtenir de nouveaux jetons d'accès arrive à expiration.
5. Une fois que l'utilisateur a terminé le processus d'association de compte, toutes les étapes suivantes envoyée par Google contient un jeton d'accès.

Gérer les requêtes d'autorisation

Lorsque vous devez associer des comptes à l'aide du code d'autorisation OAuth 2.0 flux d'autorisation, Google redirige l'utilisateur vers votre point de terminaison d'autorisation avec une requête comprend 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.
scope	Facultatif:un ensemble de chaînes de champ d'application délimitées par un espace qui spécifient le pour lesquelles Google demande une autorisation.
response_type	Type de valeur à renvoyer dans la réponse. Pour le protocole OAuth 2.0, flux avec code d'autorisation, le type de réponse est toujours code.
user_locale	Le paramètre linguistique du compte Google RFC5646 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&scope=REQUESTED_SCOPES&response_type=code&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 que client_id correspond à l'ID client que vous avez attribué à Google et que redirect_uri correspond à l'URL de redirection fournie par Google pour votre service. Ces vérifications sont importantes pour empêcher l'accès à des applications clientes non intentionnelles ou mal configurées. Si vous acceptez plusieurs Pour les flux OAuth 2.0, vérifiez également que response_type est défini sur code.
2. Vérifiez si l'utilisateur est connecté à votre service. Si l'utilisateur n'est pas connecté, terminer le processus de connexion ou d'inscription de votre service.
3. Générez un code d'autorisation que Google utilisera pour accéder à votre API. Le code d'autorisation peut être n'importe quelle valeur de chaîne, mais il doit être unique représenter l'utilisateur, le client auquel le jeton est destiné et la date d'expiration du code et ne doit pas être devinable. Vous émettez généralement une autorisation codes qui expirent au bout de 10 minutes environ.
4. Vérifiez que l'URL spécifiée par le paramètre redirect_uri comporte le ce formulaire:

     https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID
     https://oauth-redirect-sandbox.googleusercontent.com/r/YOUR_PROJECT_ID
     

5. Redirigez le navigateur de l'utilisateur vers l'URL spécifiée par le paramètre Paramètre redirect_uri. Indiquez le code d'autorisation généré et la valeur d'état non modifiée d'origine lorsque vous redirigez en ajoutant les paramètres code et state. Voici un exemple exemple de l'URL obtenue:

   https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID?code=AUTHORIZATION_CODE&state=STATE_STRING

Gérer les requêtes d'échange de jetons

Le point de terminaison de l'échange de jetons de votre service est responsable de deux types de jetons places de marché:

• Échangez des codes d'autorisation contre des jetons d'accès et d'actualisation
• Échanger des jetons d'actualisation contre des jetons d'accès

Les requêtes d'échange de jetons incluent les paramètres suivants:

Paramètres du point de terminaison d'échange de jetons
client_id	Chaîne identifiant Google à l'origine de la requête. Cette chaîne ne doit doit être enregistré 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.
grant_type	Type de jeton échangé. C'est soit authorization_code ou refresh_token.
code	Si la valeur est grant_type=authorization_code, ce paramètre correspond au code que Google a reçu de votre connexion ou de votre échange de jetons point de terminaison unique.
redirect_uri	Si la valeur est grant_type=authorization_code, ce paramètre correspond au URL utilisée dans la requête d'autorisation initiale.
refresh_token	Si la valeur est grant_type=refresh_token, ce paramètre correspond au jeton d'actualisation que Google a reçu du point de terminaison de votre échange de jetons.

Échangez des codes d'autorisation contre des jetons d'accès et d'actualisation

Une fois que l'utilisateur s'est connecté et que votre point de terminaison d'autorisation renvoie un code d'autorisation à Google, celui-ci envoie une demande à votre échange de jetons pour échanger le code d'autorisation contre un jeton d'accès et une actualisation à partir d'un jeton d'accès.

Pour ces requêtes, la valeur de grant_type est authorization_code, et La valeur code correspond à la valeur du code d'autorisation que vous avez accordé précédemment. à Google. Voici un exemple de requête d'échange un code d'autorisation pour un jeton d'accès et un jeton d'actualisation:

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

Pour échanger des codes d'autorisation contre un jeton d'accès et un jeton d'actualisation, votre Le point de terminaison de l'échange de jetons répond aux requêtes POST en exécutant la commande suivante : étapes:

1. Vérifiez que client_id identifie l'origine de la requête comme étant autorisée l'origine et que client_secret correspond à la valeur attendue.
2. Vérifiez que le code d'autorisation est valide et qu'il n'a pas expiré, et que le spécifié dans la requête correspond à l'identifiant client associé au d'autorisation.
3. Vérifiez que l'URL spécifiée par le paramètre redirect_uri est identique à la valeur utilisée dans la requête d'autorisation initiale.
4. Si vous ne pouvez pas vérifier tous les critères ci-dessus, renvoyez une réponse Erreur 400 "Requête incorrecte" avec {"error": "invalid_grant"} dans le corps.
5. Sinon, utilisez l'ID utilisateur du code d'autorisation pour générer une actualisation. et un jeton d'accès. Ces jetons peuvent être de n'importe quelle valeur de chaîne, mais ils doit représenter de manière unique l'utilisateur et le client pour lequel le jeton est destiné. ne doit pas être devinable. Pour les jetons d'accès, notez également l'heure d'expiration le jeton, qui est généralement une heure après son émission. Les jetons d'actualisation n'expirent pas.
6. Renvoyez l'objet JSON suivant dans le corps de la réponse HTTPS:

   {
   "token_type": "Bearer",
   "access_token": "ACCESS_TOKEN",
   "refresh_token": "REFRESH_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Google stocke le jeton d'accès et le jeton d'actualisation pour l'utilisateur et les enregistrements l'expiration du jeton d'accès. Lorsque le jeton d'accès expire, Google utilise le jeton d'actualisation pour obtenir un nouveau jeton d'accès à partir du point de terminaison de votre échange de jetons.

Échanger des jetons d'actualisation contre des jetons d'accès

Lorsqu'un jeton d'accès expire, Google envoie une demande à votre échange de jetons pour échanger un jeton d'actualisation contre un nouveau jeton d'accès.

Pour ces requêtes, la valeur de grant_type est refresh_token, et la valeur de refresh_token est la valeur du jeton d'actualisation que vous avez précédemment accordé Google Voici un exemple de requête d'échange d'un jeton d'actualisation pour un jeton d'accès:

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

Pour échanger un jeton d'actualisation contre un jeton d'accès, votre point de terminaison échange répond aux requêtes POST en procédant comme suit:

1. Vérifiez que client_id identifie l'origine de la requête comme étant Google. que client_secret correspond à la valeur attendue.
2. Vérifiez que le jeton d'actualisation est valide et que l'ID client spécifié dans la requête correspond à l'ID client associé au jeton d'actualisation.
3. Si vous ne pouvez pas vérifier tous les critères ci-dessus, renvoyez une erreur HTTP 400 Erreur de requête incorrecte avec {"error": "invalid_grant"} dans le corps.
4. Sinon, utilisez l'ID utilisateur du jeton d'actualisation pour générer un accès à partir d'un jeton d'accès. Ces jetons peuvent correspondre à n'importe quelle valeur de chaîne, mais ils doivent être uniques représentent l'utilisateur et le client auquel est destiné le jeton, et ils ne doivent pas être devinable. Pour les jetons d'accès, enregistrez également l'heure d'expiration du jeton, généralement une heure après l'émission du jeton.
5. Renvoyez l'objet JSON suivant dans le corps de la requête réponse:

   {
   "token_type": "Porteur",
   "access_token": "ACCESS_TOKEN",
   "expires_in": SECONDS_TO_EXPIRATION
   }

Remarque :Vous pouvez éventuellement renvoyer un nouveau refresh_token dans votre réponse. Pour Pour en savoir plus sur le renvoi d'un nouveau refresh_token, consultez Utiliser des jetons

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:

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.