Connexion OpenID

Le point de terminaison OpenID Connect de Google est certifié OpenID.

Les API OAuth 2.0 de Google peuvent être utilisées à la fois pour l'authentification et l'autorisation. Ce document décrit notre implémentation OAuth 2.0 pour l'authentification, qui est conforme à la spécification OpenID Connect et est certifiée OpenID . La documentation trouvée dans Utilisation d'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 Google OAuth 2.0 Playground . Pour obtenir de l'aide sur Stack Overflow , marquez vos questions avec "google-oauth".

Configuration d'OAuth 2.0

Avant 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 pour obtenir des informations d'identification OAuth 2.0, définir un URI de redirection et (éventuellement) personnaliser les informations de marque que vos utilisateurs voient sur le écran de consentement de l'utilisateur. Vous pouvez également utiliser API Console pour créer un compte de service, activer la facturation, configurer le filtrage et effectuer d'autres tâches. Pour plus de détails, consultez l' Google API Console .

Obtenir les identifiants OAuth 2.0

Vous avez besoin d'informations d'identification OAuth 2.0, y compris un ID client et un secret client, pour authentifier les utilisateurs et accéder aux API de 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 où Google envoie les réponses à vos demandes 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 de l'utilisateur

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é à donner à votre application l'accès à 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 demande d'authentification . Vous pouvez également utiliser des champs d'application pour demander l'accès à d'autres API Google.

L'écran de consentement de l'utilisateur présente également des informations de marque telles que le nom de votre produit, votre logo et une URL de page d'accueil. Vous contrôlez les informations de marque dans le 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 consentement suivante montre ce qu'un utilisateur verrait lorsqu'une combinaison de champs d'application OAuth 2.0 et Google Drive est présente dans la demande. (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 marque qui seraient définies dans API Console.)

Capture d'écran de la page de consentement

Accéder au service

Google et des tiers fournissent des bibliothèques que vous pouvez utiliser pour prendre en charge de nombreux détails de mise en œuvre de l'authentification des utilisateurs et de l'accès aux API Google. Les exemples incluent Google Sign-In et les bibliothèques clientes Google , qui sont disponibles pour diverses plates-formes.

Si vous choisissez de ne pas utiliser de bibliothèque, suivez les instructions du reste de ce document, qui décrit les flux de requêtes HTTP qui sous-tendent les bibliothèques disponibles.

Authentification de l'utilisateur

L'authentification de l'utilisateur implique l'obtention d'un jeton d'identification et sa validation. Les jetons d'identification sont une fonctionnalité standardisée d' OpenID Connect conçue pour être utilisée dans le partage d'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 le flux "serveur" et le flux "implicite". Le flux de serveur permet au serveur principal 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 directement aux API au lieu de passer par son serveur principal.

Ce document décrit comment exécuter le flux de serveur pour authentifier l'utilisateur. Le flux implicite est nettement plus compliqué en raison des risques de sécurité liés à la gestion et à l'utilisation des jetons côté client. Si vous devez mettre en œuvre un flux implicite, nous vous recommandons vivement d'utiliser Google Sign-In .

Flux de serveur

Assurez-vous de configurer votre application dans le API Console pour lui permettre d'utiliser ces protocoles et d'authentifier vos utilisateurs. Lorsqu'un utilisateur essaie de se connecter avec Google, vous devez :

  1. Créer un jeton d'état anti-contrefaçon
  2. Envoyer une demande d'authentification à Google
  3. Confirmer le jeton d'état anti-contrefaçon
  4. code d'échange pour le jeton d'accès et le jeton d'identification
  5. Obtenir des informations sur l'utilisateur à partir du jeton d'identification
  6. Authentifier l'utilisateur

1. Créer un jeton d'état anti-contrefaçon

Vous devez protéger la sécurité de vos utilisateurs en empêchant les attaques par falsification de requête. 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 demande et non un attaquant malveillant. Ces jetons sont souvent appelés jetons CSRF (cross-site request forgery).

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é qui est gardée secrète sur votre back-end.

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 afin d'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 afin d'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. Envoyez une demande d'authentification à Google

