Mulai menggunakan Library Google Auth

Ringkasan

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

Dengan mengikuti panduan ini, Anda akan mempelajari cara:

  • Tambahkan dependensi Library Auth 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).
  • Mengonfigurasi skenario autentikasi lanjutan, termasuk Workload Identity Federation, Workforce Identity Federation, dan peniruan akun layanan.
  • Membuat dan menggunakan token yang diperkecil cakupannya untuk membatasi izin.
  • Mengintegrasikan kredensial dengan library klien HTTP Google.

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

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. Library ini juga menyediakan pendekatan sisi server untuk membuat token dengan cakupan yang dipersempit.
  • google-auth-library-cab-token-generator menyediakan pendekatan sisi klien untuk membuat token yang diperkecil cakupannya.

Memvalidasi konfigurasi kredensial

Saat Anda menggunakan konfigurasi kredensial, seperti JSON, jalur file, atau aliran data, 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 dari eksternal. Kredensial Default Aplikasi.

Mengimpor Library Auth

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

Libraries-bom Java SDK

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

Misalnya, untuk mengimpor Library Auth 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

Serupa 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 perlukan. 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. Oleh karena itu, saat menggunakan Scala, Anda tidak dapat mengimpor google-auth-library-bom untuk otomatis menangani versi yang kompatibel dari modul Library Auth dan dependensi transitifnya.

Sebagai gantinya, Anda harus menambahkan setiap submodul yang diperlukan langsung ke file build.sbt. Sangat penting untuk menentukan dan menyelaraskan versi semua modul google-auth-library yang Anda gunakan secara eksplisit. Jika versi tidak konsisten, konflik versi dapat terjadi 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

Library Auth Java merekomendasikan logging menggunakan logging debug library klien. 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 Library Auth untuk mencegah kebocoran token sensitif.

Fungsi logging debug klien bersifat opsional dan memerlukan penyiapan.

Logging Debug dapat mencatat hal berikut berdasarkan level log:

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

Bermigrasi 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 adalah pendekatan yang direkomendasikan:

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();

Cara Anda menggunakan GoogleCredentials bergantung pada library klien:

Kredensial Default Aplikasi

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

Gunakan ADC jika 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, yang memungkinkan aplikasi mengakses resource Google Cloud dari platform eksternal seperti Amazon Web Services (AWS), Microsoft Azure, atau penyedia identitas apa pun yang mendukung OpenID Connect (OIDC). 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 mengizinkan seluruh aplikasi.

Berikut ini adalah urutan penelusuran untuk menemukan Kredensial Default Aplikasi:

  1. File kredensial yang ditunjukkan oleh variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS.
  2. Kredensial yang disediakan oleh perintah gcloud auth application-default login Google Cloud SDK.
  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.

GoogleCredentials credentials = GoogleCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));
credentials.refreshIfExpired();
AccessToken token = credentials.getAccessToken();
// OR
AccessToken token = credentials.refreshAccessToken();

Kredensial yang ditiru identitasnya

Gunakan ImpersonatedCredentials untuk mengizinkan kredensial (akun utama) meniru akun layanan (target). Hal ini memungkinkan akun utama mengakses resource sebagai target, tanpa memerlukan kunci pribadi target.

Untuk menggunakan ImpersonatedCredentials, Anda harus memenuhi persyaratan berikut:

  • Project akun utama harus mengaktifkan IAMCredentials API.
  • Akun utama harus memiliki peran Service Account Token Creator (Identity and Access Management) di akun layanan target.

Contoh kode berikut membuat ImpersonatedCredentials. Kredensial akun utama diperoleh dari Kredensial Default Aplikasi (ADC). ImpersonatedCredentials yang dihasilkan kemudian digunakan untuk mengakses Google Cloud Storage sebagai akun layanan target.

// The principal (ADC) has the Service Account Token Creator role on the target service account.
GoogleCredentials sourceCredentials =
    GoogleCredentials.getApplicationDefault()
        .createScoped(Arrays.asList("https://www.googleapis.com/auth/iam"));

ImpersonatedCredentials credentials =
    ImpersonatedCredentials.newBuilder()
        .setSourceCredentials(sourceCredentials)
        .setTargetPrincipal(
            "impersonated-account@project.")
        .setScopes(Arrays.asList("https://www.googleapis.com/auth/devstorage.read_only"))
        .build();

Storage storage =
    StorageOptions.newBuilder().setProjectId("project-id").setCredentials(credentials).build()
        .getService();

for (Bucket b : storage.list().iterateAll()) {
  System.out.println(b);
}

Token terikat sertifikat untuk identitas agen

Saat aplikasi Anda berjalan dengan identitas agen (misalnya, layanan atau tugas Cloud Run yang di-deploy dengan --identity-type=agent-identity), ComputeEngineCredentials akan meminta token akses dan token ID terikat sertifikat dari server metadata secara default. Token terikat dikaitkan dengan sertifikat X.509 workload dan memerlukan pembuktian kepemilikan kunci pribadi yang cocok melalui mutual TLS (mTLS). Karena kunci pribadi tersebut hanya tersedia untuk workload, token yang bocor tidak dapat digunakan dari tempat lain.

Token terikat hanya diterima jika permintaan yang membawanya dikirim melalui mTLS dengan sertifikat yang sama. Library Klien Cloud untuk Java mengonfigurasi mTLS dan memuat ulang sertifikat workload yang dirotasi secara otomatis saat identitas agen diaktifkan. Jika Anda memanggil Google API dengan klien HTTP Anda sendiri, Anda harus mengonfigurasi mTLS dengan sertifikat workload dan memuat ulang sertifikat tersebut saat runtime merotasi sertifikat di disk. Setelah rotasi, token refresh yang baru akan terikat ke sertifikat baru; jika token baru dikirim melalui koneksi mTLS yang dibuat dengan sertifikat sebelumnya, API akan menolak permintaan dengan 401 UNAUTHENTICATED.

Library hanya meminta token terikat jika semua hal berikut terpenuhi:

  • Sertifikat workload ditemukan, baik melalui file yang diberi nama oleh variabel lingkungan GOOGLE_API_CERTIFICATE_CONFIG atau di lokasi default (/var/run/secrets/workload-spiffe-credentials/).
  • ID SPIFFE sertifikat termasuk dalam domain kepercayaan identitas agen.
  • Pengikatan token dan mTLS belum dinonaktifkan (lihat Menonaktifkan pengikatan token).

Di semua lingkungan lainnya, ComputeEngineCredentials berperilaku seperti sebelumnya dan menampilkan token yang tidak terikat.

