Autentícate como cuenta de servicio

En este tema, se explica cómo autenticar una aplicación como una cuenta de servicio. Para obtener información general sobre la autenticación en las API de Google Cloud, incluidas las situaciones y las estrategias de autenticación comunes, consulta Descripción general de la autenticación. Para obtener más información sobre las cuentas de servicio, consulta cuentas de servicio en la documentación de la administración de identidades y accesos.

Encuentra credenciales automáticamente

Si tu aplicación se ejecuta dentro de un entorno de Google Cloud y adjuntas una cuenta de servicio a ese entorno, tu aplicación puede recuperar credenciales para la cuenta de servicio. Así, la aplicación puede usar las credenciales para llamar a las API de Google Cloud.

Puedes adjuntar cuentas de servicio a los recursos de muchos servicios diferentes de Google Cloud, incluidos Compute Engine, Google Kubernetes Engine, App Engine, Cloud Run y Cloud Functions. Recomendamos usar esta estrategia porque es más conveniente y segura que pasar las credenciales de forma manual.

Además, te recomendamos usar las bibliotecas cliente de Google Cloud para tu aplicación. Las bibliotecas cliente de Google Cloud usan una biblioteca llamada credenciales predeterminadas de la aplicación (ADC) para encontrar de forma automática las credenciales de la cuenta de servicio. ADC busca las credenciales de la cuenta de servicio en el siguiente orden:

  1. Si se establece la variable de entorno GOOGLE_APPLICATION_CREDENTIALS, ADC usa la clave de la cuenta de servicio o el archivo de configuración al que apunta la variable.

  2. Si no se configuró la variable de entorno GOOGLE_APPLICATION_CREDENTIALS, ADC usa la cuenta de servicio adjunta al recurso que ejecuta tu código.

    Esta cuenta de servicio puede ser una cuenta de servicio predeterminada que proporcionan Compute Engine, Google Kubernetes Engine, App Engine, Cloud Run o Cloud Functions. También puede ser una cuenta de servicio administrada por el usuario que creaste.

  3. Si ADC no puede usar ninguna de las credenciales ya mencionadas, aparecerá un error.

En el siguiente ejemplo de código, se ilustra cómo usar la biblioteca de ADC en el código de la aplicación. Para ejecutar este ejemplo, debes instalar la biblioteca cliente de 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

Pasa las credenciales de forma manual

Si tu aplicación se ejecuta en un entorno sin una cuenta de servicio adjunta, como una local o en otro proveedor de servicios en la nube, debes usar la federación de Workload Identity.

Si no puedes usar la federación de Workload Identity, debes crear una cuenta de servicio y una o más claves de cuenta de servicio, que son credenciales asociadas con la cuenta de servicio. Las claves de la cuenta de servicio se pueden pasar de forma manual a tu aplicación.

Asegúrate de revisar las prácticas recomendadas para administrar claves de cuentas de servicio.

Crea una cuenta de servicio

En los siguientes pasos, se describe cómo crear una cuenta de servicio si no tienes una:

Console

Crear una cuenta de servicio:

  1. En la consola, ve a la página Crear cuenta de servicio.

    Ve a Crear cuenta de servicio
  2. Selecciona tu proyecto.

  3. Ingresa un nombre en el campo Nombre de cuenta de servicio. La consola completa el campo ID de cuenta de servicio según este nombre.

    Opcional: en el campo Descripción de la cuenta de servicio, ingresa una descripción. Por ejemplo, Service account for quickstart.

  4. Haz clic en Crear y continuar.

  5. Para proporcionar acceso a tu proyecto, otorga los siguientes roles a tu cuenta de servicio: Proyecto > Propietario .

    En la lista Seleccionar un rol, elige un rol.

    Para obtener roles adicionales, haz clic en Agregar otro rol y agrega cada rol adicional.

  6. Haga clic en Continuar.

  7. Haz clic en Listo para terminar de crear la cuenta de servicio.

    No cierres la ventana del navegador. La usarás en la próxima tarea.

Para crear una clave de cuenta de servicio, haz lo siguiente:

  1. En la consola, haz clic en la dirección de correo electrónico de la cuenta de servicio que creaste.
  2. Haga clic en Claves.
  3. Haz clic en Agregar clave y, luego, en Crear clave nueva.
  4. Haga clic en Crear. Se descargará un archivo de claves JSON en tu computadora.
  5. Haga clic en Cerrar.

gcloud

Configura la autenticación:

  1. Crea la cuenta de servicio: 

    gcloud iam service-accounts create NAME

    Reemplaza NAME por un nombre para la cuenta de servicio.

  2. Otorga roles a la cuenta de servicio. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM: roles/owner: 

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

    Reemplaza lo siguiente:

    • SERVICE_ACCOUNT_NAME: el nombre de la cuenta de servicio
    • PROJECT_ID: el ID del proyecto en el que creaste la cuenta de servicio
    • ROLE: el rol a otorgar

  3. Genera el archivo de claves: 

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

    Reemplaza lo siguiente:

    • FILE_NAME: un nombre para el archivo de claves
    • SERVICE_ACCOUNT_NAME: el nombre de la cuenta de servicio
    • PROJECT_ID: el ID del proyecto en el que creaste la cuenta de servicio

Pasa las credenciales a través de la variable de entorno

Configura la variable de entorno GOOGLE_APPLICATION_CREDENTIALS para proporcionar credenciales de autenticación al código de la aplicación. Esta variable se aplica solo a tu sesión de shell actual. Si quieres que la variable se aplique a sesiones de shell futuras, configura la variable en tu archivo de inicio de shell, por ejemplo, en el archivo ~/.bashrc o ~/.profile.

Linux o macOS

export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Reemplaza KEY_PATH por la ruta de acceso del archivo JSON que contiene la clave de tu cuenta de servicio.

Por ejemplo:

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

Windows

Para PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Reemplaza KEY_PATH por la ruta de acceso del archivo JSON que contiene la clave de tu cuenta de servicio.

Por ejemplo:

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

Para el símbolo del sistema:

set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

Reemplaza KEY_PATH por la ruta de acceso del archivo JSON que contiene la clave de tu cuenta de servicio.

Después de completar los pasos anteriores, ADC puede encontrar tus credenciales de forma automática, como se describe en la sección anterior. Recomendamos usar ADC porque requiere menos código y este es portátil en entornos diferentes.

Pasa las credenciales mediante código

También puedes apuntar de forma explícita hacia el archivo de la cuenta de servicio en el código, como se muestra en el siguiente ejemplo. Instala la biblioteca cliente de Cloud Storage para ejecutar el siguiente ejemplo.

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

Soluciona errores de la API

Consulta Errores de las API de Cloud para obtener más información sobre cómo solucionar problemas de las solicitudes a la API con errores.

¿Qué sigue?

Pruébalo tú mismo

Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

Comenzar gratis