google auth library java

Perpustakaan Google Auth

Pustaka klien autentikasi sumber terbuka untuk Java.

• Dokumentasi API

Proyek ini terdiri dari 3 artefak:

• google-auth-library-credentials : berisi kelas dasar dan antarmuka untuk kredensial Google
• google-auth-library-appengine : berisi kredensial App Engine. Artefak ini bergantung pada App Engine SDK.
• google-auth-library-oauth2-http : berisi beragam kredensial serta metode utilitas untuk membuatnya dan untuk mendapatkan Kredensial Default Aplikasi

Daftar isi:

• Mulai cepat

• google-auth-library-oauth2-http

  • Kredensial Default Aplikasi
  • Kredensial yang Ditiru
  • Federasi Identitas Beban Kerja
    • Mengakses sumber daya dari AWS
    • Mengakses sumber daya dari Azure
    • Mengakses sumber daya dari penyedia identitas OIDC
    • Mengakses sumber daya menggunakan kredensial bersumber yang dapat dieksekusi
    • Mengakses sumber daya menggunakan pemasok khusus untuk OIDC atau SAML
    • Mengakses sumber daya menggunakan pemasok khusus dengan AWS
    • Seumur Hidup Token yang Dapat Dikonfigurasi
  • Federasi Identitas Tenaga Kerja
    • Mengakses sumber daya menggunakan penyedia identitas OIDC atau SAML 2.0
    • Mengakses sumber daya menggunakan kredensial tenaga kerja pengguna resmi akun eksternal
    • Mengakses sumber daya menggunakan kredensial bersumber yang dapat dieksekusi
    • Mengakses sumber daya menggunakan pemasok khusus untuk OIDC atau SAML
  • Downscoping dengan Batasan Akses Kredensial
  • Mengonfigurasi Proksi
  • Menggunakan Kredensial dengan google-http-client
  • Memverifikasi Token JWT

• kredensial-perpustakaan-google-auth

• google-auth-library-appengine

• Status CI

• Berkontribusi

• Lisensi

Mulai cepat

Jika Anda menggunakan Maven, tambahkan ini ke file pom.xml Anda (perhatikan bahwa Anda dapat mengganti google-auth-library-oauth2-http dengan google-auth-library-credentials dan google-auth-library-appengine , tergantung pada kebutuhan aplikasi Anda):

< dependency >
  < groupId >com.google.authgroupId >
  < artifactId >google-auth-library-oauth2-httpartifactId >
  < version >1.19.0version >
dependency >

Jika Anda menggunakan Gradle, tambahkan ini ke dependensi Anda

implementation ' com.google.auth:google-auth-library-oauth2-http:1.19.0 '

Jika Anda menggunakan SBT, tambahkan ini ke dependensi Anda

libraryDependencies + = " com.google.auth " % " google-auth-library-oauth2-http " % " 1.19.0 " 

google-auth-library-oauth2-http

Kredensial Default Aplikasi

Pustaka ini menyediakan implementasi Kredensial Default Aplikasi untuk Java. Kredensial Default Aplikasi memberikan cara sederhana untuk mendapatkan kredensial otorisasi untuk digunakan dalam memanggil Google API.

Mereka paling cocok untuk kasus-kasus ketika panggilan harus memiliki tingkat identitas dan otorisasi yang sama untuk aplikasi yang independen dari pengguna. Ini adalah pendekatan yang direkomendasikan untuk mengotorisasi panggilan ke Cloud API, khususnya saat Anda membuat aplikasi yang menggunakan Google Cloud Platform.

Kredensial Default Aplikasi juga mendukung federasi identitas beban kerja untuk mengakses sumber daya Google Cloud dari platform non-Google Cloud termasuk Amazon Web Services (AWS), Microsoft Azure, atau penyedia identitas apa pun yang mendukung OpenID Connect (OIDC). Federasi identitas beban kerja direkomendasikan untuk lingkungan non-Google Cloud karena menghindari kebutuhan untuk mendownload, mengelola, dan menyimpan kunci pribadi akun layanan secara lokal, lihat: Federasi Identitas Beban Kerja.

