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 implémentation OAuth 2.0 pour l'authentification, qui est conforme à la spécification OpenID Connect et certifiée OpenID. La documentation disponible 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 tag "google-oauth" à vos questions.

Remarque : Pour ajouter un bouton "Se connecter avec Google" à votre site Web, utilisez Google Identity Services, notre bibliothèque cliente de connexion basée sur le protocole OpenID Connect. Cette bibliothèque fournit des jetons d'identité au format OpenID Connect. Les applications Android doivent utiliser l'API Credential Manager pour implémenter le flux Se connecter avec Google.

Configurer 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 la pour obtenir des identifiants OAuth 2.0, définir un URI de redirection et (facultativement) personnaliser les informations de branding que vos utilisateurs voient sur l'écran de consentement. Vous pouvez également utiliser 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' aide .

Obtenir des identifiants OAuth 2.0

Vous avez besoin d'identifiants OAuth 2.0, y compris d'un ID client et d'un code secret client, 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 in :

1. Go to the Credentials page.
2. Click the name of your client or the edit () 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 définissez dans détermine l'emplacement où Google envoie les réponses à vos demandes 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. Click on the client.
3. View or edit the redirect URIs.

If there is no listed client in the Clients page, then your project has no OAuth credentials. To create one, click Create client.

Personnaliser l'écran d'autorisation de l'utilisateur

Pour vos utilisateurs, l'expérience d'authentification OAuth 2.0 inclut un écran de consentement qui décrit les informations que l'utilisateur partage et les conditions applicables. 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 des niveaux d'accès pour demander l'accès à d'autres API Google.

L'écran d'autorisation de l'utilisateur présente également des informations sur la marque, telles que le nom et le logo de votre produit, ainsi que l'URL d'une page d'accueil. Vous contrôlez les informations sur la marque dans .

To enable your project's consent screen:

1. Open the in the .
2. If prompted, select a project, or create a new one.
3. Fill out the form and click Save.

La boîte de dialogue de consentement suivante montre ce qu'un utilisateur verrait lorsqu'une combinaison de périmètres OAuth 2.0 et Google Drive est 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. Elle n'inclut donc pas les informations de branding qui seraient définies dans .)

Figure 1. 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 gérer de nombreux détails d'implémentation de l'authentification des utilisateurs et de l'accès aux API Google. Par exemple, les services d'identité Google et les bibliothèques clientes Google sont disponibles pour différentes plates-formes.

Remarque : Compte tenu des implications en termes de sécurité liées à la bonne implémentation, nous vous encourageons vivement à utiliser une bibliothèque ou un service préécrits. Il est important d'authentifier correctement les utilisateurs pour leur sécurité et la vôtre. Il est généralement recommandé d'utiliser du code bien débogué écrit par d'autres. Pour en savoir plus, consultez Bibliothèques clientes.

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.

Authentifier l'utilisateur

L'authentification de l'utilisateur implique l'obtention et la validation d'un jeton d'identité. Les jetons d'identité sont une fonctionnalité standard d'OpenID Connect conçue pour partager des assertions d'identité sur Internet.

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

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

Flux du serveur

Assurez-vous de configurer votre application dans pour lui permettre d'utiliser ces protocoles et d'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'identité
5. Obtenir des informations sur l'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ête. La première étape consiste à créer un jeton de session unique qui conserve 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 la demande est effectuée par l'utilisateur et non par un pirate informatique malveillant. Ces jetons sont souvent appelés jetons de falsification des requêtes intersites (CSRF).

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

Le code suivant montre comment générer des jetons de session uniques.

PHP

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

// 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

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

// 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

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

# 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 GET HTTPS avec les paramètres URI appropriés. Notez que nous utilisons 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 .
• 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 doit être openid email dans une requête de base. (Pour en savoir plus, consultez 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 Credentials page. Si cette valeur ne correspond pas à un URI autorisé, la requête échouera et renverra 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épart). (Pour en savoir plus, consultez state.)
• nonce est une valeur aléatoire générée par votre application qui permet la protection contre la relecture 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 connecté, l'écran de consentement inclut une demande d'approbation pour communiquer l'adresse e-mail de l'utilisateur à 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 spécifique associé à une organisation Google Workspace ou Cloud (pour en savoir plus, consultez hd).
Remarque : Il s'agit de certains des paramètres les plus couramment utilisés. Pour obtenir la liste complète et plus d'informations sur tous les paramètres, consultez 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 consentement si votre application demande de nouvelles informations les concernant ou si elle demande l'accès à un compte qu'ils n'ont pas approuvé auparavant.

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

