Melakukan autentikasi untuk gcloud CLI

Dokumen ini hanya membahas autentikasi untuk Google Cloud CLI dalam mengakses resourceGoogle Cloud . Jika Anda perlu mengautentikasi beban kerja menggunakan Library Klien Cloud atau Library Klien Google API, lihat Cara kerja Kredensial Default Aplikasi.

Sebelum memulai

Jika Anda baru menggunakan Google Cloud dan hanya ingin mulai menggunakan perintah gcloud CLI di lingkungan pengembangan lokal, Anda dapat melakukan inisialisasi gcloud CLI dengan perintah berikut:

gcloud init

Inisialisasi akan memandu Anda melalui alur autentikasi, menyiapkan konfigurasi gcloud CLI, dan memberi otorisasi gcloud CLI untuk bertindak atas nama Anda. Tidak perlu melakukan langkah autentikasi terpisah.

Bagian lain dari dokumen ini membahas skenario yang lebih kompleks seperti menggunakan gcloud CLI dengan berbagai jenis prinsipal, metode autentikasi yang sesuai untuk lingkungan yang berbeda, mengganti prinsipal, dan mengelola kredensial yang disimpan.

Metode autentikasi

Semua perintah gcloud CLI perlu diautentikasi ke Google Cloud API. Anda dapat melakukan autentikasi dengan cara berikut:

  • Mengizinkan dan menyimpan kredensial: Cocok untuk digunakan manusia di lingkungan pengembangan lokal. Anda dapat mengizinkan gcloud CLI untuk bertindak atas nama pokok menggunakan perintah gcloud auth login. Setelah autentikasi awal, perintah ini menyimpan kredensial di direktori konfigurasi gcloud CLI. gcloud CLI menggunakan kredensial yang disimpan ini untuk melakukan autentikasi secara otomatis untuk perintah berikutnya hingga sesi Anda berakhir, atau Anda mencabut otorisasi.

  • Mengautentikasi dengan file kredensial: Cocok untuk workload yang berjalan di luar Google Cloud. Anda dapat menggunakan variabel lingkungan atau properti konfigurasi gcloud CLI untuk menentukan file kredensial untuk autentikasi otomatis. File ini dapat berupa salah satu dari berikut ini:

    • File konfigurasi kredensial Workload Identity Federation.

    • Kunci akun layanan.

  • Menyediakan token akses: Cocok untuk alur kerja otomatis yang sangat terisolasi atau sesi tanpa status di komputer bersama. Anda dapat melewati penyimpanan kredensial dengan menyediakan token akses langsung ke gcloud CLI. Anda dapat melakukannya dengan menyetel variabel lingkungan tertentu ke string token akses mentah, atau dengan mengarahkan gcloud CLI ke file yang berisi token akses.

Setelah melakukan autentikasi, Anda dapat secara opsional mengizinkan gcloud CLI meniru identitas akun layanan dengan memberikan alamat email akun layanan.

Anda dapat menggunakan beberapa metode autentikasi dalam satu lingkungan. Namun, hanya satu prinsipal yang digunakan untuk perintah gcloud tertentu. Untuk menentukan prinsipal mana yang akan digunakan, gcloud CLI mengikuti urutan prioritas.

Saat Anda tidak perlu melakukan autentikasi

Anda tidak perlu melakukan autentikasi untuk gcloud CLI dalam situasi berikut:

  • Segera setelah Anda melakukan inisialisasi gcloud CLI. Autentikasi dan otorisasi disertakan dalam proses inisialisasi. Anda mungkin masih perlu melakukan autentikasi lagi jika Anda perlu mengakses resource yang berbeda menggunakan principal yang berbeda, atau jika Anda perlu melakukan autentikasi ulang principal Anda.
  • Saat menggunakan gcloud CLI dari resource yang mengekspos server metadata Compute Engine. Hal ini mencakup resource seperti instance VM Compute Engine, layanan Cloud Run, dan build Cloud Build. Gcloud CLI melakukan autentikasi menggunakan akun layanan yang terpasang ke VM, dan diizinkan untuk mengakses resource yang sama dengan akun layanan tersebut dalam batas cakupan akses yang telah diterapkan.
  • Saat menggunakan Cloud Shell. gcloud CLI otomatis melakukan autentikasi menggunakan prinsipal yang Anda gunakan untuk login ke konsol Google Cloud . Saat Anda menjalankan perintah gcloud CLI untuk pertama kalinya dalam sesi Cloud Shell baru, Anda akan diminta untuk memberi otorisasi Cloud Shell menggunakan prinsipal tersebut.