Mendapatkan Kredensial Default Aplikasi

Untuk mendapatkan Kredensial Default Aplikasi, gunakan GoogleCredentials.getApplicationDefault() atau GoogleCredentials.getApplicationDefault(HttpTransportFactory) . Metode ini mengembalikan Kredensial Default Aplikasi yang digunakan untuk mengidentifikasi dan mengotorisasi seluruh aplikasi. Berikut ini dicari (untuk) menemukan Kredensial Default Aplikasi:

1. File kredensial yang ditunjuk oleh variabel lingkungan GOOGLE_APPLICATION_CREDENTIALS
2. Kredensial yang diberikan oleh perintah gcloud auth application-default login Google Cloud SDK
3. Kredensial bawaan Google App Engine
4. Kredensial bawaan Google Cloud Shell
5. Kredensial bawaan Google Compute Engine
   • Lewati pemeriksaan ini dengan menyetel variabel lingkungan NO_GCE_CHECK=true
   • Sesuaikan alamat server metadata GCE dengan mengatur variabel lingkungan GCE_METADATA_HOST=

Pemuatan Kredensial Eksplisit

Untuk mendapatkan Kredensial dari kunci JSON Akun Layanan, gunakan GoogleCredentials.fromStream(InputStream) atau GoogleCredentials.fromStream(InputStream, HttpTransportFactory) . Perhatikan bahwa kredensial harus di-refresh 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

Mengizinkan kredensial yang dikeluarkan untuk pengguna atau akun layanan untuk meniru identitas orang lain. Proyek sumber yang menggunakan ImpersonatedCredentials harus mengaktifkan API "IAMCredentials". Selain itu, akun layanan target harus memberikan peran IAM "Pembuat Token Akun Layanan" kepada entitas utama asal.

 String credPath = "/path/to/svc_account.json" ;
ServiceAccountCredentials sourceCredentials = ServiceAccountCredentials
     . fromStream ( new FileInputStream ( credPath ));
sourceCredentials = ( ServiceAccountCredentials ) sourceCredentials
    . createScoped ( Arrays . asList ( "https://www.googleapis.com/auth/iam" ));

ImpersonatedCredentials targetCredentials = ImpersonatedCredentials . create ( sourceCredentials ,
    "[email protected]" , null ,
    Arrays . asList ( "https://www.googleapis.com/auth/devstorage.read_only" ), 300 );

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

for ( Bucket b : storage_service . list (). iterateAll ())
    System . out . println ( b ); 

Federasi Identitas Beban Kerja

Dengan menggunakan federasi identitas beban kerja, aplikasi Anda dapat mengakses sumber daya Google Cloud 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 resource Google Cloud. Dengan menggunakan federasi identitas, beban kerja Anda dapat meniru identitas akun layanan. Hal ini memungkinkan beban kerja eksternal mengakses resource Google Cloud secara langsung, sehingga menghilangkan beban pemeliharaan dan keamanan yang terkait dengan kunci akun layanan.

Mengakses sumber daya dari AWS

Untuk mengakses sumber daya Google Cloud dari Amazon Web Services (AWS), diperlukan persyaratan berikut:

• Kumpulan identitas beban kerja perlu dibuat.
• AWS perlu ditambahkan sebagai penyedia identitas di kumpulan identitas beban kerja (kebijakan organisasi Google harus mengizinkan federasi dari AWS).
• Izin untuk menyamar sebagai akun layanan perlu diberikan kepada identitas eksternal.

Ikuti petunjuk mendetail tentang cara mengonfigurasi federasi identitas beban kerja dari AWS.

Setelah mengonfigurasi penyedia AWS untuk meniru akun layanan, file konfigurasi kredensial perlu dibuat. Tidak seperti file kredensial akun layanan, file konfigurasi kredensial yang dihasilkan berisi metadata non-sensitif untuk menginstruksikan perpustakaan tentang cara mengambil token subjek eksternal dan menukarnya dengan token akses akun layanan. File konfigurasi dapat dibuat dengan menggunakan gcloud CLI.

Untuk menghasilkan konfigurasi identitas beban kerja AWS, jalankan perintah berikut:

 # Generate an AWS configuration file.
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