La réponse est envoyée à l'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 :

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 vérifier que la requête est envoyée par l'utilisateur et non par un script malveillant.

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

PHP

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

// 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

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

// 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

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

# 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'identité

La réponse inclut un paramètre code, un code d'autorisation à usage unique que votre serveur peut échanger contre un jeton d'accès et un jeton d'identité. 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 que vous obtenez à partir de , comme décrit dans Obtenir des identifiants OAuth 2.0.
client_secret	Code secret du client que vous obtenez à partir de , comme décrit dans Obtenir des identifiants OAuth 2.0.
redirect_uri	URI de redirection autorisé pour le client_id donné spécifié dans le , comme décrit dans Définir un URI de redirection.
grant_type	Ce champ doit contenir la valeur authorization_code, telle que définie 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 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é numériquement par Google.
scope	Champs d'application de l'accès accordé par access_token, exprimés sous la forme d'une liste de chaînes sensibles à la casse et délimitées par des espaces.
token_type	Identifie le type de jeton renvoyé. Pour le moment, 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 demande d'authentification. Pour en savoir plus, consultez Jetons d'actualisation.

Remarque : Le nombre de jetons par compte utilisateur Google est limité. Toute demande d'authentification dépassant cette limite peut invalider silencieusement un jeton d'actualisation en cours. Pour en savoir plus, consultez Expiration du jeton.

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

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 de valider un jeton d'identité avant de l'utiliser. Toutefois, comme 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 recevez provient réellement de Google et qu'il est valide. Si votre serveur transmet le jeton d'identité à 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 décodage des valeurs encodées en base64url et l'analyse du JSON, vous finirez probablement par valider le jeton de toute façon lorsque vous accéderez aux revendications dans le jeton d'identité.

Charge utile d'un jeton d'ID

Un jeton d'identité est un objet JSON contenant un ensemble de paires nom/valeur. Voici un exemple, mis en forme pour plus de 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"
}

Avertissement : Lorsque vous implémentez votre système de gestion de compte, vous ne devez pas utiliser le champ email du jeton d'identité comme identifiant unique pour un utilisateur. Utilisez toujours le champ sub, car il est unique à un compte Google, même si l'utilisateur modifie son adresse e-mail.

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

Revendication	Fourni	Description
aud	toujours	Audience à laquelle ce jeton d'identité est destiné. Il doit s'agir de l'un des ID client OAuth 2.0 de votre application.
exp	toujours	Heure d'expiration à partir de laquelle le jeton d'identité ne doit plus être accepté. Représenté en heure Unix (entier en secondes).
iat	toujours	Heure à laquelle le jeton d'identité a été émis. Représenté en heure Unix (entier 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 unique de l'utilisateur parmi tous les comptes Google. Il 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 du jeton d'accès. Valide que le jeton d'accès est lié au jeton d'identité. Si le jeton d'identité 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ête intersite. Toutefois, si vous suivez les étapes 1 et 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'identité n'est pas la même que l'audience du jeton d'identité. 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. Fourni uniquement si vous avez inclus le champ d'application email dans votre requête. La valeur de cette revendication n'est pas forcément unique à ce compte et peut changer au fil du temps. Par conséquent, vous ne devez pas l'utiliser comme identifiant principal pour l'associer à votre enregistrement utilisateur. Vous ne pouvez pas non plus vous appuyer sur le domaine de la revendication email pour identifier les utilisateurs des organisations Google Workspace ou Cloud. Utilisez plutôt la revendication hd. Avertissement : N'utilisez pas le champ email comme identifiant unique pour un utilisateur. Utilisez toujours le champ sub.
email_verified		True si l'adresse e-mail de l'utilisateur a été validée, sinon false.
family_name		Nom(s) de famille de l'utilisateur. Peut être fourni lorsqu'une revendication name est présente.
given_name		Prénom(s) 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 cocher cette case lorsque vous limitez l'accès à une ressource aux membres de certains domaines uniquement. L'absence de cette revendication indique que le compte n'appartient pas à un domaine hébergé par Google.
locale		Paramètres régionaux de l'utilisateur, représentés par un tag 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 : La chaîne "profile" était incluse dans le champ d'application de la requête. Le jeton d'identité 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 cette revendication n'est jamais garantie.
nonce		Valeur de nonce fournie par votre application dans la requête d'authentification. Vous devez vous protéger contre les attaques par rejeu en ne présentant cette valeur qu'une seule fois.
picture		URL de la photo de profil de l'utilisateur. Peut être fourni dans les cas suivants : La chaîne "profile" était incluse dans le champ d'application de la requête. Le jeton d'identité 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 cette revendication n'est jamais garantie.
profile		URL de la page de profil de l'utilisateur. Peut être fourni dans les cas suivants : La chaîne "profile" était incluse dans le champ d'application de la requête. Le jeton d'identité 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 cette revendication n'est jamais garantie.