Pilih principal yang tepat untuk tugas tersebut

Ada berbagai jenis akun utama untuk penggunaan manusia dan workload otomatis. Jenis akun utama yang perlu Anda gunakan memengaruhi cara Anda melakukan autentikasi.

  • Akun pengguna: Akun ini adalah Akun Google yang ditujukan bagi manusia untuk melakukan pekerjaan interaktif, seperti tugas administratif insidental, konfigurasi layanan non-terprogram, pengujian, eksperimen, dan kemampuan observasi. Google Cloud

    Anda mengautentikasi sebagai akun pengguna dengan kredensial pengguna, seperti sandi dan kode sekali pakai.

  • Akun layanan: Ini adalah akun khusus untuk Google Cloud beban kerja yang dapat digunakan untuk mengakses layanan atau resource. Biasanya, Anda tidak melakukan autentikasi sebagai akun layanan secara langsung. Sebagai gantinya, Anda melampirkan akun layanan ke resource seperti VM Compute Engine, atau menggunakan peniruan identitas akun layanan.

  • Akun utama gabungan: Ini adalah identitas yang mereferensikan akun pengguna atau layanan di penyedia identitas eksternal. Ada dua jenis akun utama gabungan yang didukung oleh Google Cloud, yang memiliki nama serupa:

Menggunakan gcloud CLI sebagai pengguna

Untuk tugas interaktif, Anda biasanya melakukan autentikasi dengan salah satu cara berikut:

  • Akun pengguna

  • Identitas pengguna gabungan, menggunakan Workforce Identity Federation

Akun pengguna

Cara Anda melakukan autentikasi dengan akun pengguna untuk gcloud CLI bergantung pada apakah browser web diinstal di perangkat Anda.

Perangkat saya memiliki browser web

Untuk mengautentikasi dengan akun pengguna di perangkat dengan browser web, selesaikan langkah-langkah berikut:

  1. Jalankan perintah berikut untuk memulai proses:

    gcloud auth login

  2. Ikuti alur berbasis browser untuk mengautentikasi dan memberi otorisasi gcloud CLI agar dapat mengakses resource atas nama Anda untuk perintah di masa mendatang.

Perintah gcloud auth login menyimpan kredensial akses di direktori beranda Anda. Principal yang diautentikasi menjadi principal aktif dalam konfigurasi gcloud CLI aktif Anda. Kecuali diganti, gcloud CLI menggunakan kredensial tersimpan ini untuk mengakses Google Cloud.

Perangkat saya tidak memiliki browser web

Jika perangkat yang Anda gunakan untuk menjalankan gcloud CLI tidak memiliki browser web, Anda dapat melakukan autentikasi dengan akun pengguna Anda di perangkat tepercaya lainnya. Proses ini berubah, bergantung pada software yang diinstal di perangkat tepercaya lainnya.

Mengautentikasi menggunakan perangkat tepercaya lain

Pilih software yang tersedia di perangkat tepercaya lainnya.

gcloud CLI dan browser web

Gunakan flag --no-browser untuk menyelesaikan proses autentikasi di perangkat lain dengan browser web dan gcloud CLI yang diinstal:

  1. Jalankan perintah berikut di perangkat asli yang ingin Anda gunakan untuk menjalankan gcloud CLI:

    Linux and macOS 

    gcloud auth login \
    --no-browser

    Windows (PowerShell) 

    gcloud auth login `
    --no-browser

  2. Salin perintah gcloud yang dimulai dengan gcloud auth login --remote-bootstrap=" untuk digunakan di perangkat lain.

  3. Buka perangkat tepercaya lain yang memiliki browser web dan gcloud CLI versi 372.0.0 atau yang lebih baru.

  4. Di terminal, jalankan perintah yang Anda salin sebelumnya yang dimulai dengan gcloud auth login --remote-bootstrap=", dan selesaikan alur berbasis browser.

  5. Di terminal, salin URL yang dimulai dengan https://localhost untuk digunakan di perangkat asli.

  6. Kembali ke perangkat asli.

  7. Di terminal, pada perintah, tempelkan URL https://localhost yang Anda salin sebelumnya. Tekan Enter atau Return di keyboard Anda untuk menyelesaikan proses.

Perintah gcloud auth login menyimpan kredensial akses di direktori beranda Anda. Principal yang diautentikasi menjadi principal aktif dalam konfigurasi gcloud CLI aktif Anda. Kecuali diganti, gcloud CLI menggunakan kredensial tersimpan ini untuk mengakses Google Cloud.

Khusus browser web

Gunakan tanda --no-launch-browser untuk menyelesaikan proses autentikasi menggunakan browser web perangkat lain:

  1. Jalankan perintah berikut di perangkat asli yang ingin Anda gunakan untuk menjalankan gcloud CLI:

    Linux and macOS 

    gcloud auth login \
    --no-launch-browser

    Windows (PowerShell) 

    gcloud auth login `
    --no-launch-browser

  2. Salin URL yang diawali dengan https://accounts.google.com/o/oauth2/auth untuk digunakan di perangkat lain.

  3. Buka perangkat tepercaya lain yang telah menginstal browser web.

  4. Buka browser web, buka URL yang Anda salin sebelumnya, dan selesaikan alur berbasis browser.

  5. Salin kode verifikasi untuk digunakan di perangkat asli.

  6. Kembali ke perangkat asli.

  7. Di terminal, pada perintah, tempelkan kode verifikasi yang Anda salin sebelumnya. Tekan Enter atau Return di keyboard Anda untuk menyelesaikan proses.

