Menyiapkan Kredensial Default Aplikasi

Halaman ini menjelaskan cara menyiapkan Kredensial Default Aplikasi (ADC) untuk digunakan oleh Library Klien Cloud, Library Klien Google API, serta REST API dan RPC API di berbagai lingkungan. Anda menyiapkan ADC dengan memberikan kredensial ke ADC di lingkungan tempat kode Anda dijalankan.

Application Default Credentials (ADC) adalah strategi yang digunakan oleh library autentikasi Google untuk menemukan kredensial secara otomatis berdasarkan lingkungan aplikasi. Library autentikasi menyediakan kredensial tersebut untuk Library Klien Cloud dan Library Klien Google API. Saat menggunakan ADC, kode Anda dapat berjalan di lingkungan pengembangan atau produksi tanpa mengubah cara aplikasi Anda melakukan autentikasi ke layanan Google Cloud dan Google Cloud API.

Untuk informasi tentang tempat ADC mencari kredensial dan urutannya, lihat Cara kerja Kredensial Default Aplikasi.

Jika menggunakan kunci API, Anda tidak perlu menyiapkan ADC. Untuk informasi selengkapnya, lihat Menggunakan kunci API.

Cara memberikan kredensial ke ADC

Pilih lingkungan tempat kode Anda dijalankan:

Lingkungan pengembangan lokal

Anda dapat memberikan kredensial pengguna atau kredensial akun layanan ke ADC di lingkungan pengembangan lokal.

Kredensial pengguna

Saat kode Anda berjalan di lingkungan pengembangan lokal, seperti workstation pengembangan, opsi terbaik adalah menggunakan kredensial yang terkait dengan akun pengguna Anda.

Saat memberikan kredensial pengguna untuk membuat file ADC lokal, Anda harus mengetahui fakta berikut:

  • Kredensial pengguna mungkin tidak berfungsi untuk beberapa metode dan API, seperti Cloud Translation API atau Cloud Vision API, tanpa parameter atau konfigurasi tambahan. Jika Anda melihat pesan error tentang API yang tidak diaktifkan dalam project, atau tidak ada project kuota yang tersedia, lihat Memecahkan masalah penyiapan ADC.

  • ADC lokal berisi token akses dan refresh Anda. Setiap pengguna yang memiliki akses ke sistem file Anda dapat menggunakan kredensial tersebut. Jika tidak lagi memerlukan kredensial lokal ini, Anda dapat mencabutnya menggunakan perintah gcloud auth application-default revoke.

  • Jika akun pengguna Anda tidak memiliki peran Identity and Access Management (IAM) yang diperlukan dalam project, kode Anda mungkin tidak dapat mengakses beberapa resource. Jika ini terjadi, seseorang harus memberi Anda peran yang diperlukan.

  • File ADC lokal Anda dikaitkan dengan akun pengguna, bukan konfigurasi gcloud CLI Anda. Beralih ke konfigurasi gcloud CLI yang berbeda tidak memengaruhi file ADC lokal atau kredensial yang diberikan ke ADC.

Cara memberikan kredensial pengguna ke ADC bergantung pada apakah akun pengguna Anda dikelola oleh Google—dengan kata lain, akun tersebut adalah Akun Google—atau oleh penyedia identitas (IdP) lain, dan digabungkan menggunakan federasi identitas tenaga kerja.

Berikan kredensial pengguna untuk Akun Google Anda

Untuk memberikan kredensial pengguna Anda ke ADC untuk Akun Google, gunakan Google Cloud CLI:

  1. Instal dan lakukan inisialisasi gcloud CLI.

    Saat melakukan inisialisasi gcloud CLI, pastikan untuk menentukan project Google Cloud yang izinnya Anda miliki untuk mengakses resource yang dibutuhkan aplikasi Anda.

  2. Buat file kredensial Anda:

    gcloud auth application-default login

    Layar login akan muncul. Setelah Anda login, kredensial Anda akan disimpan di file kredensial lokal yang digunakan oleh ADC.

Memberikan kredensial pengguna untuk akun yang dikelola oleh IdP eksternal

