Halaman ini menjelaskan cara menggunakan Batas Akses Kredensial untuk memperkecil cakupan, atau membatasi, izin Identity and Access Management (IAM) yang dapat digunakan kredensial yang berlaku singkat.
Anda dapat menggunakan Batas Akses Kredensial untuk membuat token akses OAuth 2.0 yang menampilkan akun layanan, tetapi memiliki lebih sedikit izin daripada akun layanan. Contohnya, jika salah satu pelanggan Anda perlu mengakses data Cloud Storage yang Anda kontrol, Anda dapat melakukan hal berikut:
- Buat akun layanan yang dapat mengakses setiap bucket Cloud Storage yang Anda miliki.
- Buat token akses OAuth 2.0 untuk akun layanan.
- Terapkan Batas Akses Kredensial yang hanya mengizinkan akses ke bucket yang berisi data pelanggan Anda.
Cara kerja Batas Akses Kredensial
Untuk memperkecil cakupan izin, tentukan Batas Akses Kredensial yang menentukan resource mana yang dapat diakses oleh kredensial yang berlaku singkat, serta batas atas pada izin yang tersedia di setiap resource. Anda kemudian dapat membuat kredensial yang berlaku singkat, lalu menukarnya dengan kredensial baru yang mematuhi Batas Akses Kredensial.
Jika Anda perlu memberikan serangkaian izin yang berbeda kepada akun utama untuk setiap sesi, menggunakan Batas Akses Kredensial akan lebih efisien daripada membuat banyak akun layanan yang berbeda dan memberi setiap akun layanan serangkaian peran yang berbeda.
Contoh Batas Akses Kredensial
Bagian berikut menampilkan contoh Batas Akses Kredensial untuk kasus penggunaan umum. Anda menggunakan Batas Akses Kredensial saat menukar token akses OAuth 2.0 dengan token yang diperkecil cakupannya.
Membatasi izin untuk bucket
Contoh berikut menampilkan Batas Akses Kredensial sederhana. Hal ini berlaku untuk
bucket Cloud Storage example-bucket
, dan menetapkan batas atas ke
izin yang disertakan dalam peran Storage Object Viewer
(roles/storage.objectViewer
):
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:roles/storage.objectViewer"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket"
}
]
}
}
Membatasi izin untuk beberapa bucket
Contoh berikut menunjukkan Batas Akses Kredensial yang menyertakan aturan untuk beberapa bucket:
- Bucket Cloud Storage
example-bucket-1
: Untuk bucket ini, hanya izin dalam peran Storage Object Viewer (roles/storage.objectViewer
) yang tersedia. - Bucket Cloud Storage
example-bucket-2
: Untuk bucket ini, hanya izin dalam peran Pembuat Storage Object (roles/storage.objectCreator
) yang tersedia.
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:roles/storage.objectViewer"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket-1"
},
{
"availablePermissions": [
"inRole:roles/storage.objectCreator"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket-2"
}
]
}
}
Membatasi izin untuk objek tertentu
Anda juga dapat menggunakan IAM Conditions untuk menentukan
objek Cloud Storage mana yang dapat diakses akun utama. Contohnya, Anda dapat
menambahkan kondisi yang menyediakan izin untuk objek yang namanya diawali
dengan customer-a
:
{ "accessBoundary": { "accessBoundaryRules": [ { "availablePermissions": [ "inRole:roles/storage.objectViewer" ], "availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket", "availabilityCondition": { "expression" : "resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a')" } } ] } }
Membatasi izin saat mencantumkan objek
Saat Anda mencantumkan objek di bucket Cloud Storage, Anda
memanggil metode pada resource bucket, bukan resource objek. Akibatnya,
jika suatu kondisi dievaluasi untuk permintaan daftar, dan kondisi tersebut mengacu pada
nama resource, maka nama resource akan mengidentifikasi bucket,
bukan objek di dalam bucket. Contohnya, saat Anda mencantumkan objek dalam
example-bucket
, nama resource adalah projects/_/buckets/example-bucket
.
Konvensi penamaan ini dapat menyebabkan perilaku yang tidak diharapkan saat Anda mencantumkan objek.
Contohnya, Anda menginginkan Batas Akses Kredensial yang mengizinkan akses
tampilan ke objek di example-bucket
dengan awalan customer-a/invoices/
.
Anda dapat mencoba menggunakan kondisi berikut di Batas Akses Kredensial:
Tidak lengkap: Kondisi yang hanya memeriksa nama resource
resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/')
Kondisi ini berfungsi untuk membaca objek, tetapi tidak untuk mencantumkan objek:
- Saat akun utama mencoba membaca objek dalam
example-bucket
dengan awalancustomer-a/invoices/
, kondisi akan bernilaitrue
. - Saat akun utama mencoba mencantumkan objek dengan awalan tersebut, kondisi
akan bernilai
false
. Nilairesource.name
adalahprojects/_/buckets/example-bucket
, yang tidak dimulai denganprojects/_/buckets/example-bucket/objects/customer-a/invoices/
.
Untuk mencegah masalah ini, selain menggunakan resource.name.startsWith()
, kondisi
Anda dapat memeriksa atribut API bernama
storage.googleapis.com/objectListPrefix
. Atribut ini berisi nilai
parameter prefix
yang digunakan untuk memfilter daftar objek. Sebagai hasilnya,
Anda dapat menulis kondisi yang merujuk pada nilai parameter prefix
.
Contoh berikut menunjukkan cara menggunakan atribut API dalam sebuah kondisi. Hal ini
mengizinkan pembacaan dan mencantumkan objek dalam example-bucket
dengan awalan
customer-a/invoices/
:
Lengkap: Kondisi yang memeriksa nama resource dan awalan
resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/') || api.getAttribute('storage.googleapis.com/objectListPrefix', '') .startsWith('customer-a/invoices/')
Sekarang Anda dapat menggunakan kondisi ini di Batas Akses Kredensial:
{
"accessBoundary": {
"accessBoundaryRules": [
{
"availablePermissions": [
"inRole:roles/storage.objectViewer"
],
"availableResource": "//storage.googleapis.com/projects/_/buckets/example-bucket",
"availabilityCondition": {
"expression":
"resource.name.startsWith('projects/_/buckets/example-bucket/objects/customer-a/invoices/') || api.getAttribute('storage.googleapis.com/objectListPrefix', '').startsWith('customer-a/invoices/')"
}
}
]
}
}
Sebelum memulai
Sebelum Anda menggunakan Batas Akses Kredensial, pastikan Anda memenuhi persyaratan berikut:
Anda hanya perlu memperkecil cakupan izin untuk Cloud Storage, bukan untuk layanan Google 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:
-
Aktifkan API IAM and Security Token Service.
Membuat kredensial yang berlaku singkat yang diperkecil cakupannya
Untuk membuat token akses OAuth 2.0 dengan izin yang diperkecil cakupannya, ikuti 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.
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.
Komponen Batas Akses Kredensial
Batas Akses Kredensial adalah objek yang berisi daftar aturan batas akses. Setiap aturan berisi informasi berikut:
- Resource tempat aturan diterapkan.
- Batas atas izin yang tersedia pada resource tersebut.
- Opsional: Kondisi yang membatasi izin lebih lanjut. Kondisi mencakup
hal berikut:
- Ekspresi kondisi yang bernilai
true
ataufalse
. Jika bernilaitrue
, akses akan diizinkan; jika tidak, akses akan ditolak. - Opsional: Judul yang mengidentifikasi kondisi.
- Opsional: Deskripsi yang berisi informasi selengkapnya tentang kondisi tersebut.
- Ekspresi kondisi yang bernilai
Jika Anda menerapkan Batas Akses Kredensial ke kredensial yang berlaku singkat, maka kredensial hanya dapat mengakses resource di Batas Akses Kredensial. Tidak ada izin yang tersedia di resource lain.
Batas Akses Kredensial dapat berisi hingga 10 aturan batas akses. Anda hanya dapat menerapkan satu Batas Akses Kredensial untuk setiap kredensial yang berlaku singkat.
Saat ditampilkan sebagai objek JSON, Batas Akses Kredensial berisi kolom berikut:
Kolom | |
---|---|
accessBoundary |
Wrapper untuk Batas Akses Kredensial. |
accessBoundary.accessBoundaryRules[] |
Daftar aturan batas akses untuk diterapkan ke kredensial yang berlaku singkat. |
accessBoundary.accessBoundaryRules[].availablePermissions[] |
Daftar yang menentukan batas atas pada izin yang tersedia untuk resource.
Setiap nilai adalah ID untuk
peran bawaan atau
peran khusus IAM, dengan
awalan |
accessBoundary.accessBoundaryRules[].availableResource |
Nama lengkap resource bucket Cloud Storage tempat aturan
diterapkan. Gunakan format
|
accessBoundary.accessBoundaryRules[].availabilityCondition |
Opsional. Kondisi yang membatasi ketersediaan izin untuk objek Cloud Storage tertentu. Gunakan kolom ini jika Anda ingin menyediakan izin untuk objek tertentu, bukan semua objek dalam bucket Cloud Storage. |
accessBoundary.accessBoundaryRules[].availabilityCondition.expression |
Ekspresi kondisi yang menentukan objek Cloud Storage yang izinnya tersedia.
Untuk mempelajari cara merujuk ke objek tertentu dalam ekspresi kondisi,
lihat
atribut
|
accessBoundary.accessBoundaryRules[].availabilityCondition.title |
Opsional. String pendek yang mengidentifikasi tujuan kondisi. |
accessBoundary.accessBoundaryRules[].availabilityCondition.description |
Opsional. Detail tentang tujuan kondisi. |
Untuk contoh dalam format JSON, lihat Contoh Batas Akses Kredensial di halaman ini.
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.
Menukar dan memuat ulang token akses secara otomatis
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:
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 mana dari paket ini yang Anda gunakan, jalankan perintah berikut dalam 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 mana dari artefak ini yang Anda gunakan, 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 mana dari paket ini yang Anda gunakan, jalankan perintah berikut dalam 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 mana dari paket ini yang Anda gunakan, 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 format 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 ada jika token akses asli menampilkan akun layanan. Jika kolom ini tidak ada, token yang diperkecil cakupannya akan memiliki waktu yang sama dengan masa berlaku token akses asli. |
issued_token_type |
Berisi nilai
|
token_type |
Berisi nilai |
Contohnya, jika Batas Akses Kredensial format 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 harus merespons dengan token yang diperkecil cakupannya dan jumlah detik hingga masa berlakunya habis. Untuk memuat ulang token yang diperkecil cakupannya, konsumen dapat meminta token yang diperkecil cakupannya dari broker sebelum masa berlaku token yang ada habis.
Langkah selanjutnya
- Pelajari tentang kontrol akses untuk Cloud Storage.
- Membuat kredensial akun layanan yang berlaku singkat.
- Membuat token akses OAuth 2.0 untuk akun layanan, menggunakan alur OAuth 2.0 server ke server atau Service Account Credentials API.
- Membuat token akses OAuth 2.0 untuk pengguna.
- Lihat izin di setiap peran bawaan.
- Pelajari tentang peran khusus.