Menonaktifkan pengikatan token

Jika Anda perlu menonaktifkan pengikatan token (lihat Batasan umum), tetapkan variabel lingkungan berikut:

GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false
Variabel lingkungan Efek
GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN Tetapkan ke false untuk meminta token tidak terikat.
GOOGLE_API_USE_CLIENT_CERTIFICATE Menyetelnya ke false akan menonaktifkan mTLS sepenuhnya, yang juga akan menonaktifkan pengikatan token. Pilih GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false jika Anda hanya memerlukan token tidak terikat.

Nilai tidak peka huruf besar/kecil dan spasi kosong di sekitarnya akan diabaikan. Hanya false yang menonaktifkan fitur; nilai lainnya akan mempertahankan setelan default.

Variabel lingkungan berlaku untuk seluruh proses, sehingga menonaktifkan pengikatan token akan memengaruhi setiap library di aplikasi Anda yang menggunakan Kredensial Default Aplikasi, bukan hanya library yang membutuhkannya. Jika Anda hanya memerlukan token ID tidak terikat untuk beberapa target, gunakan opsi per target yang dijelaskan dalam Meminta token ID tidak terikat untuk target tertentu.

Meminta token ID tidak terikat untuk target tertentu

Token ID terikat menyertakan sidik jari sertifikat workload dalam klaim cnf (x5t#S256). Layanan penerima dapat memvalidasi klaim ini terhadap sertifikat klien yang ditampilkan selama handshake mTLS, atau mengabaikan klaim jika tidak menerapkan binding sertifikat.

Cloud Run otomatis menerapkan pengikatan sertifikat saat klaim cnf ada dalam token ID. Jika Anda memanggil layanan Cloud Run dengan token ID terikat, Anda harus memanggil URL *.mtls.run.app-nya melalui mTLS; permintaan ke URL *.run.app standar atau domain kustom tanpa mTLS akan ditolak dengan 401 Unauthorized.

Jika Anda memanggil layanan yang menerapkan binding sertifikat melalui endpoint non-mTLS (seperti URL *.run.app standar), atau jika Anda tidak memerlukan binding sertifikat untuk endpoint target, teruskan IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN untuk meminta token ID yang tidak terikat hanya untuk target tersebut:

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
IdTokenCredentials idTokenCredentials =
    IdTokenCredentials.newBuilder()
        .setIdTokenProvider((IdTokenProvider) credentials)
        .setTargetAudience("https://my-service-12345.us-central1.run.app")
        .setOptions(Arrays.asList(IdTokenProvider.Option.DISABLE_BOUND_ID_TOKEN))
        .build();

Token akses dan token ID untuk target lain masih terikat. Opsi ini hanya didukung oleh ComputeEngineCredentials; implementasi IdTokenProvider lainnya tidak meminta token ID terikat dan mengabaikan opsi ini, sehingga kode yang sama juga berfungsi di luar lingkungan identitas agen.

Batasan umum

  • Agent Development Kit (ADK) untuk Java tidak menggunakan mTLS saat memanggil Google API, seperti Gemini di Vertex AI. Dengan token terikat (default), panggilan tersebut akan gagal dengan com.google.genai.errors.ClientException: 401 . Request had invalid authentication credentials. Untuk mengatasi masalah ini, tetapkan GOOGLE_API_ENABLE_RUNTIME_BOUND_TOKEN=false untuk agen yang menggunakan ADK untuk Java. Untuk mengetahui informasi selengkapnya, lihat Mengautentikasi agen di Cloud Run.

Workload Identity Federation

Workload Identity Federation memungkinkan aplikasi Anda mengakses resource Google Cloud dari Amazon Web Services (AWS), Microsoft Azure, atau penyedia identitas apa pun yang mendukung OpenID Connect (OIDC).

Secara konvensional, aplikasi yang berjalan di luar Google Cloud telah menggunakan kunci akun layanan untuk mengakses resource Google Cloud . Dengan menggunakan workload identity federation, workload Anda dapat meniru akun layanan. Hal ini memungkinkan workload eksternal mengakses resource Google Cloud secara langsung, sehingga menghilangkan beban pemeliharaan dan keamanan yang terkait dengan kunci akun layanan.

Mengakses resource dari AWS

Untuk mengakses resource Google Cloud dari Amazon Web Services (AWS), Anda harus mengonfigurasi workload identity federation terlebih dahulu. Proses penyiapan dijelaskan secara mendetail di Mengakses resource dari AWS.

Sebagai bagian dari proses tersebut, Anda akan membuat file konfigurasi kredensial. File ini berisi metadata yang tidak sensitif yang menginstruksikan library cara mengambil token subjek eksternal dan menukarnya dengan token akses akun layanan. Anda dapat membuat file menggunakan Google Cloud CLI:

# Generate an AWS configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --aws \
    --output-file /path/to/generated/config.json

Ganti kode berikut:

  • PROJECT_NUMBER: nomor project Google Cloud .
  • POOL_ID: ID workload identity pool.
  • AWS_PROVIDER_ID: ID penyedia AWS.
  • SERVICE_ACCOUNT_EMAIL: email akun layanan yang akan ditiru identitasnya.

Contoh ini menghasilkan file konfigurasi dalam file output yang ditentukan.

Jika Anda menggunakan AWS IMDSv2 , Anda perlu menambahkan flag tambahan --enable-imdsv2 ke perintah gcloud iam workload-identity-pools create-cred-config:

gcloud iam workload-identity-pools create-cred-config \
    projects/PROJECT_NUMBER/locations/global/workloadIdentityPools/POOL_ID/providers/AWS_PROVIDER_ID \
    --service-account SERVICE_ACCOUNT_EMAIL \
    --aws \
    --output-file /path/to/generated/config.json \
    --enable-imdsv2

Sekarang Anda dapat menggunakan library Auth untuk memanggil resourceGoogle Cloud dari AWS.

Mengakses resource dari Microsoft Azure

Untuk mengakses resource Google Cloud dari Microsoft Azure, Anda harus mengonfigurasi workload identity federation terlebih dahulu. Proses penyiapan dijelaskan secara mendetail di Mengakses resource dari Azure.

Sebagai bagian dari proses tersebut, Anda akan membuat file konfigurasi kredensial. File ini berisi metadata tidak sensitif yang menginstruksikan library cara mengambil token subjek eksternal dan menukarnya dengan token akses akun layanan. Anda dapat membuat file menggunakan Google Cloud CLI:

# Generate an Azure configuration file.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AZURE_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --azure \
    --output-file /path/to/generated/config.json

Ganti kode berikut:

  • PROJECT_NUMBER: nomor project Google Cloud .
  • POOL_ID: ID workload identity pool.
  • AZURE_PROVIDER_ID: ID penyedia Azure.
  • SERVICE_ACCOUNT_EMAIL: email akun layanan yang akan ditiru identitasnya.

Perintah ini akan membuat file konfigurasi di file output yang ditentukan.

Anda kini dapat menggunakan library Auth untuk memanggil resource Google Clouddari Azure.

Mengakses resource dari penyedia identitas OIDC

Untuk mengakses resource Google Cloud dari penyedia identitas yang mendukung OpenID Connect (OIDC), Anda harus mengonfigurasi workload identity federation terlebih dahulu seperti yang dijelaskan dalam Mengonfigurasi workload identity federation dari penyedia identitas OIDC.

Sebagai bagian dari proses tersebut, Anda akan membuat file konfigurasi kredensial menggunakan Google Cloud CLI. File ini berisi metadata yang tidak sensitif yang menginstruksikan library cara mengambil token subjek eksternal dan menukarnya dengan token akses akun layanan.

Untuk penyedia OIDC, library Auth dapat mengambil token OIDC dari file lokal (kredensial dari file), server lokal (kredensial dari URL), atau kombinasi sertifikat X.509 dan kunci pribadi (kredensial dari sertifikat X.509).

Kredensial dari file

Untuk kredensial yang bersumber dari file, proses latar belakang harus terus-menerus memperbarui lokasi file dengan token OIDC baru sebelum masa berlakunya habis. Untuk token dengan masa berlaku satu jam, Anda harus memperbarui token dalam file setiap jam. Anda dapat menyimpan token secara langsung sebagai teks biasa atau dalam format JSON.

Untuk membuat konfigurasi OIDC dari file, jalankan perintah berikut:

# Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-file <var>PATH_TO_OIDC_ID_TOKEN</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

Ganti kode berikut:

  • PROJECT_NUMBER: nomor project Google Cloud .
  • POOL_ID: ID workload identity pool.
  • OIDC_PROVIDER_ID: ID penyedia OIDC.
  • SERVICE_ACCOUNT_EMAIL: email akun layanan yang akan ditiru identitasnya.
  • PATH_TO_OIDC_ID_TOKEN: jalur yang digunakan untuk mengambil token OIDC.

Perintah ini akan menghasilkan file konfigurasi dalam file output yang ditentukan.

Kredensial dari URL

Untuk kredensial dari URL, server lokal harus menghosting endpoint GET yang menyediakan token OIDC dalam format teks biasa atau JSON. Anda dapat menentukan header HTTP tambahan untuk dikirim dalam permintaan token, jika diperlukan oleh endpoint.

Untuk membuat konfigurasi workload identity OIDC dari URL, jalankan perintah berikut:

# Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>OIDC_PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-source-url <var>URL_TO_GET_OIDC_TOKEN</var> \
    --credential-source-headers <var>HEADER_KEY=HEADER_VALUE</var> \
    # Optional arguments for file types. Default is "text":
    # --credential-source-type "json" \
    # Optional argument for the field that contains the OIDC credential.
    # This is required for json.
    # --credential-source-field-name "id_token" \
    --output-file /path/to/generated/config.json

Ganti kode berikut:

  • PROJECT_NUMBER: nomor project Google Cloud .
  • POOL_ID: ID workload identity pool.
  • OIDC_PROVIDER_ID: ID penyedia OIDC.
  • SERVICE_ACCOUNT_EMAIL: email akun layanan yang akan ditiru identitasnya.
  • URL_TO_GET_OIDC_TOKEN: URL endpoint server lokal yang akan dipanggil untuk mengambil token OIDC.
  • HEADER_KEY dan HEADER_VALUE: pasangan kunci dan nilai header tambahan yang akan diteruskan bersama permintaan GET ke URL_TO_GET_OIDC_TOKEN, misalnya Metadata-Flavor=Google.

Sekarang Anda dapat menggunakan library Auth untuk memanggil resourceGoogle Cloud dari penyedia OIDC.

Mengakses resource menggunakan kredensial yang bersumber dari sertifikat X.509

Untuk kredensial yang bersumber dari sertifikat X.509, library autentikasi menggunakan sertifikat X.509 dan kunci pribadi untuk membuktikan identitas aplikasi Anda. Sertifikat X.509 menyertakan tanggal habis masa berlaku dan harus diperpanjang sebelum masa berlakunya habis untuk mempertahankan akses.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi resmi.

Membuat file konfigurasi untuk penggabungan X.509

Untuk mengonfigurasi kredensial yang bersumber dari sertifikat X.509, Anda membuat dua file terpisah: file konfigurasi kredensial utama dan file konfigurasi sertifikat.

  • File konfigurasi kredensial utama berisi metadata yang diperlukan untuk autentikasi. File ini juga mereferensikan file konfigurasi sertifikat.
  • File konfigurasi sertifikat menentukan jalur file untuk sertifikat X.509, kunci pribadi, dan rantai kepercayaan.

Perintah gcloud iam workload-identity-pools create-cred-config dapat digunakan untuk membuat keduanya.

Lokasi tempat gcloud membuat file konfigurasi sertifikat bergantung pada apakah Anda menggunakan flag --credential-cert-configuration-output-file.

Jika Anda menghilangkan flag --credential-cert-configuration-output-file, gcloud akan membuat file konfigurasi sertifikat di lokasi default yang umum dan dapat ditemukan secara otomatis oleh library Auth. Pendekatan ini cocok untuk sebagian besar kasus penggunaan. File konfigurasi kredensial default diberi nama config.json dan file konfigurasi sertifikat default diberi nama certificate_config.json.

Misalnya, jalankan perintah berikut untuk membuat file konfigurasi menggunakan perilaku default:

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --output-file /path/to/config.json

Ganti kode berikut:

  • PROJECT_NUMBER: nomor project Google Cloud .
  • POOL_ID: ID workload identity pool.
  • PROVIDER_ID: ID penyedia.
  • SERVICE_ACCOUNT_EMAIL: email akun layanan yang akan ditiru identitasnya.
  • PATH_TO_CERTIFICATE: jalur tempat sertifikat X.509 leaf Anda berada.
  • PATH_TO_PRIVATE_KEY: jalur tempat kunci pribadi yang sesuai untuk sertifikat entitas akhir berada.
  • PATH_TO_TRUST_CHAIN: jalur file rantai kepercayaan sertifikat X.509. File ini harus berupa file berformat PEM yang berisi sertifikat perantara yang diperlukan untuk menyelesaikan rantai kepercayaan antara sertifikat entitas akhir dan trust store yang dikonfigurasi di Workload Identity Federation pool. Sertifikat entitas akhir bersifat opsional dalam file ini.

Perintah ini akan menghasilkan hal berikut:

  • /path/to/config.json: Dibuat di jalur yang Anda tentukan. File ini akan berisi "use_default_certificate_config": true untuk menginstruksikan klien agar mencari konfigurasi sertifikat di jalur default.
  • certificate_config.json: Dibuat di jalur konfigurasi Google Cloud CLI default, yang biasanya berupa ~/.config/gcloud/certificate_config.json di Linux dan macOS, atau %APPDATA%\gcloud\certificate_config.json di Windows.

Perilaku lokasi kustom

Jika Anda perlu menyimpan file konfigurasi sertifikat di lokasi non-default, gunakan flag --credential-cert-configuration-output-file.

Contoh perintah (lokasi kustom):

gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
    --credential-cert-path "<var>PATH_TO_CERTIFICATE</var>" \
    --credential-cert-private-key-path "<var>PATH_TO_PRIVATE_KEY</var>" \
    --credential-cert-trust-chain-path "<var>PATH_TO_TRUST_CHAIN</var>" \
    --credential-cert-configuration-output-file "/custom/path/cert_config.json" \
    --output-file /path/to/config.json

Perintah ini menghasilkan:

  • /path/to/config.json: dibuat di jalur yang Anda tentukan. File ini akan berisi kolom "certificate_config_location" yang mengarah ke jalur kustom Anda.
  • cert_config.json: dibuat di /custom/path/cert_config.json, seperti yang ditentukan oleh flag.

Sekarang Anda dapat menggunakan library Auth untuk memanggil resourceGoogle Cloud dengan kredensial yang bersumber dari sertifikat X.509.

Menggunakan kredensial dari file yang dapat dieksekusi dengan OIDC dan SAML

Untuk kredensial dari file yang dapat dieksekusi, file yang dapat dieksekusi lokal digunakan untuk mengambil token pihak ketiga. File yang dapat dieksekusi harus memberikan token ID OIDC atau pernyataan SAML yang valid dan belum habis masa berlakunya dalam format JSON ke stdout.

Untuk menggunakan kredensial dari file yang dapat dieksekusi, variabel lingkungan GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES harus ditetapkan ke 1.

Untuk membuat konfigurasi workload identity dari file yang dapat dieksekusi, jalankan perintah berikut:

# Generate a configuration file for executable-sourced credentials.
gcloud iam workload-identity-pools create-cred-config \
    projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>PROVIDER_ID</var> \
    --service-account=<var>SERVICE_ACCOUNT_EMAIL</var> \
    --subject-token-type=<var>SUBJECT_TOKEN_TYPE</var> \
    # The absolute path for the program, including arguments.
    # e.g. --executable-command="/path/to/command --foo=bar"
    --executable-command=<var>EXECUTABLE_COMMAND</var> \
    # Optional argument for the executable timeout. Defaults to 30s.
    # --executable-timeout-millis=<var>EXECUTABLE_TIMEOUT</var> \
    # Optional argument for the absolute path to the executable output file.
    # See below on how this argument impacts the library behaviour.
    # --executable-output-file=<var>EXECUTABLE_OUTPUT_FILE</var> \
    --output-file /path/to/generated/config.json

Ganti kode berikut:

  • PROJECT_NUMBER: nomor project Google Cloud .
  • POOL_ID: ID workload identity pool.
  • PROVIDER_ID: ID penyedia OIDC atau SAML.
  • SERVICE_ACCOUNT_EMAIL: email akun layanan yang akan ditiru identitasnya.
  • SUBJECT_TOKEN_TYPE: jenis token subjek.
  • EXECUTABLE_COMMAND: perintah lengkap yang akan dijalankan, termasuk argumen. Harus berupa jalur absolut ke program.

Flag --executable-timeout-millis bersifat opsional; flag ini menentukan durasi (dalam milidetik) library Auth akan menunggu file yang dapat dieksekusi selesai. Jika tidak diberikan, nilai defaultnya adalah 30 detik. Nilai maksimum yang diizinkan adalah dua menit, dan minimumnya adalah lima detik.

Flag --executable-output-file opsional menentukan jalur untuk meng-cache respons kredensial pihak ketiga dari file yang dapat dieksekusi. Caching membantu meningkatkan performa karena library autentikasi akan memeriksa file ini terlebih dahulu untuk menemukan kredensial yang valid dan belum habis masa berlakunya sebelum menjalankan file yang dapat dieksekusi. Jika kredensial yang valid dan di-cache ada, library akan menggunakannya, sehingga menghindari eksekusi file yang tidak perlu.

File yang dapat dieksekusi harus menulis respons kredensial ke file ini. Library autentikasi hanya membaca dari lokasi ini. Konten file harus sesuai dengan format JSON yang diharapkan.

Untuk mengambil token pihak ketiga, library akan menjalankan file yang dapat dieksekusi menggunakan perintah yang ditentukan. Output file yang dapat dieksekusi harus mematuhi format respons yang ditentukan dalam contoh berikut, dan harus menghasilkan respons ke stdout.

Berikut adalah contoh respons OIDC yang dapat dieksekusi dan berhasil:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:id_token",
  "id_token": "HEADER.PAYLOAD.SIGNATURE",
  "expiration_time": 1620499962
}

