OpenID Connect

Les API OAuth 2.0 de Google peuvent être utilisées pour l'authentification et l'autorisation. Ce document décrit notre mise en œuvre OAuth 2.0 pour l'authentification, conforme à la spécification OpenID Connect et certifiée OpenID. La documentation Utiliser OAuth 2.0 pour accéder aux API Google s'applique également à ce service. Si vous souhaitez explorer ce protocole de manière interactive, nous vous recommandons de consulter Google OAuth 2.0 Playground. Pour obtenir de l'aide sur Stack Overflow, ajoutez le tag "google-oauth" à vos questions.

Configurer OAuth 2.0

Pour que votre application puisse utiliser le système d'authentification OAuth 2.0 de Google pour la connexion des utilisateurs, vous devez configurer un projet dans Google API Console afin d'obtenir des identifiants OAuth 2.0, de définir un URI de redirection et (éventuellement) de personnaliser les informations de branding que vos utilisateurs verront sur l'écran de consentement. Vous pouvez également utiliser l' API Console pour créer un compte de service, activer la facturation, configurer le filtrage et effectuer d'autres tâches. Pour en savoir plus, consultez l'aideGoogle API Console.

Obtenir les identifiants OAuth 2.0

Vous avez besoin d'identifiants OAuth 2.0, y compris un ID et un code secret du client, pour authentifier les utilisateurs et accéder aux API Google.

Pour afficher l'ID client et le secret client pour une information d'identification OAuth 2.0 donnée, cliquez sur le texte suivant: Sélectionnez les informations d'identification . Dans la fenêtre qui s'ouvre, choisissez votre projet et les informations d'identification souhaitées, puis cliquez sur Afficher .

Ou affichez votre ID client et votre secret client sur la page API Console identification dans API Console :

  1. Go to the Credentials page.
  2. Cliquez sur le nom de vos informations d'identification ou sur l'icône en forme de crayon ( ). Votre identifiant client et votre secret sont en haut de la page.

Définir un URI de redirection

L'URI de redirection que vous définissez dans API Console détermine l'endroit où Google envoie les réponses à vos requêtes d'authentification.

Pour créer, afficher ou modifier les URI de redirection pour une information d'identification OAuth 2.0 donnée, procédez comme suit:

  1. Go to the Credentials page.
  2. Dans la section ID client OAuth 2.0 de la page, cliquez sur une information d'identification.
  3. Affichez ou modifiez les URI de redirection.

S'il n'y a pas de section ID client OAuth 2.0 sur la page Informations d'identification, votre projet n'a pas d'informations d'identification OAuth. Pour en créer un, cliquez sur Créer des informations d'identification .

Personnaliser l'écran de consentement des utilisateurs

Pour vos utilisateurs, l'expérience d'authentification OAuth 2.0 comprend un écran de consentement qui décrit les informations que l'utilisateur publie et les conditions qui s'appliquent. Par exemple, lorsque l'utilisateur se connecte, il peut être invité à autoriser votre application à accéder à son adresse e-mail et aux informations de base de son compte. Vous demandez l'accès à ces informations à l'aide du paramètre scope, que votre application inclut dans sa requête d'authentification. Vous pouvez également utiliser les niveaux d'accès pour demander l'accès à d'autres API Google.

L'écran de consentement de l'utilisateur présente également des informations de branding telles que le nom et le logo de votre produit, ainsi qu'une URL de page d'accueil. Vous contrôlez les informations de branding dans les API Console.

Pour activer l'écran de consentement de votre projet:

  1. Ouvrez le Consent Screen page dans le Google API Console .
  2. If prompted, select a project, or create a new one.
  3. Remplissez le formulaire et cliquez sur Enregistrer .

La boîte de dialogue de collecte du consentement suivante montre ce qu'un utilisateur voit lorsque la requête contient une combinaison de champs d'application OAuth 2.0 et Google Drive. (Cette boîte de dialogue générique a été générée à l'aide de Google OAuth 2.0 Playground. Elle n'inclut donc pas les informations de branding qui seraient définies dans le API Console.)

Capture d'écran de la page de consentement

Accéder au service

Google et des tiers fournissent des bibliothèques qui vous permettent de gérer de nombreux aspects de la mise en œuvre de l'authentification des utilisateurs et de l'accès aux API Google. Exemples : Google Identity Services et les bibliothèques clientes Google, disponibles pour diverses plates-formes.

Si vous choisissez de ne pas utiliser de bibliothèque, suivez les instructions dans la suite de ce document, qui décrivent les flux de requêtes HTTP sous-jacents aux bibliothèques disponibles.

Authentifier l'utilisateur

L'authentification de l'utilisateur implique l'obtention d'un jeton d'identification et la validation. Les jetons d'ID sont une fonctionnalité standardisée d'OpenID Connect. Ils sont conçus pour être utilisés pour partager des assertions d'identité sur Internet.