L'étape suivante consiste à former une requête HTTPS GET avec les paramètres URI appropriés. Notez l'utilisation de HTTPS plutôt que HTTP dans toutes les étapes de ce processus ; Les connexions HTTP sont refusées. Vous devez récupérer l'URI de base à partir du document Discovery à l'aide de la authorization_endpoint de métadonnées authentication_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 API ConsoleCredentials page.
  • response_type , qui dans une demande de flux de code d'autorisation de base doit être code . (En savoir plus sur response_type .)
  • scope , qui dans une requête de base devrait être openid email . (En savoir plus sur scope .)
  • redirect_uri doit être le point de terminaison HTTP sur 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 ConsoleCredentials page. Si cette valeur ne correspond pas à un URI autorisé, la requête échouera avec une erreur redirect_uri_mismatch .
  • state doit inclure la valeur du jeton de session unique anti-contrefaçon, ainsi que toute autre information nécessaire pour récupérer le contexte lorsque l'utilisateur revient à votre application, par exemple, l'URL de départ. (En savoir plus sur state .)
  • nonce est une valeur aléatoire générée par votre application qui active la protection contre la relecture lorsqu'elle est présente.
  • login_hint peut être l'adresse e-mail de l'utilisateur ou la sub -chaîne, qui équivaut à l'identifiant 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'approbation pour divulguer l'adresse e-mail de l'utilisateur à votre application. (En savoir plus sur login_hint .)
  • Utilisez le paramètre hd pour optimiser le flux OpenID Connect pour les utilisateurs d'un domaine particulier associé à une organisation Google Cloud. (En savoir plus sur hd .)

Voici un exemple d'URI d'authentification OpenID Connect complet, avec des sauts de ligne et des espaces pour la 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 à leur sujet ou si votre application demande un accès à un compte qu'ils n'ont pas préalablement approuvé.

3. Confirmer le jeton d'état anti-contrefaçon

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 illustré 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 l' state reçu de Google correspond au jeton de session que vous avez créé à l' étape 1 . Cette vérification aller-retour permet de s'assurer que l'utilisateur, et non un script malveillant, fait la demande.

Le code suivant illustre la confirmation des 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 afin d'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 afin d'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. code d'échange pour le jeton d'accès et le jeton d'identification

La réponse inclut un paramètre de code , un code d'autorisation à usage unique que votre serveur peut échanger contre un jeton d'accès et un jeton d'identification. Votre serveur effectue cet échange en envoyant une requête HTTPS POST . La demande POST est envoyée au point de terminaison de jeton, que vous devez récupérer à partir du document Discovery à 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 :

Des champs
code Code d'autorisation renvoyé à partir de la demande initiale .
client_id L'ID client que vous obtenez à partir de API ConsoleCredentials page, comme décrit dans Obtenir des informations d'identification OAuth 2.0 .
client_secret Le secret client que vous obtenez à partir de API ConsoleCredentials page, comme décrit dans Obtenir des informations d'identification OAuth 2.0 .
redirect_uri Un URI de redirection autorisé pour le client_id donné spécifié dans API ConsoleCredentials page, comme décrit dans Définir un URI de redirection .
grant_type Ce champ doit contenir une valeur de authorization_code , tel que défini dans la spécification OAuth 2.0 .

La requête réelle peut ressembler à l'exemple suivant :

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 :

Des 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 d'identité sur l'utilisateur signées numériquement par Google.
scope Les étendues d'accès accordées par le access_token d'accès exprimées sous la forme d'une liste de chaînes délimitées par des espaces et sensibles à la casse.
token_type Identifie le type de jeton renvoyé. Pour le moment, ce champ a toujours la valeur Bearer .
refresh_token (optionnel)

Ce champ n'est présent que si le paramètre access_type a été défini sur offline dans la demande d'authentification . Pour plus de détails, consultez Actualiser les jetons .

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

Un jeton d'identification est un JWT (jeton Web JSON), c'est-à-dire un objet JSON encodé en Base64 et signé de manière cryptographique. Normalement, il est essentiel que vous validiez un jeton d'identification avant de l'utiliser, mais puisque vous communiquez directement avec Google via un canal HTTPS sans intermédiaire et que vous utilisez votre secret client pour vous authentifier auprès de Google, vous pouvez être sûr que le jeton que vous recevoir provient vraiment de Google et est valide. Si votre serveur transmet le jeton d'identification à d'autres composants de votre application, il est extrêmement important que les autres composants valident le jeton avant de l'utiliser.

