Bekerja dengan sumber identitas dalam skema dan kebijakan - Izin Terverifikasi Amazon

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Bekerja dengan sumber identitas dalam skema dan kebijakan

Anda mungkin menemukan bahwa Anda ingin menambahkan sumber identitas ke toko kebijakan dan klaim penyedia peta ke skema toko kebijakan Anda. Anda dapat mengotomatiskan proses ini atau memperbarui skema Anda secara manual. Bagian panduan pengguna ini memiliki informasi berikut:

  • Bila Anda dapat secara otomatis mengisi atribut ke skema penyimpanan kebijakan

  • Cara menggunakan klaim token Amazon Cognito dan OIDC dalam kebijakan Izin Terverifikasi

  • Cara membuat skema untuk sumber identitas secara manual

Penyimpanan kebijakan terkait API dan penyimpanan kebijakan dengan sumber identitas melalui Penyiapan terpandu tidak memerlukan pemetaan manual atribut token identitas (ID) ke skema. Anda dapat memberikan Izin Terverifikasi dengan atribut di kumpulan pengguna atau token OIDC dan membuat skema yang diisi dengan atribut pengguna. Dalam otorisasi token ID, Izin Terverifikasi memetakan klaim ke atribut entitas utama. Anda mungkin perlu memetakan token Amazon Cognito secara manual ke skema Anda dalam kondisi berikut:

  • Anda membuat toko kebijakan kosong atau penyimpanan kebijakan dari sampel.

  • Anda ingin memperluas penggunaan token akses di luar kontrol akses berbasis peran (RBAC).

  • Anda membuat penyimpanan kebijakan dengan REST API Izin Terverifikasi, AWS SDK, atau. AWS CDK

Untuk menggunakan Amazon Cognito atau penyedia identitas OIDC (iDP) sebagai sumber identitas di toko kebijakan Izin Terverifikasi, Anda harus memiliki atribut penyedia dalam skema Anda. Jika Anda membuat toko kebijakan dengan cara yang secara otomatis mengisi skema Anda dari informasi penyedia dalam token ID, Anda siap untuk menulis kebijakan. Jika Anda membuat penyimpanan kebijakan tanpa skema untuk sumber identitas Anda, Anda harus menambahkan atribut penyedia ke skema. Skema Anda harus sesuai dengan entitas yang dibuat oleh token penyedia IsAuthorizedWithTokenatau permintaan BatchIsAuthorizedWithToken API. Kemudian Anda dapat menulis kebijakan menggunakan atribut dari token penyedia.

Untuk informasi selengkapnya tentang menggunakan ID Amazon Cognito dan token akses untuk pengguna yang diautentikasi di Izin Terverifikasi, lihat Otorisasi dengan Izin Terverifikasi Amazon di Panduan Pengembang Amazon Cognito.

Hal-hal yang perlu diketahui tentang pemetaan skema

Pemetaan atribut berbeda antara jenis token

Dalam otorisasi token akses, Izin Terverifikasi memetakan klaim ke konteks. Dalam otorisasi token ID, Izin Terverifikasi memetakan klaim ke atribut utama. Untuk penyimpanan kebijakan yang Anda buat di konsol Izin Terverifikasi, hanya penyimpanan kebijakan kosong dan sampel yang tidak memiliki sumber identitas dan mengharuskan Anda mengisi skema Anda dengan atribut kumpulan pengguna untuk otorisasi token ID. Otorisasi token akses didasarkan pada kontrol akses berbasis peran (RBAC) dengan klaim keanggotaan grup dan tidak secara otomatis memetakan klaim lain ke skema penyimpanan kebijakan.

Atribut sumber identitas tidak diperlukan

Saat Anda membuat sumber identitas di konsol Izin Terverifikasi, tidak ada atribut yang ditandai sebagai wajib. Ini mencegah klaim yang hilang menyebabkan kesalahan validasi dalam permintaan otorisasi. Anda dapat mengatur atribut ke required sesuai kebutuhan, tetapi atribut tersebut harus ada di semua permintaan otorisasi.

RBAC tidak memerlukan atribut dalam skema