Dimana variabel berikut perlu diganti:

• $PROJECT_NUMBER : Nomor proyek Google Cloud.
• $POOL_ID : ID kumpulan identitas beban kerja.
• $AWS_PROVIDER_ID : ID penyedia AWS.
• $SERVICE_ACCOUNT_EMAIL : Email akun layanan yang akan ditiru.

Ini menghasilkan file konfigurasi dalam file output yang ditentukan.

Jika Anda menggunakan AWS IMDSv2, tanda tambahan --enable-imdsv2 perlu ditambahkan 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

Anda sekarang dapat menggunakan perpustakaan Auth untuk memanggil sumber daya Google Cloud dari AWS.

Akses sumber daya dari Microsoft Azure

Untuk mengakses resource Google Cloud dari Microsoft Azure, diperlukan persyaratan berikut:

• Kumpulan identitas beban kerja perlu dibuat.
• Azure perlu ditambahkan sebagai penyedia identitas di kumpulan identitas beban kerja (kebijakan organisasi Google harus mengizinkan federasi dari Azure).
• Penyewa Azure perlu dikonfigurasi untuk federasi identitas.
• Izin untuk menyamar sebagai akun layanan perlu diberikan kepada identitas eksternal.

Ikuti petunjuk mendetail tentang cara mengonfigurasi federasi identitas beban kerja dari Microsoft Azure.

Setelah mengonfigurasi penyedia Azure untuk meniru akun layanan, file konfigurasi kredensial perlu dibuat. Tidak seperti file kredensial akun layanan, file konfigurasi kredensial yang dihasilkan berisi metadata non-sensitif untuk menginstruksikan perpustakaan tentang cara mengambil token subjek eksternal dan menukarnya dengan token akses akun layanan. File konfigurasi dapat dibuat dengan menggunakan gcloud CLI.

Untuk menghasilkan konfigurasi identitas beban kerja Azure, jalankan perintah berikut:

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

Dimana variabel berikut perlu diganti:

• $PROJECT_NUMBER : Nomor proyek Google Cloud.
• $POOL_ID : ID kumpulan identitas beban kerja.
• $AZURE_PROVIDER_ID : ID penyedia Azure.
• $SERVICE_ACCOUNT_EMAIL : Email akun layanan yang akan ditiru.

Ini menghasilkan file konfigurasi dalam file output yang ditentukan.

Anda sekarang dapat menggunakan perpustakaan Auth untuk memanggil sumber daya Google Cloud dari Azure.

Mengakses sumber daya dari penyedia identitas OIDC

Untuk mengakses resource Google Cloud dari penyedia identitas yang mendukung OpenID Connect (OIDC), diperlukan persyaratan berikut:

• Kumpulan identitas beban kerja perlu dibuat.
• Penyedia identitas OIDC perlu ditambahkan di kumpulan identitas beban kerja (kebijakan organisasi Google harus mengizinkan penggabungan dari penyedia identitas).
• Izin untuk menyamar sebagai akun layanan perlu diberikan kepada identitas eksternal.

Ikuti petunjuk mendetail tentang cara mengonfigurasi federasi identitas beban kerja dari penyedia identitas OIDC.

Setelah mengonfigurasi penyedia OIDC untuk meniru akun layanan, file konfigurasi kredensial perlu dibuat. Tidak seperti file kredensial akun layanan, file konfigurasi kredensial yang dihasilkan berisi metadata non-sensitif untuk menginstruksikan perpustakaan tentang cara mengambil token subjek eksternal dan menukarnya dengan token akses akun layanan. File konfigurasi dapat dibuat dengan menggunakan gcloud CLI.

Untuk penyedia OIDC, perpustakaan Auth dapat mengambil token OIDC baik dari lokasi file lokal (kredensial bersumber file) atau dari server lokal (kredensial bersumber URL).

Kredensial bersumber file Untuk kredensial bersumber file, proses latar belakang harus terus menyegarkan lokasi file dengan token OIDC baru sebelum masa berlakunya habis. Untuk token dengan masa hidup satu jam, token perlu diperbarui dalam file setiap jam. Token dapat disimpan langsung sebagai teks biasa atau dalam format JSON.