6. Authentifier l'utilisateur

Après avoir obtenu les informations utilisateur à partir du jeton d'identité, vous devez interroger la base de données des utilisateurs 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 exigences de connexion sont satisfaites par la réponse de l'API Google.

Si l'utilisateur n'existe pas dans votre base de données, vous devez le rediriger vers votre processus d'inscription pour les nouveaux utilisateurs. Vous pourrez peut-être enregistrer automatiquement l'utilisateur en fonction des informations que vous recevez de Google, ou au moins préremplir de nombreux champs requis dans votre formulaire d'inscription. En plus des informations contenues dans le jeton d'identité, vous pouvez obtenir des informations supplémentaires sur le profil utilisateur au niveau de nos points de terminaison de 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 matière d'authentification et d'autorisation.

Accès aux 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 (comme YouTube, Google Drive, Agenda ou Contacts) en même temps que vous authentifiez l'utilisateur. Pour ce faire, incluez les autres niveaux d'accès 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 de portée openid email https://www.googleapis.com/auth/profile.agerange.read. L'utilisateur est invité à donner son autorisation de manière appropriée sur l'écran d'autorisation. Le jeton d'accès que vous recevez de Google permettra à votre application d'accéder à toutes les API liées aux niveaux d'accès que vous avez demandés et obtenus.

Remarque : Si votre application demande de nombreux niveaux d'accès, l'écran de consentement contient de nombreuses lignes de texte. Plus votre application demande d'autorisations, moins l'utilisateur est susceptible de les accorder. Par conséquent, votre application ne doit demander que les autorisations 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 permet à votre application d'accéder en continu aux API Google lorsque l'utilisateur n'est pas présent dans votre application. Pour demander un jeton d'actualisation, définissez le paramètre access_type sur offline dans votre demande d'authentification.

Remarques :

• Veillez à stocker le jeton d'actualisation de manière sécurisée et permanente, car vous ne pouvez l'obtenir 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, auquel cas les jetons d'actualisation plus anciens cessent de fonctionner.

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

Demander à nouveau le consentement

Vous pouvez inviter l'utilisateur à réautoriser votre application en définissant le paramètre prompt sur consent dans votre demande d'authentification. Lorsque prompt=consent est inclus, l'écran d'autorisation 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 lorsque cela est nécessaire.

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

Paramètres de l'URI d'authentification