Skema untuk sumber identitas bergantung pada asosiasi entitas yang Anda buat saat menambahkan sumber identitas. Sumber identitas memetakan satu klaim ke jenis entitas pengguna, dan satu klaim ke jenis entitas grup. Pemetaan entitas ini adalah inti dari konfigurasi sumber identitas. Dengan informasi minimum ini, Anda dapat menulis kebijakan yang melakukan tindakan otorisasi untuk pengguna tertentu dan grup tertentu yang mungkin menjadi anggota pengguna, dalam model kontrol akses berbasis peran (RBAC). Penambahan klaim token ke skema memperluas cakupan otorisasi toko kebijakan Anda. Atribut pengguna dari token ID memiliki informasi tentang pengguna yang dapat berkontribusi pada otorisasi kontrol akses berbasis atribut (ABAC). Atribut konteks dari token akses memiliki informasi seperti cakupan OAuth 2.0 yang dapat menyumbangkan informasi kontrol akses tambahan dari penyedia Anda, tetapi memerlukan modifikasi skema tambahan.

Opsi Pengaturan dengan API Gateway dan sumber identitas serta Penyiapan terpandu di konsol Izin Terverifikasi menetapkan klaim token ID ke skema. Ini tidak berlaku untuk klaim token akses. Untuk menambahkan klaim token akses non-grup ke skema Anda, Anda harus mengedit skema Anda dalam mode JSON dan menambahkan atribut CommonTypes. Untuk informasi selengkapnya, lihat Memetakan token akses.

Klaim grup OIDC mendukung berbagai format

Saat menambahkan penyedia OIDC, Anda dapat memilih nama klaim grup di ID atau token akses yang ingin dipetakan ke keanggotaan grup pengguna di toko kebijakan Anda. Izin terverifikasi mengenali klaim grup dalam format berikut:

  1. String tanpa spasi: "groups": "MyGroup"

  2. Daftar yang dibatasi ruang:. "groups": "MyGroup1 MyGroup2 MyGroup3" Setiap string adalah grup.

  3. Daftar JSON (dibatasi koma): "groups": ["MyGroup1", "MyGroup2", "MyGroup3"]

catatan

Izin Terverifikasi menafsirkan setiap string dalam klaim grup yang dipisahkan spasi sebagai grup terpisah. Untuk menafsirkan nama grup dengan karakter spasi sebagai grup tunggal, ganti atau hapus spasi dalam klaim. Misalnya, format grup bernama My Group sebagaiMyGroup.

Pilih jenis token

Cara penyimpanan kebijakan Anda bekerja dengan sumber identitas Anda bergantung pada keputusan kunci dalam konfigurasi sumber identitas: apakah Anda akan memproses ID atau token akses. Dengan penyedia identitas Amazon Cognito, Anda memiliki pilihan jenis token saat membuat toko kebijakan terkait API. Saat membuat penyimpanan kebijakan terkait API, Anda harus memilih apakah Anda ingin menyiapkan otorisasi untuk ID atau token akses. Informasi ini memengaruhi atribut skema yang diterapkan Izin Terverifikasi ke penyimpanan kebijakan Anda, dan sintaks otorisasi Lambda untuk API Gateway API Anda. Dengan penyedia OIDC, Anda harus memilih jenis token saat menambahkan sumber identitas. Anda dapat memilih ID atau token akses, dan pilihan Anda mengecualikan jenis token yang tidak dipilih untuk diproses di toko kebijakan Anda. Terutama jika Anda ingin mendapatkan keuntungan dari pemetaan otomatis klaim token ID ke atribut di konsol Izin Terverifikasi, putuskan lebih awal tentang jenis token yang ingin Anda proses sebelum Anda membuat sumber identitas Anda. Mengubah jenis token membutuhkan upaya yang signifikan untuk memfaktorkan ulang kebijakan dan skema Anda. Topik berikut menjelaskan penggunaan ID dan token akses dengan toko kebijakan.

Parser cedar membutuhkan tanda kurung untuk beberapa karakter