Untuk menghasilkan konfigurasi OIDC bersumber file, jalankan perintah berikut:

 # Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workload-identity-pools create-cred-config 
    projects/ $PROJECT_NUMBER /locations/global/workloadIdentityPools/ $POOL_ID /providers/ $OIDC_PROVIDER_ID 
    --service-account $SERVICE_ACCOUNT_EMAIL 
    --credential-source-file $PATH_TO_OIDC_ID_TOKEN 
    # 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

Dimana variabel berikut perlu diganti:

• $PROJECT_NUMBER : Nomor proyek Google Cloud.
• $POOL_ID : ID kumpulan identitas beban kerja.
• $OIDC_PROVIDER_ID : ID penyedia OIDC.
• $SERVICE_ACCOUNT_EMAIL : Email akun layanan yang akan ditiru.
• $PATH_TO_OIDC_ID_TOKEN : Jalur file yang digunakan untuk mengambil token OIDC.

Ini menghasilkan file konfigurasi dalam file output yang ditentukan.

Kredensial bersumber URL Untuk kredensial bersumber URL, server lokal perlu menghosting titik akhir GET untuk mengembalikan token OIDC. Responsnya bisa dalam teks biasa atau JSON. Header permintaan tambahan yang diperlukan juga dapat ditentukan.

Untuk menghasilkan konfigurasi identitas beban kerja OIDC yang bersumber dari URL, jalankan perintah berikut:

 # Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workload-identity-pools create-cred-config 
    projects/ $PROJECT_NUMBER /locations/global/workloadIdentityPools/ $POOL_ID /providers/ $OIDC_PROVIDER_ID 
    --service-account $SERVICE_ACCOUNT_EMAIL 
    --credential-source-url $URL_TO_GET_OIDC_TOKEN 
    --credential-source-headers $HEADER_KEY = $HEADER_VALUE 
    # 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

Dimana variabel berikut perlu diganti:

• $PROJECT_NUMBER : Nomor proyek Google Cloud.
• $POOL_ID : ID kumpulan identitas beban kerja.
• $OIDC_PROVIDER_ID : ID penyedia OIDC.
• $SERVICE_ACCOUNT_EMAIL : Email akun layanan yang akan ditiru.
• $URL_TO_GET_OIDC_TOKEN : URL titik akhir server lokal yang akan dipanggil untuk mengambil token OIDC.
• $HEADER_KEY dan $HEADER_VALUE : Pasangan kunci/nilai header tambahan untuk meneruskan permintaan GET ke $URL_TO_GET_OIDC_TOKEN , misalnya Metadata-Flavor=Google .

Anda sekarang dapat menggunakan perpustakaan Auth untuk memanggil sumber daya Google Cloud dari penyedia OIDC.

Menggunakan kredensial bersumber yang dapat dieksekusi dengan OIDC dan SAML

Kredensial bersumber yang dapat dieksekusi Untuk kredensial bersumber yang dapat dieksekusi, executable lokal digunakan untuk mengambil token pihak ketiga. Eksekusi harus menangani penyediaan token ID OIDC yang valid dan belum kedaluwarsa atau pernyataan SAML dalam format JSON ke stdout.

Untuk menggunakan kredensial bersumber yang dapat dieksekusi, variabel lingkungan GOOGLE_EXTERNAL_ACCOUNT_ALLOW_EXECUTABLES harus disetel ke 1 .

Untuk menghasilkan konfigurasi identitas beban kerja bersumber yang dapat dieksekusi, jalankan perintah berikut:

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

Dimana variabel berikut perlu diganti:

• $PROJECT_NUMBER : Nomor proyek Google Cloud.
• $POOL_ID : ID kumpulan identitas beban kerja.
• $PROVIDER_ID : ID penyedia OIDC atau SAML.
• $SERVICE_ACCOUNT_EMAIL : Email akun layanan yang akan ditiru.
• $SUBJECT_TOKEN_TYPE : Jenis token subjek.
• $EXECUTABLE_COMMAND : Perintah lengkap untuk dijalankan, termasuk argumen. Harus menjadi jalur mutlak menuju program.

