AWS CognitoでWebアプリにログイン機能を追加する — User PoolsとIdentity Poolsの使い分け

Webアプリに「サインアップ」と「サインイン」を実装しようとしたとき、AWSコンソールを開くと『Cognito User Pools』と『Cognito Identity Pools』という2つの選択肢が並んでいる。どちらを使えばいいのか迷うのは当然で、名前が似ているせいで混同しやすい。結論から言うと、ユーザーのログイン管理にはUser Poolsを使う。Identity Poolsはまったく別の目的のサービスだ。

TL;DR — AWS Cognitoの使い分け早見表

目的 使うべきサービス 主な機能
サインアップ / サインイン / ユーザー管理 Cognito User Pools ユーザーDB、JWT発行、MFA、パスワードポリシー
AWSリソース（S3, DynamoDBなど）への一時的アクセス Cognito Identity Pools フェデレーテッドID、STS一時認証情報の払い出し
ログイン後にAWSリソースも直接操作させたい 両方を組み合わせる User PoolsでJWT取得 → Identity Poolsで一時認証情報に交換

AWS Cognito User Poolsの仕組みを理解する

User Poolsは、アプリケーション専用のユーザーディレクトリだ。メールアドレスとパスワードでサインアップしたユーザーの情報を保持し、認証が成功するとOpenID Connect準拠のJWTトークン（IDトークン、アクセストークン、リフレッシュトークン）を発行する。バックエンドAPIはこのJWTを検証するだけでよく、セッション管理の複雑さをCognitoに委譲できる。

sequenceDiagram participant Browser as ブラウザ participant UserPool as Cognito User Pools participant API as バックエンドAPI Browser->>UserPool: サインアップ (メール/パスワード) UserPool-->>Browser: 確認コード送信 Browser->>UserPool: confirm-sign-up (確認コード) UserPool-->>Browser: 確認完了 Browser->>UserPool: initiate-auth (USER_SRP_AUTH) UserPool-->>Browser: IDトークン / アクセストークン / リフレッシュトークン Browser->>API: APIリクエスト (Authorization: IDトークン) API->>UserPool: JWKSエンドポイントでトークン検証 UserPool-->>API: 検証結果 API-->>Browser: レスポンス
  1. サインアップ / サインイン: ブラウザからCognito User Poolsへ認証リクエストを送る。
  2. JWT発行: 認証成功後、IDトークン・アクセストークン・リフレッシュトークンの3種類が返される。
  3. APIアクセス: フロントエンドはAuthorizationヘッダにIDトークンを付けてバックエンドAPIを呼ぶ。
  4. JWT検証: API GatewayまたはバックエンドがUser PoolsのJWKSエンドポイントを使ってトークンを検証する。

Identity Poolsはこのフローとは無関係だ。Identity Poolsの役割は、認証済みユーザー（またはゲストユーザー）にAWS STSの一時的な認証情報を払い出すことであり、ユーザーのパスワードやプロフィールを管理する機能は持っていない。

User Poolsを『アプリのユーザーDB + 認証サーバー』、Identity Poolsを『AWSリソースへの入場券発行機』と考えると役割が整理しやすい。

AWS Cognito User Poolsでサインアップ・サインインを実装する

以下の手順でUser Poolsを作成し、アプリクライアントを設定する。CLIで一連の操作を完結させることができる。

Step 1: User Poolsを作成する

まずUser Poolsを作成する。ここでパスワードポリシーやMFAの設定が決まる。作成後に返されるUserPoolIdは以降の手順で必要になるため、必ず記録しておく。

aws cognito-idp create-user-pool \
  --pool-name MyAppUserPool \
  --policies 'PasswordPolicy={MinimumLength=8,RequireUppercase=true,RequireLowercase=true,RequireNumbers=true,RequireSymbols=false}' \
  --auto-verified-attributes email \
  --region us-east-1

--auto-verified-attributes emailを指定すると、サインアップ時にメールアドレス確認コードが自動送信される。本番環境では--mfa-configurationオプションでMFAを有効化することを強く推奨する。

Step 2: アプリクライアントを作成する

User Poolsを作成しただけではアプリから認証できない。アプリクライアントを作成することで、フロントエンドやバックエンドがUser Poolsと通信するためのクライアントIDが払い出される。--no-generate-secretはSPAやモバイルアプリなどクライアントシークレットを安全に保管できない環境向けの設定だ。

