Mulai menggunakan Library Google Auth

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

Google Auth Library 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 memberikan 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 stream, 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 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

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 submodule 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 di 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"

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:

Library Klien Cloud: Library ini otomatis menggunakan Kredensial Default Aplikasi (ADC), sehingga Anda tidak perlu memberikan kredensial dalam kode.
Library Klien Google API: Anda harus membuat instance GoogleCredentials dan meneruskannya ke klien. Sebagai contoh, lihat Panduan Klien Java Google API.

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 tingkat otorisasi dan identitas 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:

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

Gunakan ImpersonatedCredentials untuk mengizinkan kredensial (akun utama) meniru identitas akun layanan (target). Dengan begitu, prinsipal dapat 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.iam.gserviceaccount.com")
        .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);
}

Workload Identity Federation

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

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

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 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 di-impersonate.

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 Google Cloud resource dari Microsoft Azure, Anda harus mengonfigurasi workload identity federation terlebih dahulu. Proses penyiapan dijelaskan dalam Mengakses resource dari Azure.

# 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 di-impersonate.

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

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

Mengakses resource dari penyedia identitas OIDC

Untuk mengakses Google Cloud resource 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 memuat ulang lokasi file dengan token OIDC baru sebelum masa berlaku token berakhir. 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 di-impersonate.
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 memberikan 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 identitas workload 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 di-impersonate.
URL_TO_GET_OIDC_TOKEN: URL endpoint server lokal yang akan dipanggil untuk mengambil token OIDC.
HEADER_KEY dan HEADER_VALUE: pasangan nilai kunci 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 Google Cloud resource 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 mencakup tanggal habis masa berlaku dan harus diperpanjang sebelum habis masa berlakunya untuk mempertahankan akses.

Untuk mengetahui informasi selengkapnya, lihat dokumentasi resmi.

Membuat file konfigurasi untuk federasi 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.

Perilaku default (direkomendasikan)

Jika Anda tidak menyertakan flag --credential-cert-configuration-output-file, gcloud akan membuat file konfigurasi sertifikat di lokasi default yang sudah dikenal yang 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 di-impersonate.
PATH_TO_CERTIFICATE: jalur tempat sertifikat X.509 leaf Anda berada.
PATH_TO_PRIVATE_KEY: jalur tempat kunci pribadi yang sesuai untuk sertifikat leaf 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 leaf dan trust store yang dikonfigurasi di pool Workload Identity Federation. Sertifikat leaf 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 ~/.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 akan 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 tanda.

Sekarang Anda dapat menggunakan library Auth untuk memanggil Google Cloud resource 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 di-impersonate.
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) yang akan digunakan library Auth untuk menunggu hingga file yang dapat dieksekusi selesai. Jika tidak diberikan, defaultnya adalah 30 detik. Nilai maksimum yang diizinkan adalah dua menit, dan nilai minimumnya adalah lima detik.

Flag --executable-output-file opsional menentukan jalur untuk menyimpan respons kredensial pihak ketiga dari file yang dapat dieksekusi ke cache. Caching membantu meningkatkan performa karena library autentikasi akan memeriksa file ini terlebih dahulu untuk mendapatkan 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 yang tidak perlu.

Dapat dieksekusi Anda harus menulis respons kredensial ke file ini. Library auth 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 sesuai dengan format respons yang ditentukan dalam contoh berikut, dan harus menampilkan 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 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 yang dapat dieksekusi yang berhasil harus menyertakan kolom expiration_time. Dengan demikian, Auth Library dapat secara efektif meng-cache dan mengelola validitas kredensial yang disimpan dalam file tersebut.

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 (true), respons harus menyertakan token pihak ketiga dan jenis token. 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 (false), respons harus menyertakan kolom kode dan pesan error 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 audiens 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 hardcode nilai-nilai ini.

Pertimbangan keamanan

Praktik keamanan berikut direkomendasikan:

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

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 mekanisme tersebut tidak memenuhi persyaratan spesifik Anda.

