Memberikan otorisasi ke gcloud CLI

Untuk mengakses Google Cloud, biasanya Anda harus mengizinkan Google Cloud CLI. Halaman ini menunjukkan opsi otorisasi yang tersedia dan cara mengelola akun yang Anda gunakan untuk otorisasi. Jika Anda menggunakan instance Compute Engine atau Cloud Shell, Anda tidak perlu mengizinkan gcloud CLI.

Jenis akun

Untuk memberikan otorisasi ke gcloud CLI agar dapat mengakses Google Cloud, Anda dapat menggunakan akun pengguna atau akun layanan.

Akun pengguna adalah akun Google Cloud yang memungkinkan pengguna akhir melakukan autentikasi ke aplikasi Anda. Untuk sebagian besar kasus penggunaan umum, terutama penggunaan gcloud CLI secara interaktif, penggunaan akun pengguna adalah praktik terbaik.

Akun layanan adalah akun Google Cloud yang terkait dengan project Google Cloud Anda, bukan pengguna tertentu. Anda dapat menggunakan akun layanan bawaan yang tersedia saat menggunakan fungsi Cloud Run, App Engine, Compute Engine, atau Google Kubernetes Engine. Akun layanan direkomendasikan untuk menjalankan skrip gcloud CLI di beberapa komputer.

Memilih jenis otorisasi

Anda harus memberikan otorisasi ke Google Cloud CLI untuk mengelola resource. Google CloudGoogle Cloud CLI dan Google Cloud menggunakan OAuth2 untuk autentikasi dan otorisasi.

Pilih salah satu jenis otorisasi berikut:

Jenis Deskripsi
Akun pengguna Direkomendasikan jika Anda menggunakan gcloud CLI dari command line atau Anda menulis skrip dengan gcloud CLI untuk digunakan di satu mesin.
Akun layanan Direkomendasikan jika Anda menginstal dan menyiapkan gcloud CLI sebagai bagian dari proses deployment mesin dalam produksi, atau untuk digunakan di instance mesin virtual Compute Engine tempat semua pengguna memiliki akses ke root.

Untuk mengetahui informasi selengkapnya tentang autentikasi dan Google Cloud, lihat Ringkasan autentikasi.

Memberikan otorisasi dengan akun pengguna

Bagian ini menjelaskan cara memberikan otorisasi dengan akun pengguna.

Melakukan autentikasi dengan Akun Google

Gunakan perintah gcloud CLI berikut untuk mengizinkan akses dengan akun pengguna:

Perintah Deskripsi
gcloud init Memberikan otorisasi akses dan melakukan langkah-langkah penyiapan umum lainnya.
gcloud auth login Hanya mengizinkan akses.

Selama otorisasi, perintah ini mendapatkan kredensial akun dari Google Cloud dan menyimpannya di sistem lokal. Akun yang ditentukan akan menjadi akun aktif di konfigurasi Anda. gcloud CLI menggunakan kredensial yang disimpan untuk mengakses Google Cloud. Anda dapat memiliki sejumlah akun dengan kredensial tersimpan untuk satu penginstalan gcloud CLI, tetapi hanya satu akun yang aktif dalam satu waktu.

Jalankan gcloud init

gcloud init memberikan otorisasi akses dan melakukan langkah penyiapan umum lainnya. gcloud init menggunakan alur otorisasi berbasis web untuk mengautentikasi akun pengguna dan memberikan izin akses.

Untuk mengizinkan akses dan melakukan langkah-langkah penyiapan umum lainnya:

  1. Jalankan gcloud init:

    gcloud init

    Atau, untuk mencegah perintah membuka browser web secara otomatis:

    gcloud init --console-only

    Penggunaan flag --console-only berguna jika Anda menjalankan perintah di sistem jarak jauh menggunakan ssh dan tidak memiliki akses ke browser di sistem tersebut. Kemudian, Anda harus membuka URL yang diberikan secara manual di browser pada sistem lokal untuk menyelesaikan proses otorisasi.

  2. Ikuti alur otorisasi berbasis browser untuk mengautentikasi akun dan memberikan izin akses.