aws cognito-idp create-user-pool-client \
  --user-pool-id us-east-1_XXXXXXXXX \
  --client-name MyAppClient \
  --no-generate-secret \
  --explicit-auth-flows ALLOW_USER_SRP_AUTH ALLOW_REFRESH_TOKEN_AUTH \
  --region us-east-1

Step 3: ユーザーのサインアップとメール確認

アプリクライアントIDが取得できたら、実際にユーザーを登録できる。以下はCLIでサインアップを実行する例だ。実際のアプリではAWS Amplify LibrariesやCognito Hosted UIを使うことが多いが、動作確認にはCLIが便利だ。

aws cognito-idp sign-up \
  --client-id YOUR_CLIENT_ID \
  --username user@example.com \
  --password 'MyP@ssword1' \
  --region us-east-1

サインアップ後、登録メールアドレスに確認コードが届く。そのコードで確認を完了させる。

aws cognito-idp confirm-sign-up \
  --client-id YOUR_CLIENT_ID \
  --username user@example.com \
  --confirmation-code 123456 \
  --region us-east-1

Step 4: サインインしてJWTを取得する

メール確認が完了したユーザーでサインインする。USER_SRP_AUTHフローはパスワードをネットワーク上に平文で送らないSRP（Secure Remote Password）プロトコルを使用する。CLIでの簡易確認にはUSER_PASSWORD_AUTHフローも使えるが、本番アプリではUSER_SRP_AUTHを使うこと。

aws cognito-idp initiate-auth \
  --auth-flow USER_PASSWORD_AUTH \
  --auth-parameters USERNAME=user@example.com,PASSWORD='MyP@ssword1' \
  --client-id YOUR_CLIENT_ID \
  --region us-east-1

成功するとAuthenticationResultの中にIdToken、AccessToken、RefreshTokenが返される。バックエンドAPIの認証にはこのIdTokenをAuthorizationヘッダに付与する。

よくある誤解 — Identity PoolsをユーザーDBとして使おうとした場合

「Identity Poolsにもユーザーを追加できるのでは？」と考えてAWSコンソールを操作すると、Identity Poolsにはユーザー登録フォームが存在しないことに気づく。Identity Poolsが管理するのはIAMロールへのマッピングであり、ユーザーのパスワードやメールアドレスを保持する仕組みではない。

graph LR User["ユーザー"] --> UP["Cognito User Pools
認証 / JWT発行"] UP -- "JWTトークン" --> IP["Cognito Identity Pools
JWT → 一時認証情報に交換"] IP -- "STS一時認証情報" --> STS["AWS STS"] STS -- "IAM一時認証情報" --> AWSRes["AWSリソース
S3 / DynamoDB など"] UP -- "JWTトークン" --> APIGW["API Gateway
Cognitoオーソライザー"] APIGW --> Backend["バックエンドAPI"]
  1. 認証フェーズ: User Poolsがユーザー認証を担当し、JWTを発行する。
  2. 認証情報交換フェーズ: Identity PoolsはUser PoolsのJWTを受け取り、STSに一時的なIAM認証情報を要求する。
  3. AWSリソースアクセス: フロントエンドはSTSから受け取った一時認証情報を使ってS3やDynamoDBに直接アクセスする。

ユーザーのサインアップ・サインインだけが目的なら、Identity Poolsは不要だ。S3バケットへの直接アップロードなど、フロントエンドからAWSリソースを直接操作させたい場合にのみ、User PoolsとIdentity Poolsを組み合わせる構成を検討する。

Cognito User Pools管理に必要なIAMポリシー

CI/CDパイプラインや管理スクリプトからUser Poolsを操作する場合、最小権限の原則に従ったIAMポリシーが必要だ。CreateUserPoolはリソースレベルの権限制御をサポートしていないため、このアクションだけResource: "*"が必要になる。その他のアクションは特定のUser Pool ARNに絞ることができる。

🔽 IAMポリシーサンプルを展開する 
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "CognitoCreateUserPool",
      "Effect": "Allow",
      "Action": [
        "cognito-idp:CreateUserPool"
      ],
      "Resource": "*"
    },
    {
      "Sid": "CognitoManageSpecificUserPool",
      "Effect": "Allow",
      "Action": [
        "cognito-idp:DescribeUserPool",
        "cognito-idp:UpdateUserPool",
        "cognito-idp:DeleteUserPool",
        "cognito-idp:CreateUserPoolClient",
        "cognito-idp:DescribeUserPoolClient",
        "cognito-idp:AdminCreateUser",
        "cognito-idp:AdminDeleteUser",
        "cognito-idp:AdminGetUser",
        "cognito-idp:ListUsers"
      ],
      "Resource": "arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_XXXXXXXXX"
    }
  ]
}