Perintah gcloud auth login menyimpan kredensial akses di direktori beranda Anda. Principal yang diautentikasi menjadi principal aktif dalam konfigurasi gcloud CLI aktif Anda. Kecuali diganti, gcloud CLI menggunakan kredensial tersimpan ini untuk mengakses Google Cloud.

Identitas pengguna gabungan

Anda dapat menggunakan gcloud CLI dengan identitas pengguna gabungan yang dikelola di penyedia identitas (IdP) eksternal. Anda dapat melakukannya dengan Workforce Identity Federation.

Petunjuk berikut mengasumsikan bahwa Anda telah menyiapkan pool dan penyedia Workforce Identity Federation agar berfungsi dengan IdP Anda.

Untuk menggunakan gcloud CLI dengan identitas pengguna gabungan, Anda membuat file konfigurasi login, lalu login menggunakan alur berbasis browser:

  1. Jalankan perintah berikut untuk membuat file konfigurasi login:

    Linux and macOS

    gcloud iam workforce-pools create-login-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --output-file=LOGIN_CONFIG_PATH

    Windows (PowerShell)

    gcloud iam workforce-pools create-login-config `
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID `
    --output-file=LOGIN_CONFIG_PATH

    Ganti kode berikut:

    • WORKFORCE_POOL_ID: ID pool Workforce Identity Federation.
    • WORKFORCE_PROVIDER_ID: ID penyedia Workforce Identity Federation.
    • LOGIN_CONFIG_PATH: Jalur untuk menulis file konfigurasi login ke. Contoh, login-config.json.

    File konfigurasi login berisi endpoint yang digunakan oleh gcloud CLI untuk mengaktifkan alur autentikasi berbasis browser dan menetapkan audience ke IdP yang dikonfigurasi di penyedia workforce identity pool. File tidak berisi informasi rahasia.

    Konten file konfigurasi login akan terlihat seperti berikut:

    {
  "universe_domain": "googleapis.com",
  "universe_cloud_web_domain": "cloud.google",
  "type": "external_account_authorized_user_login_config",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "auth_url": "https://auth.cloud.google/authorize",
  "token_url": "https://sts.googleapis.com/v1/oauthtoken",
  "token_info_url": "https://sts.googleapis.com/v1/introspect"
}

  2. Arahkan ke file konfigurasi login dengan variabel lingkungan, properti dalam konfigurasi gcloud CLI aktif, atau gunakan secara langsung dengan perintah gcloud auth login:

    Variabel lingkungan

    Untuk menggunakan file konfigurasi login dengan variabel lingkungan, selesaikan petunjuk berikut:

    1. Tetapkan variabel lingkungan CLOUDSDK_AUTH_LOGIN_CONFIG_FILE ke jalur file konfigurasi login.

    2. Jalankan perintah berikut:

      gcloud auth login
    3. gcloud CLI mereferensikan variabel lingkungan untuk menemukan file konfigurasi login, lalu memulai proses autentikasi. Ikuti alur berbasis browser untuk mengautentikasi dan mengizinkan gcloud CLI mengakses resource atas nama Anda untuk perintah mendatang.

    Untuk berhenti menggunakan file konfigurasi login untuk perintah gcloud auth login, hapus variabel lingkungan CLOUDSDK_AUTH_LOGIN_CONFIG_FILE.

    Konfigurasi gcloud CLI

    Untuk menggunakan file konfigurasi login dengan properti konfigurasi gcloud CLI, selesaikan petunjuk berikut:

    1. Tetapkan properti auth/login_config_file konfigurasi gcloud CLI aktif ke jalur file konfigurasi login dengan perintah berikut: 

      gcloud config set auth/login_config_file LOGIN_CONFIG_PATH

    2. Jalankan perintah berikut:

      gcloud auth login
    3. gcloud CLI mereferensikan properti konfigurasi untuk menemukan file konfigurasi login, lalu memulai proses autentikasi. Ikuti alur berbasis browser untuk mengautentikasi dan mengizinkan gcloud CLI mengakses resource atas nama Anda untuk perintah mendatang.

    Untuk berhenti menggunakan file konfigurasi login untuk perintah gcloud auth login, hapus setelan properti dengan perintah berikut: 

    gcloud config unset auth/login_config_file

    gcloud auth login

    Untuk menggunakan file konfigurasi login secara langsung dengan perintah gcloud auth login, selesaikan petunjuk berikut:

    • Jika Anda menggunakan flag --activate saat membuat file konfigurasi login, jalankan perintah berikut: 

      gcloud auth login

    • Jika Anda tidak menggunakan flag --activate saat membuat file konfigurasi login, jalankan perintah berikut:

      Linux and macOS

      gcloud auth login \
    --login-config=LOGIN_CONFIG_PATH

      Windows (PowerShell)

      gcloud auth login `
    --login-config=LOGIN_CONFIG_PATH

      Ganti LOGIN_CONFIG_PATH dengan jalur file konfigurasi login Anda.

    Perintah gcloud auth login menyimpan kredensial akses di direktori beranda Anda. Principal yang diautentikasi menjadi principal aktif dalam konfigurasi gcloud CLI aktif Anda. Kecuali diganti, gcloud CLI menggunakan kredensial tersimpan ini untuk mengakses Google Cloud.

Menggunakan gcloud CLI dengan workload

Untuk workload otomatis, Anda biasanya melakukan autentikasi dengan salah satu hal berikut:

  • Identitas beban kerja gabungan, menggunakan Workload Identity Federation

  • Akun layanan, menggunakan peniruan

Identitas workload gabungan

Anda dapat menggunakan gcloud CLI dengan workload identity gabungan. Anda melakukannya dengan Workload Identity Federation.

Workload dapat mengakses Google Cloud resource secara langsung dengan bertindak sebagai akun utama yang ditentukan oleh workload identity pool, atau meniru identitas akun layanan yang terlampir ke workload identity pool.

Sebaiknya gunakan metode akses langsung untuk menghindari akun layanan dengan hak istimewa berlebih, dan untuk mencatat akses resource menggunakan ID prinsipal gabungan. Hanya gunakan peniruan akun layanan jika Google Cloud API tidak mendukung Workload Identity Federation.

Petunjuk berikut mengasumsikan bahwa Anda telah menyiapkan pool dan penyedia Workload Identity Federation agar berfungsi dengan IdP Anda.

  1. Buat file konfigurasi kredensial untuk Workload Identity Federation dengan mengikuti petunjuk untuk penyedia identitas yang didukung.

  2. Tentukan jalur ke file konfigurasi kredensial dalam variabel lingkungan, sebagai properti dalam konfigurasi gcloud CLI aktif, atau dengan perintah gcloud auth login:

    Variabel lingkungan

    Tetapkan variabel lingkungan CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE ke jalur file konfigurasi kredensial. gcloud CLI mereferensikan file setiap kali menjalankan perintah, dan mendapatkan kredensial dari IdP Anda. Kredensial ini ditukar dengan token akses ke Google Cloud.

    Untuk berhenti menggunakan file konfigurasi kredensial, hapus variabel lingkungan CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

    Konfigurasi gcloud CLI

    Tetapkan properti auth/credential_file_override konfigurasi gcloud CLI aktif ke jalur file konfigurasi kredensial dengan perintah berikut:

    gcloud config set auth/credential_file_override CONFIGURATION_PATH

    Ganti CONFIGURATION_PATH dengan jalur ke file konfigurasi kredensial.

    Untuk berhenti menggunakan file konfigurasi kredensial secara default untuk perintah gcloud, hapus setelan properti dengan perintah berikut:

    gcloud config unset auth/credential_file_override

    gcloud auth login

    Jalankan perintah berikut menggunakan flag --cred-file:

    Linux and macOS 

    gcloud auth login \
    --cred-file=CONFIGURATION_PATH

    Windows (PowerShell) 

    gcloud auth login `
    --cred-file=CONFIGURATION_PATH

    Ganti CONFIGURATION_PATH dengan jalur ke file konfigurasi kredensial.

    Perintah gcloud auth login menyimpan kredensial akses di direktori beranda Anda. Principal yang diautentikasi menjadi principal aktif dalam konfigurasi gcloud CLI aktif Anda. Kecuali diganti, gcloud CLI menggunakan kredensial tersimpan ini untuk mengakses Google Cloud.

