Integrasikan REST API dengan kumpulan pengguna Amazon Cognito - Amazon API Gateway

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 CreateAuthorizertindakan 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, lihatMenerapkan REST API di API Gateway.

Untuk membuat COGNITO_USER_POOLS otorisasi menggunakan konsol API Gateway

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

  2. Di panel navigasi utama, pilih Authorizers.

  3. Pilih Buat Authorizer.

  4. 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.

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

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.

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

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

  4. 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']"
    }
}

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

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

Dengan COGNITO_USER_POOLS otorisasi, jika opsi OAuth Scopes 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_USER_POOLS dengan file definisi OpenAPI

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

  2. 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}"
        ]
      }
    }

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

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

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