Les approches les plus couramment utilisées pour authentifier un utilisateur et obtenir un jeton d'identification sont appelées flux "serveur" et flux "implicite". Le flux serveur permet au serveur backend d'une application de vérifier l'identité de la personne à l'aide d'un navigateur ou d'un appareil mobile. Le flux implicite est utilisé lorsqu'une application côté client (généralement une application JavaScript exécutée dans le navigateur) doit accéder aux API directement plutôt que via son serveur backend.

Ce document décrit comment exécuter le flux de serveur pour authentifier l'utilisateur. Le flux implicite est beaucoup plus compliqué en raison des risques de sécurité liés au traitement et à l'utilisation des jetons côté client. Si vous devez implémenter un flux implicite, nous vous recommandons vivement d'utiliser les Google Identity Services.

Flux du serveur

Veillez à configurer votre application dans API Console pour lui permettre d'utiliser ces protocoles et d'authentifier vos utilisateurs. Lorsqu'un utilisateur tente de se connecter avec Google, procédez comme suit:

  1. Créer un jeton d'état anti-falsification
  2. Envoyer une demande d'authentification à Google
  3. Confirmer le jeton d'état anti-falsification
  4. Échangez code contre un jeton d'accès et un jeton d'ID
  5. Obtenir des informations utilisateur à partir du jeton d'ID
  6. Authentifier l'utilisateur

1. Créer un jeton d'état anti-falsification

Vous devez protéger la sécurité de vos utilisateurs en empêchant les attaques par falsification de requêtes. La première étape consiste à créer un jeton de session unique qui contient l'état entre votre application et le client de l'utilisateur. Vous associez ensuite ce jeton de session unique à la réponse d'authentification renvoyée par le service de connexion Google OAuth pour vérifier que l'utilisateur effectue la requête et non un pirate informatique malveillant. Ces jetons sont souvent appelés "jetons de falsification de requêtes intersites" (CSRF).

Un bon choix pour un jeton d'état est une chaîne d'environ 30 caractères construite à l'aide d'un générateur de nombres aléatoires de haute qualité. Un autre est un hachage généré en signant certaines de vos variables d'état de session avec une clé gardée secrète sur votre backend.

Le code suivant illustre la génération de jetons de session uniques.

PHP

Vous devez télécharger la bibliothèque cliente des API Google pour PHP pour utiliser cet exemple.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
$state = bin2hex(random_bytes(128/8));
$app['session']->set('state', $state);
// Set the client ID, token state, and application name in the HTML while
// serving it.
return $app['twig']->render('index.html', array(
    'CLIENT_ID' => CLIENT_ID,
    'STATE' => $state,
    'APPLICATION_NAME' => APPLICATION_NAME
));

Java

Vous devez télécharger la bibliothèque cliente des API Google pour Java pour utiliser cet exemple.

// Create a state token to prevent request forgery.
// Store it in the session for later validation.
String state = new BigInteger(130, new SecureRandom()).toString(32);
request.session().attribute("state", state);
// Read index.html into memory, and set the client ID,
// token state, and application name in the HTML before serving it.
return new Scanner(new File("index.html"), "UTF-8")
    .useDelimiter("\\A").next()
    .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID)
    .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state)
    .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}",
    APPLICATION_NAME);

Python

Vous devez télécharger la bibliothèque cliente des API Google pour Python pour utiliser cet exemple.

# Create a state token to prevent request forgery.
# Store it in the session for later validation.
state = hashlib.sha256(os.urandom(1024)).hexdigest()
session['state'] = state
# Set the client ID, token state, and application name in the HTML while
# serving it.
response = make_response(
    render_template('index.html',
                    CLIENT_ID=CLIENT_ID,
                    STATE=state,
                    APPLICATION_NAME=APPLICATION_NAME))

2. Envoyer une demande d'authentification à Google

L'étape suivante consiste à créer une requête HTTPS GET avec les paramètres URI appropriés. Notez l'utilisation du protocole HTTPS plutôt que HTTP dans toutes les étapes de ce processus, car les connexions HTTP sont refusées. Vous devez récupérer l'URI de base du document de découverte à l'aide de la valeur de métadonnées authorization_endpoint. La discussion suivante suppose que l'URI de base est https://accounts.google.com/o/oauth2/v2/auth.