Le tableau suivant fournit des descriptions plus complètes 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 que vous obtenez à partir de , comme décrit dans Obtenir des identifiants OAuth 2.0.
nonce	(Obligatoire)	Valeur aléatoire générée par votre application qui permet la protection contre les attaques par rejeu.
response_type	(Obligatoire)	Si la valeur est code, un flux de code d'autorisation de base est lancé, ce qui nécessite un POST au point de terminaison du jeton pour obtenir les jetons. Si la valeur est token id_token ou id_token token, un flux implicite est lancé, ce qui nécessite l'utilisation de JavaScript au niveau de l'URI de redirection pour récupérer les jetons à partir de l'identifiant 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 (y compris le schéma HTTP ou HTTPS, la casse et la barre oblique de fin, 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 du champ d'application profile est présente, le jeton d'identité peut inclure (mais ce n'est pas garanti) les revendications profile par défaut de l'utilisateur. Si la valeur du champ d'application email est présente, le jeton d'identité inclut les revendications email et email_verified. En plus de 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 portée doivent être séparées par un espace. Par exemple, si vous souhaitez accéder aux fichiers d'un utilisateur dans Google Drive, votre paramètre de portée peut être openid profile email https://www.googleapis.com/auth/drive.file. Pour en savoir plus 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 qui est renvoyée dans le protocole, c'est-à-dire qu'elle est renvoyée en tant que paramètre URI dans le flux de base et dans l'identifiant 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é, l'utilisation d'une valeur state peut vous assurer 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 state, vous pouvez valider la réponse pour vérifier que la requête et la réponse proviennent du même navigateur. Cela permet de se protéger contre les attaques telles que la contrefaçon de requêtes intersites.
access_type	(Facultatif)	Les valeurs autorisées sont offline et online. L'effet est documenté dans 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 façon dont 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 Google, mais n'ont aucun effet sur le comportement du flux de protocole : page, popup, touch et wap.
hd	(Facultatif)	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 plutôt qu'un seul domaine d'organisation Google Cloud, définissez la valeur d'un astérisque (*) : hd=*. Ne vous fiez pas à cette optimisation de l'UI 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 la valeur de la revendication hd du jeton d'ID renvoyé correspond à celle attendue (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. Vous pouvez donc faire confiance à sa valeur.
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 inclura toutes les autorisations précédemment accordées à cette combinaison utilisateur/application pour d'autres niveaux d'accès. Pour en savoir plus, consultez 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 comme indication au serveur d'authentification. Le fait de transmettre cet indice supprime le sélecteur de compte et préremplit la zone de texte de l'adresse e-mail dans le formulaire de connexion ou sélectionne la session appropriée (si l'utilisateur utilise la connexion multiple). 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 délimitées par des espaces qui indique 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 ni 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 demande le consentement de l'utilisateur 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 choisir parmi les 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 autorisé l'accès auparavant, un écran de consentement s'affiche.

Valider un jeton d'identité

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

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

• Envoyer des jetons d'ID avec les requêtes qui doivent être authentifiées. Les jetons d'identité vous indiquent l'utilisateur spécifique qui effectue la requête et le client pour lequel ce jeton d'identité a été accordé.

Les jetons d'identité 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 en utilisant uniquement des 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.

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

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

1. Vérifiez que le jeton d'identité est correctement signé par l'émetteur. Les jetons émis par Google sont signés à l'aide de l'un des certificats disponibles à 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'identité est égale à https://accounts.google.com ou accounts.google.com.
3. Vérifiez que la valeur de la revendication aud dans le jeton d'identité est égale à l'ID client de votre application.
4. Vérifiez que le délai d'expiration (revendication exp) du jeton d'identité 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'identité comporte une revendication hd qui correspond à 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 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 le comparer au traitement local implémenté sur votre serveur ou appareil. Supposons que la valeur de votre jeton d'identité 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 la forme d'un 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 adressées au point de terminaison de débogage peuvent être limitées ou faire l'objet d'erreurs intermittentes.

Étant donné que Google ne modifie ses clés publiques que rarement, 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 de nombreux langages pour y parvenir (voir jwt.io).

Obtenir des informations sur le 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 demande d'authentification.

   Si vous souhaitez inclure l'adresse e-mail de l'utilisateur, vous pouvez spécifier une valeur de portée 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 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 ne pas fournir certaines informations. Il est donc possible que vous n'obteniez pas d'informations pour tous les champs 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, y compris des jetons, des informations utilisateur et des clés publiques.

Pour simplifier les implémentations et accroître la flexibilité, OpenID Connect permet d'utiliser un "document de découverte". Il s'agit d'un document JSON situé à un emplacement bien connu et contenant des paires clé-valeur qui fournissent des informations sur la configuration du fournisseur OpenID Connect, y compris les URI des points de terminaison d'autorisation, de jeton, de révocation, d'informations utilisateur et de clés publiques. Le document de découverte du service OpenID Connect de Google peut être récupéré à l'adresse suivante :

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 récupère les URI de point de terminaison à partir de celui-ci, 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 d'un tel 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 purement illustratives et peuvent changer, bien qu'elles soient copiées à partir d'une version récente du document de découverte Google :

{
  "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 populaires :

• 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
• Contrôleurs OAuth 2.0 de Google Toolbox pour Mac

Conformité avec OpenID Connect

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