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 penggunaan gcloud CLI dengan berbagai jenis prinsipal, metode autentikasi yang sesuai untuk lingkungan yang berbeda, penggantian prinsipal, dan pengelolaan kredensial yang disimpan.

Metode autentikasi

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

• Memberi otorisasi dan menyimpan kredensial: Cocok untuk digunakan manusia di lingkungan pengembangan lokal. Anda dapat mengizinkan gcloud CLI untuk bertindak atas nama prinsipal 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 guna melakukan autentikasi otomatis. File ini dapat berupa salah satu dari berikut:

  • File konfigurasi kredensial Workload Identity Federation.

  • Kunci akun layanan.

• Menyediakan token akses: Cocok untuk alur kerja otomatis yang sangat terisolasi atau sesi stateless di mesin bersama. Anda dapat melewati penyimpanan kredensial dengan memberikan token akses langsung ke gcloud CLI. Anda dapat melakukannya dengan menetapkan 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 gcloud CLI untuk bertindak atas nama Anda disertakan dalam proses inisialisasi. Anda mungkin masih perlu melakukan autentikasi lagi jika Anda perlu mengakses resource yang berbeda menggunakan prinsipal yang berbeda, atau jika Anda perlu melakukan autentikasi ulang prinsipal 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 dapat 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:

  • Workforce Identity Federation: Memungkinkan pengguna manusia login ke Google Cloud dengan identitas yang dikelola oleh penyedia identitas eksternal. Jika organisasi Anda sudah menyiapkan single sign-on (SSO), Anda dapat menggunakan jenis identitas ini untuk mengautentikasi ke Google Cloud.

    Penyedia identitas Anda harus mendukung OpenID Connect (OIDC) atau SAML 2.0 untuk menggunakan Workforce Identity Federation.

  • Workload Identity Federation: Memungkinkan beban kerja yang berjalan di luar Google Cloud beroperasi pada resource Google Cloud .

    Anda dapat menggunakan Workload Identity Federation dengan workload yang melakukan autentikasi menggunakan sertifikat klien X.509; yang berjalan di Amazon Web Services (AWS) atau Azure; Active Directory on-premise; layanan deployment, seperti GitHub dan GitLab; dan dengan penyedia identitas apa pun yang mendukung OpenID Connect (OIDC) atau Security Assertion Markup Language (SAML) V2.0.

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.

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 Federasi Identitas Tenaga Kerja.
   • 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 identitas beban kerja 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