Kebijakan biasanya referensi atribut skema dalam format sepertiprincipal.username. Dalam kasus sebagian besar karakter non-alfanumerik seperti:,., atau / yang mungkin muncul di nama klaim token, Izin Terverifikasi tidak dapat mengurai nilai kondisi seperti atau. principal.cognito:groups context.ip-address Anda harus memformat kondisi ini dengan notasi braket dalam format principal["cognito:username"] ataucontext["ip-address"], masing-masing. Karakter garis bawah _ adalah karakter yang valid dalam nama klaim, dan satu-satunya pengecualian non-alfanumerik untuk persyaratan ini.

Contoh sebagian skema untuk atribut utama jenis ini terlihat seperti berikut:

"User": { "shape": { "type": "Record", "attributes": { "cognito:username": { "type": "String", "required": true }, "custom:employmentStoreCode": { "type": "String", "required": true, }, "email": { "type": "String", "required": false } } } }

Contoh sebagian skema untuk atribut konteks jenis ini terlihat seperti berikut:

"GetOrder": { "memberOf": [], "appliesTo": { "resourceTypes": [ "Order" ], "context": { "type": "Record", "attributes": { "ip-address": { "required": false, "type": "String" } } }, "principalTypes": [ "User" ] } }

Contoh kebijakan untuk atribut yang akan memvalidasi skema ini terlihat seperti berikut:

permit ( principal in MyCorp::UserGroup::"us-west-2_EXAMPLE|MyUserGroup", action, resource ) when { principal["cognito:username"] == "alice" && principal["custom:employmentStoreCode"] == "petstore-dallas" && principal has email && principal.email == "alice@example.com" && context["ip-address"] like "192.0.2.*" };

Memetakan token ID ke skema

Izin Terverifikasi memproses klaim token ID sebagai atribut pengguna: nama dan judul mereka, keanggotaan grup mereka, informasi kontak mereka. Token ID paling berguna dalam model otorisasi kontrol akses berbasis atribut (ABAC). Jika Anda ingin Izin Terverifikasi menganalisis akses ke sumber daya berdasarkan siapa yang membuat permintaan, pilih token ID untuk sumber identitas Anda.

Token ID Amazon Cognito

Token ID Amazon Cognito berfungsi dengan sebagian besar pustaka relying-party OIDC. Mereka memperluas fitur OIDC dengan klaim tambahan. Aplikasi Anda dapat mengautentikasi pengguna dengan operasi API autentikasi kumpulan pengguna Amazon Cognito, atau dengan UI yang dihosting kumpulan pengguna. Untuk informasi selengkapnya, lihat Menggunakan API dan titik akhir di Panduan Pengembang Amazon Cognito.

Klaim yang berguna dalam token ID Amazon Cognito
cognito:username dan preferred_username

Varian dari nama pengguna pengguna.

sub

Pengenal pengguna unik pengguna (UUID)

Klaim dengan custom: awalan

Awalan untuk atribut kumpulan pengguna kustom seperticustom:employmentStoreCode.

Klaim standar

Standar OIDC mengklaim seperti email dan. phone_number Untuk informasi selengkapnya, lihat Klaim standar di OpenID Connect Core 1.0 yang menggabungkan errata set 2.

cognito:groups

Keanggotaan grup pengguna. Dalam model otorisasi berdasarkan kontrol akses berbasis peran (RBAC), klaim ini menyajikan peran yang dapat Anda evaluasi dalam kebijakan Anda.

Klaim sementara

Klaim yang bukan milik pengguna, tetapi ditambahkan saat runtime oleh kumpulan pengguna Pre token generation Lambda trigger. Klaim transien menyerupai klaim standar tetapi berada di luar standar, misalnya tenant atau. department

Dalam kebijakan yang mereferensikan atribut Amazon Cognito yang memiliki : pemisah, rujuk atribut dalam format. principal["cognito:username"] Klaim peran cognito:groups adalah pengecualian untuk aturan ini. Izin Terverifikasi memetakan konten klaim ini ke entitas induk entitas pengguna.

Untuk informasi selengkapnya tentang struktur token ID dari kumpulan pengguna Amazon Cognito, lihat Menggunakan token ID di Panduan Pengembang Amazon Cognito.