Untuk mengetahui informasi selengkapnya tentang gcloud init, lihat Menginisialisasi gcloud CLI.

Jalankan gcloud auth login

Menjalankan gcloud auth login hanya mengizinkan akun pengguna. Untuk mengizinkan akses tanpa melakukan langkah penyiapan lainnya, gunakan salah satu opsi berikut.

  • Jika Anda ingin mengotorisasi gcloud CLI di mesin dengan browser, ikuti langkah-langkah berikut.

    1. Beri otorisasi gcloud CLI:

      gcloud auth login

    2. Ikuti alur otorisasi berbasis browser untuk mengautentikasi akun dan memberikan izin akses.

  • Jika Anda ingin mengotorisasi gcloud CLI di komputer yang tidak memiliki browser dan Anda dapat menginstal gcloud CLI di komputer lain yang memiliki browser, gunakan flag --no-browser.

    1. Beri otorisasi gcloud CLI:

      gcloud auth login --no-browser

    2. Salin perintah panjang yang dimulai dengan gcloud auth login --remote-bootstrap=".

    3. Tempel dan jalankan perintah ini di command line komputer lain yang tepercaya yang memiliki penginstalan lokal browser web dan alat gcloud CLI versi 372.0 atau yang lebih baru.

    4. Salin output URL panjang dari komputer dengan browser web.

    5. Tempelkan kembali URL panjang ke mesin pertama di bagian perintah, "Enter the output of the above command", lalu tekan Enter untuk menyelesaikan otorisasi.

  • Jika Anda ingin memberi otorisasi gcloud CLI di komputer yang tidak memiliki browser dan Anda tidak dapat menginstal gcloud CLI di komputer lain yang memiliki browser, gunakan flag --no-launch-browser. Flag --no-launch-browser mencegah perintah membuka browser web secara otomatis.

    1. Beri otorisasi gcloud CLI:

      gcloud auth login --no-launch-browser

    2. Salin URL panjang yang diawali dengan https://accounts.google.com/o/oauth2/auth...

    3. Tempelkan URL ini ke browser di komputer lain yang tepercaya dan memiliki browser web.

    4. Salin kode otorisasi dari komputer dengan browser web.

    5. Tempelkan kembali kode otorisasi ke mesin pertama pada perintah, "Enter verification code", lalu tekan Enter untuk menyelesaikan otorisasi.

  • Jika Anda sudah memiliki token akses, gunakan salah satu metode berikut untuk meneruskan token akses ke gcloud CLI:

    • Simpan token akses dalam file dan tetapkan jalurnya melalui flag --access-token-file.
    • Simpan token akses dalam file dan tetapkan jalur file tersebut di properti auth/access_token_file.
    • Tetapkan variabel lingkungan CLOUDSDK_AUTH_ACCESS_TOKEN ke nilai token akses.

Mengautentikasi dengan Workforce Identity Federation

Bagian ini menjelaskan cara login ke gcloud CLI menggunakan Workforce Identity Federation.

Login berbasis browser gcloud CLI

