Utiliser OAuth 2.0 pour l'authentification serveur à serveur

?

Pour en savoir plus, consultez Présentation de l'authentification dans la documentation Google Cloud Platform.

Le système Google OAuth 2.0 prend en charge les interactions de serveur à serveur, telles que celles entre une application Web et un service Google. Pour ce scénario, vous avez besoin d'un compte de service, qui appartient à votre application et non à un utilisateur final individuel. Votre application appelle les API Google au nom du compte de service. Les utilisateurs ne sont donc pas directement impliqués. Ce scénario est parfois appelé "OAuth en deux étapes" ou "2LO". (Le terme associé "OAuth en trois étapes" fait référence aux scénarios dans lesquels votre application appelle les API Google au nom des utilisateurs finaux et dans lesquels un consentement de l'utilisateur est parfois requis.)

Généralement, une application utilise un compte de service lorsqu'elle utilise les API Google pour utiliser ses propres données plutôt que celles d'un utilisateur. Par exemple, une application qui utilise Google Cloud Datastore pour la persistance des données utilisera un compte de service pour authentifier ses appels à l'API Google Cloud Datastore.

Les administrateurs de domaine Google Workspace peuvent également accorder aux comptes de service de l'autorité au niveau du domaine l'accès aux données des utilisateurs au nom des utilisateurs du domaine.

Ce document explique comment une application peut terminer le flux OAuth 2.0 de serveur à serveur à l'aide d'une bibliothèque cliente des API Google (recommandé) ou de HTTP.

Avec certaines API Google, vous pouvez effectuer des appels d'API autorisés à l'aide d'un jeton JWT signé au lieu d'utiliser OAuth 2.0, qui permet d'économiser une requête réseau. Consultez Annexe: Autorisation du compte de service sans OAuth.

Présentation

Pour permettre les interactions de serveur à serveur, créez d'abord un compte de service pour votre projet dans le API Console. Si vous souhaitez accéder aux données utilisateur des utilisateurs de votre compte Google Workspace, déléguez l'accès au compte de service à l'échelle du domaine.

Votre application se prépare ensuite à effectuer des appels d'API autorisés à l'aide des identifiants du compte de service pour demander un jeton d'accès au serveur d'authentification OAuth 2.0.

Enfin, votre application peut utiliser le jeton d'accès pour appeler les API Google.

Recommandation:Votre application peut effectuer ces tâches en utilisant la bibliothèque cliente des API Google pour votre langage ou en interagissant directement avec le système OAuth 2.0 via HTTP. Cependant, le mécanisme des interactions d'authentification de serveur à serveur nécessite que les applications créent et signent de manière chiffrée des jetons Web JSON (JWT), et il est facile de faire de graves erreurs qui peuvent avoir de graves conséquences sur la sécurité de votre application.

C'est pourquoi nous vous encourageons vivement à utiliser des bibliothèques telles que les bibliothèques clientes des API Google, qui extraient la cryptographie du code de votre application.

Créer un compte de service

Les identifiants d'un compte de service incluent une adresse e-mail générée unique et au moins une paire de clés publique/privée. Si la délégation au niveau du domaine est activée, un ID client fait également partie des identifiants du compte de service.

Si votre application s'exécute sur Google App Engine, un compte de service est configuré automatiquement lorsque vous créez votre projet.

Si votre application s'exécute sur Google Compute Engine, un compte de service est également configuré automatiquement lorsque vous créez votre projet, mais vous devez spécifier les champs d'application auxquels votre application doit accéder lorsque vous créez une instance Google Compute Engine. Pour en savoir plus, consultez Préparer une instance pour utiliser les comptes de service.

Si votre application n'est pas exécutée sur Google App Engine ou Google Compute Engine, vous devez vous procurer ces identifiants dans le Google API Console. Pour générer les identifiants du compte de service ou afficher les identifiants publics que vous avez déjà générés, procédez comme suit:

Tout d'abord, créez un compte de service :

1. Ouvrez le Service accounts page.
2. If prompted, select a project, or create a new one.
3. Cliquez sur Créer un compte de service .
4. Sous Détails du compte de service , saisissez un nom, un ID et une description pour le compte de service, puis cliquez sur Créer et continuer .
5. Facultatif : sous Accorder à ce compte de service l'accès au projet , sélectionnez les rôles IAM à accorder au compte de service.
6. Cliquez sur Continuer .
7. Facultatif : sous Accorder aux utilisateurs l'accès à ce compte de service , ajoutez les utilisateurs ou les groupes autorisés à utiliser et à gérer le compte de service.
8. Cliquez sur Terminé .

