OpenID Connect

Les API OAuth 2.0 de Google peuvent être utilisées à la fois pour l'authentification et l'autorisation. Ce document décrit notre mise en œuvre OAuth 2.0 pour l'authentification. Il est conforme à la spécification OpenID Connect et certifié OpenID. La documentation décrite dans 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 d'utiliser Google OAuth 2.0 Playground. Pour obtenir de l'aide sur Stack Overflow, ajoutez le libellé "google-oauth" à vos questions.

Remarque:Si vous souhaitez ajouter un bouton "Se connecter avec Google" à votre site Web ou à votre application, nous vous recommandons d'utiliser Google Identity Services, notre bibliothèque cliente de connexion basée sur le protocole OpenID Connect et qui fournit des jetons d'identification au format OpenID Connect.

Configurer OAuth 2.0

Avant que votre application puisse utiliser le système d'authentification OAuth 2.0 de Google pour la connexion de l'utilisateur, vous devez configurer un projet dans le Google API Console afin d'obtenir les identifiants OAuth 2.0 et définir un URI de redirection, et (éventuellement) personnaliser les informations de branding que vos utilisateurs voient sur l'é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 en savoir plus, consultez l'aideGoogle API Console.

Obtenir des identifiants OAuth 2.0

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

To view the client ID and client secret for a given OAuth 2.0 credential, click the following text: Select credential. In the window that opens, choose your project and the credential you want, then click View.

Or, view your client ID and client secret from the Credentials page in API Console:

1. Go to the Credentials page.
2. Click the name of your credential or the pencil () icon. Your client ID and secret are at the top of the page.

Définir un URI de redirection

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

To create, view, or edit the redirect URIs for a given OAuth 2.0 credential, do the following:

1. Go to the Credentials page.
2. In the OAuth 2.0 client IDs section of the page, click a credential.
3. View or edit the redirect URIs.

If there is no OAuth 2.0 client IDs section on the Credentials page, then your project has no OAuth credentials. To create one, click Create credentials.

Personnaliser l'écran de consentement de l'utilisateur

Pour vos utilisateurs, l'authentification OAuth 2.0 inclut un écran de consentement qui décrit les informations que l'utilisateur libère 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 demande d'authentification. Vous pouvez également utiliser les 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 branding telles que le nom de votre produit, votre logo et une URL de page d'accueil. Vous contrôlez les informations de branding dans 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 verra lorsqu'une combinaison de champs d'application OAuth 2.0 et Google Drive sera présente dans la requête. Cette boîte de dialogue générique a été générée à l'aide de Google OAuth 2.0 Playground. Les informations de branding définies dans API Consolene sont donc pas incluses.

Accéder au service

Google et des tiers fournissent des bibliothèques qui vous permettent de gérer de nombreux détails de 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.

Remarque:Compte tenu des implications sur la sécurité de l'implémentation, nous vous recommandons vivement de tirer parti d'une bibliothèque ou d'un service prédéfini. L'authentification appropriée des utilisateurs est importante pour leur sécurité et pour celle-ci. Il est généralement recommandé d'utiliser un code bien débogué écrit par d'autres utilisateurs. Pour en savoir plus, consultez la section Bibliothèques clientes.

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

Authentification de l'utilisateur

Pour authentifier l'utilisateur, vous devez obtenir un jeton d'ID et le valider. Les jetons d'ID sont une fonctionnalité normalisée d'OpenID Connect. Conçue pour le partage des assertions d'identité sur Internet,

Les approches les plus courantes pour authentifier un utilisateur et obtenir un jeton d'ID sont appelées "flux" 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 directement aux API plutôt que via son serveur backend.

Ce document explique comment exécuter le flux du 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 services Google Identity.

Flux de serveur

