メニュー
Amazon API Gateway
開発者ガイド

Amazon Cognito ユーザープールを使用

IAM のロールとポリシーまたはカスタム認証を使用することに加えて、API Gateway で API にアクセスできるユーザーを制御するために Amazon Cognito でユーザープールを使用できます。 ユーザープールはユーザーディレクトリを管理する ID プロバイダーとして機能します。 これはユーザー登録とサインインをサポートし、サインインしたユーザーの ID トークンをプロビジョニングします。

注記

Amazon Cognito の認証情報を使用して、IAM ロールのアクセス許可を取得するには、「Amazon Cognito フェデレーテッドアイデンティティ」を使用して一時的な認証情報を取得し、API で認証タイプを AWS_IAM に設定します。

ユーザープールは、どのメソッドにも適用できるメソッドオーソライザーとして API と統合されています。有効になっているこのような認証でメソッドを呼び出す場合、API クライアントはリクエストヘッダーにユーザープールからプロビジョニングされたユーザーの ID トークンを含みます。 API Gateway は、トークンを検証して、それが設定済みユーザープールに属し、バックエンドにリクエストを渡す前に呼び出し元を認証するようにします。

API を Amazon Cognito ID プロバイダーと統合するには、API の開発者としてユーザープールを作成、所有し、ユーザプールに接続された API Gateway 認証を作成し、選択した API メソッドで、認証を有効にします。 また、API クライアント開発者にユーザープール ID、クライアント ID、および場合によってはユーザープールからプロビジョニングされた関連するクライアントシークレットを配布する必要があります。 クライアントは、ユーザープールへのユーザーの登録、サインイン機能の提供、ユーザープールからプロビジョニングされたユーザー ID トークンの保有のためにこの情報が必要です。

このセクションでは、ユーザープールの作成方法、API Gateway API をユーザープールと統合する方法、ユーザープールと統合された API を呼び出す方法を学習します。

ユーザープールを作成する

API をユーザープールと統合する前に、Amazon Cognito でユーザープールを作成する必要があります。 ユーザープールを作成する方法については、Amazon Cognito 開発者ガイドユーザープールのセットアップ」を参照してください。

注記

選択した場合、ユーザープール ID、クライアント ID、クライアントシークレットを書き留めます。クライアントは、ユーザーがユーザープールに登録、サインインし、ユーザープールを使用して設定された API メソッドを呼び出すリクエストに含めるための ID トークンを取得するために、それらを Amazon Cognito に提供する必要があります。 また、API Gateway の認証としてユーザープールを設定する場合、以下に説明するようにユーザープール名を指定する必要があります。

API をユーザープールと統合

API をユーザープールと統合するには、API Gateway に、ユーザープールに接続しているユーザープール承認を作成する必要があります。 以下の手順は、API Gateway コンソールを使用してこれを行うステップを説明します。

API Gateway コンソールを使用してユーザープール承認を作成する

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

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

  3. [Authorizers] で、[Create New Authorizer] を選択し、次の操作を行って新しい Amazon Cognito ユーザープールオーソライザーを設定します。

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

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

    3. [Cognito User Pool] からリージョンを選択します。

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

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

    6. 必要に応じて、Amazon Cognito で承認する前にトークンを検証するように [Token validation] フィールドに正規表現を入力します。

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

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

メソッドで、ユーザープール認証を有効にする

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

  2. [Method Request] を選択します。

  3. [Settings] で [Authorization] の横の鉛筆アイコンを選択します。

  4. ドロップダウンリストから利用可能な [Amazon Cognito user pool authorizers] の 1 つを選択します。

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

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

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

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

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

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

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

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

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

Swagger 定義ファイルを使ってユーザープール認証をインポートするには

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

  2. securityDefinitions にユーザープールの設定を追加します。

    Copy
    "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 メソッドに示すように、メソッドのオーソライザーとして Amazon Cognito ユーザープール (MyUserPool) を有効化します。

    Copy
    "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. 必要に応じて、Swagger 定義または拡張機能を使用し、他の API 設定を設定します。詳細については、「Swagger に対する API Gateway 拡張」を参照してください。

ユーザープールに統合された API を呼び出す

設定されたユーザープールオーソライザーを使用して、メソッドを呼び出すには、クライアントは以下を実行する必要があります。

  • ユーザープールにサインアップすることを可能にします。

  • ユーザープールにサインインすることを可能にします。

  • ユーザープールからサインインしているユーザーの ID トークンを取得します。

  • [Authorization] ヘッダー (または、認証作成時に指定した別のヘッダー) に ID トークンを含めます。

これらのタスクを実行するのに、AWS SDK の 1 つを使用できます。 (例:

次の手順では、これらのタスクを実行するステップを簡単に示しています。 詳細については、「Android SDK と Amazon Cognito ユーザープールを使用する」および「iOS 用の Amazon Cognito ユーザープールを使用する」を参照してください。

ユーザープールに統合された API を呼び出すには

  1. 指定されたユーザープールに初めて使用するユーザーをサインアップします。

  2. ユーザープールにユーザーをサインインします。

  3. ユーザーの ID トークンを取得します。

  4. ユーザープールオーソライザーを使用して設定された API メソッドを呼び出し、Authorization ヘッダーまたは選択した他のヘッダーで期限切れでないトークンを指定します。

  5. トークンの期限が切れている場合、ステップ 2 ~ 4 を繰り返してください。 Amazon Cognito によりプロビジョニングされた ID トークンは 1 時間以内に有効期限切れになります。

コード例については、「Android Java サンプル」および「iOS Objective-C サンプル」を参照してください。