Untuk login ke gcloud CLI menggunakan alur login berbasis browser, lakukan langkah berikut:

  1. Buat file konfigurasi login.

    Untuk membuat file konfigurasi login, jalankan perintah berikut. Secara opsional, Anda dapat mengaktifkan file sebagai default untuk gcloud CLI dengan menambahkan flag --activate. Kemudian, Anda dapat menjalankan gcloud auth login tanpa menentukan jalur file konfigurasi setiap kali. 

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

    Ganti kode berikut:

    • WORKFORCE_POOL_ID: ID workforce pool
    • PROVIDER_ID: ID penyedia
    • LOGIN_CONFIG_FILE_PATH: jalur ke file konfigurasi yang Anda tentukan—misalnya, login.json

    File ini 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.

    Outputnya terlihat mirip dengan yang berikut ini:

    {
  "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",
}

    Untuk menghentikan gcloud auth login menggunakan file konfigurasi ini secara otomatis, Anda dapat membatalkannya dengan menjalankan gcloud config unset auth/login_config_file.

  2. Login menggunakan autentikasi berbasis browser.

    Untuk mengautentikasi menggunakan autentikasi login berbasis browser, Anda dapat menggunakan salah satu metode berikut:

    • Jika Anda menggunakan flag --activate saat membuat file konfigurasi, atau jika Anda mengaktifkan file konfigurasi dengan gcloud config set auth/login_config_file, gcloud CLI akan menggunakan file konfigurasi Anda secara otomatis: 

      gcloud auth login

    • Untuk login dengan menentukan lokasi file konfigurasi, jalankan perintah berikut: 

      gcloud auth login --login-config=LOGIN_CONFIG_FILE_PATH
    • Untuk menggunakan variabel lingkungan guna menentukan lokasi file konfigurasi, tetapkan CLOUDSDK_AUTH_LOGIN_CONFIG_FILE ke jalur konfigurasi.

Untuk menghentikan penggunaan file konfigurasi login, lakukan langkah berikut:

  • Jika Anda menggunakan flag --activate saat membuat file konfigurasi, atau jika Anda mengaktifkan file konfigurasi dengan gcloud config set auth/login_config_file, Anda harus menjalankan perintah berikut untuk membatalkan penetapannya: 

    gcloud config unset auth/login_config_file
  • Hapus variabel lingkungan CLOUDSDK_AUTH_LOGIN_CONFIG_FILE, jika telah ditetapkan.

Login headless gcloud CLI

Untuk login ke gcloud CLI, menggunakan alur headless, lakukan langkah berikut:

OIDC

  1. Buat pengguna login ke aplikasi IdP Anda dan dapatkan token OIDC.

    Untuk mengetahui informasi tentang cara mendapatkan token, lihat dokumentasi OIDC IdP Anda.

  2. Simpan token OIDC yang ditampilkan oleh IdP di lokasi yang aman pada komputer lokal Anda.

  3. Buat file konfigurasi dengan menjalankan perintah berikut:

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID \
    --subject-token-type="urn:ietf:params:oauth:token-type:id_token" \
    --credential-source-file="PATH_TO_OIDC_ID_TOKEN" \
    --workforce-pool-user-project="WORKFORCE_POOL_USER_PROJECT" \
    --output-file="config.json"

Ganti kode berikut:

  • WORKFORCE_POOL_ID: ID workforce pool
  • PROVIDER_ID: ID penyedia
  • PATH_TO_OIDC_TOKEN: jalur ke file kredensial IdP OIDC
  • WORKFORCE_POOL_USER_PROJECT: nomor project yang terkait dengan project pengguna workforce pool

Akun utama harus memiliki izin serviceusage.services.use di project ini.

Saat Anda menjalankan perintah, file konfigurasi IdP OIDC akan dihasilkan dengan format seperti berikut:

{
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
  "token_url": "https://sts.googleapis.com/v1/token",
  "workforce_pool_user_project": "WORKFORCE_POOL_USER_PROJECT",
  "credential_source": {
    "file": "PATH_TO_OIDC_CREDENTIALS_FILE"
  }
}