Sekarang Anda dapat menggunakan library Auth untuk memanggil Google Cloud resource 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 jangan menyimpan token yang ditampilkan dalam cache, jadi terapkan logika penyimpanan dalam cache 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();

Lokasi 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 menginisialisasi AwsCredentials. Jika disediakan, instance AwsCredentials akan menggunakan supplier untuk mengambil kredensial keamanan AWS untuk ditukar 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 menyimpan kredensial keamanan dan region AWS yang ditampilkan dalam cache, jadi terapkan logika penyimpanan dalam cache di penyedia 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();

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

Masa berlaku token yang dapat dikonfigurasi

Saat membuat konfigurasi kredensial dengan workload identity federation menggunakan peniruan identitas 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 di-impersonate.
TOKEN_LIFETIME: durasi masa aktif yang dipilih untuk token akses akun layanan dalam detik.

Flag service-account-token-lifetime-seconds bersifat opsional. Jika tidak diberikan, tanda defaultnya adalah satu jam. Nilai minimum yang diizinkan adalah 600 (10 menit) dan nilai maksimum yang diizinkan adalah 43200 (12 jam). Jika Anda memerlukan masa aktif yang lebih dari satu jam, Anda harus menambahkan akun layanan sebagai nilai yang diizinkan di Layanan Kebijakan Organisasi 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. Hal ini 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 sah untuk akun eksternal memungkinkan Anda login dengan browser web ke akun penyedia identitas eksternal menggunakan gcloud CLI dan membuat konfigurasi untuk digunakan oleh pustaka autentikasi.

Untuk membuat konfigurasi identitas tenaga kerja pengguna yang diizinkan akun eksternal, jalankan perintah berikut:

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

Dengan variabel berikut yang perlu diganti:

LOGIN_CONFIG: file konfigurasi login yang dibuat dengan konsol Google Cloud atau gcloud iam workforce-pools create-login-config

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

Kemudian, library Auth akan menggunakan token refresh yang diberikan 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 kumpulan tenaga kerja, dan Anda dapat menyetelnya 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 menginisialisasi 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 secara eksplisit menginisialisasi klien akun eksternal 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 diperkecil cakupannya. Penggunaan kredensial yang cakupannya dipersempit memastikan bahwa token dalam proses 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. Hal ini juga menentukan batas atas pada izin yang tersedia di setiap resource. Objek ini mencakup satu atau beberapa objek AccessBoundaryRule.

Cuplikan berikut menunjukkan cara menginisialisasi CredentialAccessBoundary dengan satu AccessBoundaryRule. Aturan ini menentukan bahwa token yang cakupannya dipersempit 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 membuat kredensial yang diturunkan cakupannya dari kredensial sumber akses yang lebih tinggi. Kemudian, token tersebut meneruskan token akses jangka pendek yang diperkecil cakupannya ke konsumen token melalui saluran terautentikasi yang aman untuk akses terbatas ke Google Cloud resource Storage.

Membuat token yang cakupannya lebih sempit

Ada dua cara untuk membuat token yang cakupannya lebih sempit menggunakan CredentialAccessBoundary:

Sisi server (menggunakan DownscopedCredentials): klien memanggil Security Token Service (STS) setiap kali token dengan cakupan terbatas diperlukan. Hal ini cocok untuk aplikasi yang aturan Batas Akses Kredensialnya jarang berubah atau tempat Anda menggunakan kembali satu kredensial yang diperkecil cakupannya berkali-kali. Pertimbangan utama 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 mempermudah 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 kriptografi satu kali, lalu membuat beberapa token dengan cakupan terbatas secara lokal. Hal ini meminimalkan panggilan ke STS dan lebih efisien saat aturan Credential Access Boundary sering berubah, karena klien tidak perlu menghubungi STS untuk setiap perubahan aturan. Cara ini juga lebih efisien untuk aplikasi yang perlu membuat banyak token yang dicakup ke bawah yang unik. Pendekatan ini tersedia di modul google-auth-library-cab-token-generator. Namun, modul ini memiliki serangkaian dependensinya sendiri. Dependensi ini dapat menambah kompleksitas project Anda. Pertimbangkan pendekatan ini jika meminimalkan panggilan STS dan membuat banyak token unik adalah perhatian utama. Anda juga perlu mengelola dependensi tambahan.