Pour une requête de base, spécifiez les paramètres suivants:

  • client_id, que vous obtenez à partir de la Credentials pagede API Console.
  • response_type, qui, dans une requête de flux de code d'autorisation de base, doit être code. Pour en savoir plus, consultez la page response_type.
  • scope, qui dans une requête de base devrait être openid email. Pour en savoir plus, consultez scope.
  • redirect_uri doit être le point de terminaison HTTP de votre serveur qui recevra la réponse de Google. La valeur doit correspondre exactement à l'un des URI de redirection autorisés pour le client OAuth 2.0, que vous avez configuré dans API Console Credentials page. Si cette valeur ne correspond à aucun URI autorisé, la requête échoue et renvoie une erreur redirect_uri_mismatch.
  • state doit inclure la valeur du jeton de session unique anti-falsification, ainsi que toute autre information nécessaire pour récupérer le contexte lorsque l'utilisateur revient dans votre application (par exemple, l'URL de démarrage). Pour en savoir plus, consultez state.
  • nonce est une valeur aléatoire générée par votre application qui active la protection contre la relecture, le cas échéant.
  • login_hint peut être l'adresse e-mail de l'utilisateur ou la chaîne sub, qui équivaut à l'ID Google de l'utilisateur. Si vous ne fournissez pas de login_hint et que l'utilisateur est actuellement connecté, l'écran de consentement inclut une demande d'autorisation pour la libération de l'adresse e-mail de l'utilisateur dans votre application. (Pour en savoir plus, consultez la page login_hint.)
  • Utilisez le paramètre hd afin d'optimiser le flux OpenID Connect pour les utilisateurs d'un domaine spécifique associé à une organisation Google Workspace ou Cloud (pour en savoir plus, consultez la page hd).

Voici un exemple d'URI d'authentification OpenID Connect complet, avec des sauts de ligne et des espaces pour une meilleure lisibilité:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//oauth2.example.com/code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=jsmith@example.com&
 nonce=0394852-3190485-2490358&
 hd=example.com

Les utilisateurs sont tenus de donner leur consentement si votre application demande de nouvelles informations les concernant ou si votre application demande l'accès à un compte qu'ils n'ont pas précédemment approuvés.

3. Confirmer le jeton d'état anti-falsification

La réponse est envoyée au redirect_uri que vous avez spécifié dans la requête. Toutes les réponses sont renvoyées dans la chaîne de requête, comme indiqué ci-dessous:

https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email

Sur le serveur, vous devez confirmer que la valeur state envoyée par Google correspond au jeton de session que vous avez créé à l'étape 1. Cette vérification aller-retour permet de s'assurer que c'est bien l'utilisateur, et non un script malveillant, qui est à l'origine de la requête.

Le code suivant montre comment confirmer les jetons de session que vous avez créés à l'étape 1:

PHP

Vous devez télécharger la bibliothèque cliente des API Google pour PHP pour utiliser cet exemple.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if ($request->get('state') != ($app['session']->get('state'))) {
  return new Response('Invalid state parameter', 401);
}

Java

Vous devez télécharger la bibliothèque cliente des API Google pour Java pour utiliser cet exemple.

// Ensure that there is no request forgery going on, and that the user
// sending us this connect request is the user that was supposed to.
if (!request.queryParams("state").equals(
    request.session().attribute("state"))) {
  response.status(401);
  return GSON.toJson("Invalid state parameter.");
}

Python

Vous devez télécharger la bibliothèque cliente des API Google pour Python pour utiliser cet exemple.

# Ensure that the request is not a forgery and that the user sending
# this connect request is the expected user.
if request.args.get('state', '') != session['state']:
  response = make_response(json.dumps('Invalid state parameter.'), 401)
  response.headers['Content-Type'] = 'application/json'
  return response

4. Échangez code contre un jeton d'accès et un jeton d'ID

La réponse inclut un paramètre code, un code d'autorisation unique que votre serveur peut échanger contre un jeton d'accès et un jeton d'ID. Votre serveur effectue cet échange en envoyant une requête HTTPS POST. La requête POST est envoyée au point de terminaison du jeton, que vous devez récupérer à partir du document de découverte à l'aide de la valeur de métadonnées token_endpoint. La discussion suivante suppose que le point de terminaison est https://oauth2.googleapis.com/token. La requête doit inclure les paramètres suivants dans le corps POST:

Champs
code Code d'autorisation renvoyé par la requête initiale.
client_id ID client obtenu à partir de API Console Credentials page, comme décrit dans la section Obtenir des identifiants OAuth 2.0.
client_secret Code secret du client obtenu à partir de API Console Credentials page, comme décrit dans la section Obtenir des identifiants OAuth 2.0.
redirect_uri URI de redirection autorisé pour le client_id donné et spécifié dans le API Console Credentials page, comme décrit dans la section Définir un URI de redirection.
grant_type Ce champ doit contenir la valeur authorization_code comme défini dans la spécification OAuth 2.0.

La requête réelle peut se présenter comme suit:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your-client-id&
client_secret=your-client-secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Une réponse réussie à cette requête contient les champs suivants dans un tableau JSON:

Champs
access_token Un jeton qui peut être envoyé à une API Google.
expires_in Durée de vie restante du jeton d'accès en secondes.
id_token JWT contenant des informations sur l'identité de l'utilisateur signée numériquement par Google.
scope Niveaux d'accès accordés par access_token, exprimés sous la forme d'une liste de chaînes sensibles à la casse et séparées par des espaces.
token_type Identifie le type de jeton renvoyé. Pour le moment, ce champ comporte toujours la valeur Bearer.
refresh_token (facultatif)

Ce champ n'est présent que si le paramètre access_type a été défini sur offline dans la requête d'authentification. Pour en savoir plus, consultez la section Jetons d'actualisation.