CreateUserPoolをResource: "*"にしなければならない理由は、User Pool作成時点ではARNがまだ存在しないためだ。作成後の操作（DescribeUserPool、AdminCreateUserなど）は特定のARNに絞ることができ、最小権限の原則を維持できる。

実際の障害パターン — 『トークンは返ってくるのにAPIが401を返す』

サインインは成功してIDトークンが取得できているのに、API Gatewayが401を返し続けるケースがある。最初はCognitoの設定を疑うが、実際にはAPI GatewayのCognitoオーソライザー設定の問題であることが多い。

具体的には、オーソライザーに設定したUser Pool ARNと、トークンを発行したUser Poolが一致していないケースだ。開発環境と本番環境でUser Poolsを分けているときに、デプロイ時に環境変数の差し替えを忘れると発生する。CloudFormationやTerraformでインフラを管理していても、API Gatewayのオーソライザーだけをコンソールでアドホックに変更していると見落としやすい。

確認コマンドはシンプルだ。

aws apigateway get-authorizer \
  --rest-api-id YOUR_API_ID \
  --authorizer-id YOUR_AUTHORIZER_ID \
  --region us-east-1

返ってきたproviderARNsの値と、トークンを発行したUser PoolのARNを突き合わせる。一致していなければオーソライザーを更新する。

aws apigateway update-authorizer \
  --rest-api-id YOUR_API_ID \
  --authorizer-id YOUR_AUTHORIZER_ID \
  --patch-operations op=replace,path=/providerARNs/0,value=arn:aws:cognito-idp:us-east-1:123456789012:userpool/us-east-1_XXXXXXXXX \
  --region us-east-1

JWTの中身をjwt.ioでデコードしてissクレームを確認すると、どのUser Poolが発行したトークンかが一目でわかる。401が出たらまずここを見る習慣をつけると診断が早い。

AWS Cognito User Poolsのまとめと次のステップ

WebアプリのサインアップとサインインにはCognito User Poolsを使う。Identity Poolsはユーザーデータベースではなく、認証済みユーザーにAWSリソースへの一時的なアクセス権を付与するための仕組みだ。この2つを混同すると設計が複雑になるだけなので、目的に応じて明確に使い分けることが重要だ。

次のステップとして、以下を参照することを推奨する。

用語集

用語 説明
User Pools Cognitoが提供するユーザーディレクトリ。サインアップ・サインイン・JWT発行を担う。
Identity Pools 認証済みユーザーにAWS STSの一時的な認証情報を払い出す仕組み。ユーザーDBではない。
JWT (JSON Web Token) 認証成功後にUser Poolsが発行する署名付きトークン。IDトークン・アクセストークン・リフレッシュトークンの3種類がある。
SRP (Secure Remote Password) パスワードをネットワーク上に平文で送らずに認証するプロトコル。Cognitoの推奨認証フロー。
アプリクライアント User Poolsに対してアプリが認証リクエストを送るための識別子。クライアントIDとして使用する。

Related Posts

コメント

コメントを投稿

このブログの人気の投稿

SQS Visibility Timeoutの完全解説：メッセージ二重処理の原因と対策

SQSキューから取得したメッセージが複数のコンシューマーに重複処理される——この問題はVisibility Timeoutの設定ミスが原因であることがほとんどだ。処理時間がタイムアウト値を超えた瞬間、SQSはそのメッセージを「未処理」と判断して再度可視化し、別のワーカーが同じメッセージを拾ってしまう。 TL;DR：Visibility Timeoutとは何か 項目 内容 定義 コンシューマーがメッセージを受信してから、他のコンシューマーに見えなくなる時間 デフォルト値 30秒 設定範囲 0秒〜43,200秒（12時間） 二重処理の原因 処理時間がVisibility Timeoutを超えるとメッセージが再可視化される 対策 処理時間に余裕を持たせた値を設定、または処理中に延長APIを呼ぶ 削除タイミング 処理完了後に明示的に DeleteMessage を呼ぶ必要がある Visibility Timeoutの仕組みを理解する SQSはメッセージを受信した時点でそのメッセージを一時的に「不可視」にする。これはキューからメッセージを削除するわけではなく、他のコンシューマーから見えなくするだけだ。コンシューマーが処理を完了して DeleteMessage を呼べばメッセージは消える。しかしVisibility Timeoutが切れる前に削除されなければ、メッセージはキューに戻り、再度取得可能になる。 この設計は意図的なものだ。コンシューマーがクラッシュしたり応答しなくなった場合に、メッセージが失われないようにするためのフェイルセーフとして機能している。問題は、正常に動作しているコンシューマーの処理時間がタイムアウトを超えたときに、同じフェイルセーフが誤発動することだ。 sequenceDiagram participant CA as コンシューマーA participant SQS as SQS キュー participant CB as コンシューマーB CA->>SQS: ReceiveMessage SQS...
続きを読む