Contoh ID token berikut memiliki masing-masing dari empat jenis atribut. Ini termasuk klaim khusus Amazon Cognitocognito:username, klaim khususcustom:employmentStoreCode, klaim standaremail, dan klaim sementara. tenant

{ "sub": "91eb4550-XXX", "cognito:groups": [ "Store-Owner-Role", "Customer" ], "email_verified": true, "clearance": "confidential", "iss": "https://cognito-idp.us-east-2.amazonaws.com/us-east-2_EXAMPLE", "cognito:username": "alice", "custom:employmentStoreCode": "petstore-dallas", "origin_jti": "5b9f50a3-05da-454a-8b99-b79c2349de77", "aud": "1example23456789", "event_id": "0ed5ad5c-7182-4ecf-XXX", "token_use": "id", "auth_time": 1687885407, "department": "engineering", "exp": 1687889006, "iat": 1687885407, "tenant": "x11app-tenant-1", "jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN1111111", "email": "alice@example.com" }

Saat membuat sumber identitas dengan kumpulan pengguna Amazon Cognito, Anda menentukan jenis entitas utama yang dihasilkan oleh Izin Terverifikasi dalam permintaan otorisasi. IsAuthorizedWithToken Kebijakan Anda kemudian dapat menguji atribut prinsipal tersebut sebagai bagian dari evaluasi permintaan tersebut. Skema Anda mendefinisikan jenis dan atribut utama untuk sumber identitas, dan kemudian Anda dapat mereferensikannya dalam kebijakan Cedar Anda.

Anda juga menentukan jenis entitas grup yang ingin Anda peroleh dari klaim grup token ID. Dalam permintaan otorisasi, Izin Terverifikasi memetakan setiap anggota grup yang diklaim ke jenis entitas grup tersebut. Dalam kebijakan, Anda dapat mereferensikan entitas grup tersebut sebagai prinsipal.

Contoh berikut menunjukkan cara mencerminkan atribut dari token identitas contoh dalam skema Izin Terverifikasi Anda. Untuk informasi selengkapnya tentang mengedit skema Anda, lihatMengedit skema dalam mode JSON. Jika konfigurasi sumber identitas Anda menentukan tipe utamaUser, maka Anda dapat menyertakan sesuatu yang mirip dengan contoh berikut untuk membuat atribut tersebut tersedia untuk Cedar.

"User": { "shape": { "type": "Record", "attributes": { "cognito:username": { "type": "String", "required": false }, "custom:employmentStoreCode": { "type": "String", "required": false }, "email": { "type": "String" }, "tenant": { "type": "String", "required": true } } } }

Setelah memperbarui skema untuk mencerminkan atribut Amazon Cognito, Anda dapat membuat kebijakan yang mereferensikan atribut.

permit ( principal in MyCorp::UserGroup::"us-west-2_EXAMPLE|MyUserGroup", action, resource ) when { principal["cognito:username"] == "alice" && principal["custom:employmentStoreCode"] == "petstore-dallas" && principal.tenant == "x11app-tenant-1" && principal has email && principal.email == "alice@example.com" };

Token ID OIDC

Bekerja dengan token ID dari penyedia OIDC hampir sama dengan bekerja dengan token ID Amazon Cognito. Perbedaannya ada pada klaim. IDP Anda mungkin menampilkan atribut OIDC standar, atau memiliki skema khusus. Saat membuat penyimpanan kebijakan baru di konsol Izin Terverifikasi, Anda dapat menambahkan sumber identitas OIDC dengan token ID contoh, atau Anda dapat memetakan klaim token secara manual ke atribut pengguna. Karena Izin Terverifikasi tidak mengetahui skema atribut IDP Anda, Anda harus memberikan informasi ini.

Untuk informasi selengkapnya, lihat Membuat toko kebijakan Izin Terverifikasi.

Berikut ini adalah contoh skema untuk toko kebijakan dengan sumber identitas OIDC.

"User": { "shape": { "type": "Record", "attributes": { "email": { "type": "String" }, "email_verified": { "type": "Boolean" }, "name": { "type": "String", "required": true }, "phone_number": { "type": "String" }, "phone_number_verified": { "type": "Boolean" } } } }