5. Obtenir des informations sur l'utilisateur à partir du jeton d'ID

Un jeton d'ID est un JWT (jeton Web JSON), c'est-à-dire un objet JSON encodé en base64 avec signature cryptographique. Normalement, il est essentiel de valider un jeton d'ID avant de l'utiliser. Toutefois, étant donné que vous communiquez directement avec Google via un canal HTTPS sans intermédiaire et que vous utilisez votre code secret de client pour vous authentifier auprès de Google, vous pouvez être sûr que le jeton que vous recevez provient réellement de Google et qu'il est valide. Si votre serveur transmet le jeton d'ID à d'autres composants de votre application, il est extrêmement important que ces autres composants valident le jeton avant de l'utiliser.

Étant donné que la plupart des bibliothèques d'API combinent la validation au décodage des valeurs encodées en base64url et à l'analyse du JSON qu'elles contiennent, vous finirez probablement par valider le jeton lorsque vous accéderez aux revendications du jeton d'ID.

La charge utile d'un jeton d'ID

Un jeton d'identification est un objet JSON contenant un ensemble de paires nom/valeur. Voici un exemple, mis en forme pour une meilleure lisibilité:

{
  "iss": "https://accounts.google.com",
  "azp": "1234987819200.apps.googleusercontent.com",
  "aud": "1234987819200.apps.googleusercontent.com",
  "sub": "10769150350006150715113082367",
  "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q",
  "hd": "example.com",
  "email": "jsmith@example.com",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Les jetons d'ID Google peuvent contenir les champs suivants (appelés revendications):

Revendication Fourni Description
aud toujours Audience à laquelle ce jeton d'ID est destiné. Il doit s'agir de l'un des ID client OAuth 2.0 de votre application.
exp toujours Délai d'expiration après lequel le jeton d'ID ne doit pas être accepté. Représenté en temps Unix (nombre entier de secondes).
iat toujours Heure à laquelle le jeton d'ID a été émis. Représenté en temps Unix (nombre entier de secondes).
iss toujours Identifiant de l'émetteur de la réponse. Toujours https://accounts.google.com ou accounts.google.com pour les jetons d'ID Google.
sub toujours Identifiant de l'utilisateur, unique parmi tous les comptes Google et jamais réutilisé. Un compte Google peut avoir plusieurs adresses e-mail à différents moments, mais la valeur sub n'est jamais modifiée. Utilisez sub dans votre application comme clé d'identifiant unique pour l'utilisateur. Longueur maximale de 255 caractères ASCII sensibles à la casse.
at_hash Hachage du jeton d'accès. Fournit une validation confirmant que le jeton d'accès est lié au jeton d'identité. Si le jeton d'ID est émis avec une valeur access_token dans le flux du serveur, cette revendication est toujours incluse. Cette revendication peut être utilisée comme un autre mécanisme de protection contre les attaques par falsification de requêtes intersites, mais si vous suivez les étapes 1 et l'étape 3, il n'est pas nécessaire de valider le jeton d'accès.
azp client_id du présentateur autorisé. Cette revendication n'est nécessaire que lorsque la partie qui demande le jeton d'ID n'est pas la même que l'audience du jeton d'ID. Cela peut être le cas chez Google pour les applications hybrides où une application Web et une application Android ont une client_id OAuth 2.0 différente, mais partagent le même projet d'API Google.
email Adresse e-mail de l'utilisateur. Fourni uniquement si vous avez inclus le champ d'application email dans votre requête. Il est possible que la valeur de cette réclamation ne soit pas propre à ce compte et qu'elle soit susceptible d'évoluer au fil du temps. Vous ne devez donc pas l'utiliser comme identifiant principal à associer à votre dossier utilisateur. Vous ne pouvez pas non plus vous fier au domaine de la revendication email pour identifier les utilisateurs d'organisations Google Workspace ou Cloud. Utilisez plutôt la revendication hd.
email_verified "True" si l'adresse e-mail de l'utilisateur a été vérifiée ; sinon "false".
family_name Noms de famille ou noms de famille de l'utilisateur. Peut être fourni lorsqu'une revendication name est présente.
given_name Noms ou prénoms de l'utilisateur. Peut être fourni lorsqu'une revendication name est présente.
hd Domaine associé à l'organisation Google Workspace ou Cloud de l'utilisateur Fourni uniquement si l'utilisateur appartient à une organisation Google Cloud. Vous devez vérifier cette revendication lorsque vous restreignez l'accès à une ressource aux seuls membres de certains domaines. L'absence de cette revendication indique que le compte n'appartient pas à un domaine hébergé par Google.
locale Les paramètres régionaux de l'utilisateur, représentés par une balise de langue BCP 47. Peut être fourni lorsqu'une revendication name est présente.
name Nom complet de l'utilisateur, sous une forme affichable. Peut être fourni dans les cas suivants :
  • Le champ d'application de la requête incluait la chaîne "profile"
  • Le jeton d'ID est renvoyé lors de l'actualisation d'un jeton

Lorsque des revendications name sont présentes, vous pouvez les utiliser pour mettre à jour les enregistrements utilisateur de votre application. Notez que la présence de cette revendication n'est jamais garantie.

nonce Valeur de nonce fournie par votre application dans la requête d'authentification. Vous devez appliquer une protection contre les attaques par rejeu en vous assurant qu'elle n'est présentée qu'une seule fois.
picture URL de la photo de profil de l'utilisateur. Peut être fourni dans les cas suivants :
  • Le champ d'application de la requête incluait la chaîne "profile"
  • Le jeton d'ID est renvoyé lors de l'actualisation d'un jeton

Lorsque des revendications picture sont présentes, vous pouvez les utiliser pour mettre à jour les enregistrements utilisateur de votre application. Notez que la présence de cette revendication n'est jamais garantie.

profile URL de la page du profil de l'utilisateur. Peut être fourni dans les cas suivants :
  • Le champ d'application de la requête incluait la chaîne "profile"
  • Le jeton d'ID est renvoyé lors de l'actualisation d'un jeton

Lorsque des revendications profile sont présentes, vous pouvez les utiliser pour mettre à jour les enregistrements utilisateur de votre application. Notez que la présence de cette revendication n'est jamais garantie.

6. Authentifier l'utilisateur

Après avoir obtenu des informations sur l'utilisateur à partir du jeton d'ID, vous devez interroger la base de données utilisateur de votre application. Si l'utilisateur existe déjà dans votre base de données, vous devez démarrer une session d'application pour cet utilisateur si la réponse de l'API Google répond à toutes les conditions de connexion.

Si l'utilisateur n'existe pas dans votre base de données, vous devez le rediriger vers votre parcours d'inscription. Vous pouvez enregistrer automatiquement l'utilisateur sur la base des informations que vous recevez de Google ou, au minimum, préremplir de nombreux champs obligatoires de votre formulaire d'inscription. En plus des informations contenues dans le jeton d'ID, vous pouvez obtenir des informations de profil utilisateur supplémentaires sur les points de terminaison de nos profils utilisateur.

Rubriques avancées

Les sections suivantes décrivent l'API Google OAuth 2.0 plus en détail. Ces informations sont destinées aux développeurs ayant des exigences avancées en matière d'authentification et d'autorisation.

Accès à d'autres API Google

L'un des avantages de l'authentification via OAuth 2.0 est que votre application peut obtenir l'autorisation d'utiliser d'autres API Google pour le compte de l'utilisateur (comme YouTube, Google Drive, Agenda ou Contacts) en même temps que vous authentifiez l'utilisateur. Pour ce faire, incluez les autres champs d'application dont vous avez besoin dans la requête d'authentification que vous envoyez à Google. Par exemple, pour ajouter la tranche d'âge de l'utilisateur à votre requête d'authentification, transmettez le paramètre de champ d'application openid email https://www.googleapis.com/auth/profile.agerange.read. L'écran de consentement affiche une notification appropriée à l'utilisateur. Le jeton d'accès que vous recevez de Google vous permet d'accéder à toutes les API associées aux niveaux d'accès que vous avez demandés et qui vous ont été accordés.

Jetons d'actualisation

Dans votre demande d'accès à l'API, vous pouvez demander qu'un jeton d'actualisation soit renvoyé lors de l'échange code. Un jeton d'actualisation fournit à votre application un accès continu aux API Google lorsque l'utilisateur n'est pas présent dans votre application. Pour demander un jeton d'actualisation, ajoutez le paramètre access_type sur offline dans votre requête d'authentification.

Notions clés :

  • Veillez à stocker le jeton d'actualisation en toute sécurité et de manière permanente, car vous ne pouvez obtenir un jeton d'actualisation que la première fois que vous effectuez le flux d'échange de code.
  • Le nombre de jetons d'actualisation émis est limité: une limite par combinaison client/utilisateur et une autre par utilisateur pour tous les clients. Si votre application demande trop de jetons d'actualisation, elle peut atteindre ces limites. Dans ce cas, les jetons d'actualisation plus anciens cesseront de fonctionner.

Pour plus d'informations, consultez la section Actualiser un jeton d'accès (accès hors connexion).

Vous pouvez inviter l'utilisateur à autoriser à nouveau votre application en définissant le paramètre prompt sur consent dans votre requête d'authentification. Lorsque prompt=consent est inclus, l'écran de consentement s'affiche chaque fois que votre application demande l'autorisation de champs d'application d'accès, même si tous les champs d'application ont déjà été accordés à votre projet d'API Google. Pour cette raison, n'incluez prompt=consent que si nécessaire.

Pour en savoir plus sur le paramètre prompt, consultez la section prompt dans le tableau Paramètres de l'URI d'authentification.

Paramètres d'URI d'authentification

Le tableau suivant donne une description plus complète des paramètres acceptés par l'API d'authentification OAuth 2.0 de Google.

Paramètres Obligatoire Description
client_id (Obligatoire) Chaîne d'ID client obtenue à partir de API Console Credentials page, comme décrit dans la section Obtenir des identifiants OAuth 2.0.
nonce (Obligatoire) Valeur aléatoire générée par votre application qui permet la protection contre la rejeu.
response_type (Obligatoire) Si la valeur est code, lance un flux de code d'autorisation de base, nécessitant un POST sur le point de terminaison du jeton pour obtenir les jetons. Si la valeur est token id_token ou id_token token, il lance un flux implicite nécessitant l'utilisation de JavaScript au niveau de l'URI de redirection pour récupérer les jetons à partir de l'identifiant #fragment de l'URI.
redirect_uri (Obligatoire) Détermine la destination de la réponse. La valeur de ce paramètre doit correspondre exactement à l'une des valeurs de redirection autorisées que vous avez définies dans API Console Credentials page (y compris le schéma HTTP ou HTTPS, la casse et le caractère "/" de fin, le cas échéant).
scope (Obligatoire)

Le paramètre de champ d'application doit commencer par la valeur openid, puis inclure la valeur profile, la valeur email ou les deux.

Si la valeur de champ d'application profile est présente, le jeton d'ID peut inclure les revendications profile par défaut de l'utilisateur (mais cela n'est pas garanti).

