S'authentifier pour utiliser les bibliothèques clientes

Cette page explique comment utiliser les bibliothèques clientes et les ADC (Identifiants par défaut de l'application) pour accéder aux API Google.

Les bibliothèques clientes facilitent l'accès aux API Google Cloud à l'aide d'un langage compatible. Vous pouvez utiliser directement les API Google Cloud en envoyant des requêtes brutes au serveur, mais les bibliothèques clientes fournissent des simplifications qui réduisent considérablement la quantité de code à écrire. Cela est particulièrement vrai pour l'authentification, car les bibliothèques clientes sont compatibles avec le service Identifiants par défaut de l'application (ADC, Application Default Credentials).

Si vous souhaitez utiliser une clé API, vous n'utiliserez pas le service ADC. Pour en savoir plus, consultez la page Utiliser une clé API avec des bibliothèques clientes.

Utiliser les identifiants par défaut de l'application avec les bibliothèques clientes

Pour authentifier votre application à l'aide du service d'identifiants par défaut de l'application (ADC), vous devez d'abord configurer ADC pour l'environnement dans lequel votre application s'exécute. Lorsque vous utilisez la bibliothèque cliente pour créer un client, celle-ci recherche et utilise automatiquement les identifiants que vous avez fournis au service ADC pour s'authentifier auprès des API utilisées par votre code. Votre application n'a pas besoin de s'authentifier explicitement ou de gérer les jetons. Ces points sont gérés automatiquement par les bibliothèques d'authentification.

Pour un environnement de développement local, vous pouvez configurer le service ADC avec vos identifiants utilisateur ou avec l'emprunt d'identité d'un compte de service en utilisant gcloud CLI. Pour les environnements de production, vous devez configurer le service ADC en associant un compte de service.

Exemple de création de client

Les exemples de code suivants créent un client pour le service Cloud Storage. Votre code va probablement nécessiter différents clients. Ces exemples visent simplement à montrer comment vous pouvez créer un client et l'utiliser sans code pour vous authentifier explicitement.

Avant de pouvoir exécuter les exemples suivants, vous devez effectuer les étapes ci-après :

• Configurer les ADC pour votre environnement
• Installer la bibliothèque cliente Cloud Storage

Go

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
	"google.golang.org/api/iterator"
)

// authenticateImplicitWithAdc uses Application Default Credentials
// to automatically find credentials and authenticate.
func authenticateImplicitWithAdc(w io.Writer, projectId string) error {
	// projectId := "your_project_id"

	ctx := context.Background()

	// NOTE: Replace the client created below with the client required for your application.
	// Note that the credentials are not specified when constructing the client.
	// The client library finds your credentials using ADC.
	client, err := storage.NewClient(ctx)
	if err != nil {
		return fmt.Errorf("NewClient: %w", err)
	}
	defer client.Close()

	it := client.Buckets(ctx, projectId)
	for {
		bucketAttrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			return err
		}
		fmt.Fprintf(w, "Bucket: %v\n", bucketAttrs.Name)
	}

	fmt.Fprintf(w, "Listed all storage buckets.\n")

	return nil
}

Java

import com.google.api.gax.paging.Page;
import com.google.cloud.storage.Bucket;
import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;
import java.io.IOException;

public class AuthenticateImplicitWithAdc {

  public static void main(String[] args) throws IOException {
    // TODO(Developer):
    //  1. Before running this sample,
    //  set up Application Default Credentials as described in
    //  https://cloud.google.com/docs/authentication/external/set-up-adc
    //  2. Replace the project variable below.
    //  3. Make sure you have the necessary permission to list storage buckets
    //  "storage.buckets.list"
    String projectId = "your-google-cloud-project-id";
    authenticateImplicitWithAdc(projectId);
  }

  // When interacting with Google Cloud Client libraries, the library can auto-detect the
  // credentials to use.
  public static void authenticateImplicitWithAdc(String project) throws IOException {

    // *NOTE*: Replace the client created below with the client required for your application.
    // Note that the credentials are not specified when constructing the client.
    // Hence, the client library will look for credentials using ADC.
    //
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    Storage storage = StorageOptions.newBuilder().setProjectId(project).build().getService();

    System.out.println("Buckets:");
    Page<Bucket> buckets = storage.list();
    for (Bucket bucket : buckets.iterateAll()) {
      System.out.println(bucket.toString());
    }
    System.out.println("Listed all storage buckets.");
  }
}

Node.js