Kebijakan berikut berlaku untuk anggota grup di penyedia OIDC Anda.

permit ( principal in MyCorp::UserGroup::"MyOIDCProvider|MyUserGroup", action, resource ) when { principal.email_verified == true && principal.email == "alice@example.com" && principal.phone_number_verified == true && principal.phone_number like "+1206*" };

Memetakan token akses

Izin Terverifikasi memproses klaim token akses selain klaim grup sebagai atribut tindakan, atau atribut konteks. Seiring dengan keanggotaan grup, token akses dari IDP Anda mungkin berisi informasi tentang akses API. Token akses berguna dalam model otorisasi yang menggunakan kontrol akses berbasis peran (RBAC). Model otorisasi yang mengandalkan klaim token akses selain keanggotaan grup memerlukan upaya tambahan dalam konfigurasi skema.

Memetakan token akses Amazon Cognito

Token akses Amazon Cognito memiliki klaim yang dapat digunakan untuk otorisasi:

Klaim yang berguna dalam token akses Amazon Cognito
client_id

ID aplikasi klien dari pihak yang mengandalkan OIDC. Dengan ID klien, Izin Terverifikasi dapat memverifikasi bahwa permintaan otorisasi berasal dari klien yang diizinkan untuk penyimpanan kebijakan. Dalam otorisasi machine-to-machine (M2M), sistem permintaan mengotorisasi permintaan dengan rahasia klien dan memberikan ID klien dan cakupan sebagai bukti otorisasi.

scope

Cakupan OAuth 2.0 yang mewakili izin akses pembawa token.

cognito:groups

Keanggotaan grup pengguna. Dalam model otorisasi berdasarkan kontrol akses berbasis peran (RBAC), klaim ini menyajikan peran yang dapat Anda evaluasi dalam kebijakan Anda.

Klaim sementara

Klaim yang bukan merupakan izin akses, tetapi ditambahkan saat runtime oleh kumpulan pengguna Pre token generation Lambda trigger. Klaim transien menyerupai klaim standar tetapi berada di luar standar, misalnya tenant atau. department Kustomisasi token akses menambah biaya pada AWS tagihan Anda.

Untuk informasi selengkapnya tentang struktur token akses dari kumpulan pengguna Amazon Cognito, lihat Menggunakan token akses di Panduan Pengembang Amazon Cognito.

Token akses Amazon Cognito dipetakan ke objek konteks saat diteruskan ke Izin Terverifikasi. Atribut token akses dapat direferensikan menggunakancontext.token.attribute_name. Contoh token akses berikut mencakup scope klaim client_id dan klaim.

{ "sub": "91eb4550-9091-708c-a7a6-9758ef8b6b1e", "cognito:groups": [ "Store-Owner-Role", "Customer" ], "iss": "https://cognito-idp.us-east-2.amazonaws.com/us-east-2_EXAMPLE", "client_id": "1example23456789", "origin_jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN1111111", "event_id": "bda909cb-3e29-4bb8-83e3-ce6808f49011", "token_use": "access", "scope": "MyAPI/mydata.write", "auth_time": 1688092966, "exp": 1688096566, "iat": 1688092966, "jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN2222222", "username": "alice" }

Contoh berikut menunjukkan cara mencerminkan atribut dari token akses contoh dalam skema Izin Terverifikasi Anda. Untuk informasi selengkapnya tentang mengedit skema Anda, lihatMengedit skema dalam mode JSON.

{ "MyApplication": { "actions": { "Read": { "appliesTo": { "context": { "type": "ReusedContext" }, "resourceTypes": [ "Application" ], "principalTypes": [ "User" ] } } }, ... ... "commonTypes": { "ReusedContext": { "attributes": { "token": { "type": "Record", "attributes": { "scope": { "type": "Set", "element": { "type": "String" } }, "client_id": { "type": "String" } } } }, "type": "Record" } } } }

Setelah memperbarui skema untuk mencerminkan atribut Amazon Cognito, Anda dapat membuat kebijakan yang mereferensikan atribut.

permit(principal, action in [MyApplication::Action::"Read", MyApplication::Action::"GetStoreInventory"], resource) when { context.token.client_id == "52n97d5afhfiu1c4di1k5m8f60" && context.token.scope.contains("MyAPI/mydata.write") };

