Mengautentikasi workload ke Google Cloud API menggunakan akun layanan


Halaman ini menjelaskan cara menggunakan akun layanan untuk memungkinkan aplikasi yang berjalan di instance virtual machine (VM) Anda dapat melakukan autentikasi ke Google Cloud API dan memberikan akses ke resource.

Agar dapat menggunakan akun layanan untuk autentikasi, Anda harus memastikan terlebih dahulu bahwa VM Anda dikonfigurasi untuk menggunakan akun layanan. Untuk melakukannya, selesaikan salah satu prosedur berikut:

Sebelum memulai

  • Tinjau Ringkasan akun layanan.
  • Jika Anda belum melakukannya, siapkan autentikasi. Autentikasi adalah proses verifikasi identitas Anda untuk mengakses layanan dan API Google Cloud. Untuk menjalankan kode atau contoh dari lingkungan pengembangan lokal, Anda dapat mengautentikasi ke Compute Engine dengan memilih salah satu opsi berikut:

    Untuk menggunakan contoh Python di halaman ini dalam lingkungan pengembangan lokal, instal dan lakukan inisialisasi gcloud CLI, lalu siapkan Kredensial Default Aplikasi dengan kredensial pengguna Anda.

    1. Install the Google Cloud CLI.
    2. To initialize the gcloud CLI, run the following command:

      gcloud init
    3. If you're using a local shell, then create local authentication credentials for your user account:

      gcloud auth application-default login

      You don't need to do this if you're using Cloud Shell.

    Untuk informasi selengkapnya, lihat Set up authentication for a local development environment.

Ringkasan

Setelah Anda menyiapkan instance VM untuk dijalankan menggunakan akun layanan, aplikasi yang berjalan pada instance VM dapat menggunakan salah satu metode berikut untuk autentikasi:

Mengautentikasi aplikasi menggunakan kredensial akun layanan

Setelah menyiapkan instance untuk dijalankan sebagai akun layanan, Anda dapat menggunakan kredensial akun layanan untuk mengautentikasi aplikasi yang berjalan pada instance tersebut.

Mengautentikasi aplikasi dengan library klien

Library klien dapat menggunakan Kredensial Default Aplikasi untuk melakukan autentikasi dengan Google API dan mengirim permintaan ke API tersebut. Kredensial Default Aplikasi memungkinkan aplikasi mendapatkan kredensial secara otomatis dari berbagai sumber, sehingga Anda dapat menguji aplikasi secara lokal, lalu men-deploy-nya ke instance Compute Engine tanpa mengubah kode aplikasi.

Untuk mengetahui informasi tentang cara menyiapkan Kredensial Default Aplikasi, lihat Memberikan kredensial ke Kredensial Default Aplikasi.

Contoh ini menggunakan library klien Python untuk mengautentikasi dan membuat permintaan ke Cloud Storage API untuk mencantumkan bucket dalam sebuah project. Contoh tersebut menggunakan prosedur berikut:

  1. Dapatkan kredensial autentikasi yang diperlukan untuk Cloud Storage API dan lakukan inisialisasi layanan Cloud Storage dengan metode build() dan kredensial tersebut.
  2. Cantumkan bucket di Cloud Storage.

Anda dapat menjalankan contoh ini pada instance yang memiliki akses untuk mengelola bucket di Cloud Storage.

import argparse
from typing import List

from google.cloud import storage


def create_client() -> storage.Client:
    """
    Construct a client object for the Storage API using the
    application default credentials.

    Returns:
        Storage API client object.
    """
    # Construct the service object for interacting with the Cloud Storage API -
    # the 'storage' service, at version 'v1'.
    # Authentication is provided by application default credentials.
    # When running locally, these are available after running
    # `gcloud auth application-default login`. When running on Compute
    # Engine, these are available from the environment.
    return storage.Client()


def list_buckets(client: storage.Client, project_id: str) -> List[storage.Bucket]:
    """
    Retrieve bucket list of a project using provided client object.


    Args:
        client: Storage API client object.
        project_id: name of the project to list buckets from.

    Returns:
        List of Buckets found in the project.
    """
    buckets = client.list_buckets()
    return list(buckets)


def main(project_id: str) -> None:
    client = create_client()
    buckets = list_buckets(client, project_id)
    print(buckets)


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("project_id", help="Your Google Cloud Project ID.")

    args = parser.parse_args()

    main(args.project_id)

Mengautentikasi aplikasi secara langsung dengan token akses

Untuk sebagian besar aplikasi, Anda dapat melakukan autentikasi menggunakan Kredensial Default Aplikasi, yang menemukan kredensial dan mengelola token untuk Anda. Namun, jika aplikasi Anda mengharuskan Anda menyediakan token akses OAuth2, Compute Engine memungkinkan Anda mendapatkan token akses dari server metadatanya untuk digunakan dalam aplikasi Anda.

Ada beberapa opsi untuk mendapatkan dan menggunakan token akses ini untuk mengautentikasi aplikasi Anda. Misalnya, Anda dapat menggunakan curl untuk membuat permintaan sederhana, atau menggunakan bahasa pemrograman seperti Python agar lebih fleksibel.

cURL