Étant donné que la plupart des bibliothèques d'API combinent la validation avec le travail de décodage des valeurs encodées en base64url et d'analyse du JSON à l'intérieur, vous finirez probablement par valider le jeton de toute façon lorsque vous accéderez aux revendications dans le jeton d'identification.

La charge utile d'un jeton d'identification

Un jeton d'identification est un objet JSON contenant un ensemble de paires nom/valeur. Voici un exemple, formaté pour la 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'identification Google peuvent contenir les champs suivants (appelés revendications ) :

Prétendre À condition de La description
aud toujours L'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 à partir duquel ou après lequel le jeton d'identification ne doit pas être accepté. Représenté en temps Unix (secondes entières).
iat toujours Heure à laquelle le jeton d'identification a été émis. Représenté en temps Unix (secondes entières).
iss toujours Identificateur de l'émetteur de la réponse. Toujours https://accounts.google.com ou accounts.google.com pour les jetons d'identification 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 sub -valeur n'est jamais modifiée. Utilisez sub dans votre application comme clé d'identification unique pour l'utilisateur. Longueur maximale de 255 caractères ASCII sensibles à la casse.
at_hash Hachage du jeton d'accès. Fournit la validation 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 demande est toujours incluse. Cette revendication peut être utilisée comme mécanisme alternatif pour se protéger contre les attaques de falsification de demande intersites, mais si vous suivez les étapes 1 et 3 , il n'est pas nécessaire de vérifier le jeton d'accès.
azp Le client_id du présentateur autorisé. Cette revendication n'est nécessaire que lorsque la partie demandant le jeton d'identification n'est pas la même que l'audience du jeton d'identification. Cela peut être le cas chez Google pour les applications hybrides où une application Web et une application Android ont un client_id OAuth 2.0 différent mais partagent le même projet d'API Google.
email L'adresse e-mail de l'utilisateur. Cette valeur peut ne pas être propre à cet utilisateur et ne convient pas à une utilisation en tant que clé primaire. Fourni uniquement si votre étendue incluait la valeur d'étendue de l'e- email .
email_verified Vrai si l'adresse e-mail de l'utilisateur a été vérifiée ; sinon faux.
family_name Le(s) nom(s) ou nom(s) de famille de l'utilisateur. Peut être fourni lorsqu'une revendication de name est présente.
given_name Le(s) prénom(s) ou prénom(s) de l'utilisateur. Peut être fourni lorsqu'une revendication de name est présente.
hd Domaine associé à l'organisation Google Cloud de l'utilisateur. Fourni uniquement si l'utilisateur appartient à une organisation Google Cloud.
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 de name est présente.
name Le nom complet de l'utilisateur, sous une forme affichable. Peut être fourni lorsque :
  • La portée de la demande comprenait la chaîne "profil"
  • Le jeton d'ID est renvoyé à partir d'une actualisation de jeton

Lorsque des revendications de name sont présentes, vous pouvez les utiliser pour mettre à jour les enregistrements d'utilisateurs de votre application. Notez que cette revendication n'est jamais garantie d'être présente.

nonce La valeur du nonce fourni par votre application dans la demande d'authentification. Vous devez appliquer la protection contre les attaques par relecture en vous assurant qu'elle n'est présentée qu'une seule fois.
picture L'URL de la photo de profil de l'utilisateur. Peut être fourni lorsque :
  • La portée de la demande comprenait la chaîne "profil"
  • Le jeton d'ID est renvoyé à partir d'une actualisation de jeton

Lorsque des revendications picture sont présentes, vous pouvez les utiliser pour mettre à jour les enregistrements d'utilisateurs de votre application. Notez que cette revendication n'est jamais garantie d'être présente.

profile L'URL de la page de profil de l'utilisateur. Peut être fourni lorsque :
  • La portée de la demande comprenait la chaîne "profil"
  • Le jeton d'ID est renvoyé à partir d'une actualisation de jeton

