Le système Google OAuth 2.0 est compatible avec les interactions de serveur à serveur, comme 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 à deux acteurs" ou "2LO". L'expression "OAuth en trois étapes" fait référence aux scénarios dans lesquels votre application appelle les API Google pour le compte des utilisateurs finaux et dans lesquels le consentement de l'utilisateur est parfois requis.
En règle générale, une application utilise un compte de service lorsqu'elle utilise les API Google pour travailler avec 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 peut utiliser un compte de service pour authentifier ses appels à l'API Google Cloud Datastore.
Les administrateurs de domaine Google Workspace peuvent également autoriser les comptes de service au niveau du domaine à accéder aux données des utilisateurs du domaine.
Ce document explique comment une application peut exécuter le flux OAuth 2.0 de serveur à serveur à l'aide d'une bibliothèque cliente des API Google (recommandé) ou du protocole HTTP.
Présentation
Pour prendre en charge les interactions de serveur à serveur, commencez par créer un compte de service pour votre projet dans 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 au niveau du domaine.
Votre application se prépare ensuite à effectuer des appels d'API autorisés en utilisant les 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.
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 automatiquement configuré lors de la création de votre projet. Toutefois, vous devez spécifier les champs d'application auxquels votre application doit avoir accès lorsque vous créez une instance Google Compute Engine. Pour en savoir plus, consultez la section Préparer une instance à utiliser des comptes de service.
Si votre application ne s'exécute pas sur Google App Engine ou Google Compute Engine, vous devez obtenir ces identifiants dans le fichier Google API Console. Pour générer des identifiants de 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 :
- Ouvrez le Service accounts page.
- If prompted, select a project, or create a new one.
- Cliquez sur Créer un compte de service .
- 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 .
- Facultatif : sous Accorder à ce compte de service l'accès au projet , sélectionnez les rôles IAM à accorder au compte de service.
- Cliquez sur Continuer .
- 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.
- Cliquez sur Terminé .
Ensuite, créez une clé de compte de service :
- Cliquez sur l'adresse e-mail du compte de service que vous avez créé.
- Cliquez sur l'onglet Clés .
- Dans la liste déroulante Ajouter une clé , sélectionnez Créer une nouvelle clé .
- 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 à la API Console à tout moment pour afficher l'adresse e-mail, les empreintes de la clé publique et d'autres informations, ou pour générer d'autres paires de clés publique/privée. Pour en savoir plus sur les identifiants du compte de service dans le fichier 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 par votre application. Votre application en a besoin pour effectuer des appels d'API autorisés.
Déléguer une autorité au niveau du domaine au compte de service
Avec un compte Google Workspace, un administrateur Workspace de l'organisation peut autoriser une application à accéder aux données utilisateur Workspace pour le compte 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 Agenda 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 d'utilisateurs d'un domaine est parfois appelé "délégation d'autorité au niveau du domaine" à un compte de service.
Pour déléguer une autorité à un compte de service au niveau du domaine, un super-administrateur du domaine Google Workspace doit procéder comme suit:
- Dans la console d'administration de votre domaine Google Workspace, accédez à Menu principal > Sécurité > Contrôle des accès et des données > Commandes des API.
- Dans le volet Délégation au niveau du domaine, sélectionnez Gérer la délégation au niveau du domaine.
- Cliquez sur Ajouter.
- Dans le champ ID client, saisissez l'ID client du compte de service. Vous trouverez l'ID client de votre compte de service dans le fichier Service accounts page.
- Dans le champ Champs d'application OAuth (séparés par des virgules), saisissez la liste des champs d'application auxquels votre application doit avoir accès. Par exemple, si votre application nécessite un accès complet à l'API Google Drive et à l'API Google Calendar à l'échelle du domaine, saisissez : https://www.googleapis.com/auth/drive, https://www.googleapis.com/auth/calendar.
- Cliquez sur Autoriser.
Votre application est désormais autorisée à effectuer des appels d'API en tant qu'utilisateurs de votre domaine Workspace (pour "emprunter l'identité"). Lorsque vous vous préparez à effectuer ces appels d'API délégués, vous devez spécifier explicitement l'utilisateur dont vous souhaitez emprunter l'identité.
Préparer 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 afin de créer un objet GoogleCredential
à partir des identifiants du compte de service et des niveaux d'accès auxquels votre application doit avoir accès. 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, ce qui peut simplifier le processus.
Déléguer une autorité au niveau du domaine
Si vous avez délégué l'accès au compte de service au niveau du domaine et que vous souhaitez emprunter l'identité d'un compte utilisateur, spécifiez l'adresse e-mail du compte utilisateur avec 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("workspace-user@example.com");
Le code ci-dessus utilise l'objet GoogleCredential
pour appeler sa méthode createDelegated()
. L'argument de la méthode createDelegated()
doit correspondre à un utilisateur appartenant à votre compte Workspace. Le code qui effectue la requête utilisera cet identifiant pour appeler les API Google à l'aide de votre compte de service.
Python
Après avoir obtenu l'adresse e-mail et la clé privée du client à partir de API Console, utilisez la bibliothèque cliente des API Google pour Python pour effectuer les étapes suivantes:
- Créez un objet
Credentials
à partir des identifiants du compte de service et des niveaux d'accès auxquels votre application a besoin d'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, ce qui peut simplifier le processus.
- Déléguer une autorité au niveau du domaine
Si vous avez délégué l'accès au compte de service au niveau du domaine et que vous souhaitez emprunter l'identité d'un compte utilisateur, utilisez la méthode
with_subject
d'un objetServiceAccountCredentials
existant. Exemple :delegated_credentials = credentials.with_subject('user@example.org')
Utilisez l'objet Credentials pour appeler les API Google dans votre application.
HTTP/REST
Une fois que vous avez obtenu l'ID client et la clé privée à partir de API Console, votre application doit procéder comme suit:
- Créez un jeton Web JSON (JWT, prononcé "jot") qui comprend un en-tête, un ensemble de revendications et une signature.
- Demandez un jeton d'accès au serveur d'autorisation Google OAuth 2.0.
- Gérez la réponse JSON renvoyée par le serveur d'autorisation.
Les sections suivantes décrivent comment réaliser 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 se peut que votre requête JWT et de jeton ne soit pas correctement formée, ou que le compte de service ne dispose pas des autorisations nécessaires pour 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 en demande un autre.
Le reste de cette section décrit les spécificités de la création d'un jeton JWT, de sa signature, de la formulation de la requête de jeton d'accès et de la gestion de la réponse.
Créer un jeton JWT
Un jeton JWT est composé de 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 face aux changements d'encodage dus à des 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 est composé 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}
Formation de l'en-tête JWT
L'en-tête comprend trois champs qui indiquent l'algorithme de signature, le format de l'assertion et l'[ID de clé de la clé du compte de service](https://cloud.google.com/iam/docs/reference/rest/v1/projects.serviceAccounts.keys) utilisé pour signer le jeton JWT. L'algorithme et le format sont obligatoires, et chaque champ ne comporte qu'une seule valeur. À mesure que des algorithmes et des formats supplémentaires sont introduits, cet en-tête est 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 valider le jeton, puis le refuse si aucune clé valide n'est trouvée. Google se réserve le droit de refuser à l'avenir les jetons dont les ID de clé sont incorrects.
Les comptes de service s'appuient sur l'algorithme RSA SHA-256 et le format de jeton JWT. Par conséquent, la représentation JSON de l'en-tête est la suivante:
{"alg":"RS256","typ":"JWT", "kid":"370ab79b4513eb9bad7c9bd16a95cb76b5b2a56a"}
Voici à quoi ressemble la représentation en Base64url:
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsICJraWQiOiIzNzBhYjc5YjQ1MTNlYjliYWQ3YzliZDE2YTk1Y2I3NmI1YjJhNTZhIn0=
Créer l'ensemble de revendications JWT
L'ensemble de revendications JWT contient des informations sur ce jeton, y compris les autorisations demandées (niveaux d'accès), la cible du jeton, l'émetteur, l'heure d'émission du jeton et sa durée de vie. La plupart des champs sont obligatoires. Tout 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 requises
Les revendications requises dans l'ensemble de revendications JWT sont indiquées ci-dessous. Elles 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 des espaces. |
aud |
Descripteur de la cible prévue de l'assertion. Lorsque vous effectuez une demande 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 est limitée à une heure après l'heure d'émission. |
iat |
Heure à laquelle l'assertion a été émise, exprimée en secondes depuis le 1er janvier 1970 à 00:00:00 UTC. |
La représentation JSON des champs obligatoires dans un ensemble de revendications JWT est présentée ci-dessous:
{ "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "scope": "https://www.googleapis.com/auth/devstorage.read_only", "aud": "https://oauth2.googleapis.com/token", "exp": 1328554385, "iat": 1328550785 }
Autres revendications
Dans certains cas d'entreprise, une application peut recourir à la délégation au niveau du domaine pour agir au nom d'un utilisateur particulier au sein d'une organisation. L'autorisation d'effectuer ce type d'emprunt d'identité doit être accordée pour qu'une application puisse emprunter l'identité d'un utilisateur. Ce type d'emprunt est généralement géré par un super-administrateur. Pour en savoir plus, consultez Contrôler l'accès à l'API avec la délégation au niveau du domaine.
Pour obtenir un jeton d'accès accordant à 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
sera une erreur.
Vous trouverez ci-dessous un exemple d'ensemble de revendications JWT incluant le champ sub
:
{ "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "sub": "some.user@example.com", "scope": "https://www.googleapis.com/auth/prediction", "aud": "https://oauth2.googleapis.com/token", "exp": 1328554385, "iat": 1328550785 }
Encoder l'ensemble de revendications JWT
Comme pour l'en-tête JWT, l'ensemble de revendications JWT doit être sérialisé en UTF-8 et en Base64url. Vous trouverez ci-dessous un exemple de représentation JSON d'un ensemble de revendications JWT:
{ "iss": "761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "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 le mécanisme de génération de la signature pour le jeton JWT. L'entrée pour la signature est le 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, qui utilise l'algorithme de hachage SHA-256. Cette valeur est exprimée par RS256
dans le champ alg
de l'en-tête JWT.
Signez la représentation UTF-8 de l'entrée à l'aide de SHA256withRSA (également appelé RSASSA-PKCS1-V1_5-SIGN avec la fonction de hachage SHA-256) avec 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 jeton JWT. Il doit se présenter comme suit (des sauts de ligne ont été ajoutés pour plus de clarté):
{Base64url encoded header}. {Base64url encoded claim set}. {Base64url encoded signature}
Vous trouverez ci-dessous un exemple de jeton JWT avant l'encodage Base64url:
{"alg":"RS256","typ":"JWT"}. { "iss":"761326798069-r5mljlln1rd4lrbhg75efgigp36m78j5@developer.gserviceaccount.com", "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
Après avoir généré le jeton JWT signé, 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 obligatoires 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, signature comprise. |
Vous trouverez ci-dessous une copie brute 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
Vous trouverez ci-dessous la même requête, qui utilise 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 jeton JWT et la requête de jeton d'accès sont correctement formés, et si le compte de service est autorisé à effectuer l'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 la période spécifiée par la valeur expires_in
.
Appeler les API Google
Java
Utilisez l'objet GoogleCredential
pour appeler les API Google en procédant comme suit:
- 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();
- Envoyez des requêtes au service d'API à l'aide de l'interface fournie par l'objet de service.
Par exemple, pour répertorier les instances de bases de données Cloud SQL dans le projet "excitant-example-123", procédez comme suit :
SQLAdmin.Instances.List instances = sqladmin.instances().list("exciting-example-123").execute();
Python
Utilisez l'objet Credentials
autorisé pour appeler les API Google en procédant comme suit:
- 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 et l'objetCredentials
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)
- Envoyez des requêtes au service d'API à l'aide de l'interface fournie par l'objet de service.
Par exemple, pour répertorier les instances de bases de données Cloud SQL dans le projet "excitant-example-123", procédez comme suit :
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 appeler une API Google au nom d'un compte de service ou d'un compte utilisateur donné si 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 Bearer
d'en-tête HTTP Authorization
. Dans la mesure du possible, l'en-tête HTTP est préférable, 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 champs d'application sur le OAuth 2.0 Playground.
Exemples HTTP GET
Un appel au point de terminaison
drive.files
(l'API Drive Files) à l'aide de 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 à 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 utilisant l'option d'en-tête HTTP (recommandée):
curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files
Vous pouvez également utiliser l'option de paramètre de chaîne de requête:
curl https://www.googleapis.com/drive/v2/files?access_token=access_token
Expiration des jetons d'accès
Les jetons d'accès émis par le serveur d'autorisation Google OAuth 2.0 expirent après la durée indiquée par la valeur expires_in
. Lorsqu'un jeton d'accès expire, l'application doit générer un autre jeton d'accès, le signer et en demander un autre.
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 figurant dans la revendication Même si la procédure prend généralement quelques minutes, la propagation de l'autorisation à tous les utilisateurs de votre compte Google peut prendre jusqu'à 24 heures. |
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 |
(n'importe quelle 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 figurant dans la revendication Même si la procédure prend généralement quelques minutes, la propagation de l'autorisation à tous les utilisateurs de votre compte Google peut prendre jusqu'à 24 heures. |
admin_policy_enforced |
(n'importe quelle valeur) | Le compte Google ne peut pas autoriser un ou plusieurs champs d'application demandés en raison des règles de son administrateur Google Workspace. |
Consultez l'article d'aide pour les administrateurs Google Workspace Contrôler quelles applications tierces et internes ont accès aux données Google Workspace pour découvrir comment un administrateur peut restreindre l'accès à tous les champs d'application ou à des niveaux d'accès sensibles et restreints tant que l'accès n'a pas été explicitement autorisé à votre ID client OAuth. |
invalid_client |
(n'importe quelle 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 les bonnes revendications. Vérifiez que le client et le compte de service OAuth 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 la revendication sub (champ) est correcte. |
invalid_grant |
|
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 correct. Si nécessaire, synchronisez votre heure 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 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 signe de retour à la ligne ni signe égal de 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 correctement généré. |
invalid_scope |
Invalid OAuth scope or ID token audience provided. |
Aucun champ d'application n'a été demandé (liste de champs d'application vide) ou l'un des champs d'application demandés n'existe pas (il n'est pas valide). |
Assurez-vous que la revendication Notez que la liste des champs d'application dans la revendication |
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 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 de la requête fait partie d'un projet limitant l'accès aux comptes Google dans 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 d'un compte de service sans OAuth
Avec certaines API Google, vous pouvez effectuer des appels d'API autorisés à l'aide d'un jeton JWT signé directement en tant que jeton de support, plutôt qu'à l'aide d'un jeton d'accès OAuth 2.0. Lorsque cela est possible, vous évitez d'avoir à envoyer une requête réseau au serveur d'autorisation de Google avant d'effectuer un appel d'API.
Si une définition de service de l'API que vous souhaitez appeler est 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 :
- Créez un compte de service comme décrit ci-dessus. Veillez à conserver le fichier JSON que vous obtenez lorsque vous créez le compte.
- À l'aide d'une bibliothèque JWT standard, telle que celle disponible sur 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": "123456-compute@developer.gserviceaccount.com", "sub": "123456-compute@developer.gserviceaccount.com", "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 champprivate_key_id
du fichier JSON de votre compte de service. - Pour les champs
iss
etsub
, indiquez l'adresse e-mail de votre compte de service. Vous trouverez cette valeur dans le champclient_email
du fichier JSON de votre compte de service. - Pour le champ
aud
, spécifiez le point de terminaison de l'API. Exemple :https://SERVICE.googleapis.com/
. - Pour le champ
iat
, indiquez l'heure Unix actuelle et pour le champexp
, indiquez l'heure exactement 3 600 secondes plus tard, date à laquelle le jeton JWT expirera.
Signez le jeton JWT avec RSA-256 à l'aide de la clé privée se trouvant 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("123456-compute@developer.gserviceaccount.com") .withSubject("123456-compute@developer.gserviceaccount.com") .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': '123456-compute@developer.gserviceaccount.com', 'sub': '123456-compute@developer.gserviceaccount.com', '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')
- 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