Bendera --executable-timeout-millis bersifat opsional. Ini adalah durasi menunggu perpustakaan autentikasi hingga eksekusi selesai, dalam milidetik. Defaultnya adalah 30 detik jika tidak disediakan. Nilai maksimum yang diperbolehkan adalah 2 menit. Minimal adalah 5 detik.

Bendera --executable-output-file bersifat opsional. Jika disediakan, jalur file harus mengarah ke respons kredensial 3PI yang dihasilkan oleh file yang dapat dieksekusi. Ini berguna untuk menyimpan kredensial dalam cache. Dengan menentukan jalur ini, perpustakaan Auth akan memeriksa keberadaannya terlebih dahulu sebelum menjalankan file yang dapat dieksekusi. Dengan melakukan cache respons JSON yang dapat dieksekusi ke file ini, hal ini meningkatkan kinerja karena menghindari kebutuhan untuk menjalankan file yang dapat dieksekusi hingga kredensial yang di-cache dalam file output kedaluwarsa. Eksekusi harus menangani penulisan ke file ini - perpustakaan autentikasi hanya akan mencoba membaca dari lokasi ini. Format konten dalam file harus sesuai dengan format JSON yang diharapkan oleh file yang dapat dieksekusi seperti yang ditunjukkan di bawah ini.

Untuk mengambil token pihak ketiga, perpustakaan akan memanggil executable menggunakan perintah yang ditentukan. Output yang dapat dieksekusi harus mematuhi format respons yang ditentukan di bawah. Itu harus menampilkan respons ke stdout.

Contoh respons OIDC yang berhasil dieksekusi:

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

Contoh respons SAML yang berhasil dieksekusi:

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

Contoh respons kesalahan yang dapat dieksekusi:

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

Ini semua adalah bidang yang wajib diisi untuk respons kesalahan. Bidang kode dan pesan akan digunakan oleh perpustakaan sebagai bagian dari pengecualian yang diberikan.

Agar respons berhasil, bidang expiration_time hanya diperlukan ketika file output ditentukan dalam konfigurasi kredensial.

Ringkasan bidang format respons:

• version : Versi keluaran JSON. Saat ini hanya versi 1 yang didukung.
• success : Jika benar, respons harus berisi token pihak ketiga dan jenis token. Responsnya juga harus berisi bidang expired_time jika file output ditentukan dalam konfigurasi kredensial. Eksekusi juga harus keluar dengan kode keluar 0. Jika salah, respons harus berisi kode kesalahan dan kolom pesan dan keluar dengan nilai bukan nol.
• token_type : Jenis token subjek pihak ketiga. Harus 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 kedaluwarsa token subjek pihak ketiga dalam hitungan detik (unix epoch time).
• code : String kode kesalahan.
• message : Pesan kesalahan.

Semua tipe respons harus menyertakan kolom version dan success .

• Respons yang berhasil harus menyertakan token_type dan salah satu dari id_token atau saml_response . Bidang expiration_time juga harus ada jika file output ditentukan dalam konfigurasi kredensial.
• Respons kesalahan harus menyertakan kolom code dan message .

Perpustakaan akan mengisi variabel lingkungan berikut ketika executable dijalankan:

• GOOGLE_EXTERNAL_ACCOUNT_AUDIENCE : Bidang audiens dari konfigurasi kredensial. Selalu hadir.
• GOOGLE_EXTERNAL_ACCOUNT_TOKEN_TYPE : Jenis token subjek yang diharapkan. Selalu hadir.
• GOOGLE_EXTERNAL_ACCOUNT_IMPERSONATED_EMAIL : Email akun layanan. Hanya ada ketika peniruan identitas akun layanan digunakan.
• GOOGLE_EXTERNAL_ACCOUNT_OUTPUT_FILE : Lokasi file keluaran dari konfigurasi kredensial. Hanya ada ketika ditentukan dalam konfigurasi kredensial.

Variabel lingkungan ini dapat digunakan oleh executable untuk menghindari hard-coding nilai-nilai ini.

Pertimbangan keamanan

