S'authentifier pour utiliser REST

Cette page explique comment s'authentifier lorsque vous envoyez une requête REST à une API Google.

Pour en savoir plus sur l'authentification lorsque vous utilisez des bibliothèques clientes Google, consultez la page S'authentifier à l'aide de bibliothèques clientes.

Avant de commencer

Pour exécuter les exemples de cette page, procédez comme suit :

1. Activer les API Cloud Resource Manager and Identity and Access Management (IAM) :

   gcloud services enable cloudresourcemanager.googleapis.com iam.googleapis.com

2. Installez Google Cloud CLI, puis initialisez-la en exécutant la commande suivante :

   gcloud init

   Cette étape n'est pas nécessaire pour utiliser le serveur de métadonnées.

Types d'identifiants

Vous pouvez utiliser les types d'identifiants suivants pour authentifier un appel REST :

• Vos identifiants gcloud CLI

  Cette approche est le moyen le plus simple et le plus sécurisé de fournir des identifiants à une méthode REST dans un environnement de développement local. Si votre compte utilisateur dispose des autorisations IAM (Identity and Access Management) requises pour la méthode que vous souhaitez appeler, il s'agit de l'approche à privilégier.

  Vos identifiants gcloud sont différents de ceux que vous fournissez au service ADC à l'aide de gcloud CLI. Pour en savoir plus, consultez la documentation sur gcloud CLI et les identifiants ADC.

