Implémenter un serveur OAuth 2.0

Chaque intégration Cloud-to-cloud doit inclure un mécanisme d'authentification des utilisateurs.

L'authentification vous permet d'associer les comptes Google de vos utilisateurs aux comptes utilisateur de votre système d'authentification. Cela vous permet d'identifier vos utilisateurs lorsque votre traitement reçoit une intention de maison connectée. La maison connectée Google n'est compatible qu'avec OAuth et un flux de code d'autorisation.

Cette page explique comment configurer votre serveur OAuth 2.0 pour qu'il fonctionne avec votre intégration Cloud-to-cloud.

Association de comptes Google avec OAuth

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

• Le point de terminaison authorization, 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 à durée de vie limitée pour enregistrer le consentement des utilisateurs à l'accès demandé.

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

  1. Échange un code d'autorisation contre un jeton d'actualisation à longue durée de vie et un jeton d'accès à courte durée de vie. Cet échange se produit lorsque l'utilisateur suit le processus 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 qu'il possédait a expiré.

Principes de conception

Cette section décrit les exigences et les recommandations de conception pour l'écran utilisateur que vous hébergez pour les flux d'association OAuth. Une fois 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 consentement pour associer les comptes.

Conditions requises

1. Vous devez indiquer que le compte de l'utilisateur sera associé à Google, et non à un produit Google spécifique comme Google Home ou l'Assistant Google.
2. Vous devez inclure une déclaration d'autorisation Google, par exemple "En vous connectant, vous autorisez Google à contrôler vos appareils." Consultez la section Autorisation de contrôle des appareils Google des règles Google Home pour les développeurs.
3. Vous devez ouvrir la page d'association Web OAuth et vous assurer que les utilisateurs disposent d'une méthode claire pour se connecter à leur compte Google, par exemple des champs pour leur nom d'utilisateur et leur mot de passe. N'utilisez pas la méthode de connexion Google (GSI) qui permet aux utilisateurs d'associer leur compte sans être redirigés vers la page d'association OAuth Web. Cela constitue un non-respect du règlement de Google.
4. Vous devez inclure au moins l'un des éléments suivants sur la page d'association OAuth pour indiquer l'intégration à laquelle l'utilisateur associe son compte :
   • Logo de l'entreprise
   • Nom de l'entreprise
   • Nom de l'intégration
   • Icône de l'application

Recommandations

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

1. Affichez 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 sont les données dont Google a besoin et pourquoi, ainsi que les données d'utilisation ou d'interaction qui peuvent être partagées avec vous par Google.

3. Incitation à l'action claire : Indiquez clairement l'incitation à l'action 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 : Offrez aux utilisateurs la possibilité de revenir en arrière ou d'annuler s'ils choisissent de ne pas associer leur compte.

5. Processus de connexion clair : Assurez-vous que les utilisateurs disposent d'une méthode claire pour se connecter à leur compte Google, par exemple des champs pour leur nom d'utilisateur et leur mot de passe, ou l'option Se connecter avec Google.

6. Possibilité de dissocier les comptes. Proposez aux utilisateurs un mécanisme pour dissocier leur compte, 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é. Si un utilisateur dissocie son compte de votre intégration, utilisez agentUsers.delete pour informer Google de ce changement.

7. Possibilité de modifier le compte utilisateur Suggérez aux utilisateurs une méthode pour changer de compte. Cela est particulièrement utile si les utilisateurs ont tendance à avoir plusieurs comptes.

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

8. Incluez votre logo. Affichez 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 Logos et marques déposées.

Flux de code d'autorisation

Une implémentation de serveur OAuth 2.0 du flux avec code d'autorisation comprend deux points de terminaison, que votre service met à disposition par le biais du protocole 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 aux 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.

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 démarré sur un appareil à commande vocale uniquement pour une action, Google transfère l'exécution vers un téléphone.
2. L'utilisateur se connecte, s'il n'est pas déjà connecté, 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 avec le code d'autorisation joint à 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 de longue durée 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 flux d'association de compte, chaque requête ultérieure envoyée par Google contient un jeton d'accès.

Gérer les demandes d'autorisation

Lorsque vous devez effectuer l'association de compte à l'aide du flux avec code d'autorisation OAuth 2.0, Google envoie l'utilisateur à votre point de terminaison d'autorisation avec une requête qui inclut les paramètres suivants :

Par exemple, si votre point de terminaison d'autorisation est disponible à l'adresse 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

Pour que votre point de terminaison d'autorisation gère les demandes de connexion, procédez comme suit :

