Types de jetons

Cette page décrit les types de jetons utilisés pour l'authentification auprès des API Google, des services Google Cloud et des services créés par le client hébergés sur Google Cloud.

Si vous accédez aux API et aux services de Google à l'aide d'une bibliothèque cliente, vous pouvez configurer les identifiants par défaut de l'application, et la bibliothèque cliente gère les jetons pour vous. Il s'agit de l'approche recommandée.

Définition des jetons

Pour l'authentification et l'autorisation, un jeton est un objet numérique qui contient des informations sur l'identité du compte principal qui effectue la requête et le type d'accès pour lequel il est autorisé. Dans la plupart des flux d'authentification, l'application (ou une bibliothèque utilisée par l'application) échange un identifiant contre un jeton, qui détermine les ressources auxquelles l'application est autorisée à accéder.

Types de jetons

Différents types de jetons sont utilisés dans différents environnements. Les types de jetons suivants sont décrits sur cette page :

Cette page ne traite pas des clés API ni des ID clients, qui sont considérés comme des identifiants.

Jetons d'accès

Les jetons d'accès sont des jetons opaques conformes au framework OAuth 2.0. Ils contiennent des informations d'autorisation, mais pas d'informations d'identité. Elles permettent de s'authentifier et de fournir des informations d'autorisation aux API Google.

Si vous utilisez les identifiants par défaut de l'application et les bibliothèques clientes Cloud ou les bibliothèques clientes des API Google, vous n'avez pas besoin de gérer les jetons d'accès. Les bibliothèques récupèrent automatiquement les identifiants, les échangent contre un jeton d'accès et actualisent le jeton d'accès si nécessaire.

Contenu des jetons d'accès

Les jetons d'accès sont des jetons opaques, ce qui signifie qu'ils se présentent dans un format propriétaire. Les applications ne peuvent pas les inspecter. Vous pouvez obtenir les informations à partir d'un jeton d'accès valide (non expiré ni révoqué) à l'aide du point de terminaison tokeninfo de Google OAuth 2.0.

Remplacez ACCESS_TOKEN par le jeton d'accès valide et non expiré.

curl "https://oauth2.googleapis.com/tokeninfo?access_token=ACCESS_TOKEN"

Cette commande renvoie un résultat semblable à l'exemple suivant :

{
  "azp": "32553540559.apps.googleusercontent.com",
  "aud": "32553540559.apps.googleusercontent.com",
  "sub": "111260650121245072906",
  "scope": "openid https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/cloud-platform https://www.googleapis.com/auth/accounts.reauth",
  "exp": "1650056632",
  "expires_in": "3488",
  "email": "user@example.com",
  "email_verified": "true"
}

Le tableau suivant répertorie les champs les plus importants à comprendre :

Champ Description
azp ID du projet, de l'adresse e-mail ou du compte de service de l'application qui a demandé le jeton. Cette valeur n'est incluse que si https://www.googleapis.com/auth/userinfo.email est spécifié dans la liste des champs d'application.
scope Niveaux d'accès OAuth qui ont été ajoutés à ce jeton d'accès. Pour les services Google Cloud, il est recommandé d'utiliser le champ d'application https://www.googleapis.com/auth/cloud-platform, qui inclut toutes les API Google Cloud, ainsi que Identity and Access Management (IAM), qui fournit un contrôle des accès précis.
expires_in Nombre de secondes avant l'expiration du jeton. Pour en savoir plus, consultez la section Durée de vie d'un jeton d'accès.

Durée de vie d'un jeton d'accès

Par défaut, les jetons d'accès sont valides pendant une heure, soit 3 600 secondes. Lorsque le jeton d'accès a expiré, votre code de gestion des jetons doit en obtenir un nouveau.

Si vous avez besoin d'un jeton d'accès avec une durée de vie plus longue ou plus courte, vous pouvez utiliser la méthode serviceAccounts.generateAccessToken pour le créer. Cette méthode vous permet de choisir la durée de vie du jeton, avec une durée de vie maximale de 12 heures.

Si vous souhaitez prolonger la durée de vie du jeton au-delà de la valeur par défaut, vous devez créer une règle d'administration qui active la contrainte iam.allowServiceAccountCredentialLifetimeExtension. Vous ne pouvez pas créer de jetons d'accès avec une durée de vie prolongée pour les identifiants utilisateur ni pour les identités externes. Pour en savoir plus, consultez la page Créer un jeton d'accès de courte durée.

Jetons d'ID

Les jetons d'ID sont des jetons Web JSON (JWT, JSON Web Tokens) conformes à la spécification OpenID Connect (OIDC). Ils sont composés d'un ensemble de paires clé/valeur appelées revendications.

Contrairement aux jetons d'accès, qui sont des objets opaques qui ne peuvent pas être inspectés par l'application, les jetons d'ID sont destinés à être inspectés et utilisés par l'application. Les informations du jeton, telles que la personne qui a signé le jeton ou l'identité pour laquelle le jeton d'ID a été émis, peuvent être utilisées par l'application.

Pour plus d'informations sur la mise en œuvre d'OIDC de Google, consultez la page OpenID Connect. Pour connaître les bonnes pratiques concernant l'utilisation des jetons JWT, consultez la page Bonnes pratiques actuelles concernant les jetons Web JSON.

Contenu des jetons d'ID

Vous pouvez inspecter un jeton d'ID valide (non expiré ni révoqué) à l'aide du point de terminaison tokeninfo de Google OAuth 2.0.

Remplacez ID_TOKEN par un jeton d'ID valide et non expiré.

curl "https://oauth2.googleapis.com/tokeninfo?id_token=ID_TOKEN"

Cette commande renvoie un résultat semblable à l'exemple suivant :

{
  "iss": "https://accounts.google.com",
  "azp": "32555350559.apps.googleusercontent.com",
  "aud": "32555350559.apps.googleusercontent.com",
  "sub": "111260650121185072906",
  "hd": "google.com",
  "email": "user@example.com",
  "email_verified": "true",
  "at_hash": "_LLKKivfvfme9eoQ3WcMIg",
  "iat": "1650053185",
  "exp": "1650056785",
  "alg": "RS256",
  "kid": "f1338ca26835863f671403941738a7b49e740fc0",
  "typ": "JWT"
}

Le tableau suivant décrit les revendications de jeton d'ID obligatoires ou couramment utilisées :

Demander Description
iss Émetteur, ou signataire, du jeton. Pour les jetons d'ID signés par Google, cette valeur est https://accounts.google.com.
azp Facultatif. la personne pour laquelle le jeton a été émis.
aud Audience du jeton. La valeur de cette revendication doit correspondre à l'application ou au service qui utilise le jeton pour authentifier la requête. Pour en savoir plus, consultez la section Revendication aud d'un jeton d'ID.
sub Le sujet : ID qui représente le compte principal qui effectue la requête.
iat Heure epoch Unix lors de l'émission du jeton.
exp Heure epoch Unix lorsque le jeton expire.

D'autres revendications peuvent être présentes, en fonction de l'émetteur et de l'application.

Revendication aud d'un jeton d'ID

La revendication aud décrit le nom du service que ce jeton a été créé pour appeler. Si un service reçoit un jeton d'ID, il doit vérifier son intégrité (signature), sa validité (a-t-il expiré) et si la revendication aud correspond au nom attendu. Si ce n'est pas le cas, le service doit rejeter le jeton, car il peut s'agir d'une relecture conçue pour un autre système.

En règle générale, lorsque vous obtenez un jeton d'ID, vous utilisez les identifiants fournis par un compte de service plutôt que les identifiants de l'utilisateur. En effet, la revendication aud pour les jetons d'ID générés à l'aide d'identifiants utilisateur est statiquement liée à l'application que l'utilisateur a utilisée pour l'authentification. Lorsque vous utilisez un compte de service pour acquérir un jeton d'ID, vous pouvez spécifier une valeur différente pour la revendication aud.

Durée de vie d'un jeton d'ID

Les jetons d'ID sont valides pendant une durée maximale d'une heure (3 600 secondes). Lorsqu'un jeton d'ID expire, vous devez en acquérir un nouveau.

Validation des jetons d'ID

Lorsque votre service ou application utilise un service Google tel que Cloud Run, Cloud Functions ou Identity-Aware Proxy, Google valide les jetons d'ID à votre place. Dans ce cas, les jetons d'ID doivent être signés par Google.

Si vous devez valider les jetons d'ID dans votre application, vous pouvez le faire, bien qu'il s'agisse d'un workflow avancé. Pour en savoir plus, consultez la section Valider un jeton d'ID.

Jetons Web JSON (JWT) autosignés

Les jetons JWT autosignés sont requis pour s'authentifier auprès des API déployées avec API Gateway. De plus, vous pouvez utiliser des jetons JWT autosignés pour vous authentifier auprès de certaines API Google sans avoir à obtenir de jeton d'accès auprès du serveur d'autorisation.

La création de jetons JWT autosignés est recommandée si vous créez vos propres bibliothèques clientes pour accéder aux API Google, mais il s'agit d'un workflow avancé. Pour en savoir plus sur les jetons JWT autosignés, consultez la section Créer un jeton Web JSON autosigné. Pour connaître les bonnes pratiques concernant l'utilisation des jetons JWT, consultez la page Bonnes pratiques actuelles concernant les jetons Web JSON.

Jetons d'actualisation

Par défaut, les jetons d'accès et les jetons d'ID sont valides pendant une heure. Un jeton d'actualisation est un jeton spécial permettant d'obtenir des jetons d'accès ou des jetons d'ID supplémentaires. Lors de la première authentification de votre application, elle reçoit un jeton d'accès ou un jeton d'ID, ainsi qu'un jeton d'actualisation. Ensuite, si l'application doit à nouveau accéder aux ressources et que le jeton précédemment fourni a expiré, elle utilise le jeton d'actualisation pour demander un nouveau jeton. Les jetons d'actualisation ne sont utilisés que pour l'authentification des utilisateurs, par exemple pour Cloud Identity ou Google Workspace.

Les jetons d'actualisation n'ont pas de durée de vie définie. Ils peuvent expirer, mais, dans le cas contraire, ils restent utilisables. Pour un accès utilisateur dans Google Workspace ou Cloud Identity Premium Edition, vous pouvez configurer la durée de session pour vous assurer qu'un utilisateur doit se connecter régulièrement pour conserver l'accès aux services Google Cloud.

Si votre application crée et gère ses propres jetons, elle doit également gérer les jetons d'actualisation. Pour en savoir plus, consultez les liens suivants :

Jetons fédérés

Les jetons fédérés sont utilisés comme étape intermédiaire par la fédération d'identité de charge de travail. Les jetons fédérés sont renvoyés par Security Token Service et ne peuvent pas être utilisés directement. Vous devez les échanger contre un jeton d'accès en utilisant l'identité d'un compte de service.

Jetons de support

Les jetons de support sont une classe générale de jetons qui accorde l'accès à la partie en possession du jeton. Les jetons d'accès, les jetons d'ID et les jetons JWT autosignés sont tous des jetons de support.

L'utilisation de jetons de support pour l'authentification repose sur la sécurité fournie par un protocole chiffré, tel que HTTPS. Si un jeton de support est intercepté, il peut être utilisé par un acteur malintentionné pour obtenir l'accès.

Si les jetons de support n'offrent pas une sécurité suffisante pour votre cas d'utilisation, envisagez d'ajouter une autre couche de chiffrement ou d'utiliser une solution mutuelle Transport Layer Security (mTLS), telle que BeyondCorp Enterprise, qui limite l'accès aux seuls utilisateurs authentifiés sur un appareil vérifié.

Étapes suivantes