REST API と Amazon Cognito ユーザープールを統合する - Amazon API Gateway

REST API と Amazon Cognito ユーザープールを統合する

API Gateway で Amazon Cognito ユーザープールを作成し、そのユーザープールを使用する COGNITO_USER_POOLS オーソライザーを作成する必要があります。次の手順では、この操作を API Gateway コンソールを使用して行う方法について説明します。

注記

CreateAuthorizer アクションを使用して、複数のユーザープールを使用する COGNITO_USER_POOLS オーソライザーを作成できます。1 つの COGNITO_USER_POOLS オーソライザーには最大 1,000 のユーザープールを使用できます。この制限を増やすことはできません。

重要

以下の手順の実行後、API をデプロイまたは再デプロイして変更を伝達する必要があります。API のデプロイの詳細については、「Amazon API Gateway での REST API のデプロイ」を参照してください。

API Gateway コンソールを使用して COGNITO_USER_POOLS 認証を作成するには

  1. 新しい API を作成、または API Gateway に既存の API を選択します。

  2. メインナビゲーションペインで、[オーソライザー] を選択します。

  3. [オーソライザーの作成] を選択します。

  4. ユーザープールを使用するように新しいオーソライザーを設定するには、次の手順を実行します。

    1. [オーソライザー名] に名前を入力します。

    2. [オーソライザータイプ] には、[Cognito] を選択します。

    3. [Cognito ユーザープール] では、Amazon Cognito を作成した場所 AWS リージョン を選択し、使用可能なユーザープールを選択します。

      ユーザープールを定義するには、ステージ変数を使用できます。ユーザープールには、形式として arn:aws:cognito-idp:us-east-2:111122223333:userpool/${stageVariables.MyUserPool} を使用します。

    4. ユーザーがサインインした際に Amazon Cognito が返す ID またはアクセストークンを渡すように、[トークンソース] には、ヘッダー名として Authorization と入力します。

    5. (オプション) 必要に応じて [トークン検証] フィールドに正規表現を入力して、リクエストが Amazon Cognito で承認される前に ID トークンの aud (対象者) フィールドを検証します。アクセストークンを使用する場合、この検証では、アクセストークンが aud フィールドを含まないために要求が拒否されることに注意してください。

    6. [オーソライザーの作成] を選択します。

  5. COGNITO_USER_POOLS オーソライザーを作成した後、必要に応じて、ユーザープールからプロビジョニングされた ID トークンを指定することで、呼び出しをテストできます。Amazon Cognito ID SDK を呼び出してユーザーサインインを実行することで、この ID トークンを取得できます。InitiateAuth アクションも使用できます。[認証スコープ] を設定しない場合、API Gateway は指定されたトークンを ID トークンとして扱います。

前述の手順では、新しく作成した Amazon Cognito ユーザープールを使用する COGNITO_USER_POOLS オーソライザーを作成します。API メソッドでオーソライザーを有効にした方法に応じて、統合トークンまたは統合ユーザープールからプロビジョニングされたアクセストークンを使用できます。

メソッドで COGNITO_USER_POOLS オーソライザーを設定するには

  1. [リソース] をクリックします。新しいメソッドを選択するか、既存のメソッドを選択します。必要に応じて、リソースを作成します。

  2. [メソッドリクエスト] タブの [メソッドリクエスト設定] で、[編集] を選択します。

  3. [オーソライザー] には、ドロップダウンメニューから、先ほど作成した Amazon Cognito ユーザープールオーソライザーを選択します。

  4. ID トークンを使用するには、次の操作を行います。

    1. [認証スコープ] は空のままにしておきます。

    2. 必要に応じて、[統合リクエスト] で、ユーザープールからバックエンドに特定の ID クレームプロパティを渡すために、本文マッピングテンプレートに $context.authorizer.claims['property-name'] 式または $context.authorizer.claims.property-name 式を追加します。sub やcustom-sub などの簡単なプロパティ名については、2 つの表記法は同じです。custom:role などの複雑なプロパティ名の場合、ドット表記は使用できません。たとえば、以下のマッピング式は、バックエンドに、クレームの sub および email の標準フィールドを渡します。

      {
	"context" : {
		"sub" : "$context.authorizer.claims.sub",
		"email" : "$context.authorizer.claims.email"
	}
}

      ユーザープールを設定するときにカスタムクレームフィールドを宣言した場合は、同じパターンに従ってカスタムフィールドにアクセスできます。次の例では、クレームの role カスタムフィールドを取得します。

      {
	"context" : {
		"role" : "$context.authorizer.claims.role"
    }
}

      カスタムクレームフィールドが custom:role として宣言されている場合は、以下の例を使用してクレームのプロパティを取得します。

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

  5. アクセストークンを使用するには、次の操作を行います。

    1. [認証スコープ] には、Amazon Cognito ユーザープールが作成された際に設定されたスコープのフルネームを 1 つ以上入力します。たとえば、「REST API 用の Amazon Cognito ユーザープールを作成する」の例では、スコープの 1 つは https://my-petstore-api.example.com/cats.read です。

      実行時に、このステップのメソッドで指定されたスコープが、受信トークンで要求されているスコープと一致する場合、メソッド呼び出しは成功します。それ以外の場合、401 Unauthorized レスポンスでコールが失敗します。

    2. [Save] を選択します。

  6. 選択した他のメソッドにこれらの手順を繰り返してください。

COGNITO_USER_POOLS オーソライザーで、[OAuth Scopes] オプションが指定されていない場合、API Gateway は、指定されたトークンを ID トークンとして処理し、ユーザープールからのトークンに対して、要求された ID を検証します。それ以外の場合、API Gateway は提供されたトークンをアクセストークンとして処理し、トークンで要求されたアクセススコープをメソッドで宣言されている承認スコープと照合して検証します。

API Gateway コンソールを使う代わりに、OpenAPI 定義ファイル内で指定してメソッド上での Amazon Cognito ユーザープールを有効化し、API 定義を API Gateway にインポートすることもできます。

OpenAPI 定義ファイルを使って COGNITO_USER_POOLS オーソライザーをインポートするには

  1. API 用の OpenAPI 定義ファイルを作成 (またはエクスポート) します。

  2. OpenAPI 3.0 の securitySchemes セクション、または Open API 2.0 の securityDefinitions セクションの一部として、COGNITO_USER_POOLS オーソライザー (MyUserPool) JSON を次のように指定します。

    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. メソッドの認可にアイデンティティトークンを使用するには、ルートリソースの次の GET メソッドに示すように、メソッドの { "MyUserPool": [] } 定義に security を追加します。

      "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. メソッドの認可にアクセストークンを使用するには、上記のセキュリティ定義を { "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. 必要に応じて、OpenAPI 定義または拡張機能を使用し、他の API 設定を指定します。詳細については、「OpenAPI への API Gateway 拡張機能の使用」を参照してください。