Memetakan token akses OIDC

Sebagian besar token akses dari penyedia OIDC eksternal sejajar erat dengan token akses Amazon Cognito. Token akses OIDC dipetakan ke objek konteks saat diteruskan ke Izin Terverifikasi. Atribut token akses dapat direferensikan menggunakancontext.token.attribute_name. Contoh token akses OIDC berikut mencakup contoh klaim dasar.

{ "sub": "91eb4550-9091-708c-a7a6-9758ef8b6b1e", "groups": [ "Store-Owner-Role", "Customer" ], "iss": "https://auth.example.com", "client_id": "1example23456789", "aud": "https://myapplication.example.com" "scope": "MyAPI-Read", "exp": 1688096566, "iat": 1688092966, "jti": "a1b2c3d4-e5f6-a1b2-c3d4-TOKEN2222222", "username": "alice" }

Contoh berikut menunjukkan cara mencerminkan atribut dari token akses contoh dalam skema Izin Terverifikasi Anda. Untuk informasi selengkapnya tentang mengedit skema Anda, lihatMengedit skema dalam mode JSON.

{ "MyApplication": { "actions": { "Read": { "appliesTo": { "context": { "type": "ReusedContext" }, "resourceTypes": [ "Application" ], "principalTypes": [ "User" ] } } }, ... ... "commonTypes": { "ReusedContext": { "attributes": { "token": { "type": "Record", "attributes": { "scope": { "type": "Set", "element": { "type": "String" } }, "client_id": { "type": "String" } } } }, "type": "Record" } } } }

Setelah memperbarui skema untuk mencerminkan atribut IDP, Anda dapat membuat kebijakan yang mereferensikan atribut.

permit( principal, action in [MyApplication::Action::"Read", MyApplication::Action::"GetStoreInventory"], resource ) when { context.token.client_id == "52n97d5afhfiu1c4di1k5m8f60" && context.token.scope.contains("MyAPI-read") };

Notasi alternatif untuk klaim Amazon Cognito colon-delimited

Pada saat Izin Terverifikasi diluncurkan, skema yang direkomendasikan untuk token Amazon Cognito mengklaim cognito:groups menyukai custom:store dan mengonversi string yang dibatasi titik dua ini untuk menggunakan karakter sebagai pembatas hierarki. . Format ini disebut notasi titik. Misalnya, referensi untuk cognito:groups menjadi principal.cognito.groups dalam kebijakan Anda. Meskipun Anda dapat terus menggunakan format ini, kami sarankan Anda membuat skema dan kebijakan Anda dengan notasi braket. Dalam format ini, referensi untuk cognito:groups menjadi principal["cognito:groups"] dalam kebijakan Anda. Skema yang dibuat secara otomatis untuk token ID kumpulan pengguna dari konsol Izin Terverifikasi menggunakan notasi braket.

Anda dapat terus menggunakan notasi titik dalam skema dan kebijakan yang dibuat secara manual untuk sumber identitas Amazon Cognito. Anda tidak dapat menggunakan notasi titik dengan : atau karakter non-alfanumerik lainnya dalam skema atau kebijakan untuk jenis OIDC IDP lainnya.

Skema untuk notasi titik bersarang setiap instance : karakter sebagai anak dari frasa custom awal cognito atau, seperti yang ditunjukkan pada contoh berikut:

"CognitoUser": { "shape": { "type": "Record", "attributes": { "cognito": { "type": "Record", "required": true, "attributes": { "username": { "type": "String", "required": true } } }, "custom": { "type": "Record", "required": true, "attributes": { "employmentStoreCode": { "type": "String", "required": true } } }, "email": { "type": "String" }, "tenant": { "type": "String", "required": true } } } }

Dengan skema dalam format ini, Anda dapat membuat kebijakan dengan notasi titik seperti pada contoh berikut:

permit(principal, action, resource) when { principal.cognito.username == "alice" && principal.custom.employmentStoreCode == "petstore-dallas" && principal.tenant == "x11app-tenant-1" && principal has email && principal.email == "alice@example.com" };