Praktik keamanan berikut sangat disarankan:

• Akses ke skrip harus dibatasi karena akan menampilkan kredensial ke stdout. Hal ini memastikan bahwa proses jahat tidak mendapatkan akses ke skrip.
• File konfigurasi tidak boleh dimodifikasi. Akses tulis harus dibatasi untuk menghindari proses memodifikasi bagian perintah yang dapat dieksekusi.

Mengingat kompleksitas penggunaan kredensial bersumber yang dapat dieksekusi, disarankan untuk menggunakan mekanisme yang didukung yang ada (bersumber file/bersumber URL) untuk menyediakan kredensial pihak ketiga kecuali mekanisme tersebut tidak memenuhi persyaratan spesifik Anda.

Anda sekarang dapat menggunakan perpustakaan Auth untuk memanggil sumber daya Google Cloud dari penyedia OIDC atau SAML.

Menggunakan pemasok khusus dengan OIDC dan SAML

Implementasi khusus IdentityPoolSubjectTokenSupplier dapat digunakan saat membuat IdentityPoolCredentials untuk menyediakan token subjek yang dapat ditukar dengan token akses GCP. Pemasok harus mengembalikan token subjek yang valid dan belum habis masa berlakunya saat dipanggil oleh kredensial GCP.

IdentityPoolCredentials tidak menyimpan token yang dikembalikan dalam cache, jadi logika cache harus diterapkan di pemasok 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 will pass 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 do not 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 GCP audience.
        . setSubjectTokenType ( SubjectTokenTypes . JWT ) // Sets the subject token type.
        . build ();

Lokasi audiensnya: //iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID

Dimana variabel berikut perlu diganti:

• $PROJECT_NUMBER : Nomor proyek Google Cloud.
• $WORKLOAD_POOL_ID : ID kumpulan identitas beban kerja.
• $PROVIDER_ID : ID penyedia.

Nilai untuk audiens, URL peniruan identitas akun layanan, dan kolom pembuat lainnya juga dapat ditemukan dengan membuat file konfigurasi kredensial dengan gcloud CLI.

Menggunakan pemasok khusus dengan AWS

Implementasi khusus AwsSecurityCredentialsSupplier dapat diberikan saat menginisialisasi AwsCredentials. Jika disediakan, instans AwsCredentials akan menyerahkan kepada pemasok untuk mengambil kredensial keamanan AWS untuk ditukar dengan token akses GCP. Pemasok harus mengembalikan kredensial keamanan AWS yang valid dan belum habis masa berlakunya ketika dipanggil oleh kredensial GCP.

