API ゲートウェイ REST API で、Amazon Cognito ユーザープールをオーソライザーとしてセットアップするにはどうすればよいですか?

所要時間3分

Amazon API ゲートウェイ REST API で、Amazon Cognito ユーザープールをオーソライザーとしてセットアップしたいと考えています。

簡単な説明

API ゲートウェイ REST API のオーソライザーとして Amazon Cognito ユーザープールを設定するには、2 つの方法があります。

認証には ID トークンまたはアクセストークンのいずれかを使用できます。アクセストークンは、Amazon Cognito のカスタムスコープを使用して API Gateway API へのアクセスを承認できます。Lambda オーソライザーは、Amazon Cognito が発行した ID トークンとアクセストークンのクレームを検証できます。

詳細については、次のトピックを参照してください。

解決方法

以下の手順は、COGNITO_USER_POOLS オーソライザーを作成する方法を示しています。この例では、次の 2 つのものがすでに作成されていることを前提としています。

COGNITO_USER_POOLS authorizer オーソライザーの作成

詳細については、「REST API を Amazon Cognito ユーザープールと統合する」を参照してください。「API Gateway コンソールを使用して COGNITO_USER_POOLS オーソライザーを作成するには」セクションの指示に従ってください。

新しい COGNITO_USER_POOLS オーソライザーをテストしてください

COGNITO_USER_POOLS オーソライザーを作成したら、次の操作を行います。

1. API Gateway コンソールで、新しいオーソライザーの下にある [テスト] ボタンを選択します。

2. [テスト] ウィンドウで、[認証] には新しい Amazon Cognito ユーザープールからの [ID トークン] を入力します。

3. [テスト] を選択します。

**注:**ID トークンが正しければ、テストは 200 のレスポンスコードを返します。ID トークンが正しくない場合、401 レスポンスコードが返されます。

API メソッドで COGNITO\ _USER\ _POOLS オーソライザーを設定する

詳細については、「REST API を Amazon Cognito ユーザープールと統合する」を参照してください。「メソッドで COGNITO_USER_POOLS オーソライザーを設定するには」セクションの指示に従ってください。

認証トークンの取得

認証トークンを取得するには 4 つの方法があります。

注: アプリケーションがトークンエンドポイントとのコード交換のためにコードを取得できるように、Amazon Cognito のホストされた UI を認証コード付与で設定します。

暗黙的付与タイプを使用している場合は、コールバック URL から付与を受けることができます。コールバック URL には、暗黙的なフローのアクセストークンと ID トークンのパラメータが追加されます。必ず正しいトークンタイプを使用してください。

Amazon Cognito のホスト UI を使用して認証トークンを取得するには

認証コード付与フローを使用するには、以下を実行してください。

**注:認証コード付与フローを使用する場合、レスポンスタイプパラメータは「code」**である必要があります。

1. 認証コード付与の GET リクエストを送信します。

**重要:**example_domain をユーザープールのドメイン名に置き換えます。example_app_client_id をユーザープールのアプリクライアント ID で置き換えます。example_callback_url をコールバック URLで置き換えます。

https://example_domain/oauth2/authorize?response_type=code&client_id=example_app_client_id&redirect_uri=example_callback_url

**注:**フェデレ―テッド ID プロバイダーへのリダイレクトエンドポイントに identity_provider パラメータを含めてください。アプリクライアントが Amazon Cognito ユーザープールのみに設定されている場合、次のエンドポイントは /login エンドポイントにリダイレクトします。

https://example_domain/login?response_type=code&client_id=example_app_client_id&redirect_uri=example_callback_url

2. ユーザープールまたはフェデレ―テッド ID プロバイダーにサインインします。ユーザーインターフェイスは、アプリクライアントのコールバックで指定された URL にリダイレクトされます。

**重要:**リダイレクト URL には、有効なトークンを取得するためにトークンエンドポイントと交換する必要のある認証コードが含まれています。

3. POST リクエストを /oauth2/token エンドポイントに送信して、トークンの認証コードを交換します。詳細については、「トークンエンドポイント」を参照してください。

認証コードをトークンと交換する POST リクエストの例

**注:**POST リクエストの例は以下の /oauth2/token エンドポイントを使用しています。 https://example_domain.auth.us-east-1.amazoncognito.com/oauth2/token&

Content-Type='application/x-www-form-urlencoded'&
Authorization=Basic ZXhhbXBsZTEyMzQ1Njc4OTA6enl4OTh3N3l2dHNycTY1NHBvMzIx
grant_type=authorization_code&
client_id=example1234567890&
code=AUTHORIZATION_CODE&
redirect_uri=com.myclientapp://myclient/redirect

POST リクエストのレスポンス例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token":"abCde1example",
  "id_token":"abCde2example",
  "refresh_token":"abCde3example",
  "token_type":"Bearer",
  "expires_in":3600
}

暗黙的付与フローを使用するには、次の手順を実行します。

**注:暗黙的付与フローを使用する場合、レスポンスタイプパラメータは「token」**である必要があります。

1. 暗黙的付与のために GET リクエストを送信します。

