Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris. # Integrasikan REST API dengan kumpulan pengguna Amazon Cognito Setelah membuat kumpulan pengguna Amazon Cognito, di API Gateway, Anda harus membuat `COGNITO_USER_POOLS` otorisasi yang menggunakan kumpulan pengguna. Prosedur berikut menunjukkan cara melakukannya menggunakan konsol API Gateway. **catatan** Anda dapat menggunakan [https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html](https://docs.aws.amazon.com/apigateway/latest/api/API_CreateAuthorizer.html)tindakan untuk membuat `COGNITO_USER_POOLS` otorisasi yang menggunakan beberapa kumpulan pengguna. Anda dapat menggunakan hingga 1.000 kumpulan pengguna untuk satu `COGNITO_USER_POOLS` otorisasi. Batas ini tidak dapat dinaikkan. **penting** Setelah melakukan salah satu prosedur di bawah ini, Anda harus menerapkan atau menerapkan ulang API Anda untuk menyebarkan perubahan. Untuk informasi selengkapnya tentang penerapan API Anda, lihat[Menerapkan REST APIs di API Gateway](how-to-deploy-api.md). **Untuk membuat `COGNITO_USER_POOLS` otorisasi menggunakan konsol API Gateway** 1. Buat API baru, atau pilih API yang ada di API Gateway. 1. Di panel navigasi utama, pilih **Authorizers**. 1. Pilih **Buat Authorizer**. 1. Untuk mengonfigurasi otorisasi baru untuk menggunakan kumpulan pengguna, lakukan hal berikut: 1. Untuk **nama Authorizer**, masukkan nama. 1. Untuk **jenis Authorizer**, pilih **Cognito**. 1. Untuk **kumpulan pengguna Cognito**, pilih Wilayah AWS tempat Anda membuat Amazon Cognito dan pilih kumpulan pengguna yang tersedia. Anda dapat menggunakan variabel tahap untuk menentukan kumpulan pengguna Anda. Gunakan format berikut untuk kumpulan pengguna Anda:`arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool}`. 1. Untuk **sumber Token**, masukkan **Authorization** sebagai nama header untuk meneruskan identitas atau token akses yang dikembalikan oleh Amazon Cognito saat pengguna berhasil masuk. 1. (Opsional) Masukkan ekspresi reguler di bidang **validasi Token** untuk memvalidasi bidang `aud` (audiens) token identitas sebelum permintaan diotorisasi dengan Amazon Cognito. Perhatikan bahwa saat menggunakan token akses validasi ini menolak permintaan karena token akses tidak berisi bidang. `aud` 1. Pilih **Buat Authorizer**. 1. Setelah membuat `COGNITO_USER_POOLS` otorisasi, Anda dapat menguji panggilannya dengan menyediakan token identitas yang disediakan dari kumpulan pengguna. Anda tidak dapat menggunakan token akses untuk menguji pemanggilan otorisasi Anda. Anda dapat memperoleh token identitas ini dengan memanggil [Amazon Cognito Identity SDK](https://docs.aws.amazon.com/cognito/latest/developerguide/cognito-integrate-apps.html) untuk melakukan login pengguna. Anda juga dapat menggunakan [https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html](https://docs.aws.amazon.com/cognito-user-identity-pools/latest/APIReference/API_InitiateAuth.html)aksinya. Jika Anda tidak mengonfigurasi **cakupan Otorisasi** apa pun, API Gateway memperlakukan token yang disediakan sebagai token identitas. Prosedur sebelumnya membuat `COGNITO_USER_POOLS` otorisasi yang menggunakan kumpulan pengguna Amazon Cognito yang baru dibuat. Bergantung pada cara Anda mengaktifkan otorisasi pada metode API, Anda dapat menggunakan token identitas atau token akses yang disediakan dari kumpulan pengguna terintegrasi. **Untuk mengkonfigurasi `COGNITO_USER_POOLS` otorisasi pada metode** 1. Pilih **Sumber daya**. Pilih metode baru atau pilih metode yang ada. Jika perlu, buat sumber daya. 1. Pada tab **Permintaan metode**, di bawah **Pengaturan permintaan metode**, pilih **Edit**. 1. Untuk **Authorizer, dari menu tarik-turun, pilih otorisasi** **kumpulan pengguna Amazon Cognito yang baru saja** Anda buat. 1. Untuk menggunakan token identitas, lakukan hal berikut: 1. Jaga **Cakupan Otorisasi kosong**. 1. Jika diperlukan, dalam **permintaan Integrasi**, tambahkan `$context.authorizer.claims.property-name` ekspresi `$context.authorizer.claims['property-name']` atau dalam templat pemetaan tubuh untuk meneruskan properti klaim identitas yang ditentukan dari kumpulan pengguna ke backend. Untuk nama properti sederhana, seperti `sub` atau`custom-sub`, dua notasi identik. Untuk nama properti kompleks, seperti`custom:role`, Anda tidak dapat menggunakan notasi titik. Misalnya, ekspresi pemetaan berikut meneruskan [bidang standar](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) klaim `sub` dan `email` ke backend: ``` { "context" : { "sub" : "$context.authorizer.claims.sub", "email" : "$context.authorizer.claims.email" } } ``` Jika Anda mendeklarasikan bidang klaim kustom saat mengonfigurasi kumpulan pengguna, Anda dapat mengikuti pola yang sama untuk mengakses bidang kustom. Contoh berikut mendapatkan `role` bidang khusus klaim: ``` { "context" : { "role" : "$context.authorizer.claims.role" } } ``` Jika bidang klaim kustom dideklarasikan sebagai`custom:role`, gunakan contoh berikut untuk mendapatkan properti klaim: ``` { "context" : { "role" : "$context.authorizer.claims['custom:role']" } } ``` 1. Untuk menggunakan token akses, lakukan hal berikut: 1. Untuk **Cakupan Otorisasi**, masukkan satu atau beberapa nama lengkap cakupan yang telah dikonfigurasi saat kumpulan pengguna Amazon Cognito dibuat. Misalnya, mengikuti contoh yang diberikan[Buat kumpulan pengguna Amazon Cognito untuk REST API](apigateway-create-cognito-user-pool.md), salah satu cakupannya adalah`https://my-petstore-api.example.com/cats.read`. Saat runtime, pemanggilan metode berhasil jika cakupan apa pun yang ditentukan pada metode dalam langkah ini cocok dengan cakupan yang diklaim dalam token yang masuk. Jika tidak, panggilan gagal dengan `401 Unauthorized` respons. 1. Pilih **Simpan**. 1. Ulangi langkah-langkah ini untuk metode lain yang Anda pilih. Dengan `COGNITO_USER_POOLS` otorisasi, jika opsi **OAuthScopes** tidak ditentukan, API Gateway memperlakukan token yang disediakan sebagai token identitas dan memverifikasi identitas yang diklaim terhadap yang dari kumpulan pengguna. Jika tidak, API Gateway memperlakukan token yang disediakan sebagai token akses dan memverifikasi cakupan akses yang diklaim dalam token terhadap cakupan otorisasi yang dideklarasikan pada metode. Alih-alih menggunakan konsol API Gateway, Anda juga dapat mengaktifkan kumpulan pengguna Amazon Cognito pada metode dengan menentukan file definisi OpenAPI dan mengimpor definisi API ke API Gateway. **Untuk mengimpor otorisasi COGNITO\$1USER\$1POOLS dengan file definisi OpenAPI** 1. Buat (atau ekspor) file definisi OpenAPI untuk API Anda. 1. Tentukan definisi JSON `COGNITO_USER_POOLS` authorizer (`MyUserPool`) sebagai bagian dari `securitySchemes` bagian di OpenAPI 3.0 atau `securityDefinitions` bagian di Open API 2.0 sebagai berikut: ------ #### [ OpenAPI 3.0 ] ``` "securitySchemes": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ #### [ OpenAPI 2.0 ] ``` "securityDefinitions": { "MyUserPool": { "type": "apiKey", "name": "Authorization", "in": "header", "x-amazon-apigateway-authtype": "cognito_user_pools", "x-amazon-apigateway-authorizer": { "type": "cognito_user_pools", "providerARNs": [ "arn:aws:cognito-idp:{region}:{account_id}:userpool/{user_pool_id}" ] } } ``` ------ 1. Untuk menggunakan token identitas untuk otorisasi metode, tambahkan `{ "MyUserPool": [] }` ke `security` definisi metode, seperti yang ditunjukkan dalam metode GET berikut pada sumber daya root. ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": [] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. Untuk menggunakan token akses untuk otorisasi metode, ubah definisi keamanan di atas menjadi`{ "MyUserPool": [resource-server/scope, ...] }`: ``` "paths": { "/": { "get": { "consumes": [ "application/json" ], "produces": [ "text/html" ], "responses": { "200": { "description": "200 response", "headers": { "Content-Type": { "type": "string" } } } }, "security": [ { "MyUserPool": ["https://my-petstore-api.example.com/cats.read", "http://my.resource.com/file.read"] } ], "x-amazon-apigateway-integration": { "type": "mock", "responses": { "default": { "statusCode": "200", "responseParameters": { "method.response.header.Content-Type": "'text/html'" }, } }, "requestTemplates": { "application/json": "{\"statusCode\": 200}" }, "passthroughBehavior": "when_no_match" } }, ... } ``` 1. Jika diperlukan, Anda dapat mengatur pengaturan konfigurasi API lainnya dengan menggunakan definisi atau ekstensi OpenAPI yang sesuai. Untuk informasi selengkapnya, lihat [Ekstensi OpenAPI untuk API Gateway](api-gateway-swagger-extensions.md).