Ensuite, créez une clé de compte de service :

1. Cliquez sur l'adresse e-mail du compte de service que vous avez créé.
2. Cliquez sur l'onglet Clés .
3. Dans la liste déroulante Ajouter une clé , sélectionnez Créer une nouvelle clé .
4. Cliquez sur Créer .

Votre nouvelle paire de clés publique/privée est générée et téléchargée sur votre machine ; il sert de seule copie de la clé privée. Vous êtes responsable de sa conservation en toute sécurité. Si vous perdez cette paire de clés, vous devrez en générer une nouvelle.

Vous pouvez revenir à API Console à tout moment pour afficher l'adresse e-mail, les empreintes de clé publique et d'autres informations, ou pour générer d'autres paires de clés publiques/privées. Pour en savoir plus sur les identifiants du compte de service dans API Console, consultez la section Comptes de service dans le fichier d'aide API Console.

Notez l'adresse e-mail du compte de service et stockez le fichier de clé privée du compte de service dans un emplacement accessible à votre application. Votre application en a besoin pour effectuer des appels d'API autorisés.

Remarque:Vous devez stocker et gérer des clés privées de manière sécurisée dans les environnements de développement et de production. Google ne conserve aucune copie de vos clés privées, mais uniquement de vos clés publiques. Pour en savoir plus, consultez la section Gérer les identifiants client de manière sécurisée dans les règles OAuth 2.0.

Délégation de l'autorité au niveau du domaine au compte de service

Un compte Google Workspace permet à un administrateur Workspace de l'organisation d'autoriser une application à accéder aux données utilisateur Workspace au nom des utilisateurs du domaine Google Workspace. Par exemple, une application qui se sert de l'API Google Calendar pour ajouter des événements aux agendas de tous les utilisateurs d'un domaine Google Workspace peut accéder à l'API Google Calendar pour le compte des utilisateurs via un compte de service. Le fait d'autoriser un compte de service à accéder aux données au nom des utilisateurs d'un domaine est parfois appelé "délégation de l'autorité au niveau du domaine" dans un compte de service.

Remarque:Lorsque vous utilisez Google Workspace Marketplace pour installer une application pour votre domaine, les autorisations requises sont automatiquement accordées à l'application lors de l'installation. Vous n'avez pas besoin d'autoriser manuellement les comptes de service utilisés par l'application.

Remarque:Bien que vous puissiez utiliser des comptes de service dans les applications exécutées à partir d'un domaine Google Workspace, les comptes de service ne sont pas membres de votre compte Google Workspace et ne sont pas soumis aux règles de domaine définies par les administrateurs Google Workspace. Par exemple, une règle définie dans la console d'administration Google Workspace pour limiter la capacité des utilisateurs finaux de Google Workspace à partager des documents en dehors du domaine ne s'applique pas aux comptes de service.

Pour déléguer une autorité à l'échelle du domaine à un compte de service, un super-administrateur du domaine Google Workspace doit suivre les étapes suivantes:

1. Dans la console d'administration de votre domaine Google Workspace, accédez au menu principal > Sécurité > Contrôle des accès et des données > Commandes des API.
2. Dans le volet Délégation au niveau du domaine, sélectionnez Gérer la délégation au niveau du domaine.
3. Cliquez sur Ajouter.
4. Dans le champ ID client, saisissez l'ID client du compte de service. L'ID client de votre compte de service se trouve dans Service accounts page.
5. Dans le champ Champs d'application OAuth (délimités par des virgules), saisissez la liste des champs d'application auxquels votre application doit être autorisée à accéder. Par exemple, si votre application a besoin d'un accès complet au niveau du domaine à l'API Google Drive et à l'API Google Calendar, saisissez https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
6. Cliquez sur Autoriser.

Votre application est désormais autorisée à effectuer des appels d'API en tant qu'utilisateurs de votre domaine Workspace (pour se faire passer pour des utilisateurs). Lorsque vous vous préparerez à effectuer ces appels d'API délégués, vous devrez spécifier explicitement l'utilisateur à emprunter.

Remarque:L'octroi de l'accès en cas d'usurpation d'identité prend généralement quelques minutes, mais dans certains cas, la propagation de la modification à tous les utilisateurs de votre compte Google peut prendre jusqu'à 24 heures.