EC2 SSH接続タイムアウトの原因と修正方法 — セキュリティグループのインバウンドルール完全ガイド

新しいEC2インスタンスを起動してSSH接続を試みたとき、 ssh: connect to host xx.xx.xx.xx port 22: Connection timed out というエラーで止まった経験は多くのエンジニアにある。アプリケーションのエラーではなく、パケットがインスタンスに届いていないことを示すタイムアウトだ。原因の大半はセキュリティグループのインバウンドルール設定にあるが、それだけで解決しないケースも存在する。 TL;DR — EC2 SSHタイムアウトの主な原因と対処 原因レイヤー 確認項目 修正方向 セキュリティグループ ポート22のインバウンドルールが存在するか TCP 22をソースIPに対して許可 ネットワークACL サブネットレベルでポート22がブロックされていないか インバウンド/アウトバウンド両方のルールを確認 パブリックIPアドレス インスタンスにパブリックIPが割り当てられているか ElasticIPの関連付けまたはパブリックIP自動割り当ての有効化 インターネットゲートウェイ VPCにIGWがアタッチされているか IGWを作成してVPCにアタッチ ルートテーブル サブネットのルートテーブルに0.0.0.0/0 → IGWのルートがあるか デフォルトルートをIGWに向ける EC2 SSH接続の仕組み — パケットが届くまでの経路 SSHタイムアウトを正確に診断するには、クライアントのパケットがEC2インスタンスに到達するまでに通過するレイヤーを理解する必要がある。セキュリティグループだけを見て終わりにすると、別のレイヤーでブロックされているケースを見逃す。 graph LR Client["クライアント ローカルマシン"] -->|"TCP SYN port 22"| IGW["インターネット ゲートウェイ (IGW)"] IGW --> RT["ルートテーブル 0.0.0.0/0 → IGW"] RT --> ...
続きを読む

S3パブリックアクセス拒否の原因と解決策：バケットレベルの「Block Public Access」が優先される仕組み

S3に画像をアップロードしてオブジェクトACLを「public-read」に設定したのに、URLにアクセスすると「Access Denied」が返ってくる。オブジェクト単体の設定は正しいはずなのに、なぜ拒否されるのか——この問題の原因はほぼ確実に、バケットレベルの「Block Public Access」設定にある。オブジェクトACLより上位のレイヤーが存在することを知らないと、何度設定を変えても解決しない。 TL;DR：S3パブリックアクセス拒否の原因まとめ 確認レイヤー 設定項目 影響範囲 アカウントレベル S3 Block Public Access（アカウント全体） 全バケットに適用 バケットレベル S3 Block Public Access（バケット個別） そのバケット内の全オブジェクト バケットポリシー Principal: * を許可するポリシーの有無 ポリシーで指定したリソース オブジェクトACL public-read ACL 個別オブジェクト 結論： オブジェクトACLを「public-read」にしても、バケットまたはアカウントレベルの「Block Public Access」が有効な場合、そのACLは無効化される。上位レイヤーの設定が下位を上書きする構造になっている。 S3パブリックアクセス制御の仕組み：なぜオブジェクトACLだけでは不十分か S3のアクセス制御は複数のレイヤーが重なって機能する。オブジェクトACLはその中で最も下位のレイヤーに位置する。AWSは2018年以降、誤ったパブリック公開によるデータ漏洩を防ぐため「Block Public Access」という上位の制御機構を導入した。この設定が有効な場合、オブジェクトACLやバケットポリシーで「public」を許可しようとしても、Block Public Accessがそれを遮断する。 Block Public Accessには4つの独立した設定項目がある。それぞれが異なるシナリオをカバーしており、全部オフにしないとパブリックアクセスが通らないケースもある。 graph TD A[...
続きを読む