Berikut adalah contoh respons SAML yang dapat dieksekusi dan berhasil:

{
  "version": 1,
  "success": true,
  "token_type": "urn:ietf:params:oauth:token-type:saml2",
  "saml_response": "...",
  "expiration_time": 1620499962
}

Saat Anda menentukan file output menggunakan argumen --executable-output-file dalam konfigurasi kredensial, respons file yang dapat dieksekusi yang berhasil harus menyertakan kolom expiration_time. Hal ini memungkinkan Library Auth meng-cache dan mengelola validitas kredensial yang disimpan dalam file tersebut secara efektif.

Berikut adalah contoh respons error yang dapat dieksekusi:

{
  "version": 1,
  "success": false,
  "code": "401",
  "message": "Caller not authorized."
}

Semua kolom ini wajib diisi untuk respons error. Library menggunakan kolom kode dan pesan sebagai bagian dari pengecualian yang ditampilkan.

Ringkasan kolom format respons: * version: Versi output JSON. Hanya versi 1 yang didukung. success: Jika benar, respons harus menyertakan token dan jenis token pihak ketiga. Respons juga harus menyertakan kolom expiration_time jika file output ditentukan dalam konfigurasi kredensial. File yang dapat dieksekusi juga harus keluar dengan kode keluar 0. Jika salah, respons harus menyertakan kolom kode error dan pesan, serta keluar dengan nilai bukan nol. : * token_type: Kolom ini menentukan jenis token subjek pihak ketiga. Harus berupa urn:ietf:params:oauth:token-type:jwt, urn:ietf:params:oauth:token-type:id_token, atau urn:ietf:params:oauth:token-type:saml2. * id_token: Token OIDC pihak ketiga. * saml_response: Respons SAML pihak ketiga. expiration_time: Waktu habis masa berlaku token subjek pihak ketiga dalam detik (waktu epoch Unix). * code: String kode error. * message: Pesan error.

