Autenticazione come account di servizio

Questo argomento spiega come autenticare un'applicazione come account di servizio. Per informazioni generali sull'autenticazione alle API di Google Cloud, inclusi strategie e scenari di autenticazione comuni, consulta la panoramica sull'autenticazione. Per ulteriori informazioni sugli account di servizio, vedi Account di servizio nella documentazione su Identity and Access Management.

Trovare le credenziali automaticamente

Se la tua applicazione viene eseguita in un ambiente Google Cloud e hai collegato un account di servizio a quell'ambiente, l'applicazione può recuperare le credenziali per l'account di servizio. L'applicazione può quindi utilizzare le credenziali per chiamare le API Google Cloud.

Puoi collegare gli account di servizio alle risorse per molti servizi Google Cloud diversi, tra cui Compute Engine, Google Kubernetes Engine, App Engine, Cloud Run e Cloud Functions. Consigliamo di utilizzare questa strategia perché è più pratica e sicura rispetto alla trasmissione manuale delle credenziali.

Inoltre, ti consigliamo di utilizzare le librerie client di Google Cloud per la tua applicazione. Le librerie client di Google Cloud utilizzano una libreria denominata Application Default Credentials (ADC) per trovare automaticamente le credenziali del tuo account di servizio. ADC cerca le credenziali dell'account di servizio nel seguente ordine:

  1. Se è impostata la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS, ADC utilizza la chiave o il file di configurazione dell'account di servizio a cui rimanda la variabile.

  2. Se la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS non è impostata, ADC utilizza l'account di servizio collegato alla risorsa che esegue il codice.

    Questo account di servizio potrebbe essere un account di servizio predefinito fornito da Compute Engine, Google Kubernetes Engine, App Engine, Cloud Run o Cloud Functions. Potrebbe anche essere un account di servizio gestito dall'utente che hai creato.

  3. Se ADC non può utilizzare nessuna delle credenziali riportate sopra, si verifica un errore.

Il seguente codice di esempio illustra come utilizzare la libreria ADC nel codice dell'applicazione. Per eseguire questo esempio, devi installare la libreria client di Cloud Storage.

C#

public object AuthImplicit(string projectId)
{
    // If you don't specify credentials when constructing the client, the
    // client library will look for credentials in the environment.
    var credential = GoogleCredential.GetApplicationDefault();
    var storage = StorageClient.Create(credential);
    // Make an authenticated API request.
    var buckets = storage.ListBuckets(projectId);
    foreach (var bucket in buckets)
    {
        Console.WriteLine(bucket.Name);
    }
    return null;
}

Go


// implicit uses Application Default Credentials to authenticate.
func implicit() {
	ctx := context.Background()

	// For API packages whose import path is starting with "cloud.google.com/go",
	// such as cloud.google.com/go/storage in this case, if there are no credentials
	// provided, the client library will look for credentials in the environment.
	storageClient, err := storage.NewClient(ctx)
	if err != nil {
		log.Fatal(err)
	}
	defer storageClient.Close()

	it := storageClient.Buckets(ctx, "project-id")
	for {
		bucketAttrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(bucketAttrs.Name)
	}

	// For packages whose import path is starting with "google.golang.org/api",
	// such as google.golang.org/api/cloudkms/v1, use NewService to create the client.
	kmsService, err := cloudkms.NewService(ctx)
	if err != nil {
		log.Fatal(err)
	}

	_ = kmsService
}

Java