Akun layanan

Anda dapat menggunakan gcloud CLI dengan akun layanan dengan cara berikut:

  • Pada resource yang mengekspos server metadata Compute Engine, seperti instance VM Compute Engine atau layanan Cloud Run. gcloud CLI menggunakan akun layanan apa pun yang terpasang ke resource untuk melakukan autentikasi secara default.

  • Dengan menggunakan akun utama lain untuk meniru identitas akun layanan.

  • Dengan menggunakan kunci akun layanan.

Peniruan akun layanan

Untuk akses resource yang biasanya tidak tersedia untuk akun utama Anda, sebaiknya kelola eskalasi akses dengan Privileged Access Manager, bukan menggunakan peniruan akun layanan.

Jika Privileged Access Manager tidak sesuai dengan kasus penggunaan Anda, selesaikan langkah-langkah berikut untuk menggunakan gcloud CLI dengan akun layanan:

  1. Untuk meniru identitas akun layanan, pastikan Service Account Credentials API diaktifkan di project Anda.

    Peran yang diperlukan untuk mengaktifkan API

    Untuk mengaktifkan API, Anda memerlukan peran IAM Service Usage Admin (roles/serviceusage.serviceUsageAdmin), yang berisi izin serviceusage.services.enable. Pelajari cara memberikan peran.

    Mengaktifkan API

  2. Pilih akun utama yang akan digunakan untuk meniru identitas akun layanan.

  3. Untuk memastikan akun utama memiliki izin yang diperlukan untuk meniru akun layanan, minta administrator Anda untuk memberikan peran IAM Service Account Token Creator (roles/iam.serviceAccountTokenCreator) kepada akun utama di akun layanan. Untuk mengetahui informasi selengkapnya tentang cara memberikan peran, lihat Mengelola akses ke project, folder, dan organisasi.

    Peran bawaan ini berisi izin iam.serviceAccounts.getAccessToken , yang diperlukan untuk meniru akun layanan.

    Administrator Anda mungkin juga dapat memberi akun utama izin ini dengan peran khusus atau peran bawaan lainnya.

  4. Lakukan autentikasi untuk gcloud CLI dengan akun utama yang Anda pilih sebelumnya, baik akun pengguna, identitas pengguna gabungan, identitas beban kerja gabungan, atau akun layanan lain.

  5. Pilih akun layanan yang akan ditiru. Temukan akun layanan yang ada, atau buat akun layanan baru.

  6. Salin alamat Email akun layanan.

  7. Pilih apakah akan meniru akun layanan untuk semua perintah, atau hanya satu perintah:

    Semua perintah

    Untuk menggunakan peniruan akun layanan dengan gcloud CLI untuk perintah mendatang, Anda dapat menyetel variabel lingkungan, atau menyetel properti dalam konfigurasi gcloud CLI aktif:

    • Variabel lingkungan: Tetapkan variabel lingkungan CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT ke alamat email akun layanan.

      Untuk berhenti menggunakan akun layanan, hapus variabel lingkungan CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT.

    • Konfigurasi gcloud CLI: Tetapkan properti auth/impersonate_service_account konfigurasi gcloud CLI aktif dengan perintah berikut:

      gcloud config set auth/impersonate_service_account SERVICE_ACCOUNT_EMAIL

      Ganti SERVICE_ACCOUNT_EMAIL dengan alamat email akun layanan.

      Untuk berhenti menggunakan peniruan akun layanan secara default untuk perintah gcloud, hapus setelan properti dengan perintah berikut:

      gcloud config unset auth/impersonate_service_account

    Perintah tunggal

    Untuk menggunakan peniruan akun layanan dengan gcloud CLI untuk satu perintah, Anda dapat menambahkan flag --impersonate-service-account ke perintah layanan gcloud CLI.

    Misalnya, untuk mencantumkan instance VM Compute Engine menggunakan peniruan akun layanan, jalankan perintah berikut:

    Linux and macOS 

    gcloud compute instances list \
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

    Windows (PowerShell) 

    gcloud compute instances list `
    --impersonate-service-account=SERVICE_ACCOUNT_EMAIL

    Ganti SERVICE_ACCOUNT_EMAIL dengan alamat email akun layanan.

Kunci akun layanan

Sebaiknya gunakan Workload Identity Federation untuk sebagian besar workload yang berjalan di luar Google Cloud. Gunakan kunci akun layanan hanya jika workload Anda berjalan di lingkungan eksternal yang terisolasi dan tidak mendukung Workload Identity Federation.

Workload Identity Federation menawarkan keuntungan berikut:

  • Akses ke resource diberikan melalui Identity and Access Management (IAM), dengan beban kerja diperlakukan sebagai akun utama individual. Artinya, Anda tidak perlu memberikan izin berlebih pada akun layanan untuk beberapa kasus penggunaan.

  • Anda dapat mengaudit beban kerja yang menjalankan tugas apa; tindakan tidak disembunyikan di balik alamat email akun layanan.

  • Workload Identity Federation menggunakan token akses berumur pendek untuk mengurangi risiko pemindahan data yang tidak sah. Masa berlaku kunci akun layanan tidak akan berakhir kecuali jika dicabut secara manual.

Untuk menggunakan akun layanan dengan gcloud CLI untuk perintah mendatang, lakukan hal berikut:

  1. Buat kunci akun layanan, lalu simpan sebagai file di lokasi yang aman di lingkungan Anda.

  2. Tentukan jalur ke file kunci akun layanan dalam variabel lingkungan, sebagai properti dalam konfigurasi gcloud CLI aktif, atau dengan perintah gcloud auth login:

    • Variabel lingkungan: Tetapkan variabel lingkungan CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE ke jalur file kunci akun layanan.

      Untuk berhenti menggunakan kunci akun layanan, hapus variabel lingkungan CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

    • Konfigurasi gcloud CLI: Tetapkan properti auth/credential_file_override konfigurasi gcloud CLI aktif ke jalur kunci akun layanan dengan perintah berikut:

      gcloud config set auth/credential_file_override KEY_PATH

      Ganti KEY_PATH dengan jalur ke file kunci akun layanan.

      Untuk berhenti menggunakan kunci akun layanan secara default untuk perintah gcloud, hapus setelan properti dengan perintah berikut:

      gcloud config unset auth/credential_file_override

    • gcloud auth login: Jalankan perintah berikut menggunakan flag --cred-file:

      Linux and macOS 

      gcloud auth login \
    --cred-file=KEY_PATH

      Windows (PowerShell) 

      gcloud auth login `
    --cred-file=KEY_PATH

      Ganti KEY_PATH dengan jalur ke file kunci akun layanan.

      Perintah gcloud auth login menyimpan kredensial akses di direktori beranda Anda. Principal yang diautentikasi menjadi principal aktif dalam konfigurasi gcloud CLI aktif Anda. Kecuali diganti, gcloud CLI menggunakan kredensial tersimpan ini untuk mengakses Google Cloud.