Assurez-vous de configurer votre application dans API Console pour qu'elle puisse utiliser ces protocoles et authentifier vos utilisateurs. Lorsqu'un utilisateur tente de se connecter avec Google, vous devez:

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. Échanger 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 faites ensuite correspondre 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 envoie la requête et non un pirate informatique malveillant. Ces jetons sont souvent appelés jetons de requête intersites (CSRF).

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

Le code suivant montre comment générer des 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 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. 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 que vous utilisez le protocole 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 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 API Console Credentials page.
• response_type, qui, dans une requête de flux de code d'autorisation de base, doit être code. (Pour en savoir plus, consultez response_type.)
• scope, qui est openid email dans une requête de base. (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. Cette 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 pas à un 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 à 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 les relectures lorsqu'elle est présente.
• 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'approbation pour libérer l'adresse e-mail de l'utilisateur dans votre application. Pour en savoir plus, consultez 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. (Pour en savoir plus, consultez hd.)

Remarque:Seuls les paramètres les plus couramment utilisés sont listés ci-dessus. Pour en obtenir la liste complète, ainsi que des détails sur tous les paramètres, consultez la section Paramètres de l'URI d'authentification.

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=[e-mail]&
 nonce=0394852-3190485-2490358&
 hd=example.com

Les utilisateurs doivent donner leur autorisation si votre application demande de nouvelles informations les concernant ou si votre application demande l'accès au compte qu'elle n'a pas encore approuvée.

3. Confirmer le jeton d'état contre la 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 vérifier que le state reçu de Google correspond au jeton de session que vous avez créé à l'étape 1. Cette validation aller-retour permet de s'assurer que l'utilisateur effectue la requête, et non un script malveillant.

Le code suivant montre 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 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 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. Échanger code contre un jeton d'accès et un jeton d'ID

La réponse inclut un paramètre code, à savoir 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 de POST:

Champs
code	Code d'autorisation renvoyé par la requête initiale.
client_id	ID client obtenu à partir de la page API Console Credentials page, comme décrit dans la section Obtenir des identifiants OAuth 2.0.
client_secret	Code secret client obtenu à partir de la page API Console Credentials page, comme décrit dans la section Obtenir des identifiants OAuth 2.0.
redirect_uri	Un URI de redirection autorisé pour le client_id donné spécifié dans le API Console Credentials page, comme décrit dans 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 positive à cette requête contient les champs suivants dans un tableau JSON:

Champs
access_token	Jeton pouvant être envoyé à une API Google.
expires_in	Durée de vie restante du jeton d'accès en secondes.
id_token	Un JWT contenant des informations sur l'identité de l'utilisateur signée numériquement par Google
scope	Les niveaux d'accès accordés par access_token sont exprimés sous la forme d'une liste de chaînes sensibles à la casse, séparées par un espace.
token_type	Identifie le type de jeton renvoyé. À l'heure actuelle, ce champ a 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 Jetons d'actualisation.

Remarque:Le nombre de jetons par compte utilisateur Google est limité, et les requêtes d'authentification supérieures à cette limite risquent d'invalider un jeton d'actualisation en attente. Pour en savoir plus, consultez la section Expiration du jeton.

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

Un jeton d'ID est un jeton Web JSON (JWT), c'est-à-dire un objet JSON encodé au format Base64 et chiffré. Normalement, il est essentiel de valider un jeton d'ID avant de l'utiliser. Toutefois, puisque vous communiquez directement avec Google via un canal HTTPS sans intermédiaires et que vous utilisez votre code secret client pour vous authentifier auprès de Google, vous pouvez être sûr que le jeton que vous recevez provient bien 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 les autres composants valident le jeton avant de l'utiliser.

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

Charge utile d'un jeton d'ID

Un jeton d'ID est un objet JSON contenant un ensemble de paires nom/valeur. Voici un exemple, formaté 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": "[e-mail]",
  "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	Date d'expiration après laquelle le jeton d'ID ne doit pas être accepté. Représenté au temps Unix (entiers en secondes).
iat	toujours	Heure à laquelle le jeton d'ID a été émis. Représenté au temps Unix (entiers en 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 qui n'est 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 de 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 revendication est toujours incluse. Cette revendication peut être utilisée comme mécanisme alternatif pour se protéger contre les attaques par falsification de requêtes intersites. Toutefois, si vous suivez l'étape 1 et l'étape 3, vous n'avez pas besoin de vérifier 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 est différente de 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 un client_id OAuth 2.0 différent, mais partagent le même projet d'API Google.
email		Adresse e-mail de l'utilisateur. Cette valeur peut ne pas être propre à cet utilisateur et ne pas être utilisée comme clé primaire. Fourni uniquement si votre champ d'application a inclus la valeur du champ d'application email.
email_verified		"True" si l'adresse e-mail de l'utilisateur a été vérifiée ou "false" dans le cas contraire.
family_name		Nom(s) ou nom(s) de l'utilisateur. Peut être fourni lorsqu'une revendication name est présente.
given_name		Nom(s) ou prénom(s) de l'utilisateur. Peut être fourni lorsqu'une revendication 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		Paramètres régionaux de l'utilisateur, représentés par une balise de langue BCP 47. Peut être fourni en cas de revendication name.
name		Nom complet de l'utilisateur, dans un format visible. Peut être indiqué dans les cas suivants : Le champ d'application de la requête incluait la chaîne "profile" Le jeton d'ID est renvoyé après une actualisation du 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 pas garantie.
nonce		Valeur du nonce fourni par votre application dans la requête d'authentification. Vous devez appliquer une protection contre les attaques par relecture 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 indiqué dans les cas suivants : Le champ d'application de la requête incluait la chaîne "profile" Le jeton d'ID est renvoyé après une actualisation du 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 pas garantie.
profile		URL de la page de profil de l'utilisateur. Peut être indiqué dans les cas suivants : Le champ d'application de la requête incluait la chaîne "profile" Le jeton d'ID est renvoyé après une actualisation du 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 pas garantie.

6. Authentifier l'utilisateur

Après avoir obtenu les informations 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 toutes les conditions de connexion sont remplies par la réponse de l'API Google.

S'il n'existe pas dans votre base de données utilisateur, vous devez le rediriger vers le parcours d'inscription du nouvel utilisateur. Il est possible de procéder à l'enregistrement automatique de l'utilisateur en fonction des informations que vous recevez de Google ou au minimum de remplir certains des champs obligatoires dans votre formulaire d'inscription. En plus des informations du jeton d'ID, vous pouvez obtenir des informations supplémentaires sur le profil utilisateur aux points de terminaison de votre profil 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 termes d'authentification et d'autorisation.

Accès à d'autres API Google

L'un des avantages du protocole OAuth 2.0 pour l'authentification est que votre application peut être autorisée à utiliser d'autres API Google en même temps que l'utilisateur (YouTube, Google Drive, Agenda ou Contacts, par exemple). 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 demande d'authentification, transmettez un paramètre de champ d'application défini sur openid email https://www.googleapis.com/auth/profile.agerange.read. L'utilisateur est invité à le faire 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 champs d'application d'accès que vous avez demandés et accordés.

Remarque:Si votre application demande plusieurs champs d'application, l'écran de consentement contient plusieurs lignes de texte. Plus votre application a de champs d'application, moins il est probable que l'utilisateur donne son consentement. Votre application ne doit donc demander que les champs d'application dont elle a besoin.

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 tant que l'utilisateur n'est pas présent dans votre application. Pour demander un jeton d'actualisation, ajoutez le paramètre access_type à offline dans votre demande d'authentification.

Notions clés :

• Assurez-vous de stocker le jeton d'actualisation de manière sécurisée et définitive, car vous ne pouvez l'obtenir que la première fois que vous exécutez le flux d'échange de code.
• Le nombre de jetons d'actualisation émis est limité à un, pour une combinaison client/utilisateur et un autre 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 ne fonctionnent plus.

Pour en savoir plus, consultez Actualiser un jeton d'accès (accès hors connexion).

Demander un nouveau consentement

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 une autorisation pour les niveaux 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 prompt dans le tableau Paramètres d'URI d'authentification.

Paramètres d'URI d'authentification

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

Paramètre	Obligatoire	Description
client_id	(Obligatoire)	Chaîne d'ID client obtenue à partir de la méthode 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 active la protection contre les relectures.
response_type	(Obligatoire)	Si la valeur est code, lance un flux de code d'autorisation de base, qui nécessite l'envoi d'une POST au 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, ce qui nécessite d'utiliser JavaScript dans l'URI de redirection pour récupérer les jetons à partir de l'identifiant #fragment d'URI.
redirect_uri	(Obligatoire)	Détermine l'adresse à laquelle 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 le fichier API Console Credentials page (y compris le schéma HTTP ou HTTPS, la casse et le caractère "/" à la 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 du champ d'application du champ profile est présente, le jeton d'ID peut (mais cela n'est pas garanti) inclure les revendications profile par défaut de l'utilisateur. Si la valeur de champ d'application email est présente, le jeton d'ID inclut les revendications email et email_verified. Outre ces champs d'application spécifiques à OpenID, votre 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 aux fichiers Google Drive d'un utilisateur, votre paramètre de champ d'application peut être openid profile email https://www.googleapis.com/auth/drive.file. Pour en savoir plus sur les champs d'application disponibles, consultez le document Champs d'application OAuth 2.0 pour les API Google ou la documentation sur l'API Google que vous souhaitez utiliser.
state	(Facultatif, mais vivement recommandé)	Chaîne opaque aller-retour dans le protocole, c'est-à-dire renvoyée en tant que paramètre URI dans le flux de base et dans l'identifiant #fragment de l'URI dans le flux implicite. state peut être utile pour corréler les requêtes et les réponses. Comme votre redirect_uri peut être deviné, l'utilisation d'une valeur state peut vous assurer qu'une connexion entrante est le résultat d'une requête 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 (tel qu'un cookie) dans cette variable state, vous pouvez valider la réponse pour vous assurer en outre que la requête et la réponse proviennent du même navigateur. Cela fournit une protection contre les attaques telles que la falsification de requêtes intersites.
access_type	(Facultatif)	Les valeurs autorisées sont offline et online. L'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 pour spécifier comment le serveur d'autorisation affiche les pages d'authentification et d'autorisation de l'interface utilisateur. 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	(Facultatif)	Simplifiez le processus de connexion aux comptes appartenant à une organisation Google Cloud. En incluant le domaine d'organisation Google Cloud (par exemple, mycollege.edu), vous pouvez indiquer que l'interface utilisateur de sélection de comptes doit être optimisée pour les comptes de ce domaine. Pour optimiser les comptes d'organisation Google Cloud en général et non un seul domaine d'organisation Google Cloud, définissez la valeur d'un astérisque (*) : hd=*. Ne vous fiez pas à cette optimisation de l'interface utilisateur pour contrôler qui peut accéder à votre application, car les requêtes côté client peuvent être modifiées. Assurez-vous de valider que le jeton d'ID renvoyé est associé à une valeur de revendication hd correspondant à votre attente (par exemple, mycolledge.edu). Contrairement au paramètre de requête, la revendication du jeton d'ID hd est contenue dans un jeton de sécurité de Google. Ainsi, la valeur peut être approuvée.
include_granted_scopes	(Facultatif)	Si ce paramètre est fourni avec la valeur true et que la demande d'autorisation est accordée, l'autorisation inclut toutes les autorisations précédentes accordées à cette combinaison utilisateur/application pour d'autres champs d'application ; voir Autorisation incrémentielle. Notez que vous ne pouvez pas effectuer d'autorisation incrémentielle avec le flux d'application installée.
login_hint	(Facultatif)	Lorsque votre application sait quel utilisateur elle tente d'authentifier, elle peut fournir ce paramètre en tant qu'indice au serveur d'authentification. La transmission de cet indice élimine le sélecteur de compte et préremplit la zone d'e-mail sur le formulaire de connexion, ou sélectionne la session appropriée (si l'utilisateur utilise la connexion multicompte). Cela peut vous aider à éviter les problèmes qui se produisent 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 un espace, indiquant 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 qu'il 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. Cela permet à un utilisateur disposant de plusieurs comptes sur le serveur d'autorisation de sélectionner l'un des 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 encore autorisé l'accès, un écran de consentement s'affiche.

Valider un jeton d'ID

Vous devez valider tous les jetons d'ID 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'ID qu'il reçoit de vos applications clientes.

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

• Envoi de jetons d'ID avec des requêtes à authentifier. Les jetons d'ID vous indiquent l'utilisateur à l'origine de la requête et le client auquel il a été accordé.

Les jetons d'ID sont sensibles et peuvent être utilisés de manière incorrecte 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 les données POST ou dans les en-têtes de requête. Si vous stockez des jetons d'identification sur votre serveur, vous devez également les stocker de manière sécurisée.

L'un des avantages des jetons d'ID est que vous pouvez les transmettre à différents composants de votre application. Ces composants peuvent utiliser un jeton d'ID 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 compter sur celui-ci pour confirmer que l'utilisateur s'est authentifié, vous devez le valider.

La validation d'un jeton d'ID 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 se trouvant à 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 passé.
5. Si vous avez spécifié une valeur de paramètre HD dans la requête, vérifiez que le jeton d'ID possède 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 assez simples. Nous ne les détaillerons donc pas ici.

La première étape est plus complexe et implique une vérification cryptographique de la signature. À des fins de débogage, vous pouvez utiliser le point de terminaison tokeninfo de Google pour comparer le traitement en local implémenté 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 du jeton 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 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 faire l'objet d'erreurs intermittentes.

Comme 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 la validation en local beaucoup plus efficacement qu'avec 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, des bibliothèques bien débogagees sont disponibles dans de nombreux langages. (Consultez la page 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 sur 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 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. Par conséquent, vous ne recevrez peut-être pas d'informations pour chacun des champs d'application autorisés.

Document Discovery

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

Pour simplifier les implémentations et gagner en flexibilité, OpenID Connect permet d'utiliser un document de découverte, un document JSON trouvé à un emplacement connu et contenant des paires clé/valeur. Ces documents fournissent des détails sur la configuration d'OpenID Connect, y compris les URI des points de terminaison d'autorisation, de jeton, de révocation, d'utilisateur et de clé publique. Le document Discovery du service OpenID Connect de Google peut être récupéré à partir des pages suivantes:

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 les règles de mise en cache dans la réponse, puis extrait les URI du point de terminaison 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) comme URI de base pour les requêtes d'authentification envoyées à Google.

Voici un exemple de ce type de document. Les noms des champs sont ceux spécifiés dans OpenID Connect Discovery 1.0 (pour connaître leur signification, consultez le document). Les valeurs sont uniquement fournies à titre d'illustration et peuvent changer, mais elles sont 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 é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 en s'intégrant aux frameworks courants:

• Bibliothèque cliente des API Google pour Java
• Bibliothèque cliente des API Google pour Python
• Bibliothèque cliente des API Google pour .NET
• Bibliothèque cliente des API Google pour Ruby
• Bibliothèque cliente des API Google pour PHP
• Bibliothèque OAuth 2.0 pour Google Web Toolkit
• Google Toolbox pour les manettes OAuth 2.0 pour Mac

Conformité OpenID Connect

Le système d'authentification OAuth 2.0 de Google est compatible avec les fonctionnalités requises pour 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).