Préparation d'un appel d'API délégué

Java

Après avoir obtenu l'adresse e-mail du client et la clé privée à partir de API Console, utilisez la bibliothèque cliente des API Google pour Java pour créer un objet GoogleCredential à partir des identifiants du compte de service et des champs d'application auxquels votre application doit accéder. Exemple :

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.services.sqladmin.SQLAdminScopes;

// ...

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN));

Si vous développez une application sur Google Cloud Platform, vous pouvez utiliser les identifiants par défaut de l'application à la place, ce qui peut simplifier le processus.

Déléguer l'autorité à l'échelle du domaine

Si vous avez délégué un accès au niveau du domaine au niveau du domaine et que vous souhaitez emprunter l'identité d'un compte utilisateur, spécifiez l'adresse e-mail du compte utilisateur à l'aide de la méthode createDelegated de l'objet GoogleCredential. Par exemple :

GoogleCredential credential = GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"))
    .createScoped(Collections.singleton(SQLAdminScopes.SQLSERVICE_ADMIN))
    .createDelegated("[e-mail]");

Le code ci-dessus utilise l'objet GoogleCredential pour appeler sa méthode createDelegated(). L'argument de la méthode createDelegated() doit être un utilisateur appartenant à votre compte Workspace. Le code à l'origine de la requête utilisera ces identifiants pour appeler les API Google à l'aide de votre compte de service.

Python

Après avoir obtenu l'adresse e-mail du client et la clé privée à partir de API Console, procédez comme suit à l'aide de la bibliothèque cliente des API Google pour Python:

1. Créez un objet Credentials à partir des identifiants du compte de service et des champs d'application auxquels votre application doit accéder. Exemple :

   from google.oauth2 import service_account
   
   SCOPES = ['https://www.googleapis.com/auth/sqlservice.admin']
   SERVICE_ACCOUNT_FILE = '/path/to/service.json'
   
   credentials = service_account.Credentials.from_service_account_file(
           SERVICE_ACCOUNT_FILE, scopes=SCOPES)

   Si vous développez une application sur Google Cloud Platform, vous pouvez utiliser les identifiants par défaut de l'application à la place, ce qui peut simplifier le processus.

2. Déléguer l'autorité à l'échelle du domaine

   Si vous avez délégué un accès au niveau du domaine au niveau du domaine et que vous souhaitez emprunter l'identité d'un compte utilisateur, utilisez la méthode with_subject d'un objet ServiceAccountCredentials existant. Exemple :

   delegated_credentials = credentials.with_subject('[e-mail]')

Utilisez l'objet Credentials pour appeler les API Google de votre application.

HTTP/REST

Recommandation:Votre application peut effectuer ces tâches en interagissant directement avec le système OAuth 2.0 à l'aide du protocole HTTP, mais les mécanismes d'interaction d'authentification de serveur à serveur nécessitent que les applications créent et signent de manière cryptographique des jetons Web JSON (JWT), et il est facile de faire de graves erreurs qui peuvent avoir de graves conséquences sur la sécurité de votre application.

C'est pourquoi nous vous encourageons vivement à utiliser des bibliothèques telles que les bibliothèques clientes des API Google, qui extraient la cryptographie du code de votre application.

Une fois que vous avez obtenu l'ID client et la clé privée à partir du fichier API Console, votre application doit suivre les étapes suivantes:

1. Créez un jeton Web JSON (JWT, prononcé, "jot") qui comprend un en-tête, un ensemble de revendications et une signature.
2. Demandez un jeton d'accès au serveur d'autorisation Google OAuth 2.0.
3. Gérez la réponse JSON renvoyée par le serveur d'autorisation.

Les sections suivantes décrivent comment effectuer ces étapes.