Lorsque des revendications profile sont présentes, vous pouvez les utiliser pour mettre à jour les enregistrements d'utilisateurs de votre application. Notez que cette revendication n'est jamais garantie d'être présente.

6. Authentifier l'utilisateur

Après avoir obtenu les informations utilisateur à partir du jeton d'identification, 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 toutes les conditions de connexion sont remplies par la réponse de l'API Google.

Si l'utilisateur n'existe pas dans votre base de données d'utilisateurs, vous devez le rediriger vers votre flux d'inscription de nouvel utilisateur. Vous pourrez peut-être enregistrer automatiquement l'utilisateur en fonction des informations que vous recevez de Google ou, à tout le moins, vous pourrez peut-être pré-remplir de nombreux champs dont vous avez besoin sur votre formulaire d'inscription. En plus des informations contenues dans le jeton d'identification, vous pouvez obtenir des informations supplémentaires sur le profil utilisateur sur nos points de terminaison de profil utilisateur.

Sujets avancés

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'utilisation d'OAuth 2.0 pour l'authentification est que votre application peut obtenir l'autorisation d'utiliser d'autres API Google au nom de l'utilisateur (telles que YouTube, Google Drive, Calendar 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 demande d'authentification que vous envoyez à Google. Par exemple, pour ajouter la tranche d'âge de l'utilisateur à votre demande d'authentification, transmettez un paramètre d'étendue de openid email https://www.googleapis.com/auth/profile.agerange.read . L'utilisateur est invité de manière appropriée sur l' écran de consentement . Le jeton d'accès que vous recevez de Google vous permet d'accéder à toutes les API liées aux étendues d'accès que vous avez demandées et qui ont été accordées.

Actualiser les jetons

Dans votre demande d'accès à l'API, vous pouvez demander qu'un jeton d'actualisation soit renvoyé lors de l' échange de 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 demande d'authentification .

Considérations :

  • Assurez-vous de stocker le jeton d'actualisation de manière sûre et permanente, car vous ne pouvez obtenir un jeton d'actualisation que la première fois que vous exécutez 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, auquel cas les anciens jetons d'actualisation cessent de fonctionner.

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

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

Pour plus d'informations sur le paramètre prompt , consultez prompt dans le tableau des paramètres d'URI d'authentification .

Paramètres URI d'authentification

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

Paramètre Obligatoire La description
client_id (Obligatoire) La chaîne d'ID client que vous obtenez à partir de API ConsoleCredentials page, comme décrit dans Obtenir des informations d'identification OAuth 2.0 .
nonce (Obligatoire) Une valeur aléatoire générée par votre application qui active la protection contre la relecture.
response_type (Obligatoire) Si la valeur est code , lance un flux de code d'autorisation de base , nécessitant un POST au point de terminaison du jeton pour obtenir les jetons. Si la valeur est token id_token ou id_token token , lance un flux implicite , nécessitant l'utilisation de JavaScript à l'URI de redirection pour récupérer les jetons à partir de l' identificateur URI #fragment .
redirect_uri (Obligatoire) Détermine où la réponse est envoyée. La valeur de ce paramètre doit correspondre exactement à l'une des valeurs de redirection autorisées que vous avez définies dans API ConsoleCredentials page (y compris le schéma HTTP ou HTTPS, la casse et le '/' final, le cas échéant).
scope (Obligatoire)

Le paramètre scope doit commencer par la valeur openid , puis inclure la valeur profile , la valeur email ou les deux.

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

Si la valeur d'étendue de l'e- email est présente, le jeton d'ID inclut les revendications email et email_verified .

En plus de ces étendues spécifiques à OpenID, votre argument d'étendue peut également inclure d'autres valeurs d'étendue. Toutes les valeurs d'étendue doivent être séparées par des espaces. Par exemple, si vous souhaitez un accès par fichier au Google Drive d'un utilisateur, votre paramètre d'étendue peut être 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 fortement recommandé)

Une chaîne opaque qui fait l'objet d'un aller-retour dans le protocole ; c'est-à-dire qu'il est renvoyé en tant que paramètre URI dans le flux de base et dans l'identificateur URI #fragment dans le flux implicite.

