Mulai menggunakan Library Google Auth

Ringkasan

Google Auth Library adalah library klien autentikasi open source untuk Java. Dokumen ini menjelaskan cara menggunakan library ini untuk mengautentikasi aplikasi Java Anda guna mengakses layanan Google Cloud .

Dengan mengikuti panduan ini, Anda akan mempelajari cara:

  • Tambahkan dependensi Auth Library yang diperlukan ke project Anda menggunakan Maven, Gradle, atau Simple Build Tool (SBT).
  • Melakukan autentikasi menggunakan berbagai metode, dengan fokus pada Kredensial Default Aplikasi (ADC).
  • Konfigurasi skenario autentikasi lanjutan, termasuk Workload Identity Federation, Workforce Identity Federation, dan peniruan identitas akun layanan.
  • Buat dan gunakan token yang diperkecil cakupannya untuk membatasi izin.
  • Mengintegrasikan kredensial dengan library klien HTTP Google.

Dokumentasi ini ditujukan untuk developer Java. Untuk mengetahui detail lengkap API, lihat Dokumentasi Google Auth Library API.

Library Google Auth untuk Java terdiri dari empat artefak:

  • google-auth-library-credentials berisi class dasar dan antarmuka untuk kredensial Google.
  • google-auth-library-appengine berisi kredensial App Engine dan bergantung pada App Engine SDK.
  • google-auth-library-oauth2-http berisi berbagai kredensial dan metode utilitas, termasuk kemampuan untuk mendapatkan Kredensial Default Aplikasi. Dokumen ini juga menjelaskan pendekatan sisi server untuk membuat token yang cakupannya lebih sempit.
  • google-auth-library-cab-token-generator menyediakan pendekatan sisi klien untuk membuat token yang diperkecil cakupannya.

Memvalidasi konfigurasi kredensial

Saat menggunakan konfigurasi kredensial, seperti JSON, jalur file, atau aliran, dari sumber eksternal, Anda harus memvalidasinya. Memberikan kredensial yang tidak divalidasi ke Google API atau library klien untuk autentikasi keGoogle Cloud dapat membahayakan keamanan sistem dan data Anda.

Untuk mengetahui informasi selengkapnya, lihat Kredensial yang bersumber secara eksternal. Kredensial Default.

Mengimpor Library Auth

Untuk mengimpor Auth Library, gunakan com.google.cloud:libraries-bom atau gunakan Bill of Materials Google Auth Library dengan Maven atau Gradle.

Java SDK libraries-bom

Untuk melakukan autentikasi ke library klien di Java SDK (misalnya, google-cloud-datastore) menggunakan Auth Library, gunakan libraries-bom, yang akan menarik versi Auth Library yang kompatibel dengan library klien tersebut.

Misalnya, untuk mengimpor Auth Library dengan Maven menggunakan pom.xml:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>libraries-bom</artifactId>
      <version>26.53.0</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Jika Anda tidak menggunakan libraries-bom atau library klien lainnya, impor modul Auth secara langsung dengan Bill of Materials Library Google Auth.

Bill of Materials Library Google Auth

Anda dapat menggunakan Bill of Materials Library Google Auth untuk memastikan bahwa modul Auth dan dependensi transitif yang relevan kompatibel.

Maven

Tambahkan kode berikut ke file pom.xml Anda:

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>com.google.auth</groupId>
      <artifactId>google-auth-library-bom</artifactId>
      <version>1.30.1</version>
      <type>pom</type>
      <scope>import</scope>
    </dependency>
  </dependencies>
</dependencyManagement>

Di bagian <dependencies>, Anda dapat menentukan modul Auth yang diperlukan. Misalnya, untuk menyertakan modul google-auth-library-oauth2-http, tambahkan item <dependency> berikut:

<dependency>
  <groupId>com.google.auth</groupId>
  <!-- Let the BOM manage the module and dependency versions -->
  <!-- Replace with the module(s) that are needed -->
  <artifactId>google-auth-library-oauth2-http</artifactId>
</dependency>

Ganti google-auth-library-oauth2-http dalam contoh dengan google-auth-library-credentials atau google-auth-library-appengine, bergantung pada kebutuhan aplikasi Anda.

Gradle

Mirip dengan Maven, pengguna Gradle dapat menggunakan google-auth-library-bom untuk mengelola versi dependensi dan memastikan kompatibilitas antara berbagai modul google-auth-library.

Untuk menggunakan BOM dengan Gradle, tambahkan BOM sebagai dependensi platform. Kemudian, tambahkan modul google-auth-library yang Anda butuhkan. BOM memastikan bahwa versi semua modul yang Anda gunakan kompatibel. Misalnya, tambahkan kode berikut ke file build.gradle Anda:

dependencies {
    // The BOM will manage the module versions and transitive dependencies
    implementation platform('com.google.auth:google-auth-library-bom:1.30.1')
    // Replace with the module(s) that are needed
    implementation 'com.google.auth:google-auth-library-oauth2-http'
}

Scala

Tidak seperti Maven dan Gradle, SBT (Scala Build Tool) tidak mendukung Bill of Materials (BOM) Maven. Akibatnya, saat menggunakan Scala, Anda tidak dapat mengimpor google-auth-library-bom untuk menangani versi yang kompatibel dari modul Auth Library dan dependensi transitifnya secara otomatis.

Sebagai gantinya, Anda harus menambahkan setiap submodul yang diperlukan langsung ke file build.sbt Anda. Anda harus menentukan dan menyelaraskan versi semua modul google-auth-library yang Anda gunakan secara eksplisit. Jika versi tidak konsisten, hal ini dapat menyebabkan konflik versi di antara dependensi transitif, yang berpotensi menyebabkan perilaku yang tidak terduga atau error runtime dalam aplikasi Anda.

Tambahkan kode ini ke dependensi Anda jika menggunakan SBT:

// Replace this with the implementation module that suits your needs
libraryDependencies += "com.google.auth" % "google-auth-library-oauth2-http" % "1.30.1"

Logging Library Auth

Java Auth Library merekomendasikan logging menggunakan client library debug logging. Logging debug akan melakukan hashing pada token sensitif (misalnya, access_token, refresh_token, dll.) dan nilainya akan disamarkan. Logging dengan java.util.logging dinonaktifkan di Auth Library untuk mencegah kebocoran token sensitif.

Fungsi logging debug klien bersifat keikutsertaan dan memerlukan penyiapan.

Logging Debug dapat mencatat hal berikut berdasarkan tingkat log:

  • Informasi Permintaan: Header, URL, Metode (Tingkat INFO)
  • Informasi Respons: Header, Status, Pesan (level INFO)
  • Payload Respons (tingkat DEBUG)

Migrasi dari GoogleCredential ke GoogleCredentials

GoogleCredential dari google-api-java-client tidak digunakan lagi dan GoogleCredentials adalah pengganti yang direkomendasikan.

Buat instance GoogleCredentials menggunakan Kredensial Default Aplikasi (ADC). Berikut pendekatan yang direkomendasikan:

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

Cara Anda menggunakan GoogleCredentials bergantung pada library klien:

Kredensial Default Aplikasi

Google Auth Library menyediakan implementasi Kredensial Default Aplikasi (ADC) untuk Java. ADC menyediakan cara untuk mendapatkan kredensial otorisasi guna memanggil Google API.

Gunakan ADC saat aplikasi Anda memerlukan identitas dan tingkat otorisasi yang konsisten, terlepas dari pengguna. Sebaiknya gunakan ADC untuk mengizinkan panggilan ke Cloud API, terutama saat membangun aplikasi di Google Cloud.

ADC juga mendukung Workload Identity Federation, sehingga aplikasi dapat mengakses resource dari platform eksternal seperti Amazon Web Services (AWS), Microsoft Azure, atau penyedia identitas apa pun yang mendukung OpenID Connect (OIDC). Google Cloud Sebaiknya gunakan workload identity federation untuk lingkungan non-Google Cloud karena menghilangkan kebutuhan untuk mendownload, mengelola, dan menyimpan kunci pribadi akun layanan secara lokal.

Mendapatkan Kredensial Default Aplikasi

Untuk mendapatkan Kredensial Default Aplikasi, gunakan GoogleCredentials.getApplicationDefault() atau GoogleCredentials.getApplicationDefault(HttpTransportFactory). Metode ini menampilkan Kredensial Default Aplikasi untuk mengidentifikasi dan memberi otorisasi seluruh aplikasi.

Berikut adalah kredensial yang dicari, dalam urutan ini, untuk menemukan Kredensial Default Aplikasi:

  1. File kredensial yang ditunjukkan oleh variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS.
  2. Kredensial yang disediakan oleh perintah Google Cloud SDK gcloud auth application-default login.
  3. Kredensial bawaan Google App Engine.
  4. Kredensial bawaan ShellGoogle Cloud .
  5. Kredensial bawaan Google Compute Engine.
    • Lewati pemeriksaan ini dengan menetapkan variabel lingkungan NO_GCE_CHECK=true.
    • Sesuaikan alamat server metadata dengan menetapkan variabel lingkungan GCE_METADATA_HOST=<hostname>.

Pemuatan kredensial eksplisit

Untuk mendapatkan kredensial dari kunci JSON Akun Layanan, gunakan GoogleCredentials.fromStream(InputStream) atau GoogleCredentials.fromStream(InputStream, HttpTransportFactory) seperti yang ditunjukkan dalam contoh kode berikut.

Kredensial harus dimuat ulang sebelum token akses tersedia.