static void authImplicit() {
  // If you don't specify credentials when constructing the client, the client library will
  // look for credentials via the environment variable GOOGLE_APPLICATION_CREDENTIALS.
  Storage storage = StorageOptions.getDefaultInstance().getService();

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

Node.js

// Imports the Google Cloud client library.
const {Storage} = require('@google-cloud/storage');

// Instantiates a client. If you don't specify credentials when constructing
// the client, the client library will look for credentials in the
// environment.
const storage = new Storage();
// Makes an authenticated API request.
async function listBuckets() {
  try {
    const results = await storage.getBuckets();

    const [buckets] = results;

    console.log('Buckets:');
    buckets.forEach(bucket => {
      console.log(bucket.name);
    });
  } catch (err) {
    console.error('ERROR:', err);
  }
}
listBuckets();

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

def implicit():
    from google.cloud import storage

    # If you don't specify credentials when constructing the client, the
    # client library will look for credentials in the environment.
    storage_client = storage.Client()

    # Make an authenticated API request
    buckets = list(storage_client.list_buckets())
    print(buckets)

Ruby

# project_id = "Your Google Cloud project ID"

require "google/cloud/storage"

# If you don't specify credentials when constructing the client, the client
# library will look for credentials in the environment.
storage = Google::Cloud::Storage.new project: project_id

# Make an authenticated API request
storage.buckets.each do |bucket|
  puts bucket.name
end

Trasmettere manualmente le credenziali

Se la tua applicazione viene eseguita in un ambiente senza alcun account di servizio collegato, ad esempio on-premise o su un altro provider cloud, devi utilizzare la federazione delle identità dei carichi di lavoro.

Se non puoi utilizzare la federazione delle identità per i carichi di lavoro, devi creare un account di servizio e una o più chiavi per gli account di servizio, ovvero credenziali associate all'account di servizio. Le chiavi degli account di servizio possono quindi essere passate manualmente all'applicazione.

Assicurati di leggere le best practice per la gestione delle chiavi degli account di servizio.

Creazione di un account di servizio

I passaggi seguenti spiegano come creare un account di servizio se non ne hai uno:

console

Crea un account di servizio:

  1. Nella console, vai alla pagina Crea account di servizio.

    Vai a Crea account di servizio
  2. Seleziona il progetto.
  3. Inserisci un nome nel campo Nome account di servizio. La console compila il campo ID account di servizio in base a questo nome.

    Nel campo Descrizione account di servizio, inserisci una descrizione. Ad esempio, Service account for quickstart.

  4. Fai clic su Crea e continua.
  5. Per fornire l'accesso al tuo progetto, concedi i seguenti ruoli al tuo account di servizio: Progetto > proprietario.

    Nell'elenco Seleziona un ruolo, scegli un ruolo.

    Per ulteriori ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo aggiuntivo.

  6. Fai clic su Continua.
  7. Fai clic su Fine per completare la creazione dell'account di servizio.

    Non chiudere la finestra del browser. La utilizzerai nel passaggio successivo.

Crea una chiave dell'account di servizio:

  1. Nella console, fai clic sull'indirizzo email dell'account di servizio che hai creato.
  2. Fai clic su Chiavi.
  3. Fai clic su Aggiungi chiave, quindi su Crea nuova chiave.
  4. Fai clic su Crea. Il file di una chiave JSON viene scaricato sul computer.
  5. Fai clic su Chiudi.

gcloud

Configurare l'autenticazione:

  1. Crea l'account di servizio:

    gcloud iam service-accounts create NAME

    Sostituisci NAME con un nome per l'account di servizio.

  2. Concedi ruoli all'account di servizio. Esegui il comando seguente una volta per ciascuno dei seguenti ruoli IAM: roles/owner:

    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

    Sostituisci quanto segue:

    • SERVICE_ACCOUNT_NAME: nome dell'account di servizio
    • PROJECT_ID: l'ID progetto in cui hai creato l'account di servizio
    • ROLE: il ruolo da concedere
  3. Genera il file della chiave:

    gcloud iam service-accounts keys create FILE_NAME.json --iam-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

    Sostituisci quanto segue:

    • FILE_NAME: un nome per il file della chiave
    • SERVICE_ACCOUNT_NAME: nome dell'account di servizio
    • PROJECT_ID: l'ID progetto in cui hai creato l'account di servizio

Trasmettere le credenziali tramite una variabile di ambiente

Fornisci le credenziali di autenticazione al codice della tua applicazione impostando la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS. Questa variabile si applica solo alla sessione shell corrente. Se vuoi che la variabile venga applicata alle sessioni shell future, impostala nel file di avvio della shell, ad esempio nel file ~/.bashrc o ~/.profile.

Linux o macOS

export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Sostituisci KEY_PATH con il percorso del file JSON che contiene la chiave dell'account di servizio.

Ad esempio:

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

Per PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Sostituisci KEY_PATH con il percorso del file JSON che contiene la chiave dell'account di servizio.

Ad esempio:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

Per il prompt dei comandi:

set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

Sostituisci KEY_PATH con il percorso del file JSON che contiene la chiave dell'account di servizio.

Una volta completati i passaggi precedenti, ADC può trovare automaticamente le tue credenziali, come descritto nella sezione precedente. Consigliamo di utilizzare ADC perché richiede meno codice e il tuo codice è portatile in ambienti diversi.

Trasmettere le credenziali utilizzando il codice

In alternativa, puoi scegliere di puntare esplicitamente al file dell'account di servizio nel codice, come mostrato nell'esempio seguente. Per eseguire l'esempio seguente, devi installare la libreria client Cloud Storage.

C#

        // Some APIs, like Storage, accept a credential in their Create()
        // method.
        public object AuthExplicit(string projectId, string jsonPath)
        {
            // Explicitly use service account credentials by specifying
            // the private key file.
            var credential = GoogleCredential.FromFile(jsonPath);
            var storage = StorageClient.Create(credential);
            // Make an authenticated API request.
            var buckets = storage.ListBuckets(projectId);
            foreach (var bucket in buckets)
            {
                Console.WriteLine(bucket.Name);
            }
            return null;
        }
        // Other APIs, like Language, accept a channel in their Create()
        // method.
        public object AuthExplicit(string projectId, string jsonPath)
        {
            LanguageServiceClientBuilder builder = new LanguageServiceClientBuilder
            {
                CredentialsPath = jsonPath
            };

            LanguageServiceClient client = builder.Build();
            AnalyzeSentiment(client);
            return 0;
        }

Go


// explicit reads credentials from the specified path.
func explicit(jsonPath, projectID string) {
	ctx := context.Background()
	client, err := storage.NewClient(ctx, option.WithCredentialsFile(jsonPath))
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()
	fmt.Println("Buckets:")
	it := client.Buckets(ctx, projectID)
	for {
		battrs, err := it.Next()
		if err == iterator.Done {
			break
		}
		if err != nil {
			log.Fatal(err)
		}
		fmt.Println(battrs.Name)
	}
}

Java

static void authExplicit(String jsonPath) throws IOException {
  // You can specify a credential file by providing a path to GoogleCredentials.
  // Otherwise credentials are read from the GOOGLE_APPLICATION_CREDENTIALS environment variable.
  GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream(jsonPath))
        .createScoped(Lists.newArrayList("https://www.googleapis.com/auth/cloud-platform"));
  Storage storage = StorageOptions.newBuilder().setCredentials(credentials).build().getService();

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

Node.js

// Imports the Google Cloud client library.
const {Storage} = require('@google-cloud/storage');

// Instantiates a client. Explicitly use service account credentials by
// specifying the private key file. All clients in google-cloud-node have this
// helper, see https://github.com/GoogleCloudPlatform/google-cloud-node/blob/master/docs/authentication.md
// const projectId = 'project-id'
// const keyFilename = '/path/to/keyfile.json'
const storage = new Storage({projectId, keyFilename});

// Makes an authenticated API request.
async function listBuckets() {
  try {
    const [buckets] = await storage.getBuckets();

    console.log('Buckets:');
    buckets.forEach(bucket => {
      console.log(bucket.name);
    });
  } catch (err) {
    console.error('ERROR:', err);
  }
}
listBuckets();

PHP

namespace Google\Cloud\Samples\Auth;

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

/**
 * Authenticate to a cloud client library using a service account explicitly.
 *
 * @param string $projectId           The Google project ID.
 * @param string $serviceAccountPath  Path to service account credentials JSON.
 */
function auth_cloud_explicit($projectId, $serviceAccountPath)
{
    # Explicitly use service account credentials by specifying the private key
    # file.
    $config = [
        'keyFilePath' => $serviceAccountPath,
        'projectId' => $projectId,
    ];
    $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

def explicit():
    from google.cloud import storage

    # Explicitly use service account credentials by specifying the private key
    # file.
    storage_client = storage.Client.from_service_account_json(
        'service_account.json')

    # Make an authenticated API request
    buckets = list(storage_client.list_buckets())
    print(buckets)

Ruby

# project_id = "Your Google Cloud project ID"
# key_file   = "path/to/service-account.json"
require "google/cloud/storage"

# Explicitly use service account credentials by specifying the private key
# file.
storage = Google::Cloud::Storage.new project: project_id, keyfile: key_file

# Make an authenticated API request
storage.buckets.each do |bucket|
  puts bucket.name
end

Risoluzione degli errori relativi all'API

Scopri di più su come risolvere i problemi delle richieste API non riuscite in Errori relativi alle API Cloud.

Passaggi successivi

Provalo

Se non conosci Google Cloud, crea un account per valutare le prestazioni dei nostri prodotti in scenari reali. I nuovi clienti ricevono anche 300 $ di crediti gratuiti per l'esecuzione, il test e il deployment dei carichi di lavoro.

Inizia gratuitamente