Amazon API Gateway
開発者ガイド

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

API Gateway で Amazon Cognito ユーザープールを作成してから、そのユーザープールを使用する COGNITO_USER_POOLS オーソライザーを作成する必要があります。以下の手順は、API Gateway コンソールを使用してこれを行うステップを説明します。

重要

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

API Gateway コンソールを使用して COGNITO_USER_POOLS オーソライザーを作成するには

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

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

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

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

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

    2. [Cognito] オプションを選択します。

    3. [Cognito ユーザープール] からリージョンを選択します。

    4. 利用可能なユーザープールを選択します。ドロップダウンリストに表示されるには、Amazon Cognito で選択したリージョンにユーザープールを作成している必要があります。

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

    6. 必要に応じて [Token validation (トークン検証)] フィールドに正規表現を入力して、リクエストが Amazon Cognito で承認される前に ID トークンの aud (対象者) フィールドを検証します。

    7. [作成] を選択して、ユーザープールと API の統合を終了します。

  5. COGNITO_USER_POOLS オーソライザーを作成した後、必要に応じて、ユーザープールからプロビジョニングされた ID トークンを指定することで、呼び出しをテストできます。Amazon Cognito ID SDK を呼び出してユーザーサインインを実行することで、この ID トークンを取得できます。アクセストークンではなく、返された ID トークンを使用してください。

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

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

  1. API のメソッドを選択 (または作成) します。

  2. [メソッドリクエスト] を選択します。

  3. [設定] で [権限付与] の横の鉛筆アイコンを選択します。

  4. ドロップダウンリストから利用可能な [Amazon Cognito ユーザープールオーソライザー] の 1 つを選択します。

  5. チェックマークアイコンを選択して、設定を保存します。

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

    1. [OAuth スコープ] オプションを指定しないでください (NONE のままにしておきます)。

    2. 必要に応じて、[統合リクエスト] を選択して、ユーザープールからバックエンドに特定の ID クレームプロパティを渡すために、本文マッピングテンプレートに $context.authorizer.claims['property-name'] 式または $context.authorizer.claims.property-name 式を追加します。subcustom-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']" } }
  7. アクセストークンを使用するには、次の操作を行います。

    1. [OAuth スコープ] の横の鉛筆アイコンを選択します。

    2. Amazon Cognito ユーザープールが作成された際に設定されたスコープのフルネームを 1 つ以上入力します。たとえば、「REST API 用の Amazon Cognito ユーザープールを作成する」の例では、スコープの 1 つは com.hamuta.movies/drama.view です。1 つのスペースを使用して、複数のスコープを区切ります。

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

    3. チェックマークアイコンを選択して、設定を保存します。

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

COGNITO_USER_POOLS オーソライザーで、[OAuth スコープ] オプションが指定されていない場合、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.0OpenAPI 2.0
    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 メソッドに示すように、メソッドの security 定義に { "MyUserPool": [] } を追加します。

    "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": ["com.hamuta.movies/drama.view", "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 拡張」を参照してください。