Semua jenis respons harus menyertakan kolom version dan success. * Respons yang berhasil harus menyertakan token_type dan salah satu dari id_token atau saml_response. Kolom expiration_time juga harus ada jika file output ditentukan dalam konfigurasi kredensial. * Respons error harus menyertakan kolom code dan message.

Library mengisi variabel lingkungan berikut saat menjalankan file yang dapat dieksekusi:

  • GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE: kolom audience dari konfigurasi kredensial. Selalu ada.
  • GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE: jenis token subjek yang diharapkan ini. Selalu ada.
  • GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL: Alamat email akun layanan. Hanya ada jika peniruan akun layanan digunakan.
  • GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE: Lokasi file output dari konfigurasi kredensial. Hanya ada jika ditentukan dalam konfigurasi kredensial.

Variabel lingkungan ini dapat digunakan oleh file yang dapat dieksekusi untuk menghindari hard code nilai-nilai ini.

Pertimbangan keamanan

Praktik keamanan berikut direkomendasikan:

  • Cegah proses berbahaya menjalankan file yang dapat dieksekusi karena akan menghasilkan kredensial sensitif ke proses tersebut dan penggunanya melalui stdout.
  • Mencegah proses berbahaya mengubah konfigurasi atau pemanggilan file yang dapat dieksekusi.