Menggunakan gcloud CLI dengan token akses

Jika Anda telah melakukan autentikasi untuk gcloud CLI di perangkat lain, Anda dapat memperoleh token akses untuk principal aktif perangkat tersebut dengan perintah berikut:

gcloud auth print-access-token

Kemudian, Anda dapat menggunakan token akses ini di perangkat lain untuk mengakses Google Cloud resource. Penggunaan token akses menghilangkan kebutuhan untuk menetapkan pokok aktif, dan menggantikan pokok aktif yang ditetapkan dalam konfigurasi gcloud CLI aktif.

Token akses untuk akun pengguna memiliki masa berlaku default satu jam.

Anda dapat menggunakan token akses dengan gcloud CLI untuk perintah mendatang, atau hanya satu perintah.

Semua perintah

Untuk menggunakan token akses dengan gcloud CLI untuk perintah mendatang, Anda dapat menetapkan variabel lingkungan, atau menetapkan properti dalam konfigurasi gcloud CLI aktif:

  • Variabel lingkungan: Tetapkan variabel lingkungan CLOUDSDK_AUTH_ACCESS_TOKEN ke string token akses.

    Untuk berhenti menggunakan token akses, hapus variabel lingkungan CLOUDSDK_AUTH_ACCESS_TOKEN.

  • Konfigurasi gcloud CLI: Simpan token akses dalam file, lalu tetapkan properti auth/access_token_file konfigurasi gcloud CLI aktif ke jalur file dengan perintah berikut:

    gcloud config set auth/access_token_file ACCESS_TOKEN_PATH

    Ganti ACCESS_TOKEN_PATH dengan jalur ke file token akses.

    Untuk berhenti menggunakan token akses secara default untuk perintah gcloud, hapus setelan properti dengan perintah berikut:

    gcloud config unset auth/access_token_file

