Implémenter un serveur OAuth 2.0

Chaque action smart home doit inclure un mécanisme d'authentification des utilisateurs.

L'authentification vous permet d'associer les comptes Google de vos utilisateurs à ceux de votre système d'authentification. Cela vous permet d'identifier vos utilisateurs lorsque votre traitement reçoit un intent de maison connectée. Google Smart Home n'est compatible qu'avec OAuth avec un flux avec code d'autorisation.

Cette page explique comment configurer votre serveur OAuth 2.0 pour qu'il fonctionne avec votre action smart home.

Association du compte Google avec OAuth

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

  • Le point de terminaison d'autorisation, qui présente l'interface de connexion aux utilisateurs qui ne sont pas déjà 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 d'é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 flux d'association de compte.
    2. Échange un jeton d'actualisation de longue durée contre un jeton d'accès de courte durée. Cet échange se produit lorsque Google a besoin d'un nouveau jeton d'accès, car celui-ci a expiré.

Consignes de conception

Cette section décrit les exigences de conception et les recommandations 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 à l'utilisateur une page de connexion à la page Google et un écran de consentement pour l'association de compte. L'utilisateur est redirigé vers l'application Google après avoir accepté d'associer les comptes.

Cette figure montre la procédure à suivre par un utilisateur pour associer son compte Google à votre système d'authentification. La première capture d'écran montre l'association déclenchée par l'utilisateur depuis votre plate-forme. La deuxième image montre que l'utilisateur se connecte à Google, tandis que la troisième montre l'autorisation et la confirmation de l'association de son compte Google à votre application. La capture d'écran finale montre que le compte utilisateur a bien été associé dans l'appli Google.
Figure 1 : L'utilisateur pour l'association de comptes se connecte à Google et aux é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, comme Google Home ou l'Assistant Google.
  2. Vous devez disposer d'une déclaration d'autorisation Google telle que "En vous connectant, vous autorisez Google à contrôler vos appareils". Consultez la section Autorisation du contrôle des appareils Google du règlement pour les développeurs Google Home.
  3. Vous devez permettre aux utilisateurs de revenir en arrière ou de résilier l'abonnement s'ils choisissent de ne pas effectuer l'association.
  4. Vous devez ouvrir la page d'association Web avec OAuth et vous assurer que les utilisateurs disposent d'une méthode claire pour se connecter à leur compte Google, telle que des champs pour leur nom d'utilisateur et leur mot de passe. N'utilisez pas la méthode Google Sign-In (GSI) qui permet aux utilisateurs d'effectuer une association sans être redirigés vers la page "Association Web OAuth". Cela constitue un non-respect des règles de Google.

Recommandations

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

  1. Afficher les règles de confidentialité de Google Ajoutez 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 sont requises par Google et pourquoi.

  3. Incitation à l'action claire. Spécifiez 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é de dissocier des comptes. Proposez 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 un compte Google permettant aux utilisateurs de gérer leur compte associé.

  5. Possibilité de changer de 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 à Google une erreur récupérable afin qu'il puisse se connecter au compte souhaité à l'aide de l'association OAuth.
  6. 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.

Flux avec le code d'autorisation

Une mise en œuvre OAuth 2.0 du flux de code d'autorisation sur le serveur comprend deux points de terminaison, qui sont accessibles par le protocole HTTPS. Le premier est le point de terminaison de l'autorisation, qui est responsable de la recherche ou de l'obtention du consentement des utilisateurs pour l'accès aux données. Le point de terminaison de l'autorisation présente une interface de connexion aux utilisateurs qui ne sont pas déjà connectés et enregistre l'accès demandé. Le second point de terminaison est le point de terminaison d'échange de jetons, qui permet d'obtenir des chaînes chiffrées, appelées jetons, qui permettent à un utilisateur d'accéder à votre service.

Lorsqu'une application Google doit appeler l'une des API de votre service, Google utilise ces points de terminaison conjointement pour obtenir l'autorisation des utilisateurs afin qu'ils appellent ces API en leur nom.

Une session de flux de code d'autorisation OAuth 2.0 lancée par Google présente le flux suivant:

  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 sur un téléphone.
  2. L'utilisateur se connecte, s'il ne l'est pas déjà, 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 associé à la requête.
  4. Google envoie le code d'autorisation au point de terminaison d'échange de jetons, qui valide 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 identifiants 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 comptes, chaque requête envoyée par Google contient un jeton d'accès.

Gérer les demandes d'autorisation