Si la réponse inclut un jeton d'accès, vous pouvez l'utiliser pour appeler une API Google. (Si la réponse n'inclut pas de jeton d'accès, il est possible que votre jeton JWT et votre jeton de jeton ne soient pas correctement formés ou que le compte de service ne soit pas autorisé à accéder aux champs d'application demandés.)

Lorsque le jeton d'accès expire, votre application génère un autre jeton JWT, le signe et demande un autre jeton d'accès.

Le reste de cette section décrit en détail la création d'un jeton JWT, la signature du jeton JWT, la création de la requête de jeton d'accès et la gestion de la réponse.

Créer un jeton JWT

Un jeton JWT comprend trois parties: un en-tête, un ensemble de revendications et une signature. L'en-tête et l'ensemble de revendications sont des objets JSON. Ces objets JSON sont sérialisés en octets UTF-8, puis encodés en base64url. Cet encodage offre une résilience aux changements d'encodage en raison d'opérations d'encodage répétées. L'en-tête, l'ensemble de revendications et la signature sont concaténés avec un point (.).

Un jeton JWT se compose comme suit:

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

La chaîne de base de la signature est la suivante:

{Base64url encoded header}.{Base64url encoded claim set}

Former l'en-tête JWT

L'en-tête se compose de trois champs qui indiquent l'algorithme de signature, le format de l'assertion et l'[ID de clé de la clé de compte de service](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) utilisé pour signer le JWT. L'algorithme et le format sont obligatoires, et chaque champ ne comporte qu'une seule valeur. À mesure que d'autres algorithmes et formats seront introduits, cet en-tête sera modifié en conséquence. L'ID de clé est facultatif. Si un ID de clé incorrect est spécifié, GCP tente toutes les clés associées au compte de service pour vérifier le jeton et le rejette si aucune clé valide n'est trouvée. Google se réserve le droit de refuser les jetons comportant des ID de clé incorrects à l'avenir.

Les comptes de service reposent sur l'algorithme RSA SHA-256 et sur le format de jeton JWT. La représentation JSON de l'en-tête est donc la suivante:

{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}

La représentation Base64url de ceci est la suivante:

          eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=

Former l'ensemble de revendications JWT

L'ensemble de revendications JWT contient des informations sur le jeton JWT, y compris les autorisations demandées (champs d'application), la cible du jeton, l'émetteur, l'heure à laquelle le jeton a été émis et sa durée de vie. La plupart des champs sont obligatoires. Comme l'en-tête JWT, l'ensemble de revendications JWT est un objet JSON et est utilisé dans le calcul de la signature.

Revendications obligatoires

Les revendications requises dans l'ensemble de revendications JWT sont indiquées ci-dessous. Ils peuvent apparaître dans n'importe quel ordre dans l'ensemble de revendications.

Nom	Description
iss	Adresse e-mail du compte de service.
scope	Liste des autorisations demandées par l'application, séparées par un espace.
aud	Un descripteur de la cible prévue par l'assertion. Lorsque vous effectuez une requête de jeton d'accès, cette valeur est toujours https://oauth2.googleapis.com/token.
exp	Heure d'expiration de l'assertion, spécifiée en secondes depuis le 1er janvier 1970 à 00:00:00 UTC. Cette valeur ne doit pas dépasser une heure après l'heure d'émission.
iat	Heure d'émission de l'assertion, spécifiée en secondes depuis le 1er janvier 1970 à 00:00:00 UTC.

La représentation JSON des champs obligatoires d'un ensemble de revendications JWT est présentée ci-dessous:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/devstorage.read_only",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Revendications supplémentaires

Dans certains cas, une application peut utiliser la délégation au niveau du domaine pour agir au nom d'un utilisateur particulier dans une organisation. L'autorisation d'effectuer ce type d'emprunt d'identité doit être accordée pour qu'une application puisse usurper l'identité d'un utilisateur. Elle est généralement gérée par un super-administrateur. Pour en savoir plus, consultez Contrôler l'accès aux API à l'aide de la délégation au niveau du domaine.

Pour obtenir un jeton d'accès qui accorde à une application un accès délégué à une ressource, incluez l'adresse e-mail de l'utilisateur dans la revendication JWT définie comme valeur du champ sub.

Nom	Description
sub	Adresse e-mail de l'utilisateur pour lequel l'application demande un accès délégué.

Si une application n'est pas autorisée à emprunter l'identité d'un utilisateur, la réponse à une requête de jeton d'accès incluant le champ sub affichera une erreur.

Voici un exemple d'ensemble de revendications JWT comprenant le champ sub:

{
  "iss": "[e-mail]",
  "sub": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Encodage de l'ensemble de revendications JWT

Comme pour l'en-tête JWT, l'ensemble de revendications JWT doit être sérialisé avec UTF-8 et encodé en base64url-safe. Vous trouverez ci-dessous un exemple de représentation JSON d'un ensemble de revendications JWT:

{
  "iss": "[e-mail]",
  "scope": "https://www.googleapis.com/auth/prediction",
  "aud": "https://oauth2.googleapis.com/token",
  "exp": 1328554385,
  "iat": 1328550785
}

Calculer la signature

La signature Web JSON (JWS) est la spécification qui guide la mécanique de génération de la signature pour le JWT. L'entrée de la signature correspond au tableau d'octets du contenu suivant:

{Base64url encoded header}.{Base64url encoded claim set}

L'algorithme de signature de l'en-tête JWT doit être utilisé lors du calcul de la signature. Le seul algorithme de signature accepté par le serveur d'autorisation Google OAuth 2.0 est RSA à l'aide de l'algorithme de hachage SHA-256. Cela est exprimé au format RS256 dans le champ alg de l'en-tête JWT.

Signez la représentation UTF-8 de l'entrée avec SHA256withRSA (également appelé RSASSA-PKCS1-V1_5-SIGN avec la fonction de hachage SHA-256) à l'aide de la clé privée obtenue à partir de Google API Console. La sortie sera un tableau d'octets.

La signature doit ensuite être encodée en base64url. L'en-tête, l'ensemble de revendications et la signature sont concaténés avec un point (.). Le résultat est le JWT. Il doit se présenter comme suit (un saut de ligne a été ajouté pour plus de clarté):

{Base64url encoded header}.
{Base64url encoded claim set}.
{Base64url encoded signature}

Voici un exemple de jeton JWT avant encodage Base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss":"[e-mail]",
"scope":"https://www.googleapis.com/auth/prediction",
"aud":"https://oauth2.googleapis.com/token",
"exp":1328554385,
"iat":1328550785
}.
[signature bytes]

Vous trouverez ci-dessous un exemple de jeton JWT signé et prêt à être transmis:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL29hdXRoMi92NC90b2tlbiIsImV4cCI6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.UFUt59SUM2_AW4cRU8Y0BYVQsNTo4n7AFsNrqOpYiICDu37vVt-tw38UKzjmUKtcRsLLjrR3gFW3dNDMx_pL9DVjgVHDdYirtrCekUHOYoa1CMR66nxep5q5cBQ4y4u2kIgSvChCTc9pmLLNoIem-ruCecAJYgI9Ks7pTnW1gkOKs0x3YpiLpzplVHAkkHztaXiJdtpBcY1OXyo6jTQCa3Lk2Q3va1dPkh_d--GU2M5flgd8xNBPYw4vxyt0mP59XZlHMpztZt0soSgObf7G3GXArreF_6tpbFsS3z2t5zkEiHuWJXpzcYr5zWTRPDEHsejeBSG8EgpLDce2380ROQ

Envoyer la requête de jeton d'accès

Une fois le jeton JWT signé généré, une application peut l'utiliser pour demander un jeton d'accès. Cette requête de jeton d'accès est une requête HTTPS POST, et le corps est encodé au format URL. L'URL est indiquée ci-dessous:

https://oauth2.googleapis.com/token

Les paramètres suivants sont requis dans la requête HTTPS POST:

Nom	Description
grant_type	Utilisez la chaîne suivante, encodée au format URL si nécessaire : urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	Jeton JWT, y compris la signature.

Voici un vidage brut de la requête HTTPS POST utilisée dans une requête de jeton d'accès:

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

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.ixOUGehweEVX_UKXv5BbbwVEdcz6AYS-6uQV6fGorGKrHf3LIJnyREw9evE-gs2bmMaQI5_UbabvI4k-mQE4kBqtmSpTzxYBL1TCd7Kv5nTZoUC1CmwmWCFqT9RE6D7XSgPUh_jF1qskLa2w0rxMSjwruNKbysgRNctZPln7cqQ

Voici la même requête, avec curl:

curl -d 'grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiI3NjEzMjY3OTgwNjktcjVtbGpsbG4xcmQ0bHJiaGc3NWVmZ2lncDM2bTc4ajVAZGV2ZWxvcGVyLmdzZXJ2aWNlYWNjb3VudC5jb20iLCJzY29wZSI6Imh0dHBzOi8vd3d3Lmdvb2dsZWFwaXMuY29tL2F1dGgvcHJlZGljdGlvbiIsImF1ZCI6Imh0dHBzOi8vYWNjb3VudHMuZ29vZ2xlLmNvbS9vL29hdXRoMi90b2tlbiIsImV4cCI6MTMyODU3MzM4MSwiaWF0IjoxMzI4NTY5NzgxfQ.RZVpzWygMLuL-n3GwjW1_yhQhrqDacyvaXkuf8HcJl8EtXYjGjMaW5oiM5cgAaIorrqgYlp4DPF_GuncFqg9uDZrx7pMmCZ_yHfxhSCXru3gbXrZvAIicNQZMFxrEEn4REVuq7DjkTMyCMGCY1dpMa8aWfTQFt3Eh7smLchaZsU
' https://oauth2.googleapis.com/token