CAB sisi server

Class DownscopedCredentials dapat digunakan untuk menghasilkan token akses yang di-downscope 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 menginisialisasi factory, metode generateToken() dapat dipanggil berulang kali dengan objek CredentialAccessBoundary yang berbeda untuk membuat beberapa token yang cakupannya dikecilkan.

// 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 beban kerja (konsumen token) dalam jaringan yang sama mengirim permintaan terautentikasi ke broker tersebut untuk mendapatkan token yang diperkecil cakupannya. Token ini memungkinkan mereka mengakses atau mengubah bucket penyimpanan Google Cloud tertentu.

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

Token akses yang diperkecil cakupannya ini dapat digunakan oleh Konsumen Token menggunakan OAuth2Credentials atau OAuth2CredentialsWithRefresh. Anda kemudian dapat menggunakan kredensial ini untuk menginisialisasi instance klien penyimpanan guna mengakses resource Storage dengan akses terbatas. Google Cloud

// 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; layananGoogle 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 pembuatnya.

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-nya 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 dan antarmuka dasar untuk kredensial Google:

Credentials: ini adalah class dasar untuk identitas yang sah. Implementasi class ini dapat mengizinkan 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 memberikan 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 Credential Access Boundary atau pembuatan banyak token yang cakupannya lebih sempit dan unik, karena meminimalkan panggilan ke Security Token Service (STS). Untuk contoh penggunaan, lihat bagian CAB sisi klien. Modul ini memiliki serangkaian dependensinya sendiri. Evaluasi apakah manfaat pembatasan cakupan sisi klien lebih besar daripada kompleksitas tambahan untuk kasus penggunaan spesifik Anda.

Mulai menggunakan Library Google Auth Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Memvalidasi konfigurasi kredensial

Mengimpor Library Auth

Java SDK libraries-bom

Bill of Materials Library Google Auth

Maven

Gradle

Scala

Migrasi dari GoogleCredential ke GoogleCredentials

Kredensial Default Aplikasi

Mendapatkan Kredensial Default Aplikasi

Pemuatan kredensial eksplisit

Kredensial yang dipalsukan

Workload Identity Federation

Mengakses resource dari AWS

Mengakses resource dari Microsoft Azure

Mengakses resource dari penyedia identitas OIDC

Kredensial dari file

Kredensial dari URL

Mengakses resource menggunakan kredensial yang bersumber dari sertifikat X.509

Membuat file konfigurasi untuk federasi X.509

Perilaku default (direkomendasikan)

Perilaku lokasi kustom

Menggunakan kredensial dari file yang dapat dieksekusi dengan OIDC dan SAML

Pertimbangan keamanan

Menggunakan pemasok kustom dengan OIDC dan SAML

Menggunakan pemasok kustom dengan AWS

Masa berlaku token yang dapat dikonfigurasi

Menggunakan kredensial tenaga kerja pengguna yang diberi otorisasi akun eksternal

Menggunakan identitas eksternal

Pertimbangan keamanan

Memperkecil cakupan dengan Batas Akses Kredensial

Membuat CredentialAccessBoundary

Pola penggunaan umum

Membuat token yang cakupannya lebih sempit

CAB sisi server

CAB sisi klien

Menggunakan token akses yang diperkecil cakupannya

Menggunakan kredensial dengan google-http-client

Memverifikasi Token JWT (Fitur beta)

Memverifikasi tanda tangan

Menyesuaikan TokenVerifier

google-auth-library-credentials

google-auth-library-appengine

google-auth-library-cab-token-generator

Mulai menggunakan Library Google Auth

Migrasi dari `GoogleCredential` ke `GoogleCredentials`

Membuat `CredentialAccessBoundary`

Menggunakan kredensial dengan `google-http-client`

Menyesuaikan `TokenVerifier`

`google-auth-library-credentials`

`google-auth-library-appengine`