SAML

  1. Buat pengguna login ke aplikasi IdP Anda dan dapatkan pernyataan SAML.

    Untuk mengetahui informasi tentang cara mendapatkan pernyataan SAML dari IdP Anda, lihat dokumentasi SAML IdP Anda.

  2. Simpan respons SAML yang ditampilkan oleh IdP di lokasi yang aman di komputer lokal Anda, lalu simpan jalurnya, sebagai berikut:

    SAML_ASSERTION_PATH=SAML_ASSERTION_PATH

  3. Untuk membuat file konfigurasi, jalankan perintah berikut:

    gcloud iam workforce-pools create-cred-config \
    locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID \
    --subject-token-type="urn:ietf:params:oauth:token-type:saml2" \
    --credential-source-file="SAML_ASSERTION_PATH"  \
    --workforce-pool-user-project="PROJECT_ID"  \
    --output-file="config.json"

    Ganti kode berikut:

    • WORKFORCE_PROVIDER_ID: ID penyedia workforce yang Anda buat sebelumnya dalam panduan ini.
    • WORKFORCE_POOL_ID: ID workforce pool yang Anda buat sebelumnya dalam panduan ini.
    • SAML_ASSERTION_PATH: jalur file pernyataan SAML.
    • PROJECT_ID: project ID

    File konfigurasi yang dihasilkan terlihat mirip dengan berikut:

    {
  "type": "external_account",
  "audience": "//iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/providers/WORKFORCE_PROVIDER_ID",
  "subject_token_type": "urn:ietf:params:oauth:token-type:saml2",
  "token_url": "https://sts.googleapis.com/v1/token",
  "credential_source": {
    "file": "SAML_ASSERTION_PATH"
  },
  "workforce_pool_user_project": "PROJECT_ID"
}

Untuk login ke gcloud menggunakan pertukaran token, jalankan perintah berikut:

gcloud auth login --cred-file="config.json"

gcloud kemudian secara transparan menukar kredensial IdP Anda dengan token akses Google Cloud sementara, sehingga Anda dapat melakukan panggilan gcloud lainnya ke Google Cloud.

Outputnya mirip dengan hal berikut ini:

Authenticated with external account user credentials for:
[principal://iam.googleapis.com/locations/global/workforcePools/WORKFORCE_POOL_ID/subject/USER_ID].

Untuk mencantumkan akun berkredensial dan akun Anda yang saat ini aktif, jalankan perintah berikut:

gcloud auth list

Memberikan otorisasi dengan akun layanan

Perintah gcloud auth login dapat mengizinkan akses dengan akun layanan menggunakan file kredensial yang disimpan di sistem file lokal Anda. Kredensial ini dapat berupa kredensial pengguna dengan izin untuk meniru identitas akun layanan, file konfigurasi kredensial untuk Gabungan Workload Identity, atau kunci akun layanan.

Memberikan otorisasi akun layanan menggunakan peniruan akun layanan

Untuk memberi otorisasi gcloud CLI agar menggunakan kredensial akun layanan yang ditiru identitasnya, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman Akun Layanan.

    Buka Akun Layanan

  2. Pilih akun yang ada atau buat akun baru dengan mengklik Buat akun layanan.

  3. Untuk mendapatkan izin yang diperlukan untuk meniru akun layanan, minta administrator untuk memberi Anda peran IAM Service Account Token Creator (roles/iam.serviceAccountTokenCreator) 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.

    Anda mungkin juga bisa mendapatkan izin ini dengan peran khusus atau peran bawaan lainnya.

  4. Beri otorisasi gcloud CLI dengan identitas pengguna Anda dengan menjalankan gcloud auth login.

  5. Untuk menyiapkan gcloud CLI agar menggunakan identitas dan akses yang disediakan oleh akun layanan secara default, gunakan perintah konfigurasi gcloud CLI:

    gcloud config set auth/impersonate_service_account SERVICE_ACCT_EMAIL

  6. Untuk berhenti menggunakan kredensial akun layanan yang ditiru identitasnya dengan gcloud CLI secara default, hapus setelan flag dengan perintah konfigurasi gcloud CLI:

    gcloud config unset auth/impersonate_service_account

Memberikan otorisasi akun layanan menggunakan Workload Identity Federation

Untuk memberi otorisasi gcloud CLI dengan akun layanan menggunakan kredensial eksternal dari Workload Identity Federation, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman Akun Layanan.

    Buka Akun Layanan

  2. Pilih akun yang ada atau buat akun baru dengan mengklik Buat akun layanan.

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

  4. Untuk mengaktifkan akun layanan Anda, jalankan gcloud auth login dengan flag --cred-file:

    gcloud auth login --cred-file=CONFIGURATION_FILE

    Ganti CONFIGURATION_FILE dengan jalur ke file konfigurasi kredensial untuk Workload Identity Federation.

Memberikan otorisasi akun layanan menggunakan kunci akun layanan

Untuk memberi otorisasi gcloud CLI dengan akun layanan menggunakan kunci akun layanan, lakukan hal berikut:

  1. Di konsol Google Cloud , buka halaman Akun Layanan.

    Buka Akun Layanan

  2. Pilih akun yang ada atau buat akun baru dengan mengklik Buat akun layanan.

  3. Untuk membuat kunci akun layanan, lihat petunjuk IAM untuk Membuat kunci akun layanan.

  4. Untuk mengaktifkan akun layanan Anda, jalankan gcloud auth login dengan flag --cred-file:

    gcloud auth login --cred-file=KEY_FILE

    Ganti KEY_FILE dengan jalur ke file kunci akun layanan.

Cantumkan akun

Untuk mencantumkan akun yang kredensialnya disimpan di sistem lokal, jalankan gcloud auth list:

gcloud auth list

gcloud CLI mencantumkan akun dan menunjukkan akun mana yang aktif:

Credentialed accounts:
 - user-1@gmail.com (active)
 - user-2@gmail.com

Mengganti akun aktif

Untuk mengganti akun aktif, jalankan gcloud config set:

gcloud config set account ACCOUNT

dengan [ACCOUNT] adalah alamat email lengkap akun.

Anda juga dapat beralih akun dengan membuat konfigurasi terpisah yang menentukan akun yang berbeda dan beralih antar-konfigurasi:

gcloud config configurations activate CONFIGURATION

Jika Anda ingin mengganti akun yang digunakan oleh gcloud CLI berdasarkan per-pemanggilan, ganti akun aktif menggunakan flag --account.

Menetapkan durasi sesi yang diizinkan

Sebagai administrator, Anda dapat mengontrol durasi akses gcloud CLI bagi masing-masing pengguna tanpa harus melakukan autentikasi ulang. Misalnya, Anda dapat mewajibkan pengguna dengan hak istimewa yang lebih tinggi 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

Anda dapat mencabut kredensial saat ingin melarang akses oleh gcloud CLI dengan akun tertentu. Anda tidak perlu mencabut kredensial untuk beralih antar-akun.

Untuk mencabut kredensial, jalankan gcloud auth revoke:

gcloud auth revoke ACCOUNT

Untuk mencabut semua akses gcloud CLI untuk semua komputer, hapus gcloud CLI dari daftar aplikasi yang memiliki akses ke akun Anda.

Bekerja dengan file kredensial

Menemukan file kredensial Anda

Untuk menemukan lokasi file kredensial Anda, jalankan gcloud info:

gcloud info

gcloud CLI akan mencetak informasi tentang penginstalan Anda. File kredensial disimpan di direktori konfigurasi pengguna:

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

Menyiapkan Kredensial Default Aplikasi

gcloud CLI menyediakan dukungan untuk mengelola Kredensial Default Aplikasi (ADC) dengan grup perintah gcloud auth application-default. Untuk menyediakan kredensial pengguna bagi ADC, jalankan gcloud auth application-default login:

gcloud auth application-default login

Kredensial ini tidak digunakan oleh gcloud CLI. Untuk mengetahui cara lainnya dalam menyiapkan ADC, lihat Menyiapkan Kredensial Default Aplikasi.

unset GOOGLE_APPLICATION_CREDENTIALS
gcloud config unset auth/impersonate_service_account
gcloud auth application-default login

Langkah berikutnya