Gérer la réponse

Si le JWT et la requête de jeton d'accès sont correctement formés et que le compte de service est autorisé à effectuer cette opération, la réponse JSON du serveur d'autorisation inclut un jeton d'accès. Voici un exemple de réponse:

{
  "access_token": "1/8xbJqaOZXSUZbHLl5EOtu1pxz3fmmetKx9W8CV4t79M",
  "scope": "https://www.googleapis.com/auth/prediction"
  "token_type": "Bearer",
  "expires_in": 3600
}

Les jetons d'accès peuvent être réutilisés pendant l'intervalle de temps spécifié par la valeur expires_in.

Appeler des API Google

Java

Utilisez l'objet GoogleCredential pour appeler les API Google en procédant comme suit:

1. Créez un objet de service pour l'API que vous souhaitez appeler à l'aide de l'objet GoogleCredential. Exemple :

   SQLAdmin sqladmin =
       new SQLAdmin.Builder(httpTransport, JSON_FACTORY, credential).build();

2. Envoyez des requêtes au service d'API à l'aide de l'interface fournie par l'objet de service. Par exemple, pour lister les instances de bases de données Cloud SQL dans le projet excitant 123 :

   SQLAdmin.Instances.List instances =
       sqladmin.instances().list("exciting-example-123").execute();

Python

Pour appeler les API Google à l'aide de l'objet Credentials autorisé, procédez comme suit:

1. Créez un objet de service pour l'API que vous souhaitez appeler. Pour créer un objet de service, appelez la fonction build avec le nom et la version de l'API ainsi que l'objet Credentials autorisé. Par exemple, pour appeler la version 1beta3 de l'API Cloud SQL Administration :

   import googleapiclient.discovery
   
   sqladmin = googleapiclient.discovery.build('sqladmin', 'v1beta3', credentials=credentials)

2. Envoyez des requêtes au service d'API à l'aide de l'interface fournie par l'objet de service. Par exemple, pour lister les instances de bases de données Cloud SQL dans le projet excitant 123 :

   response = sqladmin.instances().list(project='exciting-example-123').execute()

HTTP/REST

Une fois que votre application a obtenu un jeton d'accès, vous pouvez l'utiliser pour effectuer des appels à une API Google au nom d'un compte de service ou d'un compte utilisateur donné, si le ou les champs d'application requis par l'API ont été accordés. Pour ce faire, incluez le jeton d'accès dans une requête adressée à l'API en incluant un paramètre de requête access_token ou une valeur Authorization d'en-tête HTTP Bearer. Dans la mesure du possible, il est préférable d'utiliser l'en-tête HTTP, car les chaînes de requête ont tendance à être visibles dans les journaux du serveur. Dans la plupart des cas, vous pouvez utiliser une bibliothèque cliente pour configurer vos appels aux API Google (par exemple, lorsque vous appelez l'API Drive Files).

Vous pouvez essayer toutes les API Google et consulter leurs habilitations sur OAuth 2.0 Playground.

Exemples HTTP GET

Un appel vers le point de terminaison drive.files (API Drive Files) avec l'en-tête HTTP Authorization: Bearer peut se présenter comme suit. Notez que vous devez spécifier votre propre jeton d'accès:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Voici un appel vers la même API pour l'utilisateur authentifié à l'aide du paramètre de chaîne de requête access_token:

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

Exemples curl

Vous pouvez tester ces commandes avec l'application de ligne de commande curl. Voici un exemple qui utilise l'option d'en-tête HTTP (recommandé):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Vous pouvez également utiliser le paramètre de chaîne de requête:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Lorsque les jetons d'accès expirent

Les jetons d'accès émis par le serveur d'autorisation Google OAuth 2.0 expirent après la durée fournie par la valeur expires_in. Lorsqu'un jeton d'accès expire, l'application doit générer un autre jeton JWT, le signer et demander un autre jeton.

Codes d'erreur JWT