Si la valeur de champ d'application email est présente, le jeton d'ID inclut les revendications email et email_verified.

En plus de ces champs d'application spécifiques à OpenID, l'argument de champ d'application peut également inclure d'autres valeurs de champ d'application. Toutes les valeurs de champ d'application doivent être séparées par un espace. Par exemple, si vous souhaitez accéder au Google Drive d'un utilisateur au niveau d'un fichier, vous pouvez définir le paramètre de champ d'application sur openid profile email https://www.googleapis.com/auth/drive.file.

Pour plus d'informations sur les champs d'application disponibles, consultez Champs d'application OAuth 2.0 pour les API Google ou la documentation de l'API Google que vous souhaitez utiliser.

state (facultatif, mais vivement recommandé)

Chaîne opaque aller-retour dans le protocole, c'est-à-dire qui est renvoyée en tant que paramètre d'URI dans le flux de base et dans l'identifiant d'URI #fragment dans le flux implicite.

Le state peut être utile pour corréler les requêtes et les réponses. Étant donné que votre redirect_uri peut être devinée, l'utilisation d'une valeur state peut vous assurer qu'une connexion entrante est le résultat d'une requête d'authentification lancée par votre application. Si vous générez une chaîne aléatoire ou encodez le hachage d'un état de client (par exemple, un cookie) dans cette variable state, vous pouvez valider la réponse pour vous assurer que la requête et la réponse proviennent du même navigateur. Cela offre une protection contre les attaques telles que la falsification de requêtes intersites.