Untuk memberikan kredensial pengguna untuk akun pengguna yang dikelola oleh IdP eksternal dan digabungkan dengan federasi identitas tenaga kerja, Anda memerlukan nama penyedia kumpulan tenaga kerja. Administrator Anda seharusnya dapat memberikan informasi ini kepada Anda. Nama penyedia kumpulan tenaga kerja memiliki format berikut:

locations/global/workforcePools/POOL_ID/provider/PROVIDER_ID

Berikan kredensial pengguna Anda ke ADC untuk akun pengguna gabungan:

  1. Buat file konfigurasi login dan tetapkan properti auth/login_config_file gcloud CLI agar mengarah ke lokasinya, menggunakan perintah iam worker-pools create-login-config:

    gcloud iam workforce-pools create-login-config PROVIDER_ID \
--output-file=LOGIN_CONFIG_FILE --activate

    Ganti kode berikut:

    • PROVIDER_ID: ID penyedia
    • LOGIN_CONFIG_FILE: jalur ke file konfigurasi yang Anda tentukan—misalnya, login.json

    File yang dibuat terlihat mirip dengan contoh berikut:

    {
"type": "external_account_authorized_user_login_config",
"audience": "//iam.googleapis.com/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. Login ke gcloud CLI menggunakan file login:

    gcloud auth login

  3. Lakukan inisialisasi gcloud CLI:

    gcloud init

  4. Buat file ADC lokal Anda:

    gcloud auth application-default login

Untuk mengetahui informasi selengkapnya, lihat Penggabungan identitas tenaga kerja.

Kredensial akun layanan

Anda dapat menyiapkan ADC dengan kredensial dari akun layanan menggunakan peniruan akun layanan atau menggunakan kunci akun layanan.

Peniruan akun layanan

Anda dapat menggunakan peniruan akun layanan untuk menyiapkan file Kredensial Default Aplikasi (ADC) lokal. Library klien yang mendukung peniruan identitas dapat menggunakan kredensial tersebut secara otomatis. File ADC lokal yang dibuat dengan menggunakan peniruan identitas didukung dalam bahasa berikut:

  • C#
  • Go
  • Java
  • Node.js
  • Python

Anda harus memiliki peran IAM Service Account Token Creator (roles/iam.serviceAccountTokenCreator) di akun layanan yang sedang Anda tiru. Untuk informasi selengkapnya, lihat Peran yang diperlukan.

Menggunakan peniruan akun layanan untuk membuat file ADC lokal: 

gcloud auth application-default login --impersonate-service-account SERVICE_ACCT_EMAIL

Kunci akun layanan

Jika tidak dapat menggunakan kredensial pengguna atau peniruan akun layanan untuk pengembangan lokal, Anda dapat menggunakan kunci akun layanan.

Untuk membuat kunci akun layanan dan menyediakannya bagi ADC:

  1. Buat akun layanan dengan peran yang dibutuhkan aplikasi Anda, serta kunci untuk akun layanan tersebut, dengan mengikuti petunjuk dalam Membuat kunci akun layanan.

  2. Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur file JSON yang berisi kredensial Anda. Variabel ini hanya berlaku untuk sesi shell Anda saat ini. Jadi, jika Anda membuka sesi baru, tetapkan variabel kembali.

Lingkungan pengembangan berbasis cloud Google Cloud

Saat Anda menggunakan lingkungan pengembangan berbasis cloud Google Cloud seperti Cloud Shell atau Cloud Code, alat ini menggunakan kredensial yang Anda berikan saat login, dan mengelola semua otorisasi yang diperlukan. Anda tidak dapat menggunakan gcloud CLI untuk memberikan kredensial ke ADC dalam lingkungan ini. Jika Anda perlu memberikan akun pengguna yang berbeda ke ADC, atau memberikan kredensial menggunakan akun layanan, gunakan lingkungan pengembangan lokal atau resource komputasi Google Cloud sebagai lingkungan pengembangan Anda.

Layanan Google Cloud yang mendukung pelampiran akun layanan

Beberapa layanan Google Cloud, seperti Compute Engine, App Engine, dan Cloud Functions, mendukung pelampiran akun layanan yang dikelola pengguna ke beberapa jenis resource. Umumnya, pelampiran akun layanan didukung jika resource layanan tersebut dapat berjalan atau menyertakan kode aplikasi. Saat Anda melampirkan akun layanan ke resource, kode yang berjalan pada resource tersebut dapat menggunakan akun layanan tersebut sebagai identitasnya.

Melampirkan akun layanan yang dikelola pengguna adalah cara yang lebih disukai untuk memberikan kredensial ke ADC bagi kode produksi yang berjalan di Google Cloud.

Untuk bantuan dalam menentukan peran yang perlu Anda berikan ke akun layanan, lihat Memilih peran yang telah ditetapkan.

Untuk informasi tentang resource mana yang dapat Anda lampirkan dengan akun layanan, dan bantuan terkait pelampiran akun layanan ke resource, lihat dokumentasi IAM tentang cara melampirkan akun layanan.

Menyiapkan autentikasi:

  1. Buat akun layanan: 

    gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

    Ganti SERVICE_ACCOUNT_NAME dengan nama untuk akun layanan.

  2. Untuk memberikan akses ke project dan resource Anda, berikan peran ke akun layanan: 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="serviceAccount:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com" --role=ROLE

    Ganti kode berikut:

    • SERVICE_ACCOUNT_NAME: nama dari akun layanan.
    • PROJECT_ID: project ID dimana Anda membuat akun layanan
    • ROLE: peran yang akan diberikan
  3. Untuk memberikan peran lain ke akun layanan, jalankan perintah seperti yang Anda lakukan di langkah sebelumnya.

  4. Memberi Akun Google Anda peran yang memungkinkan Anda menggunakan peran akun layanan dan tambahkan akun layanan tersebut ke resource lain: 

    gcloud iam service-accounts add-iam-policy-binding SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com --member="user:USER_EMAIL" --role=roles/iam.serviceAccountUser

    Ganti kode berikut:

    • SERVICE_ACCOUNT_NAME: nama dari akun layanan.
    • PROJECT_ID: project ID dimana Anda membuat akun layanan
    • USER_EMAIL: alamat email untuk Akun Google Anda

GKE atau GKE Enterprise

Autentikasi untuk aplikasi dalam container yang berjalan di GKE atau GKE Enterprise ditangani secara berbeda antara lingkungan pengujian lokal dan lingkungan Google Cloud.

Menguji aplikasi dalam container secara lokal

Untuk menguji aplikasi dalam container di workstation lokal, Anda dapat mengonfigurasi container untuk melakukan autentikasi dengan file kredensial lokal. Untuk menguji container, gunakan implementasi Kubernetes lokal seperti minikube dan add-on gcp-auth.

Menjalankan aplikasi dalam container di Google Cloud

Anda menyiapkan autentikasi untuk lingkungan dalam container Google Cloud secara berbeda, bergantung pada konteksnya:

Penyedia cloud lokal atau lainnya

Jika menjalankan aplikasi di luar Google Cloud, Anda harus memberikan kredensial yang dikenali oleh Google Cloud untuk menggunakan layanan Google Cloud.

Workload identity federation

Cara yang lebih disukai untuk melakukan autentikasi dengan Google Cloud menggunakan kredensial dari IdP yang berbeda adalah dengan menggunakan federasi identitas workload; Anda membuat file konfigurasi kredensial dan menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS agar mengarah ke file tersebut. Pendekatan ini lebih aman daripada membuat kunci akun layanan.

Untuk mendapatkan bantuan terkait penyiapan workload identity federation untuk ADC, lihat Mengonfigurasi workload identity federation dan Memperoleh kredensial jangka waktu singkat dengan federasi identitas.

Kunci akun layanan

Jika tidak dapat mengonfigurasi workload identity federation, Anda harus membuat akun layanan, memberinya peran IAM yang diperlukan aplikasi, dan membuat kunci untuk akun layanan.

Untuk membuat kunci akun layanan dan menyediakannya bagi ADC:

  1. Buat akun layanan dengan peran yang dibutuhkan aplikasi Anda, serta kunci untuk akun layanan tersebut, dengan mengikuti petunjuk dalam Membuat kunci akun layanan.

    Tetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS ke jalur file JSON yang berisi kredensial Anda. Variabel ini hanya berlaku untuk sesi shell Anda saat ini. Jadi, jika Anda membuka sesi baru, tetapkan variabel kembali.

Langkah selanjutnya