Champ error	Champ error_description	Signification	Procédure de résolution
unauthorized_client	Unauthorized client or scope in request.	Si vous essayez d'utiliser la délégation au niveau du domaine, le compte de service n'est pas autorisé dans la console d'administration du domaine de l'utilisateur.	Assurez-vous que le compte de service est autorisé sur la page Délégation au niveau du domaine de la console d'administration pour l'utilisateur dans la revendication sub (champ). Cette opération prend généralement quelques minutes, mais il peut s'écouler jusqu'à 24 heures avant que l'autorisation ne soit appliquée à tous les utilisateurs de votre compte Google.
unauthorized_client	Client is unauthorized to retrieve access tokens using this method, or client not authorized for any of the scopes requested.	Un compte de service a été autorisé à l'aide de l'adresse e-mail du client plutôt que de l'ID client (numérique) dans la console d'administration.	Sur la page Délégation au niveau du domaine de la console d'administration, supprimez le client, puis ajoutez-le à nouveau avec l'ID numérique.
access_denied	(toute valeur)	Si vous utilisez la délégation au niveau du domaine, un ou plusieurs champs d'application demandés ne sont pas autorisés dans la console d'administration.	Assurez-vous que le compte de service est autorisé sur la page Délégation au niveau du domaine de la console d'administration pour l'utilisateur dans la revendication sub (champ) et qu'il inclut tous les champs d'application que vous demandez dans la revendication scope de votre jeton JWT. Cette opération prend généralement quelques minutes, mais il peut s'écouler jusqu'à 24 heures avant que l'autorisation ne soit appliquée à tous les utilisateurs de votre compte Google.
admin_policy_enforced	(toute valeur)	Le compte Google ne peut pas autoriser un ou plusieurs niveaux d'accès demandés en raison des règles de leur administrateur Google Workspace.	Consultez l'article d'aide Administrateur Google Workspace Contrôler quelles applications tierces et internes ont accès aux données Google Workspace pour savoir comment un administrateur peut limiter l'accès à tous les champs d'application ou aux niveaux d'accès sensibles et restreints jusqu'à ce que l'accès soit explicitement accordé à votre ID client OAuth.
invalid_client	(toute valeur)	Le client OAuth ou le jeton JWT n'est pas valide ou n'est pas configuré correctement. Pour en savoir plus, consultez la description de l'erreur.	Assurez-vous que le jeton JWT est valide et qu'il contient des revendications correctes. Vérifiez que le client OAuth et le compte de service sont correctement configurés, et que vous utilisez la bonne adresse e-mail. Vérifiez que le jeton JWT est correct et qu'il a été émis pour l'ID client dans la requête.
invalid_grant	Not a valid email.	L'utilisateur n'existe pas.	Vérifiez que l'adresse e-mail indiquée dans le champ sub est correcte.
invalid_grant	Invalid JWT: Token must be a short-lived token (60 minutes) and in a reasonable timeframe. Check your 'iat' and 'exp' values and use a clock with skew to account for clock differences between systems.	Cela signifie généralement que l'heure du système local est incorrecte. Cela peut également se produire si la valeur exp est postérieure de plus de 65 minutes à la valeur iat ou si la valeur exp est inférieure à la valeur iat.	Assurez-vous que l'horloge du système sur lequel le jeton JWT est généré est correcte. Si nécessaire, synchronisez le temps avec Google NTP.
invalid_grant	Invalid JWT Signature.	L'assertion JWT est signée avec une clé privée non associée au compte de service identifié par l'adresse e-mail du client, ou la clé utilisée a été supprimée, désactivée ou a expiré. L'assertion JWT peut également être encodée de manière incorrecte. Elle doit être encodée en base64, sans retour à la ligne ni à la marge intérieure.	Décodez l'ensemble de revendications JWT et vérifiez que la clé qui a signé l'assertion est associée au compte de service. Essayez d'utiliser une bibliothèque OAuth fournie par Google pour vous assurer que le jeton JWT est généré correctement.
invalid_scope	Invalid OAuth scope or ID token audience provided.	Aucun champ d'application n'a été demandé (liste vide), ou l'un des champs d'application demandés n'existe pas (c'est-à-dire qu'il n'est pas valide).	Assurez-vous que la revendication scope (champ) du jeton JWT est renseignée et comparez les champs d'application qu'elle contient avec les champs d'application documentés pour les API que vous souhaitez utiliser, afin de vérifier qu'il n'y a pas d'erreur ni de faute de frappe. Notez que la liste des champs d'application dans la revendication scope doit être séparée par des espaces, et non par des virgules.
disabled_client	The OAuth client was disabled.	La clé utilisée pour signer l'assertion JWT est désactivée.	Accédez à Google API Console, puis sous IAM & Admin > Service Accounts (IAM et administration > Comptes de service), activez le compte de service contenant l'ID de clé utilisé pour signer l'assertion.
org_internal	This client is restricted to users within its organization.	L'ID client OAuth dans la requête fait partie d'un projet limitant l'accès aux comptes Google d'une organisation Google Cloud spécifique.	Utilisez un compte de service de l'organisation pour vous authentifier. Confirmez la configuration du type d'utilisateur pour votre application OAuth.