Perintah tunggal

Untuk menggunakan token akses dengan gcloud CLI untuk satu perintah, Anda dapat menambahkan flag --access-token-file ke perintah layanan gcloud CLI:

  1. Simpan token akses dalam file.

  2. Gunakan flag --access-token-file dengan perintah layanan gcloud apa pun.

    Misalnya, untuk mencantumkan instance VM Compute Engine menggunakan token akses, jalankan perintah berikut:

    Linux and macOS 

    gcloud compute instances list \
    --access-token-file ACCESS_TOKEN_PATH

    Windows (PowerShell) 

    gcloud compute instances list `
    --access-token-file ACCESS_TOKEN_PATH

    Ganti ACCESS_TOKEN_PATH dengan jalur ke file token akses.

Prioritas kredensial

Karena beberapa metode autentikasi dapat digunakan dalam satu lingkungan, gcloud CLI mengevaluasi metode dalam urutan tertentu untuk menentukan pokok yang akan digunakan. gcloud CLI dimulai dengan kredensial yang diberikan, lalu menilai apakah peniruan akun layanan telah diminta.

Urutan evaluasi untuk kredensial yang diberikan adalah sebagai berikut:

  1. Variabel lingkungan CLOUDSDK_AUTH_ACCESS_TOKEN, ditetapkan ke string token akses.

  2. Mengakses file token akses. Metode yang digunakan untuk menentukan jalur file token akses dievaluasi dalam urutan berikut:

    1. Flag command line --access-token-file, yang digunakan dengan perintah gcloud CLI apa pun.

    2. Variabel lingkungan CLOUDSDK_AUTH_ACCESS_TOKEN_FILE.

    3. Properti auth/access_token_file dalam konfigurasi gcloud CLI yang aktif.

  3. File kredensial. Metode yang digunakan untuk menentukan jalur file kredensial dievaluasi dalam urutan berikut:

    1. Variabel lingkungan CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE.

    2. Properti auth/credential_file_override dalam konfigurasi gcloud CLI aktif.

  4. Principal aktif yang ditetapkan oleh perintah gcloud auth login, atau dengan menetapkan properti core/account.

Prioritas peniruan akun layanan

Jika peniruan identitas akun layanan telah diminta, gcloud CLI akan memeriksa akun layanan mana yang akan ditiru identitasnya setelah kredensial diberikan untuk akun utama yang melakukan peniruan identitas. Metode yang digunakan untuk menentukan akun layanan untuk peniruan identitas dievaluasi dalam urutan berikut:

  1. Tanda command line --impersonate-service-account.

  2. Variabel lingkungan CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT.

  3. Akun layanan yang ditentukan oleh properti auth/impersonate_service_account dalam konfigurasi aktif.

Menambahkan Google Drive ke cakupan Anda

Cakupan gcloud CLI dapat diperluas untuk menyertakan akses Google Drive selain Google Cloud. Artinya, Anda dapat menggunakan Google Cloud token akses dengan Google Drive.

Untuk memperluas cakupan agar menyertakan Google Drive, Anda menambahkan flag --enable-gdrive-access saat mengizinkan gcloud CLI:

Linux and macOS 

gcloud auth login \
    --enable-gdrive-access

Windows (PowerShell) 

gcloud auth login `
    --enable-gdrive-access