AwsCredentials tidak melakukan cache kredensial atau wilayah keamanan AWS yang dikembalikan, sehingga logika cache harus diterapkan di pemasok untuk mencegah beberapa permintaan untuk sumber daya yang sama.

 class CustomAwsSupplier implements AwsSecurityCredentialsSupplier {
  @ Override
  AwsSecurityCredentials getAwsSecurityCredentials ( ExternalAccountSupplierContext context ) throws IOException {
    // Any call to the supplier will pass 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 do not 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 do not 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 GCP audience.
    . setAwsSecurityCredentialsSupplier ( supplier ) // Sets the supplier.
    . build ();

Lokasi audiensnya: //iam.googleapis.com/projects/$PROJECT_NUMBER/locations/global/workloadIdentityPools/$WORKLOAD_POOL_ID/providers/$PROVIDER_ID

Dimana variabel berikut perlu diganti:

• $PROJECT_NUMBER : Nomor proyek Google Cloud.
• $WORKLOAD_POOL_ID : ID kumpulan identitas beban kerja.
• $PROVIDER_ID : ID penyedia.

Nilai untuk audiens, URL peniruan identitas akun layanan, dan kolom pembuat lainnya juga dapat ditemukan dengan membuat file konfigurasi kredensial dengan gcloud CLI.

Seumur Hidup Token yang Dapat Dikonfigurasi

Saat membuat konfigurasi kredensial dengan federasi identitas beban kerja menggunakan peniruan identitas akun layanan, Anda dapat memberikan argumen opsional untuk mengonfigurasi masa pakai token akses akun layanan.

Untuk menghasilkan konfigurasi dengan masa pakai token yang dapat dikonfigurasi, jalankan perintah berikut (contoh ini menggunakan konfigurasi AWS, namun masa pakai token dapat dikonfigurasi untuk semua penyedia federasi identitas beban kerja):

 # Generate an AWS configuration file with configurable token lifetime.
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 
    --service-account-token-lifetime-seconds $TOKEN_LIFETIME

Dimana variabel berikut perlu diganti:

• $PROJECT_NUMBER : Nomor proyek Google Cloud.
• $POOL_ID : ID kumpulan identitas beban kerja.
• $AWS_PROVIDER_ID : ID penyedia AWS.
• $SERVICE_ACCOUNT_EMAIL : Email akun layanan yang akan ditiru.
• $TOKEN_LIFETIME : Durasi seumur hidup yang diinginkan dari token akses akun layanan dalam hitungan detik.

Tanda service-account-token-lifetime-seconds bersifat opsional. Jika tidak disediakan, defaultnya adalah satu jam. Nilai minimum yang diperbolehkan adalah 600 (10 menit) dan nilai maksimum yang diperbolehkan adalah 43200 (12 jam). Jika masa pakai lebih dari satu jam diperlukan, akun layanan harus ditambahkan sebagai nilai yang diizinkan dalam Kebijakan Organisasi yang menerapkan batasan constraints/iam.allowServiceAccountCredentialLifetimeExtension .

Perhatikan bahwa mengonfigurasi masa pakai yang singkat (misalnya 10 menit) akan mengakibatkan perpustakaan memulai seluruh aliran pertukaran token setiap 10 menit, yang akan memanggil penyedia token pihak ketiga meskipun token pihak ketiga belum kedaluwarsa.

Federasi Identitas Tenaga Kerja

Federasi identitas tenaga kerja memungkinkan Anda menggunakan penyedia identitas eksternal (IdP) untuk mengautentikasi dan memberi otorisasi tenaga kerja—sekelompok pengguna, seperti karyawan, partner, dan kontraktor—menggunakan IAM, sehingga pengguna dapat mengakses layanan Google Cloud. Federasi identitas tenaga kerja memperluas kemampuan identitas Google Cloud untuk mendukung sistem masuk tunggal berbasis atribut yang tidak tersinkronisasi.

Dengan federasi identitas tenaga kerja, tenaga kerja Anda dapat mengakses sumber daya Google Cloud menggunakan penyedia identitas eksternal (IdP) yang mendukung OpenID Connect (OIDC) atau SAML 2.0 seperti Azure Active Directory (Azure AD), Active Directory Federation Services (AD FS), Okta , dan lainnya.

Mengakses sumber daya menggunakan penyedia identitas OIDC atau SAML 2.0

Untuk mengakses resource Google Cloud dari penyedia identitas yang mendukung OpenID Connect (OIDC), diperlukan persyaratan berikut:

• Kumpulan identitas tenaga kerja perlu dibuat.
• Penyedia identitas OIDC atau SAML 2.0 perlu ditambahkan di kumpulan tenaga kerja.

Ikuti petunjuk mendetail tentang cara mengonfigurasi federasi identitas tenaga kerja.

Setelah mengonfigurasi penyedia OIDC atau SAML 2.0, file konfigurasi kredensial perlu dibuat. File konfigurasi kredensial yang dihasilkan berisi metadata non-sensitif untuk memberikan instruksi kepada perpustakaan tentang cara mengambil token subjek eksternal dan menukarnya dengan token akses GCP. File konfigurasi dapat dibuat dengan menggunakan gcloud CLI.

Pustaka Auth dapat mengambil token subjek eksternal dari lokasi file lokal (kredensial bersumber file), dari server lokal (kredensial bersumber URL), atau dengan memanggil yang dapat dieksekusi (kredensial bersumber yang dapat dieksekusi).

Kredensial bersumber file Untuk kredensial bersumber file, proses latar belakang harus terus menyegarkan lokasi file dengan token subjek baru sebelum masa berlakunya habis. Untuk token dengan masa hidup satu jam, token perlu diperbarui dalam file setiap jam. Token dapat disimpan langsung sebagai teks biasa atau dalam format JSON.

Untuk menghasilkan konfigurasi OIDC bersumber file, jalankan perintah berikut:

 # Generate an OIDC configuration file for file-sourced credentials.
gcloud iam workforce-pools create-cred-config 
    locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID 
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token 
    --credential-source-file= $PATH_TO_OIDC_ID_TOKEN 
    --workforce-pool-user-project= $WORKFORCE_POOL_USER_PROJECT 
    # 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

Dimana variabel berikut perlu diganti:

• $WORKFORCE_POOL_ID : ID kumpulan tenaga kerja.
• $PROVIDER_ID : ID penyedia.
• $PATH_TO_OIDC_ID_TOKEN : Jalur file yang digunakan untuk mengambil token OIDC.
• $WORKFORCE_POOL_USER_PROJECT : Nomor proyek yang terkait dengan proyek pengguna kumpulan tenaga kerja.

Untuk menghasilkan konfigurasi SAML bersumber file, jalankan perintah berikut:

 # Generate a SAML configuration file for file-sourced credentials.
gcloud iam workforce-pools create-cred-config 
    locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID 
    --credential-source-file= $PATH_TO_SAML_ASSERTION 
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 
    --workforce-pool-user-project= $WORKFORCE_POOL_USER_PROJECT 
    --output-file=/path/to/generated/config.json 

Dimana variabel berikut perlu diganti:

• $WORKFORCE_POOL_ID : ID kumpulan tenaga kerja.
• $PROVIDER_ID : ID penyedia.
• $PATH_TO_SAML_ASSERTION : Jalur file yang digunakan untuk mengambil pernyataan SAML yang dikodekan base64.
• $WORKFORCE_POOL_USER_PROJECT : Nomor proyek yang terkait dengan proyek pengguna kumpulan tenaga kerja.

Perintah-perintah ini menghasilkan file konfigurasi dalam file output yang ditentukan.

Kredensial bersumber URL Untuk kredensial bersumber URL, server lokal perlu menghosting titik akhir GET untuk mengembalikan token OIDC. Responsnya bisa dalam teks biasa atau JSON. Header permintaan tambahan yang diperlukan juga dapat ditentukan.

Untuk menghasilkan konfigurasi identitas tenaga kerja OIDC yang bersumber URL, jalankan perintah berikut:

 # Generate an OIDC configuration file for URL-sourced credentials.
gcloud iam workforce-pools create-cred-config 
    locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID 
    --subject-token-type=urn:ietf:params:oauth:token-type:id_token 
    --credential-source-url= $URL_TO_RETURN_OIDC_ID_TOKEN 
    --credential-source-headers $HEADER_KEY = $HEADER_VALUE 
    --workforce-pool-user-project= $WORKFORCE_POOL_USER_PROJECT 
    --output-file=/path/to/generated/config.json

Dimana variabel berikut perlu diganti:

• $WORKFORCE_POOL_ID : ID kumpulan tenaga kerja.
• $PROVIDER_ID : ID penyedia.
• $URL_TO_RETURN_OIDC_ID_TOKEN : URL titik akhir server lokal.
• $HEADER_KEY dan $HEADER_VALUE : Pasangan kunci/nilai header tambahan untuk meneruskan permintaan GET ke $URL_TO_GET_OIDC_TOKEN , misalnya Metadata-Flavor=Google .
• $WORKFORCE_POOL_USER_PROJECT : Nomor proyek yang terkait dengan proyek pengguna kumpulan tenaga kerja.

Untuk menghasilkan konfigurasi SAML bersumber URL, jalankan perintah berikut:

 # Generate a SAML configuration file for file-sourced credentials.
gcloud iam workforce-pools create-cred-config 
    locations/global/workforcePools/ $WORKFORCE_POOL_ID /providers/ $PROVIDER_ID 
    --subject-token-type=urn:ietf:params:oauth:token-type:saml2 
    --credential-source-url= $URL_TO_GET_SAML_ASSERTION 
    --credential-source-headers