access_type (Facultatif) Les valeurs autorisées sont offline et online. Cet effet est décrit dans la section Accès hors connexion. Si un jeton d'accès est demandé, le client ne reçoit pas de jeton d'actualisation, sauf si la valeur offline est spécifiée.
display (Facultatif) Valeur de chaîne ASCII permettant de spécifier la manière dont le serveur d'autorisation affiche les pages de l'interface utilisateur d'authentification et de consentement. Les valeurs suivantes sont spécifiées et acceptées par les serveurs Google, mais n'ont aucune incidence sur leur comportement : page, popup, touch et wap.
hd (Facultatif)

Simplifier le processus de connexion pour les comptes appartenant à une organisation Google Cloud En incluant le domaine de l'organisation Google Cloud (par exemple, mycollege.edu), vous pouvez indiquer que l'interface utilisateur de sélection de compte doit être optimisée pour les comptes de ce domaine. Afin d'optimiser votre stratégie pour les comptes d'organisation Google Cloud en général au lieu d'un seul domaine d'organisation Google Cloud, définissez la valeur d'un astérisque (*) : hd=*.

Ne comptez pas sur cette optimisation de l'interface utilisateur pour contrôler l'accès à votre application, car les requêtes côté client peuvent être modifiées. Veillez à validate que le jeton d'ID renvoyé a une valeur de revendication hd qui correspond à vos attentes (par exemple, mycolledge.edu). Contrairement au paramètre de requête, la revendication hd du jeton d'ID est contenue dans un jeton de sécurité de Google. La valeur peut donc être approuvée.

include_granted_scopes (Facultatif) Si ce paramètre est défini avec la valeur true et que la demande d'autorisation est accordée, l'autorisation inclura toutes les autorisations précédemment accordées à cette combinaison utilisateur/application pour les autres champs d'application. Consultez la section Autorisation incrémentielle.

Notez que vous ne pouvez pas accorder d'autorisation incrémentielle avec le flux d'applications installées.