Kemudian, Anda dapat melakukan panggilan ke Google Drive API menggunakan gcloud CLI untuk memberikan token akses. Misalnya, untuk mencantumkan semua file di Google Drive Anda, Anda dapat membuat permintaan berikut:

Linux and macOS 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files"

Windows (PowerShell) 

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files" | Select-Object -Expand Content

Kemudian, misalnya, Anda dapat menggunakan ID file dari respons perintah sebelumnya untuk mengekstrak teks dari file Google Dokumen:

Linux and macOS 

curl -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain"

Windows (PowerShell) 

Invoke-WebRequest `
  -Method GET `
  -Headers @{ "Authorization" = "Bearer $(gcloud auth print-access-token)" } `
  -ContentType "application/json; charset=utf-8" `
  -UseBasicParsing `
  -Uri "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=text/plain" | Select-Object -Expand Content

Kasus penggunaan umum untuk akses Google Drive adalah menggunakan BigQuery dengan data yang disimpan di Google Spreadsheet.

Untuk mempelajari Google Drive API lebih lanjut, lihat Ringkasan Google Drive API.

Menambahkan gcloud CLI sebagai helper kredensial ke Docker

Untuk menarik dari registry container Artifact Registry, Anda dapat menambahkan gcloud CLI sebagai pembantu kredensial ke konfigurasi Docker Anda.

Untuk melakukannya, jalankan perintah gcloud auth configure-docker:

gcloud auth configure-docker REGION-docker.pkg.dev

Mengelola prinsipal dan kredensial

Anda dapat menggunakan perintah gcloud auth login untuk mengautentikasi beberapa prinsipal di lingkungan yang sama, dan mengizinkan gcloud CLI mengakses resource atas nama mereka. Namun, hanya satu prinsipal yang dapat aktif kapan saja. Bagian berikut membahas cara mengelola prinsipal dalam konfigurasi gcloud CLI, termasuk mencantumkannya, beralih di antara prinsipal, dan mencabut kredensialnya.

Mencantumkan akun utama

Untuk mencantumkan prinsipal yang kredensial aksesnya disimpan di sistem lokal (yaitu, yang telah diautentikasi menggunakan gcloud auth login), jalankan perintah gcloud auth list:

gcloud auth list

gcloud CLI mencantumkan principal dan menunjukkan principal mana yang aktif:

Credentialed Accounts
ACTIVE  ACCOUNT
        alex@altostrat.com
*       bola@altostrat.com
        principal://iam.googleapis.com/locations/global/workforcePools/POOL_ID/subject/cruz@cymbalgroup.com

Penggantian untuk prinsipal aktif tidak disertakan dalam daftar ini. Penggantian ini mencakup variabel lingkungan berikut:

  • CLOUDSDK_AUTH_ACCESS_TOKEN
  • CLOUDSDK_AUTH_CREDENTIAL_FILE_OVERRIDE
  • CLOUDSDK_AUTH_IMPERSONATE_SERVICE_ACCOUNT

Untuk memeriksa apakah variabel lingkungan ini sudah ditetapkan, jalankan perintah berikut untuk sistem operasi Anda:

Linux and macOS 

echo "$ENVIRONMENT_VARIABLE"

Windows (PowerShell) 

echo $env:ENVIRONMENT_VARIABLE

Ganti ENVIRONMENT_VARIABLE dengan variabel lingkungan yang ingin Anda periksa.

Penggantian untuk prinsipal aktif juga mencakup properti konfigurasi berikut:

  • auth/access_token_file
  • auth/credential_file_override
  • auth/impersonate_service_account

Untuk memeriksa apakah properti konfigurasi ini ditetapkan, jalankan perintah berikut:

gcloud config list

Mengubah prinsipal aktif

Untuk beralih ke principal aktif yang telah menyimpan kredensial (yaitu, mereka sebelumnya menyelesaikan alur gcloud auth login), jalankan gcloud config set:

gcloud config set account PRINCIPAL_IDENTIFIER

Ganti PRINCIPAL_IDENTIFIER dengan ID lengkap principal.

Anda juga dapat mengganti akun utama dengan cara berikut:

Menyetel durasi sesi

Administrator dapat mengontrol durasi akses gcloud CLI bagi setiap pengguna tanpa harus melakukan autentikasi ulang. Misalnya, Anda dapat mewajibkan pengguna dengan hak istimewa yang ditingkatkan untuk melakukan autentikasi ulang lebih sering daripada pengguna reguler.

Untuk mengetahui informasi selengkapnya, lihat Menetapkan durasi sesi untuk Google Cloud layanan.

Mencabut kredensial untuk akun utama

Anda dapat mencabut kredensial untuk prinsipal yang telah melakukan autentikasi dengan gcloud auth login sehingga gcloud CLI tidak dapat bertindak atas nama mereka. Pencabutan membatalkan validitas kredensial di server otorisasi Google, dan menghapus prinsipal dari konfigurasi gcloud CLI aktif.

Untuk mencabut kredensial, jalankan gcloud auth revoke:

gcloud auth revoke PRINCIPAL_IDENTIFIER

Ganti PRINCIPAL_IDENTIFIER dengan ID lengkap principal.

Untuk mencabut akses gcloud CLI di semua perangkat yang terkait dengan Akun Google Anda, buka Aplikasi & layanan pihak ketiga di setelan Akun Google Anda, lalu hapus semua koneksi dengan Google Cloud SDK.

Mengelola kredensial tersimpan

gcloud CLI menyimpan file kredensial yang digunakannya di direktori konfigurasi gcloud CLI. Untuk menemukan lokasi file kredensial, jalankan gcloud info:

gcloud info

gcloud CLI mencetak informasi tentang penginstalan Anda. File kredensial disimpan di User Config Directory yang ditentukan dalam output:

User Config Directory: [/home/USERNAME/.config/gcloud]

Untuk Linux dan macOS, direktori konfigurasi gcloud CLI biasanya adalah /home/USERNAME/.config/gcloud. Untuk Windows, ini adalah %APPDATA%\gcloud.

Langkah berikutnya