1. Vérifiez que le client_id correspond à l'ID client que vous avez attribué à Google et que le redirect_uri correspond à l'URL de redirection fournie par Google pour votre service. Ces vérifications sont importantes pour éviter d'accorder l'accès à des applications clientes non prévues ou mal configurées. Si vous acceptez plusieurs flux OAuth 2.0, vérifiez également que le response_type est code.
2. Vérifiez si l'utilisateur est connecté à votre service. Si l'utilisateur n'est pas connecté, suivez le flux de connexion ou d'inscription de votre service.
3. Générez un code d'autorisation que Google pourra utiliser pour accéder à votre API. Le code d'autorisation peut être n'importe quelle valeur de chaîne, mais il doit représenter de manière unique l'utilisateur, le client pour lequel le jeton est destiné et l'heure d'expiration du code, et il ne doit pas être devinable. En règle générale, vous émettez des codes d'autorisation qui expirent au bout de 10 minutes environ.
4. Vérifiez que l'URL spécifiée par le paramètre redirect_uri se présente comme suit :

     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 redirect_uri paramètre. Incluez le code d'autorisation que vous venez de générer et la valeur d'état d'origine non modifiée lorsque vous effectuez la redirection en ajoutant les paramètres code et state. Voici un exemple de l'URL résultante :

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

Gérer les demandes d'échange de jetons

Le point de terminaison d'échange de jetons de votre service est responsable de deux types d'échanges de jetons :

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

Les demandes d'échange de jetons incluent les paramètres suivants :

Configurer la façon dont Google envoie les identifiants à votre serveur

Selon son implémentation, votre serveur d'autorisation s'attend à recevoir les identifiants client dans le corps de la requête ou dans l'en-tête de la requête.

Par défaut, Google envoie les identifiants dans le corps de la requête. Si votre serveur d'autorisation exige que les identifiants client figurent dans l'en-tête de la requête, vous devez configurer votre Cloud-to-cloud intégration en conséquence :

Accéder à la Developers Console

1. Dans la liste des projets, cliquez sur Ouvrir à côté du projet sur lequel vous souhaitez travailler.

2. Sous Cloud-à-cloud, sélectionnez Développer.

3. Cliquez sur Ouvrir à côté de votre intégration.

4. Faites défiler la page jusqu'à la section Autorisations (facultatif) , puis cochez la case Demander à Google de transmettre l'ID client et le secret via l'en-tête d'authentification de base HTTP.

5. Cliquez sur Enregistrer pour enregistrer les modifications.

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

Une fois que l'utilisateur s'est connecté et que votre point de terminaison d'autorisation renvoie un code d'autorisation de courte durée à Google, Google envoie une requête à votre point de terminaison d'échange de jetons pour échanger le code d'autorisation contre un jeton d'accès et un jeton d'actualisation.

Pour ces requêtes, la valeur de grant_type est authorization_code, et la valeur de code est la valeur du code d'autorisation que vous avez précédemment accordé à Google. Voici un exemple de requête permettant d'échanger un code d'autorisation contre 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 point de terminaison d'échange de jetons répond aux requêtes POST en procédant comme suit :

1. Vérifiez que le client_id identifie l'origine de la requête comme étant une origine autorisée et que le client_secret correspond à la valeur attendue.
2. Vérifiez que le code d'autorisation est valide et n'a pas expiré, et que l'ID client spécifié dans la requête correspond à l'ID client associé au code 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 demande d'autorisation initiale.
4. Si vous ne parvenez pas à vérifier tous les critères ci-dessus, renvoyez une erreur HTTP 400 "Bad Request" (Requête incorrecte) avec {"error": "invalid_grant"} comme corps.
5. Sinon, utilisez l'ID utilisateur du code d'autorisation pour générer un jeton d'actualisation et un jeton d'accès. Ces jetons peuvent être n'importe quelle valeur de chaîne, mais ils doivent représenter de manière unique l'utilisateur et le client pour lequel le jeton est destiné, et ils ne doivent pas être devinables. Pour les jetons d'accès, enregistrez également l'heure d'expiration du jeton, qui est généralement une heure après l'émission du jeton. 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 enregistre 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 de votre point de terminaison d'échange de jetons.

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

Lorsqu'un jeton d'accès expire, Google envoie une requête à votre point de terminaison d'é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 permettant d'échanger un jeton d'actualisation contre 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 d'échange de jetons répond aux requêtes POST en procédant comme suit :

1. Vérifiez que le client_id identifie l'origine de la requête comme étant Google et que le 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 parvenez pas à vérifier tous les critères ci-dessus, renvoyez une erreur HTTP 400 Bad Request (Requête incorrecte) avec {"error": "invalid_grant"} comme corps.
4. Sinon, utilisez l'ID utilisateur du jeton d'actualisation pour générer un jeton d'accès. Ces jetons peuvent être n'importe quelle valeur de chaîne, mais ils doivent représenter de manière unique l'utilisateur et le client pour lequel le jeton est destiné, et ils ne doivent pas être devinables. Pour les jetons d'accès, enregistrez également l'heure d'expiration du jeton, qui est généralement une heure après l'émission du jeton.
5. Renvoyez l'objet JSON suivant dans le corps de la réponse HTTPS :

   {
   "token_type": "Bearer",
   "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:

• 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é.

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.