Integrasikan REST API dengan kumpulan pengguna Amazon Cognito

Buat API baru, atau pilih API yang ada di API Gateway.

Di panel navigasi utama, pilih Authorizers.

Pilih Buat Authorizer.

Untuk mengonfigurasi otorisasi baru untuk menggunakan kumpulan pengguna, lakukan hal berikut:

1. Untuk nama Authorizer, masukkan nama.

2. Untuk jenis Authorizer, pilih Cognito.

3. 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}.

4. Untuk sumber Token, masukkan Authorization sebagai nama header untuk meneruskan identitas atau token akses yang dikembalikan oleh Amazon Cognito saat pengguna berhasil masuk.

5. (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

6. Pilih Buat Authorizer.

Setelah membuat COGNITO_USER_POOLS otorisasi, Anda dapat menguji panggilannya secara opsional dengan menyediakan token identitas yang disediakan dari kumpulan pengguna. Anda dapat memperoleh token identitas ini dengan memanggil Amazon Cognito Identity SDK untuk melakukan login pengguna. Anda juga dapat menggunakan InitiateAuthaksinya. Jika Anda tidak mengonfigurasi cakupan Otorisasi apa pun, API Gateway memperlakukan token yang disediakan sebagai token identitas.

Pilih Sumber daya. Pilih metode baru atau pilih metode yang ada. Jika perlu, buat sumber daya.

Pada tab Permintaan metode, di bawah Pengaturan permintaan metode, pilih Edit.

Untuk Authorizer, dari menu tarik-turun, pilih otorisasi kumpulan pengguna Amazon Cognito yang baru saja Anda buat.

Untuk menggunakan token identitas, lakukan hal berikut:

1. Jaga Cakupan Otorisasi kosong.

2. 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 ataucustom-sub, dua notasi identik. Untuk nama properti kompleks, seperticustom:role, Anda tidak dapat menggunakan notasi titik. Misalnya, ekspresi pemetaan berikut meneruskan bidang standar 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 sebagaicustom:role, gunakan contoh berikut untuk mendapatkan properti klaim:

   {
   	"context" : {
   		"role" : "$context.authorizer.claims['custom:role']"
       }
   }

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 diberikanBuat kumpulan pengguna Amazon Cognito untuk REST API, salah satu cakupannya adalahhttps://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.

2. Pilih Simpan.

Ulangi langkah-langkah ini untuk metode lain yang Anda pilih.

Buat (atau ekspor) file definisi OpenAPI untuk API Anda.

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:

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"
        }
      },
      ...
   }

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"
        }
      },
      ...
   }

Jika diperlukan, Anda dapat mengatur pengaturan konfigurasi API lainnya dengan menggunakan definisi atau ekstensi OpenAPI yang sesuai. Untuk informasi selengkapnya, lihat Buka API ekstensi untuk API Gateway.