API Gateway API においてオーソライザーとして Amazon Cognito ユーザープールをセットアップする方法を教えてください。

所要時間4分

Amazon API Gateway の REST または HTTP API においてオーソライザーとして Amazon Cognito ユーザープールをセットアップしようと考えています。

簡単な説明

Amazon API Gateway の REST または HTTP API においてオーソライザーとして Amazon Cognito ユーザープールをセットアップするには、COGNITO_USER_POOLS オーソライザーを作成します。また、AWS Lambda オーソライザーを設定することもできます。

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

解決策

注: AWS コマンドラインインターフェイス (AWS CLI) コマンドの実行中にエラーが発生した場合は、「AWS CLI のエラーのトラブルシューティング」を参照してください。また、AWS CLI の最新バージョンを使用していることを確認してください。

前提条件: アプリクライアントを備えた Amazon Cognito ユーザープールが設定されている必要があります。また、既存の API Gateway REST API または API Gateway HTTP API を持っている必要があります。

認証トークンを取得する

認証トークンは、以下のいずれかの方法で取得できます。

Amazon Cognito のホストされた UI で認証コード付与フローを使用します。
Amazon Cognito のホストされた UI で暗黙的な付与フローを使用します。
AWS CLI を使用します。
いずれかの AWS SDK を使用します。
Postman を使用します。

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 プロバイダー (IdP) にリダイレクトするには、エンドポイントに identity_provider パラメータを含めます。アプリクライアントが Amazon Cognito ユーザープールのみに設定されている場合、次のエンドポイントは /login エンドポイントへリダイレクトします。

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

ユーザープールにサインインするか、サードパーティー IdP を介してフェデレーションします。ユーザーインターフェイスは、アプリクライアントのコールバックで指定された 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 ZXhhbXBsZTEyMzQ1Njc4OTA6enl4OTh3N3l2dHNycTY1NHBvMzIxgrant_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
}

Amazon Cognito のホストされた UI で暗黙的な付与フローを使用する

暗黙的な付与フローはレガシーな認証付与フローです。暗黙的な付与フローを使用する場合、レスポンスタイプパラメータは token である必要があります。詳細については、「OAuth 2.0 grants」(OAuth 2.0 許可) の「Implicit grant」(暗黙的な付与) セクションと「The redirect and authorization endpoint」(リダイレクトエンドポイントと認証エンドポイント) を参照してください。

次の手順を実行します。

暗黙的な付与の GET リクエストを送信します:

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

注: example_domain をユーザープールのドメイン名に置き換えます。example_app_client_id をユーザープールのアプリクライアント ID に置き換えます。example_callback_url をコールバック URL に置き換えます。サードパーティー IdP にリダイレクトするには、エンドポイントに identity_provider パラメータを含めます。アプリクライアントが Amazon Cognito ユーザープールのみに設定されている場合、次のエンドポイントは /login エンドポイントへリダイレクトします。

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 コマンド initiate-auth を実行する前に、Cognito アプリクライアント設定で ALLOW_USER_PASSWORD_AUTH 認証フローを有効にしてください。このフローを有効にしないと、次のエラーが表示されます。 "An error occurred (InvalidParameterException) when calling the InitiateAuth operation: USER_PASSWORD_AUTH flow not enabled for this client"

認証トークンを取得するには、次の 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 にそれぞれ置き換えます。

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

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

いずれかの AWS SDK を使用する

詳細については、「Authentication with AWS SDKs」(AWS SDK による認証) を参照してください。

Postman を使用する

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

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

Amazon Cognito と API Gateway でカスタムスコープを使用すると、API リソースへのアクセスのレベルを区別できます。

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

ユーザープールのリソースサーバーとカスタムスコープを定義します。詳細については、「About resource servers」(リソースサーバーについて) の「Defining a resource server for your user pool (AWS Management Console)」(ユーザープールのリソースサーバーを定義する (AWS マネジメントコンソール)) セクションを参照してください。
リソースサーバー識別子には、リソースが配置されている API Gateway の HTTPS エンドポイントを入力します。
必要に応じて、ユーザープールアプリクライアントを設定し、アプリクライアント設定にカスタムスコープを追加します。
注: カスタムスコープ名には、resourceServerIdentifier/scopeName の形式を使用します。

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

REST API においてオーソライザーとして Amazon Cognito ユーザープールをセットアップする

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

API Gateway で COGNITO_USER_POOLS オーソライザーを作成したら、オーソライザーをテストすることができます。オーソライザーをテストするには、新しいオーソライザーを選択し、次に [オーソライザーのテスト] をクリックします。

重要: API Gateway を Cognito 認証でテストする場合、Cognito ユーザープールの ID トークンを使用する必要があります。ID トークンの代わりにアクセストークンを使用すると、認証が失敗します。ID トークンが正しい場合、テストは 200 レスポンスコードを返します。ID トークンが正しくない場合、401 レスポンスコードが返されます。

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

API Gateway REST API の OAuth 2.0 カスタムスコープを確認するには、次の手順を実行します。

API Gateway コンソールを開きます。
REST API を選択し、次にメソッドを選択します。
[メソッドリクエストの設定] で [編集] をクリックします。
[認証] ドロップダウンリストから、[Cognito オーソライザー] を選択します。
[OAuth スコープ] には、カスタムスコープの完全な ID を入力します。例えば、https://myresourceserver.example.com/resources.read と入力します。
[保存] をクリックし、[API をデプロイ] をクリックします。

HTTP API においてオーソライザーとして Amazon Cognito ユーザープールをセットアップする

JWT オーソライザーを作成し、次にその JWT オーソライザーを使用するようにルートを更新します。

API Gateway HTTP API のルートに認証スコープを追加するには、次の手順を完了します。

API Gateway コンソールを開きます。
お使いの HTTP API を選択します。
ナビゲーションペインで、[認証] をクリックします。
[オーソライザーをルートにアタッチ] でルートを選択します。
[認証スコープ] で、スコープを user.email と入力します。
[保存] をクリックします。

注: デフォルトのステージを使用しない場合は、必ず API をデプロイしてください。

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

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

API Gateway がアクセストークンとカスタムスコープを正常に確認および検証すると、HTTP 200 OK というレスポンスが返されます。