Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.
# Memetakan Amazon Cognito token ke skema
Anda mungkin menemukan bahwa Anda ingin menambahkan sumber identitas ke toko kebijakan dan klaim penyedia peta, atau token, ke skema toko kebijakan Anda. Anda dapat mengotomatiskan proses ini, dengan menggunakan [Penyiapan terpandu](policy-stores-create.md) untuk membuat penyimpanan kebijakan dengan sumber identitas, atau memperbarui skema secara manual setelah penyimpanan kebijakan dibuat. Setelah Anda memetakan token ke skema, Anda dapat membuat kebijakan yang mereferensikannya.
Bagian panduan pengguna ini memiliki informasi berikut:
+ Bila Anda dapat secara otomatis mengisi atribut ke skema penyimpanan kebijakan
+ Cara menggunakan klaim Amazon Cognito token dalam kebijakan Izin Terverifikasi
+ Cara membuat skema untuk sumber identitas secara manual
Penyimpanan [kebijakan terkait API dan penyimpanan](policy-stores-api-userpool.md) kebijakan dengan sumber identitas yang dibuat melalui [penyiapan Terpandu](policy-stores-create.md) tidak memerlukan pemetaan manual atribut token identitas (ID) ke skema. Anda dapat memberikan Izin Terverifikasi dengan atribut di kumpulan pengguna dan membuat skema yang diisi dengan atribut pengguna. Dalam otorisasi token ID, Izin Terverifikasi memetakan klaim ke atribut entitas utama. Anda mungkin perlu memetakan Amazon Cognito token 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 digunakan Amazon Cognito sebagai sumber identitas di toko kebijakan Izin Terverifikasi, Anda harus memiliki atribut penyedia dalam skema Anda. Skema diperbaiki dan harus sesuai dengan entitas yang dibuat oleh token penyedia [IsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_IsAuthorizedWithToken.html)atau permintaan [BatchIsAuthorizedWithToken](https://docs.aws.amazon.com/verifiedpermissions/latest/apireference/API_BatchIsAuthorizedWithToken.html)API. 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 harus menambahkan atribut penyedia ke skema yang cocok dengan entitas yang dibuat menggunakan permintaan 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](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-authorization-with-avp.html) Cognito.*
**Topics**
+ [Memetakan token ID ke skema](#cognito-map-id-token)
+ [Memetakan token akses](#cognito-map-access-token)
+ [Notasi alternatif untuk klaim yang dibatasi titik Amazon Cognito dua](#cognito-colon-claims)
+ [Hal-hal yang perlu diketahui tentang pemetaan skema](#cognito-map-token-to-schema-things-to-know)
## 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.
Amazon Cognito Token ID bekerja dengan sebagian besar pustaka [relying-party OIDC](https://openid.net/developers/certified-openid-connect-implementations/). 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](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pools-API-operations.html) di *Panduan Amazon Cognito Pengembang*.Klaim yang berguna dalam token Amazon Cognito ID
*`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 seperti`custom:employmentStoreCode`.
*Klaim standar*
Standar OIDC mengklaim seperti `email` dan. `phone_number` Untuk informasi selengkapnya, lihat [Klaim standar](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) 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](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html). Klaim transien menyerupai klaim standar tetapi berada di luar standar, misalnya `tenant` atau. `department`
Dalam kebijakan yang mereferensikan Amazon Cognito atribut 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](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html) Panduan *Amazon Cognito Pengembang*.
Contoh ID token berikut memiliki masing-masing dari empat jenis atribut. Ini termasuk klaim Amazon Cognito-spesifik`cognito:username`, klaim khusus`custom:employmentStoreCode`, klaim standar`email`, 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 Amazon Cognito pengguna, Anda menentukan jenis entitas utama yang dihasilkan 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, lihat[Mengedit skema toko kebijakan](schema-edit.md). Jika konfigurasi sumber identitas Anda menentukan tipe utama`User`, 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
}
}
}
}
```
Untuk contoh kebijakan yang akan memvalidasi skema ini, lihat. [Mencerminkan atribut token Amazon Cognito ID](policies-examples.md#policies-examples-cognito-id)
## 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.
Amazon Cognito token akses memiliki klaim yang dapat digunakan untuk otorisasi:Klaim yang berguna dalam token Amazon Cognito akses
*`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](https://datatracker.ietf.org/doc/html/rfc6749#section-3.3) 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](https://docs.aws.amazon.com/cognito/latest/developerguide/user-pool-lambda-pre-token-generation.html). 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](https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.html) Panduan *Amazon Cognito Pengembang*.
Token Amazon Cognito akses dipetakan ke objek konteks saat diteruskan ke Izin Terverifikasi. Atribut token akses dapat direferensikan menggunakan`context.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, lihat[Mengedit skema toko kebijakan](schema-edit.md).
```
{
"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"
}
}
}
}
```
Untuk contoh kebijakan yang akan memvalidasi skema ini, lihat. [Mencerminkan atribut token Amazon Cognito akses](policies-examples.md#policies-examples-cognito-access)
## Notasi alternatif untuk klaim yang dibatasi titik Amazon Cognito dua
Pada saat Izin Terverifikasi diluncurkan, skema yang direkomendasikan untuk klaim Amazon Cognito token menyukai `cognito:groups` dan `custom:store` mengonversi string yang dibatasi kolon 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](#cognito-map-token-to-schema-things-to-know). 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
}
}
}
}
```
Untuk contoh kebijakan yang akan memvalidasi skema ini dan menggunakan notasi titik, lihat. [Menggunakan notasi titik untuk referensi atribut](policies-examples.md#policies-examples-dot)
## Hal-hal yang perlu diketahui tentang pemetaan skema
**Pemetaan atribut berbeda antara jenis token**
[Dalam otorisasi token akses, Izin Terverifikasi memetakan klaim ke konteks.](context.md) 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 penyedia 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.](https://docs.cedarpolicy.com/schema/json-schema.html#schema-commonTypes) Untuk informasi selengkapnya, lihat [Memetakan token akses](#cognito-map-access-token).
**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 Amazon Cognito identitas, Anda memiliki pilihan jenis token saat membuat toko kebijakan terkait API. Saat membuat [penyimpanan kebijakan terkait API](policy-stores-api-userpool.md), Anda harus memilih apakah Anda ingin menyiapkan otorisasi untuk ID atau token akses. Informasi ini memengaruhi atribut skema yang diterapkan Izin Terverifikasi untuk penyimpanan kebijakan Anda, dan sintaks otorisasi Lambda untuk API Anda. API Gateway 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 seperti`principal.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:username` `context.ip-address` Anda harus memformat kondisi ini dengan notasi braket dalam format `principal["cognito:username"]` atau`context["ip-address"]`, masing-masing. Karakter garis bawah `_` adalah karakter yang valid dalam nama klaim, dan satu-satunya pengecualian non-alfanumerik untuk persyaratan ini.
Contoh skema parsi 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"
]
}
}
```
Untuk contoh kebijakan yang akan memvalidasi skema ini, lihat. [Menggunakan notasi braket untuk referensi atribut token](policies-examples.md#policies-examples-brackets)