https://example_domain/oauth2/authorize?response_type=token&client_id=example_app_client_id&redirect_uri=example_callback_url

https://example_domain/login?response_type=token&client_id=example_app_client_id&redirect_uri=example_callback_url

2. 既存のユーザーのユーザー名とパスワードでユーザープールにサインインするか、新しいユーザーを作成してサインインします。ユーザーインターフェイスは、アプリクライアントのコールバックで指定された URL にリダイレクトされます。

注:リダイレクト URL には、ID トークンとアクセストークンが含まれます。

リダイレクト URL の例

https://www.example.com/#id_token=123456789idtoken123456789&access_token=123456789accesstoken123456789expires_in=3600&token_type=Bearer

AWS CLI を使用して認証トークンを取得するには

注: AWS CLI コマンドの実行中にエラーが発生した場合は、最新の AWS CLI バージョンを使用していることを確認してください。

以下の AWS CLIコマンド「initiate-auth」を実行して認証トークンを取得します。

**重要:**example_user をユーザー名、example_password をパスワード、example_app_client_id をアプリクライアント ID に置き換えます。

aws cognito-idp initiate-auth --auth-flow USER_PASSWORD_AUTH --auth-parameters USERNAME=example_user,PASSWORD=example_password --client_id example_app_client_id

「initiate-auth」AWS CLI コマンドの例としてのレスポンス

{
  "AuthenticationResult": {
    "AccessToken": "abCde1example",
    "IdToken": "abCde2example",
    "RefreshToken": "abCde3example",
    "TokenType": "Bearer",
    "ExpiresIn": 3600
  },
  "ChallengeParameters": {}
}

AWS SDK のいずれかを使用して認証トークンを取得するには

詳細については、「ウェブおよびモバイルアプリとの Amazon Cognito の統合」を参照してください。

Postman を使用して認証トークンを取得するには

Postman の OAuth 2.0 認証モードを使用して認証トークンを取得します。詳細については、「Lambda 認証プログラムを作成した後に API Gateway で401 Unauthorized エラーが発生するのはなぜですか?」を参照してください。

Amazon Cognito ユーザープールで OAuth 2.0 カスタムスコープを設定し、API Gateway でスコープを検証する

スコープは、アプリがリソースにリクエストできるアクセスレベルを提供します。Amazon Cognito には、アプリケーションクライアントをユーザープールに関連付けることを許可するように設定できる OAuth スコープが組み込まれています。Amazon Cognito の組み込みスコープの詳細については、「アプリクライアント設定の用語」を参照してください。

カスタムスコープは OAuth 2.0 リソースサーバーに関連付けることができます。リソースサーバーの詳細については、「ユーザープールのリソースサーバーの定義」を参照してください。

API ゲートウェイで Amazon Cognito を使用すると、Amazon Cognito オーソライザーがリクエストを認証し、リソースを保護します。Amazon Cognito と API Gateway でカスタムスコープを使用すると、API リソースへのアクセスのレベルを差別化できます。また、リソースを公開してアクセストークンのスコープを取得する場合も、より細かく制御できます。

ユーザープールにリソースサーバーと OAuth 2.0 カスタムスコープを設定する

1. ユーザープールのリソースサーバーとカスタムスコープを定義します。
リソースサーバー識別子には、リソースが配置されている API Gateway の HTTPS エンドポイントを指定します。

2. 必要に応じて、ユーザープールアプリクライアントを設定し、アプリクライアント設定にカスタムスコープを追加します。

注: カスタムスコープ名は、resourceServerIdentifier/scopeName の形式でフォーマットされます

クライアントアプリが OAuth 2.0 フローのカスタムスコープをリクエストする場合、クライアントアプリはそのスコープの完全な識別子をリクエストする必要があります。たとえば、リソースサーバーの識別子が https://myresourceserver.example.com であり、スコープ名が resources.read である場合、クライアントアプリは実行時に https://myresourceserver.example.com/resources.read をリクエストする必要があります。

API ゲートウェイで OAuth 2.0 カスタムスコープを確認する

1. REST API を Amazon Cognito ユーザープールと統合します。

2. API ゲートウェイコンソールで REST API を選択します。

3. [リソース] ペインで、メソッド名を選択します。

4. [メソッドリクエスト] の構成を選択します。

5. [認証] ドロップダウンリストから、[Cognito オーソライザー] を選択します。これにより、[OAuth Scopes] という新しいフィールドが自動的に追加されます。

6. [OAuth Scopes] フィールドに、先ほどの形式でカスタムスコープの完全な識別子を入力します。たとえば、https://myresourceserver.example.com/resources.read などのように指定します。

7. API を保存してデプロイします。

Postman または CURL を使用してセットアップをテストする

1. クライアントに対して定義された OAuth 2.0 フローのいずれかを使用して、Amazon Cognito 認証サーバーからアクセストークンを取得します。

2. 受信したアクセストークンを、API Gatewayへのリクエストの認証ヘッダーとして送信します。

3. すべてが成功し、API Gateway がアクセストークンとカスタムスコープを検証すると、200 OK レスポンスが返されます。