Halaman ini menjelaskan cara menggunakan Batas Akses Kredensial untuk membuat token akses OAuth 2.0 dengan izin Cloud Storage yang diperkecil cakupannya.
Proses pembuatan token dengan izin yang diperkecil cakupannya mencakup langkah-langkah berikut:
- Berikan peran IAM yang tepat kepada pengguna atau akun layanan.
- Tentukan Batas Akses Kredensial yang menetapkan batas atas pada izin yang tersedia untuk pengguna atau akun layanan.
- Buat token akses OAuth 2.0 untuk akun pengguna atau layanan.
- Tukarkan token akses OAuth 2.0 dengan token baru yang mematuhi Batas Akses Kredensial.
Anda kemudian dapat menggunakan token akses OAuth 2.0 yang baru yang diperkecil cakupannya untuk melakukan autentikasi permintaan ke Cloud Storage.
Sebelum memulai
Sebelum Anda menggunakan Batas Akses Kredensial, pastikan Anda memenuhi persyaratan berikut:
Anda hanya perlu memperkecil cakupan izin untuk Cloud Storage, bukan untuk layananGoogle Cloud lainnya.
Jika Anda perlu memperkecil cakupan izin untuk layanan Google Cloud tambahan, Anda dapat membuat beberapa akun layanan dan memberikan serangkaian peran yang berbeda ke setiap akun layanan.
Anda dapat menggunakan token akses OAuth 2.0 untuk autentikasi. Jenis kredensial yang berlaku singkat lainnya tidak mendukung Batas Akses Kredensial.
Selain itu, Anda harus mengaktifkan API yang diperlukan:
-
Enable the IAM and Security Token Service APIs.
Memberikan peran IAM
Batas Akses Kredensial menetapkan batas atas pada izin yang tersedia untuk resource. Hal tersebut dapat mengurangi izin dari akun utama, tetapi tidak dapat menambahkan izin yang belum dimiliki akun utama.
Oleh karena itu, Anda juga harus memberikan peran ke akun utama yang menyediakan izin yang mereka butuhkan, baik pada bucket Cloud Storage maupun pada resource dengan level yang lebih tinggi, seperti project.
Contohnya, Anda perlu membuat kredensial yang berlaku singkat yang diperkecil cakupannya yang mengizinkan akun layanan untuk membuat objek dalam bucket:
- Setidaknya, Anda harus memberikan peran ke akun layanan yang menyertakan
izin
storage.objects.create
, seperti peran Pembuat Storage Object (roles/storage.objectCreator
). Batas Akses Kredensial juga harus menyertakan izin ini. - Anda juga dapat memberikan peran yang mencakup lebih banyak izin, seperti peran Admin Storage
Object (
roles/storage.objectAdmin
). Akun layanan hanya dapat menggunakan izin yang muncul dalam pemberian peran dan Batas Akses Kredensial.
Untuk mempelajari peran bawaan untuk Cloud Storage, lihat Peran Cloud Storage.
Tentukan Batas Akses Kredensial
Batas Akses Kredensial adalah objek yang berisi daftar aturan batas akses. Aturan terdiri dari parameter yang menentukan batas atas izin yang tersedia untuk pengguna atau akun layanan. Untuk menentukan Batas Akses Kredensial, buat objek JSON yang mencantumkan aturan batas akses dan parameternya.
Berikut adalah contoh Batas Akses Kredensial:
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:ROLE_ID"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/BUCKET_NAME"
"availabilityCondition": {
"expression" : "CONDITION"
}
]
}
}
Ganti kode berikut:
ROLE_ID
: ID peran bawaan atau kustom yang menentukan batas atas pada izin yang tersedia untuk resource. Contoh,roles/storage.objectViewer
. Untuk menentukan beberapa peran, tambahkan baris baru dengan awalaninRole:
yang diikuti dengan ID peran. Hanya izin dalam peran yang ditentukan yang akan tersedia.BUCKET_NAME
: Nama bucket Cloud Storage tempat aturan diterapkan.CONDITION
: Opsional. Ekspresi kondisi yang menentukan objek Cloud Storage yang izinnya tersedia. Misalnya, kondisi berikut menyediakan izin untuk objek yang namanya diawali dengancustomer-a
:resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a')
Untuk mempelajari lebih lanjut cara membuat dan menyesuaikan batas akses kredensial, lihat Komponen Batas Akses Kredensial.
Untuk contoh potensi kasus penggunaan Batas Akses Kredensial, lihat Contoh Batas Akses Kredensial.
Membuat token akses OAuth 2.0
Sebelum membuat kredensial yang berlaku singkat yang diperkecil cakupannya, Anda harus membuat token akses
OAuth 2.0 normal. Kemudian, Anda dapat menukar kredensial normal dengan
kredensial yang diperkecil cakupannya. Saat Anda membuat token akses, gunakan
https://www.googleapis.com/auth/cloud-platform
cakupan OAuth 2.0.
Untuk membuat token akses untuk akun layanan, Anda dapat menyelesaikan alur OAuth 2.0 server ke server, atau menggunakan Service Account Credentials API untuk membuat token akses OAuth 2.0.
Untuk membuat token akses bagi pengguna, lihat Mendapatkan token akses OAuth 2.0. Anda juga dapat menggunakan Playground OAuth 2.0 untuk membuat token akses untuk Akun Google Anda sendiri.
Menukarkan token akses OAuth 2.0
Setelah membuat token akses OAuth 2.0, Anda dapat menukar token akses tersebut dengan token yang diperkecil cakupannya yang mematuhi Batas Akses Kredensial. Proses ini biasanya melibatkan broker token dan konsumen token:
Broker token bertanggung jawab menentukan Batas Akses Kredensial dan menukar token akses untuk token yang diperkecil cakupannya.
Broker token dapat menggunakan library autentikasi yang didukung untuk menukar token akses secara otomatis, atau memanggil Layanan Token Keamanan untuk menukar token secara manual.
Konsumen token meminta token akses yang diperkecil cakupannya dari broker token, lalu menggunakan token akses yang diperkecil cakupannya untuk melakukan tindakan lain.
Konsumen token dapat menggunakan library autentikasi yang didukung untuk memuat ulang token akses secara otomatis sebelum masa berlakunya habis. Selain itu, konsumen token dapat memuat ulang token secara manual, atau membiarkan masa berlaku token habis tanpa memuat ulang token tersebut.
Ada dua cara untuk menukar token akses dengan token yang diperkecil cakupannya:
Penukaran token sisi klien (direkomendasikan): Klien mendapatkan materi kriptografi dari server Security Token Service API. Materi kriptografi memungkinkan klien membuat token yang diperkecil cakupannya dengan aturan Batas Akses Kredensial yang bervariasi secara independen di sisi klien selama jangka waktu tertentu (misalnya, 1 jam). Pendekatan ini mengurangi latensi dan meningkatkan efisiensi, terutama untuk klien yang memerlukan pembaruan aturan Batas Akses Kredensial yang sering. Cara ini juga lebih efisien untuk aplikasi yang perlu membuat banyak token yang dicakup ke bawah yang unik. Ini adalah pendekatan yang direkomendasikan karena memberikan performa, skalabilitas, dan kompatibilitas fitur mendatang yang lebih baik.
Penukaran token sisi server: Klien meminta token baru yang diperkecil cakupannya dari server API Layanan Token Keamanan setiap kali aturan Batas Akses Kredensial berubah. Pendekatan ini mudah, tetapi memerlukan perjalanan pulang pergi ke server API Security Token Service untuk setiap permintaan token yang cakupannya dikecilkan. Pendekatan ini hanya direkomendasikan bagi pelanggan yang memerlukan library klien yang tidak mendukung pertukaran token sisi klien, karena perjalanan pulang pergi ke Security Token Service API untuk setiap permintaan token yang cakupannya lebih sempit.
Penukaran token sisi klien
Jika Anda membuat broker token dan konsumen token dengan bahasa berikut, Anda dapat menggunakan library autentikasi Google untuk menukar dan memuat ulang token secara otomatis melalui pendekatan sisi klien.
Java
Untuk Java, Anda dapat menukar dan memuat ulang token secara otomatis dengan
artefak com.google.auth:google-auth-library-cab-token-generator
versi 1.32.1 atau yang lebih baru.
Untuk memeriksa versi artefak Anda, jalankan perintah Maven berikut di direktori aplikasi Anda:
mvn dependency:list -DincludeArtifactIds=google-auth-library-cab-token-generator
Contoh berikut menunjukkan bagaimana broker token dapat membuat token yang diperkecil cakupannya:
Contoh berikut menunjukkan bagaimana konsumen token dapat menggunakan pengendali refresh untuk secara otomatis memperoleh dan memuat ulang token yang diperkecil cakupannya:
Pertukaran token sisi server
Bagian ini menjelaskan metode berikut yang dapat Anda gunakan untuk menukar token melalui pendekatan sisi layanan:
- Menukarkan dan memperbarui token akses secara otomatis
- Menukar dan memperbarui token akses secara manual
Menukarkan dan memperbarui token akses secara otomatis menggunakan pendekatan sisi server
Jika Anda membuat broker token dan konsumen token dengan salah satu bahasa berikut, Anda dapat menggunakan library autentikasi Google untuk menukar dan memuat ulang token secara otomatis menggunakan pendekatan pembuatan token sisi server:
Go
Untuk Go, Anda dapat menukar dan memuat ulang token secara otomatis dengan versi
v0.0.0-20210819190943-2bc19b11175f atau yang lebih baru dari
paket golang.org/x/oauth2
.
Untuk memeriksa versi paket Anda, jalankan perintah berikut di direktori aplikasi Anda:
go list -m golang.org/x/oauth2
Contoh berikut menunjukkan bagaimana broker token dapat membuat token yang diperkecil cakupannya:
Contoh berikut menunjukkan bagaimana konsumen token dapat menggunakan pengendali refresh untuk secara otomatis memperoleh dan memuat ulang token yang diperkecil cakupannya:
Java
Untuk Java, Anda dapat menukar dan memuat ulang token secara otomatis dengan
com.google.auth:google-auth-library-oauth2-http
artefak
versi 1.1.0 atau yang lebih baru.
Untuk memeriksa versi artefak Anda, jalankan perintah Maven berikut di direktori aplikasi Anda:
mvn dependency:list -DincludeArtifactIds=google-auth-library-oauth2-http
Contoh berikut menunjukkan bagaimana broker token dapat membuat token yang diperkecil cakupannya:
Contoh berikut menunjukkan bagaimana konsumen token dapat menggunakan pengendali refresh untuk secara otomatis memperoleh dan memuat ulang token yang diperkecil cakupannya:
Node.js
Untuk Node.js, Anda dapat menukar dan memuat ulang token secara otomatis dengan
paket google-auth-library
versi 7.9.0 atau yang lebih baru.
Untuk memeriksa versi paket Anda, jalankan perintah berikut di direktori aplikasi Anda:
npm list google-auth-library
Contoh berikut menunjukkan bagaimana broker token dapat membuat token yang diperkecil cakupannya:
Contoh berikut menunjukkan bagaimana konsumen token dapat menyediakan pengendali refresh yang secara otomatis memperoleh dan memuat ulang token yang diperkecil cakupannya:
Python
Untuk Python, Anda dapat menukar dan memuat ulang token secara otomatis dengan
paket google-auth
versi 2.0.0 atau yang lebih baru.
Untuk memeriksa versi paket Anda, jalankan perintah berikut di lingkungan tempat paket diinstal:
pip show google-auth
Contoh berikut menunjukkan bagaimana broker token dapat membuat token yang diperkecil cakupannya:
Contoh berikut menunjukkan bagaimana konsumen token dapat menyediakan pengendali refresh yang secara otomatis memperoleh dan memuat ulang token yang diperkecil cakupannya:
Menukar dan memperbarui token akses secara manual
Broker token dapat menggunakan API Layanan Token Keamanan untuk menukar token akses dengan token akses yang diperkecil cakupannya. Broker token kemudian dapat menyediakan token yang diperkecil cakupannya kepada konsumen token.
Untuk menukar token akses, gunakan metode HTTP dan URL berikut:
POST https://sts.googleapis.com/v1/token
Tetapkan header Content-Type
dalam permintaan menjadi
application/x-www-form-urlencoded
. Sertakan kolom berikut dalam isi
permintaan:
Kolom | |
---|---|
grant_type |
Gunakan nilai
|
options |
Batas Akses Kredensial berformat JSON, dienkode dengan encoding persen. |
requested_token_type |
Gunakan nilai
|
subject_token |
Token akses OAuth 2.0 yang ingin Anda tukarkan. |
subject_token_type |
Gunakan nilai
|
Responsnya adalah objek JSON yang berisi kolom berikut:
Kolom | |
---|---|
access_token |
Token akses OAuth 2.0 yang diperkecil cakupannya yang mematuhi Batas Akses Kredensial. |
expires_in |
Jumlah waktu hingga token yang diperkecil cakupannya berakhir, dalam detik. Kolom ini hanya disertakan jika token akses asli menampilkan akun layanan. Jika kolom ini tidak disertakan, token yang diperkecil cakupannya akan memiliki waktu yang sama dengan masa berlaku token akses asli. |
issued_token_type |
Berisi nilai
|
token_type |
Berisi nilai |
Misalnya, jika Batas Akses Kredensial berformat JSON disimpan dalam file
./access-boundary.json
, Anda dapat menggunakan perintah
curl
berikut untuk menukar token akses. Ganti
original-token
dengan token akses asli:
curl -H "Content-Type:application/x-www-form-urlencoded" \ -X POST \ https://sts.googleapis.com/v1/token \ -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange&subject_token_type=urn:ietf:params:oauth:token-type:access_token&requested_token_type=urn:ietf:params:oauth:token-type:access_token&subject_token=original-token" \ --data-urlencode "options=$(cat ./access-boundary.json)"
Responsnya mirip dengan contoh berikut:
{
"access_token": "ya29.dr.AbCDeFg-123456...",
"issued_token_type": "urn:ietf:params:oauth:token-type:access_token",
"token_type": "Bearer",
"expires_in": 3600
}
Saat konsumen token meminta token yang diperkecil cakupannya, broker token akan merespons dengan token yang diperkecil cakupannya dan jumlah detik hingga masa berlakunya habis. Jika masa berlaku token telah berakhir, server akan menolak permintaan. Untuk memuat ulang token yang diperkecil cakupannya, konsumen dapat meminta token yang diperkecil cakupannya dari broker sebelum masa berlaku token yang ada habis.
Langkah berikutnya
- Pelajari tentang kontrol akses untuk Cloud Storage.
- Membuat kredensial akun layanan yang berlaku singkat.
- Buat token akses OAuth 2.0 untuk akun layanan dengan salah satu metode berikut:
- Membuat token akses OAuth 2.0 untuk pengguna.
- Lihat izin di setiap peran bawaan.
- Pelajari tentang peran khusus.