Lorsque vous devez associer des comptes à l'aide du flux de code d'autorisation OAuth 2.0, Google envoie l'utilisateur à votre point de terminaison d'autorisation avec une requête incluant les paramètres suivants:

Paramètres du point de terminaison d'autorisation
client_id ID client que vous avez attribué à Google.
redirect_uri URL à laquelle vous envoyez la réponse à cette requête.
state Valeur de tenue de registre transmise à Google telle quelle dans l'URI de redirection.
scope Facultatif:ensemble de chaînes de champs d'application (séparées par un espace) spécifiant les données pour lesquelles Google demande une autorisation.
response_type Type de valeur à afficher dans la réponse. Pour le flux de code d'autorisation OAuth 2.0, le type de réponse est toujours code.
user_locale Paramètre de langue du compte Google au format RFC5646, utilisé pour localiser le contenu dans la langue préférée de l'utilisateur.

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

  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 souhaitées ou mal configurées. Si vous acceptez plusieurs 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é, suivez la procédure 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 correspondre à n'importe quelle valeur de chaîne, mais il doit représenter de manière unique l'utilisateur, le client auquel le jeton est destiné et le délai d'expiration du code. Il ne doit pas être devinable. Les codes d'autorisation expirent généralement au bout de 10 minutes environ.
  4. Vérifiez que l'URL spécifiée par le paramètre redirect_uri se présente sous la forme suivante :
      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 redirect_uri. 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 une redirection en ajoutant les paramètres code et state. Voici un 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 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 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 des points de terminaison d'échange de jetons
client_id Chaîne identifiant Google comme origine de la requête. Cette chaîne doit être enregistrée 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 en cours d'échange. authorization_code ou refresh_token.
code Lorsque grant_type=authorization_code est défini, il s'agit du code que Google a reçu de votre point de terminaison de connexion ou d'échange de jetons.
redirect_uri Lorsque grant_type=authorization_code, il s'agit de l'URL utilisée dans la requête d'autorisation initiale.
refresh_token Lorsque grant_type=refresh_token est défini, il s'agit du jeton d'actualisation reçu par Google de votre point de terminaison d'échange de jetons.

Échanger 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 à Google un code d'autorisation temporaire, Google envoie une requête au 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 d'échange d'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, le point de terminaison de votre jeton d'échange répond aux requêtes POST en exécutant les étapes suivantes:

  1. Vérifiez que client_id identifie l'origine de la requête en tant qu'origine autorisée 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é. Vérifiez également que l'ID client spécifié dans la requête correspond à celui 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 requête d'autorisation initiale.
  4. Si vous ne pouvez pas vérifier tous les critères ci-dessus, renvoyez une erreur HTTP 400 Bad Request avec le corps {"error": "invalid_grant"}.
  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 correspondre à n'importe quelle valeur de chaîne, mais ils doivent représenter de manière unique l'utilisateur et le client auxquels le jeton est destiné. Ils ne doivent pas être devinables. Pour les jetons d'accès, notez également le délai d'expiration du jeton (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 l'utilise pour obtenir un nouveau jeton d'accès auprès du 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.

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 précédemment accordé à Google. Voici un exemple de requête d'échange d'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 client_id identifie l'origine de la requête en tant que Google et 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 Bad Bad avec le corps {"error": "invalid_grant"}.
  4. Sinon, utilisez l'ID utilisateur du jeton d'actualisation pour générer un jeton d'accès. Ces jetons peuvent correspondre à n'importe quelle valeur de chaîne, mais ils doivent représenter l'utilisateur et le client auxquels le jeton est destiné. Ils ne doivent pas être devinables. Pour les jetons d'accès, notez également le délai 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 réponse HTTPS:
    {token&typeSECONDS_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 des revendications au sujet de l'utilisateur associé. L'implémentation et l'hébergement du point de terminaison userinfo sont facultatifs, sauf pour les cas d'utilisation suivants:

Une fois que le jeton d'accès a été récupéré depuis le point de terminaison de votre jeton, Google envoie une requête à ce dernier pour récupérer les informations de profil de base de l'utilisateur associé.

En-têtes de requêtes 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, votre 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, une erreur HTTP 401 (non autorisé) est renvoyée avec l'en-tête de réponse WWW-Authenticate. Vous trouverez ci-dessous 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"Non autorisé"ou toute autre réponse infructueuse 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 le message et la réponse HTTP 200 avec l'objet JSON suivant dans le corps de la réponse HTTPS:

    {
    "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 HTTP 200, le jeton et les revendications récupérés sont enregistrés dans 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.