login_hint (Facultatif) Lorsque votre application sait quel utilisateur elle tente d'authentifier, elle peut fournir ce paramètre afin d'indiquer au serveur d'authentification. Si vous transmettez cet indice, le sélecteur de compte est désactivé et la zone d'adresse e-mail est préremplie dans le formulaire de connexion ou la session appropriée est sélectionnée (si l'utilisateur a recours à la connexion multicompte). Cela peut vous aider à éviter les problèmes qui surviennent si votre application se connecte au mauvais compte utilisateur. La valeur peut être une adresse e-mail ou la chaîne sub, qui équivaut à l'ID Google de l'utilisateur.
prompt (Facultatif) Liste de valeurs de chaîne séparées par des espaces qui spécifient si le serveur d'autorisation invite l'utilisateur à se réauthentifier et à donner son consentement. Les valeurs possibles sont les suivantes :
  • none

    Le serveur d'autorisation n'affiche aucun écran d'authentification ou de consentement de l'utilisateur. Il renvoie une erreur si l'utilisateur n'est pas déjà authentifié et n'a pas préconfiguré le consentement pour les champs d'application demandés. Vous pouvez utiliser none pour vérifier l'authentification et/ou le consentement existants.

  • consent

    Le serveur d'autorisation invite l'utilisateur à donner son consentement avant de renvoyer des informations au client.

  • select_account

    Le serveur d'autorisation invite l'utilisateur à sélectionner un compte utilisateur. Un utilisateur disposant de plusieurs comptes sur le serveur d'autorisation peut ainsi sélectionner un compte pour lequel il peut avoir des sessions en cours.

Si aucune valeur n'est spécifiée et que l'utilisateur n'a pas encore autorisé l'accès, un écran d'autorisation s'affiche.

Valider un jeton d'ID

Vous devez valider tous les jetons d'ID de votre serveur, sauf si vous savez qu'ils proviennent directement de Google. Par exemple, votre serveur doit s'assurer que tous les jetons d'identification envoyés par vos applications clientes sont authentiques.

Vous pouvez envoyer des jetons d'ID à votre serveur dans les situations suivantes:

  • envoyer des jetons d'identification avec des requêtes qui doivent être authentifiées ; Les jetons d'ID vous indiquent l'utilisateur à l'origine de la requête et pour quel client ce jeton d'ID a été accordé.

Les jetons d'ID sont sensibles et peuvent être utilisés de manière abusive s'ils sont interceptés. Vous devez vous assurer que ces jetons sont gérés de manière sécurisée en les transmettant uniquement via HTTPS et uniquement via des données POST ou dans des en-têtes de requête. Si vous stockez des jetons d'identification sur votre serveur, vous devez également les conserver de manière sécurisée.

Les jetons d'identification sont utiles, car vous pouvez les transmettre à différents composants de votre application. Ces composants peuvent utiliser un jeton d'identification comme mécanisme d'authentification léger authentifiant l'application et l'utilisateur. Toutefois, avant de pouvoir utiliser les informations du jeton d'ID ou de confirmer que l'utilisateur s'est authentifié, vous devez les valider.

La validation d'un jeton d'identification nécessite plusieurs étapes:

  1. Vérifiez que le jeton d'ID est correctement signé par l'émetteur. Les jetons émis par Google sont signés à l'aide de l'un des certificats trouvés dans l'URI spécifié dans la valeur de métadonnées jwks_uri du document de découverte.
  2. Vérifiez que la valeur de la revendication iss dans le jeton d'ID est égale à https://accounts.google.com ou accounts.google.com.
  3. Vérifiez que la valeur de la revendication aud dans le jeton d'ID est égale à l'ID client de votre application.
  4. Vérifiez que le délai d'expiration (revendication exp) du jeton d'ID n'est pas dépassé.
  5. Si vous avez spécifié une valeur de paramètre hd dans la requête, vérifiez que le jeton d'ID comporte une revendication hd correspondant à un domaine accepté associé à une organisation Google Cloud.

Les étapes 2 à 5 n'impliquent que des comparaisons de chaînes et de dates, qui sont assez simples. Nous ne les détaillerons donc pas ici.

La première étape, plus complexe, implique la vérification de la signature cryptographique. À des fins de débogage, vous pouvez utiliser le point de terminaison tokeninfo de Google pour effectuer une comparaison avec le traitement local mis en œuvre sur votre serveur ou votre appareil. Supposons que la valeur de votre jeton d'ID soit XYZ123. Vous devez ensuite déréférencer l'URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Si la signature du jeton est valide, la réponse correspond à la charge utile JWT sous sa forme d'objet JSON décodé.

Le point de terminaison tokeninfo est utile pour le débogage, mais à des fins de production, il vous permet de récupérer les clés publiques Google à partir du point de terminaison des clés et d'effectuer la validation localement. Vous devez récupérer l'URI des clés à partir du document de découverte à l'aide de la valeur de métadonnées jwks_uri. Les requêtes envoyées au point de terminaison de débogage peuvent être limitées ou soumises à des erreurs intermittentes.

Étant donné que Google ne modifie ses clés publiques que rarement, vous pouvez les mettre en cache à l'aide des instructions de cache de la réponse HTTP et, dans la grande majorité des cas, effectuer une validation locale bien plus efficacement qu'en utilisant le point de terminaison tokeninfo. Cette validation nécessite de récupérer et d'analyser des certificats, et d'effectuer les appels cryptographiques appropriés pour vérifier la signature. Heureusement, il existe des bibliothèques bien déboguées disponibles dans une grande variété de langages pour effectuer cette opération (voir jwt.io).

Obtenir des informations de profil utilisateur

Pour obtenir des informations de profil supplémentaires sur l'utilisateur, vous pouvez utiliser le jeton d'accès (que votre application reçoit lors du flux d'authentification) et la norme OpenID Connect:

  1. Pour être conforme à OpenID, vous devez inclure les valeurs du champ d'application openid profile dans votre requête d'authentification.

    Si vous souhaitez inclure l'adresse e-mail de l'utilisateur, vous pouvez spécifier une valeur de champ d'application supplémentaire de email. Pour spécifier à la fois profile et email, vous pouvez inclure le paramètre suivant dans l'URI de votre requête d'authentification:

    scope=openid%20profile%20email
  2. Ajoutez votre jeton d'accès à l'en-tête d'autorisation et envoyez une requête HTTPS GET au point de terminaison userinfo, que vous devez récupérer à partir du document de découverte à l'aide de la valeur de métadonnées userinfo_endpoint. La réponse userinfo inclut des informations sur l'utilisateur, comme décrit dans OpenID Connect Standard Claims et dans la valeur de métadonnées claims_supported du document de découverte. Les utilisateurs ou leurs organisations peuvent choisir de fournir ou de conserver certains champs. Il est donc possible que vous n'obteniez pas d'informations pour chaque champ de vos niveaux d'accès autorisés.

Document de découverte

Le protocole OpenID Connect nécessite l'utilisation de plusieurs points de terminaison pour authentifier les utilisateurs et demander des ressources, telles que des jetons, des informations sur les utilisateurs et des clés publiques.

Pour simplifier les mises en œuvre et accroître la flexibilité, OpenID Connect autorise l'utilisation d'un "document de découverte". Il s'agit d'un document JSON trouvé à un emplacement bien connu et contenant des paires clé/valeur qui fournissent des détails sur la configuration du fournisseur OpenID Connect, y compris les URI des points de terminaison d'autorisation, de jeton, de révocation, d'userinfo et de clés publiques. Le document de découverte du service OpenID Connect de Google peut être récupéré à partir de:

https://accounts.google.com/.well-known/openid-configuration

Pour utiliser les services OpenID Connect de Google, vous devez coder en dur l'URI du document de découverte (https://accounts.google.com/.well-known/openid-configuration) dans votre application. Votre application récupère le document, applique des règles de mise en cache dans la réponse, puis récupère les URI des points de terminaison à partir du document si nécessaire. Par exemple, pour authentifier un utilisateur, votre code récupère la valeur de métadonnées authorization_endpoint (https://accounts.google.com/o/oauth2/v2/auth dans l'exemple ci-dessous) en tant qu'URI de base pour les requêtes d'authentification envoyées à Google.

Voici un exemple de ce type de document. Les noms de champs sont ceux spécifiés dans OpenID Connect Discovery 1.0 (reportez-vous à ce document pour connaître leur signification). Les valeurs sont fournies à titre indicatif et peuvent changer, même si elles ont été copiées à partir d'une version récente du document Google Discovery:

{
  "issuer": "https://accounts.google.com",
  "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth",
  "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code",
  "token_endpoint": "https://oauth2.googleapis.com/token",
  "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo",
  "revocation_endpoint": "https://oauth2.googleapis.com/revoke",
  "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs",
  "response_types_supported": [
    "code",
    "token",
    "id_token",
    "code token",
    "code id_token",
    "token id_token",
    "code token id_token",
    "none"
  ],
  "subject_types_supported": [
    "public"
  ],
  "id_token_signing_alg_values_supported": [
    "RS256"
  ],
  "scopes_supported": [
    "openid",
    "email",
    "profile"
  ],
  "token_endpoint_auth_methods_supported": [
    "client_secret_post",
    "client_secret_basic"
  ],
  "claims_supported": [
    "aud",
    "email",
    "email_verified",
    "exp",
    "family_name",
    "given_name",
    "iat",
    "iss",
    "locale",
    "name",
    "picture",
    "sub"
  ],
  "code_challenge_methods_supported": [
    "plain",
    "S256"
  ]
}

Vous pouvez peut-être éviter un aller-retour HTTP en mettant en cache les valeurs du document de découverte. Les en-têtes de mise en cache HTTP standards sont utilisés et doivent être respectés.

Bibliothèques clientes

Les bibliothèques clientes suivantes simplifient l'implémentation d'OAuth 2.0 grâce à l'intégration à des frameworks courants:

Conformité avec OpenID Connect

Le système d'authentification OAuth 2.0 de Google est compatible avec les fonctionnalités requises par la spécification OpenID Connect Core. Tout client conçu pour fonctionner avec OpenID Connect doit interagir avec ce service (à l'exception de l'objet de requête OpenID).