/**
 * TODO(developer):
 *  1. Uncomment and replace these variables before running the sample.
 *  2. Set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
 *  3. Make sure you have the necessary permission to list storage buckets "storage.buckets.list"
 *    (https://cloud.google.com/storage/docs/access-control/iam-permissions#bucket_permissions)
 */
// const projectId = 'YOUR_PROJECT_ID';

const {Storage} = require('@google-cloud/storage');

async function authenticateImplicitWithAdc() {
  // This snippet demonstrates how to list buckets.
  // NOTE: Replace the client created below with the client required for your application.
  // Note that the credentials are not specified when constructing the client.
  // The client library finds your credentials using ADC.
  const storage = new Storage({
    projectId,
  });
  const [buckets] = await storage.getBuckets();
  console.log('Buckets:');

  for (const bucket of buckets) {
    console.log(`- ${bucket.name}`);
  }

  console.log('Listed all storage buckets.');
}

authenticateImplicitWithAdc();

PHP

// Imports the Cloud Storage client library.
use Google\Cloud\Storage\StorageClient;

/**
 * Authenticate to a cloud client library using a service account implicitly.
 *
 * @param string $projectId The Google project ID.
 */
function auth_cloud_implicit($projectId)
{
    $config = [
        'projectId' => $projectId,
    ];

    # If you don't specify credentials when constructing the client, the
    # client library will look for credentials in the environment.
    $storage = new StorageClient($config);

    # Make an authenticated API request (listing storage buckets)
    foreach ($storage->buckets() as $bucket) {
        printf('Bucket: %s' . PHP_EOL, $bucket->name());
    }
}

Python

from google.cloud import storage


def authenticate_implicit_with_adc(project_id="your-google-cloud-project-id"):
    """
    When interacting with Google Cloud Client libraries, the library can auto-detect the
    credentials to use.

    // TODO(Developer):
    //  1. Before running this sample,
    //  set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    //  2. Replace the project variable.
    //  3. Make sure that the user account or service account that you are using
    //  has the required permissions. For this sample, you must have "storage.buckets.list".
    Args:
        project_id: The project id of your Google Cloud project.
    """

    # This snippet demonstrates how to list buckets.
    # *NOTE*: Replace the client created below with the client required for your application.
    # Note that the credentials are not specified when constructing the client.
    # Hence, the client library will look for credentials using ADC.
    storage_client = storage.Client(project=project_id)
    buckets = storage_client.list_buckets()
    print("Buckets:")
    for bucket in buckets:
        print(bucket.name)
    print("Listed all storage buckets.")

Ruby

def authenticate_implicit_with_adc project_id:
  # The ID of your Google Cloud project
  # project_id = "your-google-cloud-project-id"

  ###
  # When interacting with Google Cloud Client libraries, the library can auto-detect the
  # credentials to use.
  # TODO(Developer):
  #   1. Before running this sample,
  #      set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
  #   2. Replace the project variable.
  #   3. Make sure that the user account or service account that you are using
  #      has the required permissions. For this sample, you must have "storage.buckets.list".
  ###

  require "google/cloud/storage"

  # This sample demonstrates how to list buckets.
  # *NOTE*: Replace the client created below with the client required for your application.
  # Note that the credentials are not specified when constructing the client.
  # Hence, the client library will look for credentials using ADC.
  storage = Google::Cloud::Storage.new project_id: project_id
  buckets = storage.buckets
  puts "Buckets: "
  buckets.each do |bucket|
    puts bucket.name
  end
  puts "Plaintext: Listed all storage buckets."
end

Exigences de sécurité lorsque vous utilisez des configurations d'identifiants à partir d'une source externe

En règle générale, vous générez des configurations d'identifiants à l'aide de commandes gcloud CLI ou de la console Google Cloud . Par exemple, vous pouvez utiliser gcloud CLI pour générer un fichier ADC local ou un fichier de configuration de connexion. De même, vous pouvez utiliser la console Google Cloud pour créer et télécharger une clé de compte de service.

Toutefois, dans certains cas d'utilisation, des configurations d'identifiants vous sont fournies par une entité externe. Ces configurations d'identifiants sont destinées à être utilisées pour s'authentifier auprès des API Google.

Certains types de configurations d'identifiants incluent des points de terminaison et des chemins d'accès aux fichiers, que les bibliothèques d'authentification utilisent pour acquérir un jeton. Lorsque vous acceptez des configurations d'identifiants à partir d'une source externe, vous devez valider la configuration avant de l'utiliser. Si vous ne validez pas la configuration, un acteur malveillant peut utiliser les identifiants pour compromettre vos systèmes et vos données.

Valider les configurations d'identifiants à partir de sources externes

