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 オーソライザーを作成する

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

新しい COGNITO_USER_POOLS オーソライザーをテストする

次の手順を実行します。

API Gateway コンソールを開きます。
新しいオーソライザーで、[テスト] ボタンを選択します。
[テスト] ウィンドウの **[認可] ** に、新しい Amazon Cognito ユーザープールの ID トークンを入力します。
テスト を選択します。
**注:**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」**である必要があります。

認可コード付与のフローを使用するには、次の手順を実行します。

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

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

**注:**example_domain は、ユーザープールのドメイン名に置き換えます。example_app_client_id をユーザープールのアプリクライアント ID で置き換えます。example_callback_url は、コールバック 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

ユーザープールまたはフェデレ―ション ID プロバイダーにサインインします。ユーザーインターフェイスは、アプリクライアントのコールバックで指定された URL にリダイレクトされます。
**重要:**リダイレクト URL には、有効なトークンを取得するためにトークンエンドポイントと交換する必要のある認可コードが含まれています。
POST リクエストを /oauth2/token エンドポイントに送信して、トークンの認可コードを交換します。詳細については、「Token endpoint」を参照してください。

認証コードをトークンと交換する 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」**である必要があります。

インプリシットグラントのフローを使用するには、次の手順を実行します。

インプリシットグラントの 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

既存のユーザーのユーザー名とパスワードでユーザープールにサインインするか、新しいユーザーを作成してサインインします。ユーザーインターフェイスは、アプリクライアントのコールバックで指定された 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 の最新バージョンを使用していることを確認してください。

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

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

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

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

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

AWS SDK のいずれかを使用して認可トークンを取得

詳細については、「Integrating Amazon Cognito authentication and authorization with web and mobile apps」を参照してください。

**Postman を使用して認可トークンを取得する **

Postman ウェブサイトの OAuth 2.0 認可モードを使用して、認可トークンを取得します。詳細については、「Lambda オーソライザーを作成した後に、API Gateway で401 不正エラーが発生するのはなぜですか?」を参照してください。

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

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

カスタムスコープは OAuth 2.0 リソースサーバーに関連付けることができます。リソースサーバーの詳細については、「OAuth 2.0 scopes and API authorization with resource servers」を参照してください。

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

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

ユーザープールのリソースサーバーとカスタムスコープを定義します。
リソースサーバー識別子には、リソースが配置されている API Gateway の HTTPS エンドポイントを指定します。
必要に応じて、ユーザープールアプリクライアントを設定し、アプリクライアント設定にカスタムスコープを追加します。
注: カスタムスコープ名は、resourceServerIdentifier/scopeName の形式でフォーマットされます

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

API Gateway で OAuth 2.0 カスタムスコープを確認する

REST API を Amazon Cognito ユーザープールと統合します。
API Gateway コンソールで REST API を選択します。
[リソース] ペインで、メソッド名を選択します。
[メソッドリクエスト] の構成を選択します。
[認可] ドロップダウンリストから、[Cognito オーソライザー] を選択します。これにより、[OAuth スコープ] という新しいフィールドが自動的に追加されます。
[OAuth スコープ] フィールドに、先ほどの形式でカスタムスコープの完全な識別子を入力します。例えば、https://myresourceserver.example.com/resources.read などのように指定します。
API を保存してデプロイします。

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

クライアントに対して定義された OAuth 2.0 フローのいずれかを使用して、Amazon Cognito 認可サーバーからアクセストークンを取得します。
受信したアクセストークンを、API Gateway へのリクエストの認可ヘッダーとして送信します。

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