Untuk menggunakan curl guna meminta token akses dan mengirim permintaan ke API:

  1. Pada instance tempat aplikasi Anda berjalan, buat kueri token akses ke server metadata dengan menjalankan perintah berikut:

    $ curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
    -H "Metadata-Flavor: Google"

    Permintaan tersebut menampilkan respons yang mirip dengan:

    {
          "access_token":"ya29.AHES6ZRN3-HlhAPya30GnW_bHSb_QtAS08i85nHq39HE3C2LTrCARA",
          "expires_in":3599,
          "token_type":"Bearer"
     }

    Untuk permintaan API, Anda harus menyertakan nilai access_token, bukan seluruh respons. Jika telah menginstal prosesor JSON command line jq, Anda dapat menggunakan perintah berikut untuk mengekstrak nilai token akses dari respons:

    $ ACCESS_TOKEN=`curl \
    "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token" \
    -H "Metadata-Flavor: Google" | jq -r '.access_token'`
    
  2. Salin nilai properti access_token dari respons dan gunakan untuk mengirim permintaan ke API. Misalnya, permintaan berikut mencetak daftar instance dalam project Anda dari zona tertentu:

    $ curl https://compute.googleapis.com/compute/v1/projects/PROJECT_ID/zones/ZONE/instances \
    -H "Authorization":"Bearer ACCESS_TOKEN"
    

    Ganti kode berikut:

    • PROJECT_ID: ID project untuk permintaan ini.
    • ZONE: zona untuk membuat daftar VM.
    • ACCESS_TOKEN: nilai token akses yang Anda peroleh dari langkah sebelumnya.

    Untuk mengetahui informasi tentang parameter yang dapat Anda tetapkan dalam permintaan, lihat dokumentasi Parameter sistem.

Python

Contoh ini menunjukkan cara meminta token untuk mengakses Cloud Storage API dalam aplikasi Python. Contoh tersebut menggunakan prosedur berikut:

  1. Meminta token akses dari server metadata.
  2. Mengekstrak token akses dari respons server.
  3. Menggunakan token akses untuk membuat permintaan ke Cloud Storage.
  4. Jika permintaan berhasil, skrip akan mencetak respons.

import argparse

import requests


METADATA_URL = "http://metadata.google.internal/computeMetadata/v1/"
METADATA_HEADERS = {"Metadata-Flavor": "Google"}
SERVICE_ACCOUNT = "default"


def get_access_token() -> str:
    """
    Retrieves access token from the metadata server.

    Returns:
        The access token.
    """
    url = f"{METADATA_URL}instance/service-accounts/{SERVICE_ACCOUNT}/token"

    # Request an access token from the metadata server.
    r = requests.get(url, headers=METADATA_HEADERS)
    r.raise_for_status()

    # Extract the access token from the response.
    access_token = r.json()["access_token"]

    return access_token


def list_buckets(project_id: str, access_token: str) -> dict:
    """
    Calls Storage API to retrieve a list of buckets.

    Args:
        project_id: name of the project to list buckets from.
        access_token: access token to authenticate with.

    Returns:
        Response from the API.
    """
    url = "https://www.googleapis.com/storage/v1/b"
    params = {"project": project_id}
    headers = {"Authorization": f"Bearer {access_token}"}

    r = requests.get(url, params=params, headers=headers)
    r.raise_for_status()

    return r.json()


def main(project_id: str) -> None:
    """
    Retrieves access token from metadata server and uses it to list
    buckets in a project.

    Args:
        project_id: name of the project to list buckets from.
    """
    access_token = get_access_token()
    buckets = list_buckets(project_id, access_token)
    print(buckets)


if __name__ == "__main__":
    parser = argparse.ArgumentParser(
        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
    )
    parser.add_argument("project_id", help="Your Google Cloud project ID.")

    args = parser.parse_args()

    main(args.project_id)

Token akses tidak berlaku lagi setelah beberapa saat. Server metadata menyimpan token akses ke dalam cache hingga memiliki sisa waktu 5 menit sebelum masa berlakunya berakhir. Jika token tidak dapat di-cache, permintaan yang melebihi 50 kueri per detik mungkin dibatasi kapasitasnya. Aplikasi Anda harus memiliki token akses yang valid agar panggilan API-nya berhasil.

Mengautentikasi alat pada instance menggunakan akun layanan

Beberapa aplikasi mungkin menggunakan perintah dari gcloud CLI, yang disertakan secara default di sebagian besar image Compute Engine. gcloud CLI secara otomatis mengenali akun layanan instance dan izin relevan yang diberikan ke akun layanan. Khususnya, jika Anda memberikan peran yang benar ke akun layanan, Anda dapat menggunakan gcloud CLI dari instance tanpa harus menggunakan gcloud auth login.

Pengenalan akun layanan ini terjadi secara otomatis dan hanya berlaku untuk gcloud CLI yang disertakan dengan instance. Jika membuat alat baru atau menambahkan alat kustom, Anda harus mengizinkan aplikasi Anda menggunakan library klien atau dengan menggunakan token akses langsung di aplikasi Anda.

Untuk memanfaatkan pengenalan akun layanan otomatis, berikan peran IAM yang sesuai ke akun layanan dan lampirkan akun layanan ke instance. Misalnya, jika Anda memberikan peran roles/storage.objectAdmin ke akun layanan, gcloud CLI dapat mengelola dan mengakses objek Cloud Storage secara otomatis.

Demikian pula, jika Anda mengaktifkan roles/compute.instanceAdmin.v1 untuk akun layanan, alat gcloud compute dapat mengelola instance secara otomatis.

Langkah selanjutnya

Coba sendiri

Jika Anda baru pertama kali menggunakan Google Cloud, buat akun untuk mengevaluasi performa Compute Engine dalam skenario dunia nyata. Pelanggan baru mendapatkan kredit gratis senilai $300 untuk menjalankan, menguji, dan men-deploy workload.

Coba Compute Engine gratis