Halaman ini diterjemahkan oleh Cloud Translation API.

Autentikasi untuk menggunakan library klien

Halaman ini menjelaskan cara menggunakan library klien dan Kredensial Default Aplikasi untuk mengakses Google API.

Library klien mempermudah akses ke Google Cloud API menggunakan bahasa yang didukung. Anda dapat menggunakan API Google Cloud secara langsung dengan membuat permintaan mentah ke server, tetapi library klien memberikan penyederhanaan yang secara signifikan mengurangi jumlah kode yang perlu ditulis. Hal ini terutama berlaku untuk autentikasi, karena library klien mendukung Kredensial Default Aplikasi (ADC).

Jika ingin menggunakan kunci API, jangan gunakan ADC. Untuk informasi selengkapnya, lihat Menggunakan kunci API dengan library klien.

Menggunakan Kredensial Default Aplikasi dengan library klien

Untuk menggunakan Kredensial Default Aplikasi guna mengautentikasi aplikasi, Anda harus terlebih dahulu menyiapkan ADC untuk lingkungan tempat aplikasi berjalan. Saat Anda menggunakan library klien untuk membuat klien, library klien akan otomatis memeriksa dan menggunakan kredensial yang Anda berikan ke ADC untuk melakukanautentikasi ke API yang digunakan oleh kode Anda. Aplikasi Anda tidak perlu secara eksplisit mengautentikasi atau mengelola token; persyaratan ini dikelola secara otomatis oleh library autentikasi.

Untuk lingkungan pengembangan lokal, Anda dapat menyiapkan ADC dengan kredensial pengguna atau dengan peniruan identitas akun layanan menggunakan gcloud CLI. Untuk lingkungan produksi, Anda menyiapkan ADC dengan memasang akun layanan.

Pembuatan contoh klien

Contoh kode berikut membuat klien untuk layanan Cloud Storage. Kode Anda cenderung membutuhkan klien yang berbeda; contoh ini dimaksudkan hanya untuk menunjukkan cara membuat klien dan menggunakannya tanpa kode untuk mengautentikasi secara eksplisit.

Sebelum dapat menjalankan contoh berikut, Anda harus menyelesaikan langkah-langkah berikut:

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

Persyaratan keamanan saat menggunakan konfigurasi kredensial dari sumber eksternal

Biasanya, Anda membuat konfigurasi kredensial menggunakan perintah gcloud CLI atau menggunakan Konsol Google Cloud. Misalnya, Anda dapat menggunakan gcloud CLI untuk membuat file ADC lokal atau file konfigurasi login. Demikian pula, Anda dapat menggunakan konsol Google Cloud untuk membuat dan mendownload kunci akun layanan.

Namun, untuk beberapa kasus penggunaan, konfigurasi kredensial diberikan kepada Anda oleh entitas eksternal; konfigurasi kredensial ini dimaksudkan untuk digunakan untuk melakukan autentikasi ke Google API.

Beberapa jenis konfigurasi kredensial mencakup endpoint dan jalur file, yang digunakan library autentikasi untuk memperoleh token. Saat menerima konfigurasi kredensial dari sumber eksternal, Anda harus memvalidasi konfigurasi sebelum menggunakannya. Jika Anda tidak memvalidasi konfigurasi, pelaku kejahatan dapat menggunakan kredensial untuk membahayakan sistem dan data Anda.

Memvalidasi konfigurasi kredensial dari sumber eksternal

Cara Anda memvalidasi kredensial eksternal bergantung pada jenis kredensial yang diterima aplikasi Anda.

Memvalidasi kunci akun layanan

Jika aplikasi Anda hanya menerima kunci akun layanan, gunakan loader kredensial khusus untuk kunci akun layanan, seperti yang ditunjukkan dalam contoh berikut. Loader kredensial khusus jenis hanya mengurai kolom yang ada untuk kunci akun layanan, yang tidak mengekspos kerentanan apa pun.

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)

Jika Anda tidak dapat menggunakan loader kredensial khusus jenis, validasi kredensial dengan mengonfirmasi bahwa nilai untuk kolom type adalah service_account. Jika nilai untuk kolom type adalah nilai lain, jangan gunakan kunci akun layanan.

Memvalidasi konfigurasi kredensial lainnya

Jika aplikasi Anda menerima jenis kredensial apa pun selain kunci akun layanan, Anda harus melakukan verifikasi tambahan. Contoh jenis konfigurasi kredensial lainnya meliputi file kredensial ADC, file kredensial Workload Identity Federation, atau file konfigurasi login Workforce Identity Federation.

Tabel berikut mencantumkan kolom yang perlu Anda validasi, jika ada dalam kredensial Anda. Tidak semua kolom ini ada untuk semua konfigurasi kredensial.

Kolom	Tujuan	Nilai yang diharapkan
`service_account_impersonation_url`	Library autentikasi menggunakan kolom ini untuk mengakses endpoint guna membuat token akses untuk akun layanan yang ditiru identitasnya.	`https://iamcredentials.googleapis.com.com/v1/projects/-/serviceAccounts/service account email:generateAccessToken`
`token_url`	Library autentikasi mengirim token eksternal ke endpoint ini untuk menukarnya dengan token akses gabungan.	`https://sts.googleapis.com.com/v1/token`
`credential_source.file`	Library autentikasi membaca token eksternal dari file di lokasi yang ditentukan oleh kolom ini dan mengirimkannya ke endpoint `token_url`.	Jalur untuk file yang berisi token eksternal. Anda harus mengenali jalur ini.
`credential_source.url`	Endpoint yang menampilkan token eksternal. Library autentikasi mengirimkan permintaan ke URL ini dan mengirimkan respons ke endpoint `token_url`.	Salah satu item berikut: Endpoint terkenal yang disediakan oleh penyedia cloud Anda. Endpoint yang telah Anda siapkan secara eksplisit untuk memberikan token.
`credential_source.executable.command`	Jika variabel lingkungan `GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES` ditetapkan ke `1`, library autentikasi akan menjalankan perintah atau file yang dapat dieksekusi ini.	File atau perintah yang dapat dieksekusi yang menampilkan token eksternal. Anda harus mengenali perintah ini dan memvalidasi bahwa perintah ini aman.
`credential_source.aws.url`	Library autentikasi mengeluarkan permintaan ke URL ini untuk mengambil token keamanan AWS.	Salah satu nilai persis berikut: `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`	Library autentikasi mengeluarkan permintaan ke URL ini untuk mengambil region AWS yang aktif.	Salah satu nilai persis berikut: `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`	Library autentikasi mengeluarkan permintaan ke URL ini untuk mengambil token sesi AWS.	Salah satu nilai persis berikut: `http://169.254.169.254/latest/api/token` `http://[fd00:ec2::254]/latest/api/token`

Langkah selanjutnya

Pelajari lebih lanjut tentang Kredensial Default Aplikasi.
Lihat ringkasan Metode autentikasi.