Karena kompleksitas penggunaan kredensial yang bersumber dari file yang dapat dieksekusi, sebaiknya Anda menggunakan mekanisme lain yang didukung, seperti sumber file atau URL, untuk memberikan kredensial pihak ketiga, kecuali jika kredensial tersebut tidak memenuhi persyaratan khusus Anda.

Sekarang Anda dapat menggunakan library Auth untuk memanggil resourceGoogle Cloud dari penyedia OIDC atau SAML.

Menggunakan pemasok kustom dengan OIDC dan SAML

Implementasi kustom IdentityPoolSubjectTokenSupplier dapat digunakan saat membangun IdentityPoolCredentials untuk menyediakan token subjek yang dapat ditukar dengan token akses Google Cloud . Pemasok harus menampilkan token subjek yang valid dan belum habis masa berlakunya saat dipanggil oleh kredensial Google Cloud.

IdentityPoolCredentials tidak meng-cache token yang ditampilkan, jadi terapkan logika caching di penyedia token untuk mencegah beberapa permintaan untuk token subjek yang sama.

import java.io.IOException;

public class CustomTokenSupplier implements IdentityPoolSubjectTokenSupplier {

  @Override
  public String getSubjectToken(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience and subject token type.
    string audience = context.getAudience();
    string tokenType = context.getSubjectTokenType();

    try {
      // Return a valid, unexpired token for the requested audience and token type.
      // Note that IdentityPoolCredentials don't cache the subject token so
      // any caching logic needs to be implemented in the token supplier.
      return retrieveToken(audience, tokenType);
    } catch (Exception e) {
      // If token is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private String retrieveToken(string tokenType, string audience) {
    // Retrieve a subject token of the requested type for the requested audience.
  }
}

CustomTokenSupplier tokenSupplier = new CustomTokenSupplier();
IdentityPoolCredentials identityPoolCredentials =
    IdentityPoolCredentials.newBuilder()
        .setSubjectTokenSupplier(tokenSupplier) // Sets the token supplier.
        .setAudience(...) // Sets the Google Cloud audience.
        .setSubjectTokenType(SubjectTokenTypes.JWT) // Sets the subject token type.
        .build();

Dengan audiens:

//iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

Ganti kode berikut:

  • PROJECT_NUMBER: nomor project Google Cloud .
  • WORKLOAD_POOL_ID: ID workload identity pool.
  • PROVIDER_ID: ID penyedia.

Anda juga dapat menemukan nilai untuk audiens, URL peniruan akun layanan, dan kolom builder lainnya dengan membuat file konfigurasi kredensial dengan gcloud CLI.

Menggunakan pemasok kustom dengan AWS

Implementasi kustom AwsSecurityCredentialsSupplier dapat diberikan saat melakukan inisialisasi AwsCredentials. Jika disediakan, instance AwsCredentials akan menyerahkan kepada pemasok untuk mengambil kredensial keamanan AWS yang akan ditukarkan dengan token aksesGoogle Cloud . Pemasok harus menampilkan kredensial keamanan AWS yang valid dan belum habis masa berlakunya saat dipanggil oleh kredensial Google Cloud .

AwsCredentials tidak meng-cache kredensial keamanan atau region AWS yang ditampilkan, jadi terapkan logika caching di supplier untuk mencegah beberapa permintaan untuk resource yang sama.

class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
  @Override
  AwsSecurityCredentials getAwsSecurityCredentials(ExternalAccountSupplierContext context) throws IOException {
    // Any call to the supplier passes a context object with the requested
    // audience.
    String audience = context.getAudience();

    try {
      // Return valid, unexpired AWS security credentials for the requested audience.
      // Note that AwsCredentials don't cache the AWS security credentials so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsSecurityCredentials(audience);
    } catch (Exception e) {
      // If credentials are unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  @Override
  String getRegion(ExternalAccountSupplierContext context) throws IOException {
    try {
      // Return a valid AWS region. i.e. "us-east-2".
      // Note that AwsCredentials don't cache the region so
      // any caching logic needs to be implemented in the credentials' supplier.
      return retrieveAwsRegion();
    } catch (Exception e) {
      // If region is unavailable, throw IOException.
      throw new IOException(e);
    }
  }

  private AwsSecurityCredentials retrieveAwsSecurityCredentials(string audience) {
    // Retrieve Aws security credentials for the requested audience.
  }

  private String retrieveAwsRegion() {
    // Retrieve current AWS region.
  }
}

CustomAwsSupplier awsSupplier = new CustomAwsSupplier();
AwsCredentials credentials = AwsCredentials.newBuilder()
    .setSubjectTokenType(SubjectTokenTypes.AWS4) // Sets the subject token type.
    .setAudience(...) // Sets the Google Cloud audience.
    .setAwsSecurityCredentialsSupplier(supplier) // Sets the supplier.
    .build();

Dengan audiens adalah: //iam.googleapis.com/projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>WORKLOAD_POOL_ID</var>/providers/<var>PROVIDER_ID</var>

Ganti kode berikut:

  • PROJECT_NUMBER: nomor project Google Cloud .
  • WORKLOAD_POOL_ID: ID workload identity pool.
  • PROVIDER_ID: ID penyedia.

Anda juga dapat menemukan nilai untuk audiens, URL peniruan akun layanan, dan kolom builder lainnya dengan membuat file konfigurasi kredensial dengan gcloud CLI.

Masa berlaku token yang dapat dikonfigurasi

Saat membuat konfigurasi kredensial dengan workload identity federation menggunakan peniruan akun layanan, Anda dapat memberikan argumen opsional untuk mengonfigurasi masa aktif token akses akun layanan.

Untuk membuat konfigurasi dengan masa aktif token yang dapat dikonfigurasi, jalankan perintah berikut (contoh ini menggunakan konfigurasi AWS, tetapi masa aktif token dapat dikonfigurasi untuk semua penyedia workload identity federation):

  # Generate an AWS configuration file with configurable token lifetime.
  gcloud iam workload-identity-pools create-cred-config \
      projects/<var>PROJECT_NUMBER</var>/locations/global/workloadIdentityPools/<var>POOL_ID</var>/providers/<var>AWS_PROVIDER_ID</var> \
      --service-account <var>SERVICE_ACCOUNT_EMAIL</var> \
      --aws \
      --output-file /path/to/generated/config.json \
      --service-account-token-lifetime-seconds <var>TOKEN_LIFETIME</var>

Ganti kode berikut:

  • PROJECT_NUMBER: nomor project Google Cloud .
  • POOL_ID: ID workload identity pool.
  • AWS_PROVIDER_ID: ID penyedia AWS.
  • SERVICE_ACCOUNT_EMAIL: email akun layanan yang akan ditiru identitasnya.
  • TOKEN_LIFETIME: durasi masa aktif yang dipilih dari token akses akun layanan dalam detik.

Flag service-account-token-lifetime-seconds bersifat opsional. Jika tidak diberikan, flag akan ditetapkan secara default ke satu jam. Nilai minimum yang diizinkan adalah 600 (10 menit) dan nilai maksimum yang diizinkan adalah 43200 (12 jam). Jika Anda memerlukan masa aktif lebih dari satu jam, Anda harus menambahkan akun layanan sebagai nilai yang diizinkan di Organization Policy Service yang menerapkan batasan constraints/iam.allowServiceAccountCredentialLifetimeExtension.

Mengonfigurasi masa aktif yang singkat (misalnya, 10 menit) akan menyebabkan library memulai seluruh alur pertukaran token setiap 10 menit. Tindakan ini akan memanggil penyedia token pihak ketiga meskipun token pihak ketiga belum habis masa berlakunya.

Menggunakan kredensial tenaga kerja pengguna yang diberi otorisasi akun eksternal

Kredensial pengguna yang diizinkan akun eksternal memungkinkan Anda login dengan browser web ke akun penyedia identitas eksternal menggunakan gcloud CLI dan membuat konfigurasi untuk digunakan library autentikasi.

Untuk membuat konfigurasi workforce identity pengguna yang diberi otorisasi akun eksternal, jalankan perintah berikut:

gcloud auth application-default login --login-config=LOGIN_CONFIG

Dengan variabel berikut yang perlu diganti:

Tindakan ini akan membuka alur browser agar Anda dapat login menggunakan penyedia identitas pihak ketiga yang dikonfigurasi. Kemudian, library ini akan menyimpan konfigurasi pengguna yang diizinkan akun eksternal di lokasi ADC yang dikenal.

Library Auth kemudian akan menggunakan token refresh yang disediakan dari konfigurasi untuk membuat dan memperbarui token akses guna memanggil layanan Google Cloud .

Masa berlaku default token refresh adalah satu jam. Setelah itu, Anda perlu membuat konfigurasi baru dari gcloud CLI. Anda dapat mengubah masa aktif dengan mengubah durasi sesi workforce pool, dan Anda dapat menetapkannya hingga 12 jam.

Menggunakan identitas eksternal

Anda dapat menggunakan identitas eksternal dengan Application Default Credentials. Untuk menggunakan identitas eksternal dengan Kredensial Default Aplikasi, buat file konfigurasi kredensial JSON untuk identitas eksternal Anda seperti yang dijelaskan di bagian Workload Identity Federation. Setelah dibuat, simpan jalur ke file ini dalam variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS.

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/config.json

Library kini dapat memilih jenis klien yang tepat dan melakukan inisialisasi kredensial dari konteks yang disediakan file konfigurasi.

GoogleCredentials googleCredentials = GoogleCredentials.getApplicationDefault();

String projectId = "your-project-id";
String url = "https://storage.googleapis.com/storage/v1/b?project=" + projectId;

HttpCredentialsAdapter credentialsAdapter = new HttpCredentialsAdapter(googleCredentials);
HttpRequestFactory requestFactory = new NetHttpTransport().createRequestFactory(credentialsAdapter);
HttpRequest request = requestFactory.buildGetRequest(new GenericUrl(url));

JsonObjectParser parser = new JsonObjectParser(GsonFactory.getDefaultInstance());
request.setParser(parser);

HttpResponse response = request.execute();
System.out.println(response.parseAsString());

Anda juga dapat melakukan inisialisasi klien akun eksternal secara eksplisit menggunakan file konfigurasi yang dihasilkan.

ExternalAccountCredentials credentials =
    ExternalAccountCredentials.fromStream(new FileInputStream("/path/to/credentials.json"));

Pertimbangan keamanan

Library ini tidak melakukan validasi apa pun pada kolom token_url, token_info_url, atau service_account_impersonation_url dari konfigurasi kredensial. Sebaiknya jangan gunakan konfigurasi kredensial yang tidak Anda buat dengan gcloud CLI, kecuali jika Anda memverifikasi bahwa kolom URL mengarah ke domain googleapis.com.

Memperkecil cakupan dengan Batas Akses Kredensial

Memperkecil cakupan dengan Batas Akses Kredensial memungkinkan pembatasan izin Identity and Access Management (IAM) yang dapat digunakan kredensial yang berlaku singkat untuk Cloud Storage. Hal ini melibatkan pembuatan CredentialAccessBoundary yang menentukan batasan yang berlaku untuk token yang dicakupkan lebih rendah. Penggunaan kredensial dengan cakupan yang dipersempit memastikan bahwa token yang sedang dikirim selalu memiliki hak istimewa terendah. Lihat Prinsip Hak Istimewa Terendah.

Membuat CredentialAccessBoundary

Batas Akses Kredensial menentukan resource mana yang dapat diakses oleh kredensial yang baru dibuat. Batas ini juga menentukan batas atas pada izin yang tersedia di setiap resource. Laporan ini mencakup satu atau beberapa objek AccessBoundaryRule.

Cuplikan berikut menunjukkan cara melakukan inisialisasi CredentialAccessBoundary dengan satu AccessBoundaryRule. Aturan ini menentukan bahwa token yang diperkecil cakupannya akan memiliki akses hanya baca ke objek yang dimulai dengan customer-a di bucket bucket-123.

// Create the AccessBoundaryRule.
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
        CredentialAccessBoundary.AccessBoundaryRule.AvailabilityCondition.newBuilder().setExpression(expression).build())
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

Pola penggunaan umum

Pola penggunaan umum melibatkan broker token dengan akses yang ditingkatkan. Broker ini menghasilkan kredensial yang diperkecil cakupannya dari kredensial sumber akses yang lebih tinggi. Kemudian, broker token meneruskan token akses jangka pendek yang diperkecil cakupannya ke konsumen token melalui saluran terautentikasi yang aman untuk akses terbatas ke resource Google CloudStorage.

Membuat token yang dipersempit cakupannya

Ada dua cara untuk membuat token yang diperkecil cakupannya menggunakan CredentialAccessBoundary:

  • Sisi server (menggunakan DownscopedCredentials): klien memanggil Security Token Service (STS) setiap kali token dengan cakupan yang diperkecil diperlukan. Hal ini cocok untuk aplikasi yang aturan Batas Akses Kredensialnya jarang berubah atau saat Anda menggunakan kembali satu kredensial yang diperkecil cakupannya berkali-kali. Pertimbangan utamanya adalah setiap perubahan aturan mengharuskan Anda melakukan panggilan baru ke STS. Pendekatan ini tersedia dalam library google-auth-library-oauth2-http dan tidak memerlukan dependensi tambahan. Hal ini memudahkan integrasi. Ini adalah pilihan yang baik jika kasus penggunaan Anda tidak memerlukan manfaat khusus dari pendekatan sisi klien.

  • Sisi klien (menggunakan ClientSideCredentialAccessBoundaryFactory): klien mengambil materi kriptografis satu kali, lalu membuat beberapa token dengan cakupan yang dipersempit secara lokal. Hal ini meminimalkan panggilan ke STS dan lebih efisien saat aturan Batas Akses Kredensial sering berubah, karena klien tidak perlu menghubungi STS untuk setiap perubahan aturan. Hal ini juga lebih efisien untuk aplikasi yang perlu membuat banyak token unik dengan cakupan yang dipersempit. Pendekatan ini tersedia dalam modul google-auth-library-cab-token-generator. Namun, modul ini memiliki serangkaian dependensinya sendiri. Dependensi ini dapat menambah kompleksitas pada project Anda. Pertimbangkan pendekatan ini jika meminimalkan panggilan STS dan membuat banyak token unik adalah fokus utama. Anda juga perlu mengelola dependensi tambahan.

CAB sisi server

Class DownscopedCredentials dapat digunakan untuk menghasilkan token akses yang diturunkan cakupannya dari kredensial sumber dan CredentialAccessBoundary.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the DownscopedCredentials class.
DownscopedCredentials downscopedCredentials =
    DownscopedCredentials.newBuilder()
        .setSourceCredential(sourceCredentials)
        .setCredentialAccessBoundary(CredentialAccessBoundary.newBuilder().addRule(rule).build())
        .build();

// Retrieve the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = downscopedCredentials.refreshAccessToken();

CAB sisi klien

Untuk CAB sisi klien, ClientSideCredentialAccessBoundaryFactory digunakan dengan kredensial sumber. Setelah melakukan inisialisasi factory, metode generateToken() dapat dipanggil berulang kali dengan objek CredentialAccessBoundary yang berbeda untuk membuat beberapa token downscope.

// Retrieve the source credentials from ADC.
GoogleCredentials sourceCredentials = GoogleCredentials.getApplicationDefault()
        .createScoped("https://www.googleapis.com/auth/cloud-platform");

// Create an Access Boundary Rule which will restrict the downscoped token to having read-only
// access to objects starting with "customer-a" in bucket "bucket-123".
String availableResource = "//storage.googleapis.com/projects/_/buckets/bucket-123";
String availablePermission = "inRole:roles/storage.objectViewer";
String expression =  "resource.name.startsWith('projects/_/buckets/bucket-123/objects/customer-a')";

CredentialAccessBoundary.AccessBoundaryRule rule =
    CredentialAccessBoundary.AccessBoundaryRule.newBuilder()
        .setAvailableResource(availableResource)
        .addAvailablePermission(availablePermission)
        .setAvailabilityCondition(
            new AvailabilityCondition(expression, /* title= */ null, /* description= */ null))
        .build();

// Initialize the ClientSideCredentialAccessBoundaryFactory.
ClientSideCredentialAccessBoundaryFactory factory =
    ClientSideCredentialAccessBoundaryFactory.newBuilder()
        .setSourceCredential(sourceCredentials)
        .build();

// Create the CredentialAccessBoundary with the rule.
CredentialAccessBoundary credentialAccessBoundary =
        CredentialAccessBoundary.newBuilder().addRule(rule).build();

// Generate the downscoped access token.
// You will need to pass this to the Token Consumer.
AccessToken downscopedAccessToken = factory.generateToken(credentialAccessBoundary);

Menggunakan token akses yang diperkecil cakupannya

Anda dapat menyiapkan broker token di server dalam jaringan pribadi. Berbagai workload (konsumen token) dalam jaringan yang sama mengirim permintaan yang diautentikasi ke broker tersebut untuk mendapatkan token yang diperkecil cakupannya. Token ini memungkinkan mereka mengakses atau mengubah bucket Storage Google Cloud tertentu.

Broker membuat instance kredensial yang diperkecil cakupannya yang dapat menghasilkan token akses yang diperkecil cakupannya dan berumur singkat. Kemudian, token ini diteruskan ke konsumen token.

Token akses yang diperkecil cakupannya ini dapat digunakan oleh Konsumen Token menggunakan OAuth2Credentials atau OAuth2CredentialsWithRefresh. Kemudian, Anda dapat menggunakan kredensial ini untuk melakukan inisialisasi instance klien penyimpanan guna mengakses resource Google CloudStorage dengan akses terbatas.

// You can pass an `OAuth2RefreshHandler` to `OAuth2CredentialsWithRefresh` that will allow the
// library to seamlessly handle downscoped token refreshes on expiration.
OAuth2CredentialsWithRefresh.OAuth2RefreshHandler handler =
        new OAuth2CredentialsWithRefresh.OAuth2RefreshHandler() {
    @Override
    public AccessToken refreshAccessToken() {
      // Retrieve the token from your Token Broker.
      return accessToken;
    }
};

// The downscoped token is retrieved from the token broker.
AccessToken downscopedToken = handler.refreshAccessToken();

// Build the OAuth2CredentialsWithRefresh from the downscoped token and pass a refresh handler
// to handle token expiration. Passing the original downscoped token or the expiry here is optional,
// because the refresh_handler will generate the downscoped token on demand.
OAuth2CredentialsWithRefresh credentials =
    OAuth2CredentialsWithRefresh.newBuilder()
        .setAccessToken(downscopedToken)
        .setRefreshHandler(handler)
        .build();

// Use the credentials with the Cloud Storage SDK.
StorageOptions options = StorageOptions.newBuilder().setCredentials(credentials).build();
Storage storage = options.getService();

// Call Cloud Storage APIs.
// Because we passed the downscoped credential, we will have limited read-only access to objects
// starting with "customer-a" in bucket "bucket-123".
storage.get(...)

Hanya Cloud Storage yang mendukung Batas Akses Kredensial; layanan Google Cloud lainnya tidak mendukung fitur ini.

Menggunakan kredensial dengan google-http-client

Kredensial yang disediakan oleh com.google.auth:google-auth-library-oauth2-http dapat digunakan dengan klien berbasis HTTP Google. Klien berbasis HTTP Google menyediakan HttpCredentialsAdapter yang dapat digunakan sebagai HttpRequestInitializer, argumen terakhir untuk builder-nya.

import com.google.api.client.http.HttpRequestInitializer;
import com.google.api.services.bigquery.Bigquery;
import com.google.auth.http.HttpCredentialsAdapter;
import com.google.auth.oauth2.GoogleCredentials;

GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
HttpRequestInitializer requestInitializer = new HttpCredentialsAdapter(credentials);

Bigquery bq = new Bigquery.Builder(HTTP_TRANSPORT, JSON_FACTORY, requestInitializer)
    .setApplicationName(APPLICATION_NAME)
    .build();

Memverifikasi Token JWT (Fitur beta)

Untuk memverifikasi token JWT, gunakan class TokenVerifier.

Memverifikasi tanda tangan

Untuk memverifikasi tanda tangan, gunakan TokenVerifier default:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder().build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

Menyesuaikan TokenVerifier

Untuk menyesuaikan TokenVerifier, buat instance menggunakan builder-nya:

import com.google.api.client.json.webtoken.JsonWebSignature;
import com.google.auth.oauth2.TokenVerifier;

TokenVerifier tokenVerifier = TokenVerifier.newBuilder()
  .setAudience("audience-to-verify")
  .setIssuer("issuer-to-verify")
  .build();
try {
  JsonWebSignature jsonWebSignature = tokenVerifier.verify(tokenString);
  // Optionally, verify additional claims.
  if (!"expected-value".equals(jsonWebSignature.getPayload().get("additional-claim"))) {
    // Handle custom verification error.
  }
} catch (TokenVerifier.VerificationException e) {
  // The token is invalid.
}

Untuk opsi lainnya, lihat dokumentasi TokenVerifier.Builder.

google-auth-library-credentials

Artefak ini berisi class dasar dan antarmuka untuk kredensial Google:

  • Credentials: ini adalah class dasar untuk identitas yang diizinkan. Implementasi class ini dapat memberikan otorisasi pada aplikasi Anda.
  • RequestMetadataCallback: ini adalah antarmuka untuk callback yang menerima hasil Credentials.getRequestMetadata(URI, Executor, RequestMetadataCallback) asinkron.
  • ServiceAccountSigner: ini adalah antarmuka untuk penanda tangan akun layanan. Implementasi class ini dapat menandatangani array byte menggunakan kredensial yang terkait dengan Akun Layanan Google.

google-auth-library-appengine

Artefak ini bergantung pada App Engine SDK (appengine-api-1.0-sdk). Gunakan hanya untuk aplikasi yang berjalan di lingkungan App Engine yang menggunakan urlfetch. Class AppEngineCredentials memungkinkan Anda mengizinkan aplikasi App Engine dengan instance AppIdentityService.

Penggunaan:

import com.google.appengine.api.appidentity.AppIdentityService;
import com.google.appengine.api.appidentity.AppIdentityServiceFactory;
import com.google.auth.Credentials;
import com.google.auth.appengine.AppEngineCredentials;

AppIdentityService appIdentityService = AppIdentityServiceFactory.getAppIdentityService();

Credentials credentials =
    AppEngineCredentials.newBuilder()
        .setScopes(...)
        .setAppIdentityService(appIdentityService)
        .build();

google-auth-library-cab-token-generator

Modul ini menyediakan class ClientSideCredentialAccessBoundaryFactory, yang memungkinkan pembuatan token yang diperkecil cakupannya di sisi klien untuk Cloud Storage menggunakan Batas Akses Kredensial. Pendekatan ini sangat berguna untuk aplikasi yang memerlukan perubahan rutin pada aturan Batas Akses Kredensial atau pembuatan banyak token downscoped yang unik, karena pendekatan ini meminimalkan panggilan ke Security Token Service (STS). Untuk contoh penggunaan, lihat bagian CAB sisi klien. Modul ini dilengkapi dengan kumpulan dependensinya sendiri. Evaluasi apakah manfaat penurunan cakupan sisi klien lebih besar daripada kompleksitas tambahan untuk kasus penggunaan spesifik Anda.