La méthode de validation de vos identifiants externes dépend des types d'identifiants acceptés par votre application.

Valider des clés de compte de service

Si votre application n'accepte que des clés de compte de service, utilisez un chargeur d'identifiants spécifique aux clés de compte de service, comme illustré dans les exemples suivants. Le chargeur d'identifiants spécifique au type n'analyse que les champs présents pour les clés de compte de service, qui n'exposent aucune faille.

C#

var saCredential = ServiceAccountCredential.FromServiceAccountData(stream);

C++

auto cred = google::cloud::MakeServiceAccountCredentials(json)

Java

ServiceAccountCredentials credentials =
      ServiceAccountCredentials.fromJson(json, new HttpTransportFactory());

Node.js

const keys = JSON.parse(json_input)
const authClient = JWT.fromJSON(keys);

PHP

cred = new Google\Auth\Credentials\ServiceAccountCredentials($scope, $jsonKey);

Python

cred = service_account.Credentials.from_service_account_info(json_data)

Ruby

creds = Google::Auth::ServiceAccountCredentials.make_creds(json_key_io: json_stream)

Si vous ne pouvez pas utiliser un chargeur d'identifiants spécifique au type, validez les identifiants en confirmant que la valeur du champ type est service_account. Si la valeur du champ type est une autre valeur, n'utilisez pas la clé du compte de service.

Valider d'autres configurations d'identifiants

Si votre application accepte n'importe quel type d'identifiants en plus d'une clé de compte de service, vous devez effectuer une vérification supplémentaire. Parmi les autres types de configurations d'identifiants, citons les fichiers d'identifiants ADC, les fichiers d'identifiants de la fédération d'identité de charge de travail ou les fichiers de configuration de connexion de la fédération des identités des employés.

Le tableau suivant répertorie les champs que vous devez valider, le cas échéant. Tous ces champs ne sont pas présents pour toutes les configurations d'identifiants.

Important :Si l'un de ces champs contient une valeur qui ne correspond pas à la valeur attendue, n'utilisez pas les identifiants.

Champ	Objectif	Valeur attendue
service_account_impersonation_url	Les bibliothèques d'authentification utilisent ce champ pour accéder à un point de terminaison afin de générer un jeton d'accès pour le compte de service usurpé.	https://iamcredentials.googleapis.com.com/v1/projects/-/serviceAccounts/service account email:generateAccessToken
token_url	Les bibliothèques d'authentification envoient un jeton externe à ce point de terminaison pour l'échanger contre un jeton d'accès fédéré.	https://sts.googleapis.com.com/v1/token
credential_source.file	Les bibliothèques d'authentification lisent un jeton externe à partir du fichier à l'emplacement spécifié par ce champ et l'envoient au point de terminaison token_url.	Chemin d'accès d'un fichier contenant un jeton externe. Vous devriez reconnaître ce chemin.
credential_source.url	Point de terminaison qui renvoie un jeton externe. Les bibliothèques d'authentification envoient une requête à cette URL et la réponse au point de terminaison token_url.	L'un des éléments suivants: Point de terminaison bien connu fourni par votre fournisseur de services cloud. Point de terminaison que vous avez explicitement configuré pour fournir des jetons.
credential_source.executable.command	Si la variable d'environnement GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES est définie sur 1, les bibliothèques d'authentification exécutent cette commande ou ce fichier exécutable.	Fichier exécutable ou commande qui renvoie un jeton externe. Vous devez reconnaître cette commande et vérifier qu'elle est sûre.
credential_source.aws.url	Les bibliothèques d'authentification envoient une requête à cette URL pour récupérer un jeton de sécurité AWS.	L'une des valeurs exactes suivantes: http://169.254.169.254/latest/meta-data/iam/security-credentials http://[fd00:ec2::254]/latest/meta-data/iam/security-credentials
credential_source.aws.region_url	Les bibliothèques d'authentification envoient une requête à cette URL pour récupérer la région AWS active.	L'une des valeurs exactes suivantes: http://169.254.169.254/latest/meta-data/placement/availability-zone http://[fd00:ec2::254]/latest/meta-data/placement/availability-zone
credential_source.aws.imdsv2_session_token_url	Les bibliothèques d'authentification envoient une requête à cette URL pour récupérer le jeton de session AWS.	L'une des valeurs exactes suivantes: http://169.254.169.254/latest/api/token http://[fd00:ec2::254]/latest/api/token

Étape suivante

• Apprenez-en plus sur les identifiants par défaut de l'application.
• Consultez la présentation des méthodes d'authentification.