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. Install the Google Cloud CLI.

2. To initialize the gcloud CLI, run the following command:

   gcloud init

3. Enable the Cloud Resource Manager and Identity and Access Management (IAM) APIs:

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

Si vous ne souhaitez pas utiliser gcloud CLI, vous pouvez ignorer ces étapes et utiliser l'emprunt d'identité de compte de service ou le serveur de métadonnées pour générer un jeton.

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 section Configuration de l'authentification gcloud CLI et configuration 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 du 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 section Configurer l'ADC pour une ressource avec un compte de service associé.

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

Le moyen le plus simple d'usurper l'identité d'un compte de service pour générer un jeton d'accès consiste à utiliser la gcloud CLI. Toutefois, si vous devez générer le jeton de manière programmatique ou si vous ne souhaitez pas utiliser la gcloud CLI, vous pouvez utiliser l'usurpation d'identité pour générer un jeton de courte duré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.

   • Le compte principal que vous souhaitez utiliser pour effectuer l'emprunt d'identité 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). Si vous utilisez votre compte utilisateur, vous devez ajouter 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.

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.

gcloud

1. 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"

Jeton éphémère

Pour générer un jeton éphémère à l'aide de l'emprunt d'identité d'un compte de service, suivez les instructions fournies dans la section Créer un jeton d'accès éphémère.

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
• Fonctions Cloud Run
• Cloud Run
• Google Kubernetes Engine
• Cloud Build

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.
• Découvrez comment vous authentifier en utilisant les bibliothèques clientes.
• Découvrez la configuration de l'authentification via gcloud CLI et la configuration des identifiants par défaut de l'application.