L' state peut être utile pour corréler les demandes et les réponses. Étant donné que votre redirect_uri peut être deviné, l'utilisation d'une valeur d' state peut augmenter votre assurance qu'une connexion entrante est le résultat d'une demande d'authentification initiée par votre application. Si vous générez une chaîne aléatoire ou encodez le hachage d'un état client (par exemple, un cookie) dans cette variable d' state , vous pouvez valider la réponse pour vous assurer en outre que la demande 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 (Optionnel) Les valeurs autorisées sont offline et online . L'effet est documenté dans Offline Access ; si un jeton d'accès est demandé, le client ne reçoit pas de jeton d'actualisation à moins qu'une valeur offline ne soit spécifiée.
display (Optionnel) Une valeur de chaîne ASCII pour spécifier comment le serveur d'autorisation affiche les pages d'interface utilisateur d'authentification et de consentement. Les valeurs suivantes sont spécifiées et acceptées par les serveurs de Google, mais n'ont aucun effet sur son comportement : page , popup , touch et wap .
hd (Optionnel)

Simplifiez 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. Pour optimiser 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 qui peut accéder à votre application, car les demandes côté client peuvent être modifiées. Assurez-vous de valider que le jeton d'identification renvoyé a une valeur de revendication hd qui correspond à ce que vous attendez (par exemple mycolledge.edu ). Contrairement au paramètre de requête, la revendication hd du jeton d'identification est contenue dans un jeton de sécurité de Google, de sorte que la valeur peut être approuvée.

include_granted_scopes (Optionnel) Si ce paramètre est fourni avec la valeur true et que la demande d'autorisation est accordée, l'autorisation inclura toutes les autorisations précédentes accordées à cette combinaison utilisateur/application pour d'autres étendues ; voir Autorisation incrémentielle .

Notez que vous ne pouvez pas effectuer d'autorisation incrémentielle avec le flux d'application installée.

