Bermigrasi ke Service Account Credentials API

Service Account Credentials API membuat kredensial berumur pendek untuk akun layanan Pengelolaan Akses dan Identitas (IAM). Anda juga dapat menggunakan API ini untuk menandatangani Token Web JSON (JWT), serta blob data biner yang berisi jenis token lainnya.

IAM API juga berisi metode untuk menandatangani JWT dan blob biner. Mulai tanggal 1 Juli 2020, metode ini tidak digunakan lagi di REST API dan di semua library klien untuk IAM API. Selain itu, jika menggunakan Google Cloud CLI untuk menandatangani JWT, Anda mungkin perlu menambahkan klaim baru ke JWT Claims Set. Anda masih dapat menggunakan metode yang tidak digunakan lagi, tetapi metode tersebut tidak mendukung fitur lanjutan seperti pengelompokan permintaan HTTP. Sebaiknya Anda bermigrasi ke Service Account Credentials API.

Dibandingkan dengan IAM API, Service Account Credentials API memberikan fleksibilitas yang lebih baik untuk waktu habis masa berlaku JWT yang ditandatangani. Selain itu, Service Account Credentials API menambahkan beberapa metode API baru untuk membuat token peniruan identitas.

Halaman ini menjelaskan cara memperbarui kode yang ada untuk menggunakan Service Account Credentials API. Jika memiliki masukan terkait perubahan ini, Anda dapat mengisi formulir masukan. Anda juga dapat menggunakan alamat email [e-mail] untuk meminta dukungan dan memberikan masukan yang mendetail.

Sebelum memulai

• Enable the Service Account Credentials API.

  Enable the API

Mengaktifkan log audit

Jika ingin menerima log audit untuk permintaan menandatangani JWT dan blob, Anda harus mengaktifkan log audit Akses Data untuk IAM API. Mengaktifkan log audit Akses Data untuk IAM API juga mengaktifkan log audit ini untuk Service Account Credentials API.

Ada beberapa perbedaan penting antara entri log yang dihasilkan setiap API:

Perbedaan entri log audit
Nama metode	IAM API Nama metode (protoPayload.methodName) adalah salah satu dari berikut: google.iam.admin.v1.SignBlob google.iam.admin.v1.SignJwt Service Account Credentials API Nama metode adalah salah satu dari berikut ini: SignBlob SignJwt
Jenis permintaan	IAM API Jenis permintaan (protoPayload.request.@type) adalah salah satu dari berikut: type.googleapis.com/google.iam.admin.v1.SignBlobRequest type.googleapis.com/google.iam.admin.v1.SignJwtRequest Service Account Credentials API Jenis permintaan adalah salah satu dari berikut ini: type.googleapis.com/google.iam.credentials.v1.SignBlobRequest type.googleapis.com/google.iam.credentials.v1.SignJwtRequest
Nama layanan	IAM API Nama layanan (protoPayload.serviceName) adalah iam.googleapis.com. Service Account Credentials API Nama layanan adalah iamcredentials.googleapis.com.

Log audit Akses Data diperhitungkan dalam alokasi bulanan gratis untuk penyerapan data logging. Jika melebihi alokasi ini, Anda akan dikenai biaya untuk penyerapan log. Untuk mengetahui detailnya, lihat Harga untuk Google Cloud Observability.

Memigrasikan kode untuk menandatangani JWT

Bagian ini menjelaskan cara memigrasikan kode yang menandatangani JWT ke Service Account Credentials API.

Menandatangani JWT dengan REST API

Tabel berikut menunjukkan perbedaan antara menandatangani JWT dengan IAM REST API dan menandatangani JWT dengan Service Account Credentials API. Update kode Anda untuk mencerminkan perbedaan ini:

Perbedaan untuk menandatangani JWT
Endpoint HTTP	IAM API IAM API menggunakan metode dan endpoint HTTP berikut: POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signJwt Di URL ini, project-id adalah project ID, dan sa-email adalah alamat email untuk akun layanan. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt Di URL ini, karakter pengganti - menggantikan project ID, dan sa-email adalah alamat email untuk akun layanan. Service Account Credentials API Gunakan metode HTTP dan endpoint berikut. Jangan ganti karakter pengganti dengan project ID: POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signJwt Di URL ini, sa-email adalah alamat email untuk akun layanan.
Isi permintaan	IAM API Isi permintaan menyertakan kolom payload. Nilainya adalah payload JWT yang akan ditandatangani. Payload harus berupa objek JSON, yang diserialisasi sebagai string, yang berisi Kumpulan Klaim JWT. Jika Anda memberikan klaim waktu habis masa berlaku (exp), klaim tersebut tidak boleh lebih dari 12 jam di masa mendatang. Jika dihapus, klaim exp akan ditambahkan secara otomatis dan ditetapkan ke 1 jam pada masa mendatang. Service Account Credentials API Isi permintaan menyertakan kolom payload yang identik dengan IAM API, kecuali untuk perilaku klaim waktu habis masa berlaku (exp): Jika Anda memberikan klaim exp, klaim tersebut tidak boleh lebih dari 12 jam di masa mendatang. Jika Anda menghilangkan klaim exp, klaim tidak ditambahkan secara otomatis. Anda harus memberikan klaim ini jika Anda menggunakan JWT bertanda tangan untuk mengautentikasi dengan Google API, atau dengan API lain yang memerlukan klaim exp.
Isi respons	Kedua API menggunakan kolom yang sama dalam isi respons.

Menandatangani JWT dengan library klien

Library klien untuk Service Account Credentials API terpisah dari library klien untuk IAM API.

Untuk menggunakan Service Account Credentials API, tambahkan library kliennya ke aplikasi Anda, lalu perbarui kode untuk menggunakan library klien baru:

C#

Tambahkan library klien Kredensial Akun Layanan untuk C# ke aplikasi Anda. Gunakan metode SignJwt() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien IAM untuk C#, Anda dapat menghapusnya dari aplikasi.

Go

Tambahkan library klien Kredensial Akun Layanan untuk Go ke aplikasi Anda. Gunakan IamCredentialsClient.SignJwt() function untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien IAM untuk Go, Anda dapat menghapusnya dari aplikasi Anda.

Java

Tambahkan library klien Kredensial Akun Layanan untuk Java ke aplikasi Anda. Gunakan metode IamCredentialsClient#signJwt() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien IAM untuk Java, Anda dapat menghapusnya dari aplikasi Anda.

Node.js

Tambahkan library klien Kredensial Akun Layanan untuk Node.js ke aplikasi Anda. Gunakan metode signJwt() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika Anda tidak lagi menggunakan library klien IAM untuk Node.js, Anda dapat menghapusnya dari aplikasi Anda.

PHP

Tambahkan library klien Kredensial Akun Layanan untuk PHP ke aplikasi Anda. Gunakan metode signJwt() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien IAM untuk PHP, Anda dapat menghapusnya dari aplikasi.

Python

Tambahkan library klien Kredensial Akun Layanan untuk Python ke aplikasi Anda. Gunakan metode sign_jwt() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien iam_credentials , Anda dapat menghapusnya dari aplikasi.

Ruby

Tambahkan library klien Kredensial Akun Layanan untuk Ruby ke aplikasi Anda. Gunakan metode sign_service_account_jwt() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien IAM untuk Ruby, Anda dapat menghapusnya dari aplikasi Anda.

Memigrasikan kode untuk menandatangani blob biner

Bagian ini menjelaskan cara memigrasikan kode yang menandatangani blob biner ke Service Account Credentials API.

Menandatangani blob biner dengan REST API

Tabel berikut menunjukkan perbedaan antara menandatangani blob biner dengan IAM REST API dan menandatangani blob biner dengan Service Account Credentials API. Perbarui kode Anda untuk mencerminkan perbedaan ini:

Perbedaan untuk menandatangani blob biner
Endpoint HTTP	IAM API IAM API menggunakan metode dan endpoint HTTP berikut: POST https://iam.googleapis.com/v1/projects/project-id/serviceAccounts/sa-email:signBlob Di URL ini, project-id adalah project ID, dan sa-email adalah alamat email untuk akun layanan. POST https://iam.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob Di URL ini, karakter pengganti - menggantikan project ID, dan sa-email adalah alamat email untuk akun layanan. Service Account Credentials API Gunakan metode HTTP dan endpoint berikut. Jangan ganti karakter pengganti dengan project ID: POST https://iamcredentials.googleapis.com/v1/projects/-/serviceAccounts/sa-email:signBlob Di URL ini, sa-email adalah alamat email untuk akun layanan.
Isi permintaan	IAM API Isi permintaan menyertakan kolom bytesToSign. Nilainya adalah string berenkode base64 yang mewakili blob biner yang akan ditandatangani. Service Account Credentials API Isi permintaan mencakup kolom payload yang memiliki nilai yang sama dengan kolom bytesToSign di IAM API.
Isi respons	IAM API Isi respons berisi kolom keyId, yang mengidentifikasi kunci yang digunakan untuk menandatangani blob, dan kolom signature, yang berisi string berenkode base64 yang merepresentasikan tanda tangan. Service Account Credentials API Isi respons berisi kolom keyId yang identik dengan kolom keyId di IAM API, serta kolom signedBlob yang identik dengan kolom signature di IAM API. Catatan: Kolom signedBlob hanya berisi tanda tangan, bukan blob asli.

Menandatangani blob biner dengan library klien

Library klien untuk Service Account Credentials API terpisah dari library klien untuk IAM API.

Untuk menggunakan Service Account Credentials API, tambahkan library kliennya ke aplikasi Anda, lalu perbarui kode untuk menggunakan library klien baru:

C++

Jika Anda menggunakan library klien Cloud Storage C++ untuk menandatangani blob, baik secara langsung maupun sebagai dependensi library klien lainnya:

Upgrade google-cloud-cpp ke versi 0.9.0 atau yang lebih baru.

Jika Anda menggunakan library klien lain untuk menandatangani blob:

Kontak [e-mail] untuk dukungan.

C#

Jika Anda menggunakan library klien IAM untuk C#, baik secara langsung atau sebagai dependensi library klien lainnya:

Tambahkan library klien Kredensial Akun Layanan untuk C# ke aplikasi Anda. Gunakan metode SignBlob() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien IAM untuk C#, Anda dapat menghapusnya dari aplikasi.

Jika Anda menggunakan Firebase Admin DotNet SDK, baik secara langsung maupun sebagai dependensi library klien lainnya:

Upgrade firebase-admin-dotnet ke versi 1.17.1 atau yang lebih baru.

Jika Anda menggunakan library klien lain untuk menandatangani blob:

Kontak [e-mail] untuk dukungan.

Go

Jika Anda menggunakan library klien IAM untuk Go, baik secara langsung atau sebagai dependensi library klien lainnya:

Tambahkan library klien Kredensial Akun Layanan untuk Go ke aplikasi Anda. Gunakan IamCredentialsClient.SignBlob() function untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien IAM untuk Go, Anda dapat menghapusnya dari aplikasi Anda.

Jika Anda menggunakan Firebase Admin Go SDK, baik secara langsung maupun sebagai dependensi library klien lainnya:

Upgrade firebase-admin-go ke versi 4.1.0 atau yang lebih baru.

Jika Anda menggunakan library klien lain untuk menandatangani blob:

Kontak [e-mail] untuk dukungan.

Java

Jika Anda menggunakan library klien IAM untuk Java, baik secara langsung atau sebagai dependensi library klien lainnya:

Tambahkan library klien Kredensial Akun Layanan untuk Java ke aplikasi Anda. Gunakan metode IamCredentialsClient#signBlob() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien IAM untuk Java, Anda dapat menghapusnya dari aplikasi Anda.

Jika Anda menggunakan Library Google Auth untuk Java, baik secara langsung atau sebagai dependensi library klien lainnya:

Upgrade google-auth-library-java ke versi 0.14.0 atau yang lebih baru.

Jika Anda menggunakan Firebase Admin Java SDK, secara langsung atau sebagai dependensi library klien lainnya:

Upgrade firebase-admin-java ke versi 7.0.1 atau yang lebih baru.

Jika Anda menggunakan library klien lain untuk menandatangani blob:

Kontak [e-mail] untuk dukungan.

Node.js

Jika Anda menggunakan library klien IAM untuk Node.js, baik secara langsung atau sebagai dependensi library klien lainnya:

Tambahkan library klien Kredensial Akun Layanan untuk Node.js ke aplikasi Anda. Gunakan metode signBlob() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika Anda tidak lagi menggunakan library klien IAM untuk Node.js, Anda dapat menghapusnya dari aplikasi Anda.

Jika Anda menggunakan Library Google Auth untuk Node.js, baik secara langsung atau sebagai dependensi library klien lainnya:

Upgrade google-auth-library-nodejs ke versi 6.0.0 atau yang lebih baru.

Jika Anda menggunakan Firebase Admin Node.js SDK, baik secara langsung atau sebagai dependensi library klien lainnya:

Upgrade firebase-admin-node ke versi 8.13.0 atau yang lebih baru.

Jika Anda menggunakan library klien lain untuk menandatangani blob:

Kontak [e-mail] untuk dukungan.

PHP

Jika Anda menggunakan library klien IAM untuk PHP, baik secara langsung atau sebagai dependensi library klien lainnya:

Tambahkan library klien Kredensial Akun Layanan untuk PHP ke aplikasi Anda. Gunakan metode signBlob() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien IAM untuk PHP, Anda dapat menghapusnya dari aplikasi.

Jika Anda menggunakan Library Google Auth untuk PHP, baik secara langsung maupun sebagai dependensi library klien lainnya:

Upgrade google-auth-library-php ke versi 1.5.0 atau yang lebih baru.

Jika Anda menggunakan library klien lain untuk menandatangani blob:

Kontak [e-mail] untuk dukungan.

Python

Jika Anda menggunakan library klien IAM untuk Python, baik secara langsung atau sebagai dependensi library klien lainnya:

Tambahkan library klien Kredensial Akun Layanan untuk Python ke aplikasi Anda. Gunakan metode sign_blob() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien iam_credentials , Anda dapat menghapusnya dari aplikasi.

Jika Anda menggunakan Library Google Auth untuk Python, baik secara langsung maupun sebagai dependensi library klien lainnya:

Upgrade google-auth-library-python ke versi 1.21.2 atau yang lebih baru.

Jika Anda menggunakan klien Python untuk Cloud Storage, baik secara langsung maupun sebagai dependensi library klien lainnya:

Upgrade python-storage ke versi 1.30.0 atau yang lebih baru.

Jika Anda menggunakan library klien lain untuk menandatangani blob:

Kontak [e-mail] untuk dukungan.

Ruby

Jika Anda menggunakan library klien IAM untuk Ruby, baik secara langsung atau sebagai dependensi library klien lainnya:

Tambahkan library klien Kredensial Akun Layanan untuk Ruby ke aplikasi Anda. Gunakan metode sign_service_account_blob() untuk membuat tanda tangan.

Nama akun layanan harus menggunakan karakter pengganti - untuk merepresentasikan project ID:

Valid: Nama dengan karakter pengganti

projects/-/serviceAccounts/[e-mail]

Tidak valid: Nama dengan project ID

projects/my-project/serviceAccounts/[e-mail]

Jika tidak lagi menggunakan library klien IAM untuk Ruby, Anda dapat menghapusnya dari aplikasi Anda.

Jika Anda menggunakan library klien lain untuk menandatangani blob:

Kontak [e-mail] untuk dukungan.

Memigrasikan kode yang menggunakan gcloud CLI

Google Cloud CLI menyediakan perintah yang menggunakan IAM API untuk menandatangani JWT dan blob biner, termasuk:

• gcloud beta iam service-accounts sign-jwt
• gcloud iam service-accounts sign-blob

Pada atau setelah tanggal 1 Juli 2021, kami akan memperbarui perintah ini untuk menggunakan Service Account Credentials API. Perubahan ini tidak akan memengaruhi perintah untuk menandatangani blob.

Jika menggunakan gcloud CLI untuk menandatangani JWT, Anda harus mengikuti langkah-langkah berikut sebelum 1 Juli 2021:

1. Periksa apakah Anda menyertakan klaim waktu habis masa berlaku (exp) di Kumpulan Klaim JWT.

   Jika sudah menyertakan klaim ini, Anda tidak perlu melakukan perubahan apa pun. Anda bisa melewatkan langkah lainnya.

   Jika Anda tidak menyertakan klaim ini, lanjutkan ke langkah berikutnya.

2. Periksa apakah Anda menggunakan JWT yang ditandatangani untuk mengautentikasi dengan Google API, atau dengan API lain yang memerlukan klaim exp.

   Jika Anda menghapus klaim ini, IAM API akan otomatis menetapkannya ke 1 jam ke depan. Sebaliknya, Service Account Credentials API tidak menetapkan kolom ini secara otomatis.

   Jika Anda yakin tidak memerlukan klaim exp, Anda tidak perlu melakukan perubahan apa pun. Anda bisa melewatkan langkah lainnya.

   Jika Anda tahu bahwa Anda memerlukan klaim exp, atau jika Anda tidak yakin, lanjutkan ke langkah berikutnya.

3. Perbarui kode Anda untuk membuat JWT sehingga dapat menambahkan klaim exp ke Kumpulan Klaim JWT.

   Anda dapat menetapkan klaim exp hingga 1 jam ke depan.

Memeriksa kuota

Kuota untuk Service Account Credentials API terpisah dari kuota untuk IAM API. Jika Anda menerima penambahan kuota untuk menandatangani JWT dan blob dengan IAM API, Anda mungkin juga perlu meminta peningkatan untuk Service Account Credentials API.

Catatan: Sebagian besar pelanggan Google Cloud menggunakan kuota default untuk menandatangani JWT dan blob. Jika menggunakan kuota default, Anda tidak perlu membaca bagian ini.

Untuk melihat kuota dan penggunaan sebenarnya untuk kedua API, dan untuk meminta penambahan kuota jika perlu, lakukan hal berikut:

1. Di konsol Google Cloud, buka halaman Quotas.

   Buka halaman Kuota

2. Pilih project. Anda dapat mengklik project terbaru, atau mengklik Pilih project untuk menelusuri semua project.

3. Di kotak teks Tabel filter di atas tabel, masukkan Sign requests per minute, lalu pilih nilai yang muncul.

4. Di kotak teks Tabel filter, pilih ATAU dari menu drop-down.

5. Di kotak teks Tabel filter, masukkan Generate credentials, lalu pilih nilai yang muncul.

   Google Cloud Console menunjukkan penggunaan Anda saat ini untuk menandatangani JWT dan blob selama semenit terakhir; puncak penggunaan per menit selama 7 hari terakhir; dan kuota saat ini, yang muncul di kolom Batas.

6. Bandingkan kuota untuk setiap baris dalam tabel, dan pastikan kuota Anda untuk Service Account Credentials API lebih tinggi dari puncak penggunaan IAM API Anda dalam 7 hari.

7. Opsional: Jika kuota Anda untuk Service Account Credentials API terlalu rendah, centang kotak untuk Service Account Credentials API, lalu klik Edit quotas. Isi formulir untuk meminta penambahan kuota.

8. Ulangi langkah-langkah ini untuk setiap project tempat Anda menggunakan IAM API untuk menandatangani JWT dan blob.

Langkah selanjutnya

• Cari tahu cara membuat JWT bertanda tangan atau membuat blob biner bertanda tangan dengan REST API Kredensial Akun Layanan.
• Dapatkan detail tentang REST API untuk Service Account Credentials API.
• Memahami kuota dan batas untuk IAM.