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.
In the implicit flow, Google opens your authorization endpoint in the user's browser. After successful sign in, you return a long-lived access token to Google. This access token is now included in every request sent from Google.
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:
- 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.
- 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.
Choose an OAuth 2.0 flow
Although the implicit flow is simpler to implement, Google recommends that access tokens issued by the implicit flow never expire. This is because the user is forced to link their account again after a token expires with the implicit flow. If you need token expiration for security reasons, we strongly recommend that you use the authorization code flow instead.
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
- You must communicate that the user’s account will be linked to Google, not a specific Google product like Google Home or Google Assistant.
Recommendations
We recommend that you do the following:
Display Google's Privacy Policy. Include a link to Google’s Privacy Policy on the consent screen.
Data to be shared. Use clear and concise language to tell the user what data of theirs Google requires and why.
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.
Ability to cancel. Provide a way for users to go back or cancel, if they choose not to link.
Clear sign-in process. Ensure that users have clear method for signing in to their Google account, such as fields for their username and password or Sign in with Google.
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.
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 and the implicit flow.
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.

Create the project
To create your project to use account linking:
Configure your OAuth Consent Screen
The Google Account Linking process includes a consent screen which tells users the application requesting access to their data, what kind of data they are asking for and the terms that apply. You will need to configure your OAuth consent screen before generating a Google API client ID.
- Open the OAuth consent screen page of the Google APIs console.
- If prompted, select the project you just created.
On the "OAuth consent screen" page, fill out the form and click the “Save” button.
Application name: The name of the application asking for consent. The name should accurately reflect your application and be consistent with the application name users see elsewhere. The application name will be shown on the Account Linking consent screen.
Application logo: An image on the consent screen that will help users recognize your app. The logo is shown on Account linking consent screen and on account settings
Support email: For users to contact you with questions about their consent.
Scopes for Google APIs: Scopes allow your application to access your user's private Google data. For the Google Account Linking use case, default scope (email, profile, openid) is sufficient, you don’t need to add any sensitive scopes. It is generally a best practice to request scopes incrementally, at the time access is required, rather than up front. Learn more.
Authorized domains: To protect you and your users, Google only allows applications that authenticate using OAuth to use Authorized Domains. Your applications' links must be hosted on Authorized Domains. Learn more.
Application Homepage link: Home page for your application. Must be hosted on an Authorized Domain.
Application Privacy Policy link: Shown on Google Account Linking consent screen. Must be hosted on an Authorized Domain.
Application Terms of Service link (Optional): Must be hosted on an Authorized Domain.
Figure 1. Google Account Linking Consent Screen for a fictitious Application, Tunery
Check "Verification Status", if your application needs verification then click the "Submit For Verification" button to submit your application for verification. Refer to OAuth verification requirements for details.
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:
- 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.
- 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é.
- 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.
- 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.
- 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:
- Vérifiez que
client_id
correspond à l'ID client que vous avez attribué à Google et queredirect_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 queresponse_type
est défini surcode
. - 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.
- 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.
- 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 - 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ètrescode
etstate
. 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:
- Vérifiez que
client_id
identifie l'origine de la requête comme étant autorisée l'origine et queclient_secret
correspond à la valeur attendue. - 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.
- 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. - 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. - 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.
- 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:
- Vérifiez que
client_id
identifie l'origine de la requête comme étant Google. queclient_secret
correspond à la valeur attendue. - 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.
- 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. - 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.
- 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
}
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:
- 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.
- 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: 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.HTTP/1.1 401 Unauthorized WWW-Authenticate: error="invalid_token", error_description="The Access Token expired"
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:
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.{
"sub": "USER_UUID ",
"email": "EMAIL_ADDRESS ",
"given_name": "FIRST_NAME ",
"family_name": "LAST_NAME ",
"name": "FULL_NAME ",
"picture": "PROFILE_PICTURE ",
}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
You can validate your implementation by using the OAuth 2.0 Playground tool.
In the tool, do the following steps:
- Click Configuration to open the OAuth 2.0 Configuration window.
- In the OAuth flow field, select Client-side.
- In the OAuth Endpoints field, select Custom.
- Specify your OAuth 2.0 endpoint and the client ID you assigned to Google in the corresponding fields.
- In the Step 1 section, don't select any Google scopes. Instead, leave this field blank or type a scope valid for your server (or an arbitrary string if you don't use OAuth scopes). When you're done, click Authorize APIs.
- In the Step 2 and Step 3 sections, go through the OAuth 2.0 flow and verify that each step works as intended.
You can validate your implementation by using the Google Account Linking Demo tool.
In the tool, do the following steps:
- Click the Sign-in with Google button.
- Choose the account you'd like to link.
- Enter the service ID.
- Optionally enter one or more scopes that you will request access for.
- Click Start Demo.
- When prompted, confirm that you may consent and deny the linking request.
- Confirm that you are redirected to your platform.