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 pour la 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 compte Google avec OAuth

In the authorization code flow, you need two endpoints:

• The authorization endpoint, which presents the sign-in UI to your users that aren't already signed in. The authorization endpoint also creates a short-lived authorization code to record users' consent to the requested access.

• The token exchange endpoint, which is responsible for two types of exchanges:

  1. Exchanges an authorization code for a long-lived refresh token and a short-lived access token. This exchange happens when the user goes through the account linking flow.
  2. Exchanges a long-lived refresh token for a short-lived access token. This exchange happens when Google needs a new access token because the one it had expired.

Design guidelines

This section describes the design requirements and recommendations for the user screen that you host for OAuth linking flows. After it's called by Google's app, your platform displays a sign in to Google page and account linking consent screen to the user. The user is directed back to Google's app after giving their consent to link accounts.

Requirements

1. You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.
2. You must have a Google authorization statement such as "By signing in, you are authorizing Google to control your devices." See the Google Device Control Authorization section of the Google Home Developer Policies.
3. You must open the Web OAuth linking page and ensure users have a clear method for signing in to their Google Account, such as fields for their username and password. Don't use the Google Sign-In (GSI) method that enables users to link without being taken to the Web OAuth Linking page. It is a violation of Google policy.
4. You must include at least one of the following items in the OAuth linking page to indicate the integration to which the user is linking:
   • Company logo
   • Company name
   • Integration name
   • App icon

Recommendations

We recommend that you do the following:

1. Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.

2. Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.

3. Clear call-to-action. State a clear call-to-action on your consent screen, such as “Agree and link.” This is because users need to understand what data they're required to share with Google to link their accounts.

4. Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.

5. Clear sign-in process. Ensure that users have a clear method for signing in to their Google Account, such as fields for their username and password or Sign in with Google.

6. Ability to unlink. Offer a mechanism for users to unlink, such as a URL to their account settings on your platform. Alternatively, you can include a link to Google Account where users can manage their linked account.

7. Ability to change user account. Suggest a method for users to switch their account(s). This is especially beneficial if users tend to have multiple accounts.

   • If a user must close the consent screen to switch accounts, send a recoverable error to Google so the user can sign in to the desired account with OAuth linking.

8. Include your logo. Display your company logo on the consent screen. Use your style guidelines to place your logo. If you wish to also display Google's logo, see Logos and trademarks.

Flux de code d'autorisation

Une implémentation de serveur OAuth 2.0 du flux de code d'autorisation se compose de deux points de terminaison que votre service met à disposition par 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 à vos 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 commencé sur un appareil vocal uniquement pour une Action, Google transfère l'exécution vers un téléphone.
2. L'utilisateur se connecte, s'il ne l'a pas déjà fait, 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 en joignant le code d'autorisation à 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 à longue durée de vie 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 parcours 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 associer un compte à l'aide du flux de code d'autorisation OAuth 2.0, Google redirige l'utilisateur vers 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 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 éviter d'accorder l'accès à des applications clientes non prévues ou mal configurées. Si vous êtes compatible avec 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 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 le délai d'expiration du code, et il ne doit pas être devinable. En général, 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 au format suivant :

     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 redirigez en ajoutant les paramètres code et state. Voici un exemple d'URL obtenue :

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

Traiter 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 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 du client dans le corps ou 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 du client figurent dans l'en-tête de la requête, vous devez configurer votre intégration Cloud-to-cloud en conséquence :

Accéder à la console pour les développeurs

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 code 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 d'actualisation

Une fois que l'utilisateur s'est connecté et que votre point de terminaison d'autorisation renvoie un code d'autorisation temporaire à 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 correspond à 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 exécutant les étapes suivantes :

1. Vérifiez que client_id identifie l'origine de la requête comme une origine autorisée et que 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 pouvez pas valider tous les critères ci-dessus, renvoyez une erreur HTTP 400 "Bad Request" (Mauvaise requête) 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 leur délai d'expiration, qui est généralement d'une heure après leur émission. Les jetons d'actualisation n'expirent pas.
6. Renvoie 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 de 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 correspond à 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 exécutant les étapes suivantes :

1. Vérifiez que client_id identifie Google comme origine de la requête 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 valider tous les critères ci-dessus, renvoyez une erreur HTTP 400 "Bad Request" (Mauvaise requête) 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 correspondre à n'importe quelle valeur de chaîne, mais ils doivent représenter de manière unique l'utilisateur et le client pour lesquels le jeton est destiné, et ils ne doivent pas être devinables. Pour les jetons d'accès, enregistrez également leur délai d'expiration, généralement une heure après leur émission.
5. Renvoie l'objet JSON suivant dans le corps de la réponse HTTPS :

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

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:

• Linked Account Sign-In with Google One Tap.
• Frictionless subscription on AndroidTV.

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.

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.