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 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
• Lingkungan pengembangan berbasis cloud Google Cloud
• Compute Engine atau layanan Google Cloud lainnya yang mendukung pemasangan akun layanan

• Google Kubernetes Engine

• Penyedia cloud lokal atau lainnya

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 mengonfigurasi ADC dengan akun pengguna, Anda harus mengetahui fakta berikut:

• Konfigurasi ADC dengan akun 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 bahwa tidak ada project kuota yang tersedia, lihat Kredensial pengguna tidak berfungsi.

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

• File ADC lokal Anda dikaitkan dengan akun pengguna, bukan konfigurasi gcloud CLI Anda. Beralih ke konfigurasi gcloud CLI yang berbeda dapat mengubah identitas yang digunakan oleh gcloud CLI, tetapi tidak memengaruhi file ADC lokal atau konfigurasi ADC.

Cara Anda mengonfigurasi ADC dengan akun pengguna 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 dengan menggunakan Workforce Identity Federation.

Mengonfigurasi ADC dengan Akun Google Anda

Untuk mengonfigurasi ADC dengan Akun Google, gunakan Google Cloud CLI:

1. Install the Google Cloud CLI, then initialize it by running the following command:

   gcloud init

2. 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.

   Catatan: Untuk menambahkan cakupan untuk layanan di luar Google Cloud, seperti Google Drive, buat Client ID OAuth dan berikan ke perintah gcloud auth application-default login dengan menggunakan tanda --client-id-file, tentukan cakupan Anda dengan tanda --scopes.

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

Mengonfigurasi ADC dengan akun yang dikelola oleh IdP eksternal

Untuk mengonfigurasi ADC bagi akun pengguna yang dikelola oleh IdP eksternal dan digabungkan dengan Workforce Identity Federation:

1. After installing the Google Cloud CLI, configure the gcloud CLI to use your federated identity and then initialize it by running the following command:

   gcloud init

2. 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.

   If an authentication error is returned, confirm that you have configured the gcloud CLI to use Workforce Identity Federation.

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

Kredensial akun layanan

Anda dapat mengonfigurasi 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

Sekarang Anda dapat menggunakan library klien menggunakan bahasa yang didukung dengan cara yang sama seperti yang Anda lakukan setelah menyiapkan file ADC lokal dengan kredensial pengguna. Kredensial ditemukan secara otomatis oleh library autentikasi. Untuk informasi selengkapnya, lihat Melakukan autentikasi untuk menggunakan library klien.

Kunci akun layanan

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

Catatan: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus mengautentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan atas operasi lainnya yang dijelaskan oleh Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.

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.

   Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   Catatan: Saat Anda menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS, ADC akan memeriksa lokasi ini terlebih dahulu, lalu memeriksa lokasi lain hanya jika perlu.

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 mengonfigurasi ADC di lingkungan ini. Jika Anda perlu menggunakan akun pengguna yang berbeda untuk mengonfigurasi ADC, atau mengonfigurasi ADC 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 fungsi Cloud Run, mendukung pemasangan 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.

Catatan: Banyak dari layanan Google Cloud ini juga menyediakan akun layanan default. Tidak direkomendasikan untuk menggunakan akun layanan default, karena secara default akun layanan default memiliki hak istimewa tinggi, yang melanggar prinsip hak istimewa terendah.

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.

Set up authentication:

1. Create the service account:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME

   Replace SERVICE_ACCOUNT_NAME with a name for the service account.

2. To provide access to your project and your resources, grant a role to the service account:

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

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • ROLE: the role to grant
   Note: The --role flag affects which resources the service account can access in your project. You can revoke these roles or grant additional roles later. In production environments, do not grant the Owner, Editor, or Viewer roles. Instead, grant a predefined role or custom role that meets your needs.
3. To grant another role to the service account, run the command as you did in the previous step.

4. Grant the required role to the principal that will attach the service account to other resources.

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

   Replace the following:

   • SERVICE_ACCOUNT_NAME: the name of the service account
   • PROJECT_ID: the project ID where you created the service account
   • USER_EMAIL: the email address for a Google Account

GKE

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 addon gcp-auth.

Menjalankan aplikasi dalam container di Google Cloud

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

• Untuk GKE Enterprise, lihat ringkasan autentikasi dan Menggunakan Workload Identity Federation fleet untuk GKE.
• Untuk GKE, lihat Mengakses Google Cloud API dari workload GKE.
• Untuk penayangan Knative, lihat Menggunakan Workload Identity Federation for GKE untuk penayangan Knative.

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 mengautentikasi dengan Google Cloud menggunakan kredensial dari IdP eksternal adalah dengan menggunakan Workload Identity Federation; Anda membuat file konfigurasi kredensial dan menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS untuk menunjukkannya. Pendekatan ini lebih aman daripada membuat kunci akun layanan.

Untuk mendapatkan bantuan terkait penyiapan Workload Identity Federation untuk ADC, lihat Workload Identity Federation dengan cloud lain.

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.

Catatan: Kunci akun layanan akan berisiko keamanan jika tidak dikelola dengan benar. Anda harus memilih alternatif yang lebih aman untuk kunci akun layanan jika memungkinkan. Jika harus mengautentikasi dengan kunci akun layanan, Anda bertanggung jawab atas keamanan kunci pribadi dan atas operasi lainnya yang dijelaskan oleh Praktik terbaik untuk mengelola kunci akun layanan. Jika Anda tidak dapat membuat kunci akun layanan, pembuatan kunci akun layanan mungkin dinonaktifkan untuk organisasi Anda. Untuk mengetahui informasi selengkapnya, lihat Mengelola resource organisasi yang aman secara default.

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.

   Set the environment variable GOOGLE_APPLICATION_CREDENTIALS to the path of the JSON file that contains your credentials. This variable applies only to your current shell session, so if you open a new session, set the variable again.

   Example: Linux or macOS

   export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

   Example: Windows

   For PowerShell:

   $env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   For example:

   $env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

   For command prompt:

   set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

   Replace KEY_PATH with the path of the JSON file that contains your credentials.

   Catatan: Saat Anda menetapkan variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS, ADC akan memeriksa lokasi ini terlebih dahulu, lalu memeriksa lokasi lain hanya jika perlu.

Langkah berikutnya

• Pelajari lebih lanjut cara ADC menemukan kredensial.
• Mengautentikasi untuk menggunakan Library Klien Cloud.
• Pelajari metode autentikasi.