• Les identifiants fournis aux ADC (Identifiants par défaut de l'application).

  Cette méthode est l'option recommandée pour authentifier un appel REST dans un environnement de production, car l'ADC trouve les identifiants de la ressource sur laquelle votre code est exécuté (par exemple, une machine virtuelle Compute Engine). Vous pouvez également utiliser les ADC pour vous authentifier auprès d'un environnement de développement local. Dans ce scénario, gcloud CLI crée un fichier contenant vos identifiants dans votre système de fichiers local.

• Les identifiants fournis par emprunter l'identité d'un compte de service.

  Cette méthode nécessite davantage de configuration. Si vous souhaitez utiliser vos identifiants existants afin d'obtenir des identifiants éphémères pour un autre compte de service, par exemple pour effectuer des tests avec un compte de service localement ou demander des privilèges élevés temporaires, utilisez cette approche.

• Les identifiants renvoyés par le serveur de métadonnées.

  Cette méthode ne fonctionne que dans les environnements qui ont accès à un serveur de métadonnées. Les identifiants renvoyés par le serveur de métadonnées sont identiques à ceux que les identifiants par défaut de l'application ont trouvés à l'aide du compte de service associé, mais vous demandez explicitement le jeton d'accès depuis le serveur de métadonnées, puis le fournissez avec la requête REST. L'interrogation des identifiants sur le serveur de métadonnées nécessite une requête HTTP GET. Cette méthode ne repose pas sur Google Cloud CLI.

Identifiants gcloud CLI

Pour exécuter l'exemple ci-dessous, vous avez besoin de l'autorisation resourcemanager.projects.get sur le projet. L'autorisation resourcemanager.projects.get est incluse dans différents rôles, par exemple le rôle Visiteur (roles/browser).

1. Exécutez la commande gcloud auth print-access-token pour insérer un jeton d'accès généré à partir de vos identifiants utilisateur.

   L'exemple suivant récupère les détails du projet spécifié. Vous pouvez utiliser le même modèle pour n'importe quelle requête REST.

   Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

   • PROJECT_ID : ID ou nom de votre projet Google Cloud.

   Pour envoyer votre requête, choisissez l'une des options suivantes :

   curl

   Exécutez la commande suivante :

   curl -X GET \
       -H "Authorization: Bearer $(gcloud auth print-access-token)" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   Exécutez la commande suivante :

   $cred = gcloud auth print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   Les détails de votre projet s'affichent.

Pour les API nécessitant un projet de quota, vous devez en définir un explicitement pour la requête. Pour en savoir plus, consultez la section Définir le projet de quota avec une requête REST sur cette page.

Identifiants par défaut de l'application

Pour exécuter l'exemple ci-dessous, le compte principal associé aux identifiants fournis aux Identifiants par défaut de l'application doit disposer de l'autorisation resourcemanager.projects.get sur le projet. L'autorisation resourcemanager.projects.get est incluse dans différents rôles, par exemple le rôle Visiteur (roles/browser).

1. Fournissez des identifiants à l'ADC.

   Si vous utilisez des ressources de calcul Google Cloud, vous ne devez pas fournir vos identifiants utilisateur aux ADC. Utilisez plutôt le compte de service associé pour fournir des identifiants. Pour en savoir plus, consultez la page Services Google Cloud compatibles avec l'association d'un compte de service.

2. Exécutez la commande gcloud auth application-default print-access-token pour insérer le jeton d'accès renvoyé par les ADC dans votre requête REST.

   L'exemple suivant récupère les détails du projet spécifié. Vous pouvez utiliser le même modèle pour n'importe quelle requête REST.

   Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

   • PROJECT_ID : ID ou nom de votre projet Google Cloud.

   Pour envoyer votre requête, choisissez l'une des options suivantes :

   curl

   Exécutez la commande suivante :

   curl -X GET \
       -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"

   PowerShell

   Exécutez la commande suivante :

   $cred = gcloud auth application-default print-access-token
   $headers = @{ "Authorization" = "Bearer $cred" }
   
   Invoke-WebRequest `
       -Method GET `
       -Headers $headers `
       -Uri "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID" | Select-Object -Expand Content

   Les détails de votre projet s'affichent.

   Si votre requête renvoie un message d'erreur indiquant que les identifiants d'utilisateur final ne sont pas compatibles avec cette API, consultez la section Définir le projet de quota avec une requête REST sur cette page.

Compte de service dont l'identité est empruntée

Pour en savoir plus sur l'emprunt d'identité d'un compte de service, consultez Utiliser l'emprunt d'identité d'un compte de service.

1. Consultez les autorisations requises.

   • Votre compte utilisateur doit disposer de l'autorisation iam.serviceAccounts.getAccessToken sur le compte de service dont l'identité est empruntée (également appelé compte de service avec privilège). L'autorisation iam.serviceAccounts.getAccessToken est incluse dans le rôle de créateur de jetons de compte de service (roles/iam.serviceAccountTokenCreator). Vous avez besoin de cette autorisation même si vous disposez du rôle Propriétaire (roles/owner) sur le projet. Pour en savoir plus, consultez la section Définir les autorisations requises.

   • Dans l'exemple ci-dessous, le compte de service dont vous empruntez l'identité doit disposer de l'autorisation resourcemanager.projects.get sur le projet. L'autorisation resourcemanager.projects.get est incluse dans différents rôles, par exemple le rôle Visiteur (roles/browser).

2. Identifiez ou créez le compte de service avec privilège, c'est-à-dire le compte de service dont vous emprunterez l'identité.

   Le compte de service avec privilège doit disposer des autorisations requises pour effectuer l'appel de méthode API.

3. Exécutez la commande gcloud auth print-access-token avec l'option --impersonate-service-account pour insérer un jeton d'accès avec privilège dans votre requête REST.

   L'exemple suivant récupère les détails du projet spécifié. Vous pouvez utiliser le même modèle pour n'importe quelle requête REST.

   Pour exécuter cet exemple, le compte de service dont vous empruntez l'identité doit disposer de l'autorisation resourcemanager.projects.get. L'autorisation resourcemanager.projects.get est incluse dans différents rôles, par exemple le rôle Visiteur (roles/browser).

   Effectuez les remplacements suivants :

   • PRIV_SA : l'adresse e-mail du compte de service avec privilège. Par exemple, [e-mail].

   • PROJECT_ID : ID ou nom de votre projet Google Cloud.

   curl -X GET \
       -H "Authorization: Bearer $(gcloud auth print-access-token --impersonate-service-account=PRIV_SA)" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
   

Serveur de métadonnées

Pour obtenir un jeton d'accès depuis le serveur de métadonnées, vous devez effectuer l'appel REST à l'aide de l'un des services disposant d'un accès à un serveur de métadonnées :

• Compute Engine
• Environnement standard App Engine
• Environnement flexible App Engine
• Cloud Functions
• Cloud Run
• Google Kubernetes Engine

Vous obtenez un jeton d'accès à l'aide d'un outil de ligne de commande tel que curl, puis vous l'insérez dans votre requête REST.

1. Interrogez le serveur de métadonnées pour obtenir un jeton d'accès :

   curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
       -H "Metadata-Flavor: Google"
   

   La requête renvoie une réponse semblable à l'exemple ci-dessous :

   {
         "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAi85nHq39HE3C2LTrCARA",
         "expires_in":3599,
         "token_type":"Bearer"
    }
   

2. Insérez le jeton d'accès dans votre requête REST, en effectuant les remplacements suivants :

   • ACCESS_TOKEN : jeton d'accès renvoyé à l'étape précédente.
   • PROJECT_ID : ID ou nom de votre projet Google Cloud.

   curl -X GET \
       -H "Authorization: Bearer ACCESS_TOKEN" \
       "https://cloudresourcemanager.googleapis.com/v3/projects/PROJECT_ID"
   

Définir le projet de quota avec une requête REST

Pour appeler certaines API avec des identifiants utilisateur, vous devez également définir le projet utilisé pour la facturation ainsi que pour le suivi des quotas. Si votre appel d'API renvoie un message d'erreur indiquant que les identifiants utilisateur ne sont pas compatibles ou que le projet de quota n'est pas défini, vous devez définir explicitement le projet de quota pour la requête. Pour définir le projet de quota, incluez l'en-tête x-goog-user-project dans votre requête.

Pour plus d'informations sur les scénarios susceptibles d'occasionner ce problème, consultez la section Les identifiants utilisateur ne fonctionnent pas.

Vous devez disposer de l'autorisation IAM serviceusage.services.use pour un projet si vous souhaitez le désigner comme votre projet de facturation. L'autorisation serviceusage.services.use est incluse dans le rôle IAM Consommateur Service Usage. Si vous ne disposez pas de l'autorisation serviceusage.services.use pour un projet, contactez votre administrateur de sécurité ou un propriétaire de projet qui peut vous attribuer le rôle Consommateur Service Usage sur le projet.

L'exemple suivant utilise l'API Cloud Translation pour traduire le mot "hello" en espagnol. L'API Cloud Translation est une API qui nécessite la spécification d'un projet de quota. Pour exécuter l'exemple, créez un fichier nommé request.json avec le contenu du corps de la requête.

Avant d'utiliser les données de requête ci-dessous, effectuez les remplacements suivants :

• PROJECT_ID : ID ou nom du projet Google Cloud à utiliser comme projet de facturation.

Corps JSON de la requête :

{
  "q": "hello",
  "source": "en",
  "target": "es"
}

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

curl -X POST \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "x-goog-user-project: PROJECT_ID" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://translation.googleapis.com/language/translate/v2"

PowerShell

Enregistrez le corps de la requête dans un fichier nommé request.json, puis exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred"; "x-goog-user-project" = "PROJECT_ID" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://translation.googleapis.com/language/translate/v2" | Select-Object -Expand Content

La requête de traduction aboutit. Vous pouvez exécuter la commande sans l'en-tête x-goog-user-project pour voir ce qui se passe lorsque vous ne spécifiez pas de projet de facturation.

Étapes suivantes

• Consultez la présentation de l'authentification chez Google.
• Découvrez comment vous authentifier en utilisant les bibliothèques clientes.
• Découvrez les identifiants gcloud CLI et les identifiants ADC.
• Explorez les données stockées sur le serveur de métadonnées.