login_hint (Optionnel) Lorsque votre application sait quel utilisateur elle tente d'authentifier, elle peut fournir ce paramètre comme indice au serveur d'authentification. La transmission de cet indice supprime le sélecteur de compte et pré-remplit la boîte e-mail sur le formulaire de connexion, ou sélectionne la session appropriée (si l'utilisateur utilise plusieurs connexions ), ce qui peut vous aider à éviter les problèmes qui se produisent si votre application se connecte au mauvais compte utilisateur. La valeur peut être soit une adresse e-mail, soit la sub -chaîne, qui équivaut à l'identifiant Google de l'utilisateur.
prompt (Optionnel) Une liste de valeurs de chaîne délimitées par des espaces qui spécifie si le serveur d'autorisation invite l'utilisateur à se réauthentifier et à donner son consentement. Les valeurs possibles sont :
  • none

    Le serveur d'autorisation n'affiche aucun écran d'authentification ou de consentement de l'utilisateur ; il renverra une erreur si l'utilisateur n'est pas déjà authentifié et n'a pas préconfiguré le consentement pour les étendues demandées. 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 d'utilisateur. Cela permet à un utilisateur qui possède plusieurs comptes sur le serveur d'autorisation de sélectionner parmi les multiples comptes pour lesquels il peut avoir des sessions en cours.

Si aucune valeur n'est spécifiée et que l'utilisateur n'a pas préalablement autorisé l'accès, un écran de consentement s'affiche.

Validation d'un jeton d'identification

Vous devez valider tous les jetons d'identification sur votre serveur, sauf si vous savez qu'ils proviennent directement de Google. Par exemple, votre serveur doit vérifier comme authentiques tous les jetons d'identification qu'il reçoit de vos applications clientes.

Voici des situations courantes dans lesquelles vous pouvez envoyer des jetons d'identification à votre serveur :

  • Envoi de jetons d'identification avec des demandes qui doivent être authentifiées. Les jetons d'identification vous indiquent l'utilisateur particulier qui fait la demande et pour quel client ce jeton d'identification a été accordé.

Les jetons d'identification sont sensibles et peuvent être utilisés à mauvais escient s'ils sont interceptés. Vous devez vous assurer que ces jetons sont gérés en toute sécurité 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 stocker en toute sécurité.

Une chose qui rend les jetons d'identification utiles est le fait que 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. Mais avant de pouvoir utiliser les informations du jeton d'ID ou de vous y fier comme une assertion que l'utilisateur s'est authentifiée, vous devez la valider.

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

  1. Vérifiez que le jeton d'identification est correctement signé par l'émetteur. Les jetons émis par Google sont signés à l'aide de l'un des certificats trouvés à l'URI spécifié dans la valeur de métadonnées jwks_uri du document Discovery .
  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 (demande 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 a une revendication hd qui correspond à un domaine accepté associé à une organisation Google Cloud.

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

La première étape est plus complexe et 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 appareil. Supposons que la valeur de votre jeton d'identification soit XYZ123 . Ensuite, vous déréférencerez l'URI https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 . Si la signature du jeton est valide, la réponse serait 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, récupérez les clés publiques de Google à partir du point de terminaison des clés et effectuez la validation localement. Vous devez récupérer l'URI des clés à partir du document Discovery à l'aide de la valeur de métadonnées jwks_uri . Les demandes adressées au point de terminaison de débogage peuvent être limitées ou soumises à des erreurs intermittentes.

Étant donné que Google ne modifie que rarement ses clés publiques, vous pouvez les mettre en cache à l'aide des directives de cache de la réponse HTTP et, dans la grande majorité des cas, effectuer une validation locale beaucoup plus efficacement qu'en utilisant le point de terminaison tokeninfo . Cette validation nécessite de récupérer et d'analyser les 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 accomplir cela (voir jwt.io ).

Obtenir des informations sur le profil de l'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 le standard OpenID Connect :

  1. Pour être conforme à OpenID, vous devez inclure les valeurs d'étendue du openid profile dans votre demande d'authentification .

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

    scope=openid%20profile%20email
  2. Ajoutez votre jeton d'accès à l'en-tête d'autorisation et envoyez une demande HTTPS GET au point de terminaison userinfo, que vous devez récupérer à partir du document Discovery à 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 la valeur de métadonnées claims_supported du document Discovery. Les utilisateurs ou leurs organisations peuvent choisir de fournir ou de masquer certains champs, de sorte que vous risquez de ne pas obtenir d'informations pour chaque champ pour vos étendues d'accès autorisées.

Le dossier Découverte

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

Pour simplifier les implémentations et augmenter la flexibilité, OpenID Connect permet l'utilisation d'un "document de découverte", un document JSON trouvé à un emplacement bien connu contenant des paires clé-valeur qui fournissent des détails sur la configuration du fournisseur OpenID Connect, y compris les URI de l'autorisation , jeton, révocation, informations utilisateur et points de terminaison de clés publiques. Le document Discovery pour le 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 Discovery ( https://accounts.google.com/.well-known/openid-configuration ) dans votre application. Votre application récupère le document, applique les règles de mise en cache dans la réponse, puis en extrait les URI de point de terminaison si nécessaire. Par exemple, pour authentifier un utilisateur, votre code récupère la authorization_endpoint de métadonnées authentication_endpoint ( https://accounts.google.com/o/oauth2/v2/auth dans l'exemple ci-dessous) comme URI de base pour les demandes d'authentification envoyées à Google.

Voici un exemple d'un tel document; les noms de champs sont ceux spécifiés dans OpenID Connect Discovery 1.0 (reportez-vous à ce document pour leurs significations). Les valeurs sont purement illustratives et peuvent changer, bien qu'elles soient copiées d'une version récente du document actuel de 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 pourrez peut-être éviter un aller-retour HTTP en mettant en cache les valeurs du document Discovery. Les en-têtes de mise en cache HTTP standard sont utilisés et doivent être respectés.

Bibliothèques clientes

Les bibliothèques clientes suivantes simplifient la mise en œuvre d'OAuth 2.0 en s'intégrant à des frameworks courants :

Conformité OpenID Connect

Le système d'authentification OAuth 2.0 de Google prend en charge les fonctionnalités requises de la spécification OpenID Connect Core . Tout client conçu pour fonctionner avec OpenID Connect doit interagir avec ce service (à l'exception de l' OpenID Request Object ).