Avenant: autorisation de compte de service sans OAuth

Avec certaines API Google, vous pouvez effectuer des appels d'API autorisés en utilisant un jeton JWT signé directement en tant que jeton de support, plutôt qu'en tant que jeton d'accès OAuth 2.0. Dans la mesure du possible, évitez d'envoyer une requête réseau au serveur d'autorisation de Google avant d'effectuer un appel d'API.

Si l'API que vous souhaitez appeler a une définition de service publiée dans le dépôt GitHub des API Google, vous pouvez effectuer des appels d'API autorisés à l'aide d'un jeton JWT au lieu d'un jeton d'accès. Procédez comme suit :

1. Créez un compte de service comme décrit ci-dessus. Veillez à conserver le fichier JSON obtenu lorsque vous créez le compte.
2. À l'aide de n'importe quelle bibliothèque JWT standard, telle que celle disponible à l'adresse jwt.io, créez un jeton JWT avec un en-tête et une charge utile, comme dans l'exemple suivant :

   {
     "alg": "RS256",
     "typ": "JWT",
     "kid": "abcdef1234567890"
   }
   .
   {
     "iss": "[e-mail]",
     "sub": "[e-mail]",
     "aud": "https://firestore.googleapis.com/",
     "iat": 1511900000,
     "exp": 1511903600
   }

• Dans le champ kid de l'en-tête, spécifiez l'ID de clé privée de votre compte de service. Vous trouverez cette valeur dans le champ private_key_id du fichier JSON de votre compte de service.
• Pour les champs iss et sub, spécifiez l'adresse e-mail de votre compte de service. Vous trouverez cette valeur dans le champ client_email du fichier JSON de votre compte de service.
• Dans le champ aud, spécifiez le point de terminaison de l'API. Exemple : https://SERVICE.googleapis.com/.
• Dans le champ iat, indiquez l'heure Unix actuelle. Dans le champ exp, indiquez l'heure exacte au bout de 3 600 secondes, lorsque le JWT expirera.

Signez le jeton JWT avec RSA-256 à l'aide de la clé privée qui se trouve dans le fichier JSON de votre compte de service.

Exemple :

Java

Avec google-api-java-client et java-jwt:

GoogleCredential credential =
        GoogleCredential.fromStream(new FileInputStream("MyProject-1234.json"));
PrivateKey privateKey = credential.getServiceAccountPrivateKey();
String privateKeyId = credential.getServiceAccountPrivateKeyId();

long now = System.currentTimeMillis();

try {
    Algorithm algorithm = Algorithm.RSA256(null, privateKey);
    String signedJwt = JWT.create()
        .withKeyId(privateKeyId)
        .withIssuer("[e-mail]")
        .withSubject("[e-mail]")
        .withAudience("https://firestore.googleapis.com/")
        .withIssuedAt(new Date(now))
        .withExpiresAt(new Date(now + 3600 * 1000L))
        .sign(algorithm);
} catch ...

Python

Avec PyJWT:

iat = time.time()
exp = iat + 3600
payload = {'iss': '[e-mail]',
           'sub': '[e-mail]',
           'aud': 'https://firestore.googleapis.com/',
           'iat': iat,
           'exp': exp}
additional_headers = {'kid': PRIVATE_KEY_ID_FROM_JSON}
signed_jwt = jwt.encode(payload, PRIVATE_KEY_FROM_JSON, headers=additional_headers,
                       algorithm='RS256')

1. Appelez l'API en utilisant le jeton JWT signé comme jeton de support :

   GET /v1/projects/abc/databases/123/indexes HTTP/1.1
   Authorization: Bearer SIGNED_JWT
   Host: firestore.googleapis.com