aws-auth

AWS 認証（Amazon Cognito）

Amazon Cognito と Amplify クライアント認証ライブラリを使用した、アプリケーションレベルのユーザー認証と認可です。正確さが重要な場合は、具体的な制限、クォータ、正確な API の形式を公式 AWS ドキュメントで確認してください。記憶と内容が異なる場合は、ドキュメントを優先してください。

推奨： AWS MCP サーバーを使うと、このスキルで使用する AWS API（Cognito ユーザープール／アプリクライアント／ID プールの設定、API Gateway オーソライザー）に簡潔にアクセスできます。利用できない場合は、全編に記載されている AWS CLI コマンドを直接使用できます。このスキルに MCP は必須ではありません。

使用しないケース： Amplify Gen2 のバックエンドコード（defineAuth、amplify/auth.ts、npx ampx）、IAM ポリシー／ロール／信頼ポリシーの作成、STS、IAM Identity Center コンソールの SSO、API Gateway のルート／統合設定、Lambda 関数の実装（このスキルの対象は Cognito／JWT オーソライザーの設定と、Cognito Lambda トリガーの目的のみです）。

ユーザープールと ID プール — まず選択する

これらは混同されやすい別々のサービスです。ほとんどのアプリで必要なのはユーザープールです。クライアントが AWS サービスを直接呼び出す必要がある場合に限り、ID プールも追加してください。

必要な機能	使用するもの	理由
サインアップ／サインイン、ユーザーディレクトリ、JWT の発行	ユーザープール	ユーザーを認証し、OIDC IdP として機能します
サインイン済みのクライアントによる、AWS 認証情報を使った S3／DynamoDB などへの直接アクセス	ID プール	STS を介してトークンを一時的な AWS 認証情報と交換します
両方（サインイン後に、ブラウザー／アプリから AWS リソースにアクセス）	ユーザープール → ID プール	ID プールはユーザープールを IdP として信頼します

アプリが独自のバックエンド／API のみを呼び出す場合、ID プールは不要です。ユーザープールのトークンを API に送信してください。identity-pools.md を参照してください。

重大な警告

update-user-pool-client と set-identity-pool-roles は部分更新ではなく、全置換です：省略したフィールドはすべてデフォルト値にリセットされます。変更したいフィールドだけを指定して update-user-pool-client を呼び出すと、ExplicitAuthFlows、トークンの有効期間、EnableTokenRevocation、リフレッシュトークンのローテーション、読み取り／書き込み属性が気づかないうちに消去されます。同様に、set-identity-pool-roles もロールと RoleMappings の構造全体を置き換えます。必ず読み取り・変更・書き込みの手順にしてください：最初に describe-user-pool-client（または get-identity-pool-roles）を実行し、その後、既存のすべてのフィールドと変更内容を再送信してください。エージェントのコンテキストでは、消去が見えません。呼び出し自体は成功し、後になってユーザーが必要なフローを利用しようとしたときに初めて問題が起きます。managed-login-oauth.md と identity-pools.md を参照してください。

新しいアプリでインプリシットグラントを使用しないでください：インプリシットグラント（response_type=token）は旧式で、URL フラグメントにトークンを返します。SPA とモバイルでは、PKCE を使用した認可コードグラント（response_type=code + code_challenge）を使用してください。パブリッククライアントにはクライアントシークレットは不要です。managed-login-oauth.md を参照してください。

重要度の高いアプリでは、リフレッシュトークンを localStorage に保存しないでください：localStorage は、挿入されたあらゆるスクリプトから読み取れます（XSS）。Amplify クライアントライブラリのデフォルトは localStorage です。cookieStorage に切り替え、リフレッシュトークンの有効期間を短くし、アプリクライアントでリフレッシュトークンのローテーションとトークンの失効を有効にしてください。tokens-and-sessions.md を参照してください。

アクセストークンのクレームをカスタマイズするには、有料の機能プランが必要です：pre token generation トリガーは、エントリーレベルのプラン（V1）で ID トークンをカスタマイズできますが、アクセストークンのカスタマイズ（V2/V3）には有料の機能プランが必要です。プラン名や対象機能は変更される可能性があるため、現在どのプランにこの機能が含まれているか、Cognito feature plans documentation で確認してください。エントリーレベルのプランでアクセストークンのクレームが機能すると決めつけないでください。lambda-triggers.md を参照してください。

アプリクライアントのシークレット + SPA = 認証の失敗：パブリッククライアント（ブラウザー／モバイル）には、クライアントシークレットを設定しないでください。シークレットが設定されていると、SECRET_HASH を送信しない限りトークンの呼び出しは失敗しますが、ブラウザーではシークレットを保護できません。シークレットを生成するのは、機密クライアント（サーバーサイド）に限ってください。

admin-confirm-sign-up で UNCONFIRMED ユーザーを一括確認しないでください：ユーザーが UNCONFIRMED のままになっている場合は、resend-confirmation-code を使用し、各ユーザーが confirm-sign-up で再確認してメールアドレスの所有を証明できるようにしてください（確認コードの有効期限が切れているか、迷惑メールに振り分けられた可能性があります）。admin-confirm-sign-up はステータスを即座に変更しますが、メールアドレスを検証せずにアカウントを確認するため、その属性は未検証のままです。メールアドレスをパスワードリセットやアカウントのリンクに使用する場合、これは危険です。信頼できるアカウントや移行済みのアカウントに限って使用してください。troubleshooting.md を参照してください。

クイックナビゲーション

目的	参照先
ユーザープールの作成、サインアップ／サインイン、MFA、パスワードポリシー、アプリクライアント	user-pools.md
ホスト型 UI／マネージドログイン、OAuth フロー、ソーシャルログインまたは SAML ログイン、コールバック URL、**カスタムドメイン（us-east-1 の ACM）**の追加	managed-login-oauth.md
ID／アクセス／リフレッシュトークン、ローテーション、失効、**セッションの終了（グローバルサインアウト、失効、無効化の違い）**の処理	tokens-and-sessions.md
クライアントへの一時的な AWS 認証情報の提供、ゲストアクセス、ロールマッピング	identity-pools.md
Cognito トークンで API Gateway API を保護（バックエンドでカスタムクレームも強制）	api-authorization.md
Application Load Balancer（ALB authenticate-cognito）の前段に Cognito ログインを追加	api-authorization.md
マシン間（クライアント認証情報）認証、リソースサーバー、カスタムスコープ	managed-login-oauth.md
ユーザープールグループの作成とユーザーの追加（cognito:groups、Precedence）	user-pools.md
クレームのカスタマイズ、カスタム認証チャレンジフロー、ユーザーの移行、サインアップの検証	lambda-triggers.md
パスキー／WebAuthnサインイン（USER_AUTH フロー、AllowedFirstAuthFactors、WebAuthn 登録）の追加	passkeys.md
脅威保護の設定 — 認証情報漏えい時のブロック、アダプティブ認証（リスクベースの MFA）、CloudWatch へのログ配信	threat-protection.md
問題が発生している（リダイレクト、トークン、MFA、CORS、ソーシャルログイン）	troubleshooting.md

よくあるワークフロー

「React アプリにサインアップとログインを追加する」 → ユーザープールとパブリックアプリクライアント（シークレットなし）を作成し、PKCE を使用した認可コードグラントでホスト型 UI／マネージドログインを有効にして、Amplify クライアントライブラリを接続します。user-pools.md と managed-login-oauth.md を参照してください。

「Google／ソーシャルログインを追加する」 → ユーザープールにソーシャル IdP を登録し、属性をマッピングして、アプリクライアントとホスト型 UI にプロバイダーを追加します。managed-login-oauth.md を参照してください。

「認証済みユーザーだけが API を呼び出せるようにする」 → HTTP API の場合は JWT オーソライザー、REST API の場合は Cognito ユーザープールオーソライザーを使用します。api-authorization.md を参照してください。

「ログイン後、ブラウザーから S3 にアップロードできるようにする」 → サインインにはユーザープールを使用し、その後、スコープを限定した一時的な認証情報を提供するためにアイデンティティプールを使用します。identity-pools.md を参照してください。

トラブルシューティング

エラー／症状	考えられる原因	すぐにできる対処
redirect_mismatch／ログイン後に誤った URL にリダイレクトされる	コールバック URL が登録されていない、またはスキーム／末尾のスラッシュ／大文字と小文字が異なる	正確なコールバック URL（スキームとパスを含む）をアプリクライアントの「許可されたコールバック URL」に追加します
「unable to verify secret hash」によりトークンの呼び出しに失敗する	パブリック（SPA／モバイル）クライアントにクライアントシークレットが設定されている	シークレットなしでアプリクライアントを再作成するか、機密クライアントから SECRET_HASH を送信します
有効なトークンがあるのに、ユーザーが API Gateway から 401 を受け取る	トークンの種類が誤っている、またはオーディエンス／発行者が一致しない	HTTP JWT オーソライザーの場合、発行者を https://cognito-idp.{region}.amazonaws.com/{userPoolId}、オーディエンスをアプリクライアント ID に設定し、オーソライザーが期待するトークンを送信します
ホスト型 UI／トークンエンドポイントの呼び出しで CORS エラーが発生する	ブラウザーから /oauth2/token をクロスオリジンで呼び出している、または API に CORS が設定されていない	PKCE を使用して認可コードを交換します。ブラウザーからトークンエンドポイントをプロキシしないでください
ソーシャルログインでユーザーが「すでに存在する」／属性の競合が発生する	プロバイダー間で同じメールアドレスを使うと、別々のユーザーが作成される	属性マッピングとアカウントリンクを有効にします。メールアドレスは IdP 間で一意ではないものとして扱います

表の完全版はtroubleshooting.mdをご覧ください。

セキュリティに関する考慮事項

• パブリッククライアント（SPA／モバイル）では、クライアントシークレットを使用せず、PKCE を使用した認可コードグラントを使い、最小権限のスコープをリクエストします。
• MFA（TOTP または SMS）、強力なパスワードポリシー、および利用可能な場合は高度なセキュリティ／脅威対策を有効にします。
• アクセストークンの有効期間を短くし、リフレッシュトークンのローテーションとトークンの失効を有効にします。localStorage よりも cookieStorage を優先します。
• ID プールでは、認証済み IAM ロールの権限を厳密に制限します。必要でない限り、未認証（ゲスト）アクセスを無効にします。
• 保護対象のリクエストごとに、ユーザープールの JWKS に照らして JWT（iss、aud／client_id、token_use、exp）を検証します。検証処理を独自に実装するのではなく、aws-jwt-verify などのメンテナンスされているライブラリを使用します。
• アプリのウェブページにセキュリティヘッダーを設定します。Content-Security-Policy（スクリプトのソースを制限して、トークンを盗む XSS を軽減）、Strict-Transport-Security（HSTS）、X-Frame-Options／frame-ancestors（ログインページへのクリックジャッキング対策）、および X-Content-Type-Options: nosniff を設定します。
• ログ記録とモニタリングを有効にします。Cognito API イベント（サインアップ／サインイン／管理操作）には CloudTrail を使用し、ユーザープールの脅威対策（アダプティブ認証とイベントログ記録）を有効にします。認証の失敗やスロットリングに関する CloudWatch アラームを設定し、オーソライザーの判定について API Gateway のアクセスログを有効にします。
• すべての Cognito および API エンドポイントで HTTPS/TLS のみを使用します。CloudWatch ロググループ、MFA／通知に使用する SNS トピック、および ID プール経由でアクセスするアップロード用バケットでは、カスタマー管理 KMS キー（および制限されたキーアクセス）による保存時の暗号化を有効にします。
• MFA／通知の配信に SNS を使用する場合は、トピックでサーバー側暗号化（KMS）を有効にします。また、SMS／メールの本文は受信者に必要な内容だけにし、メッセージに必要な量を超える個人情報を含めないでください。
• 参考資料：Amazon Cognito のセキュリティ機能（ユーザープール）、Amazon Cognito のセキュリティ（概要、ID プールを含む）、IAM／STS のベストプラクティス。

このスキルで情報が不足している場合の参照先

このスキルを超える詳細（正確なパラメータ形式、現在の制限、動作の詳細）が必要な場合は、推測せず、AWS の公式情報を参照してください。ポインターはコンテンツよりも古くなりにくいため、この一覧はスキルを拡張しなくても役立ちます。

• API リファレンス（正確なパラメータ、デフォルト値、エラー）： Cognito User Pools API および Cognito Identity API
• 開発者ガイド（概念、ワークフロー）： Amazon Cognito Developer Guide
• クォータ、レート制限、セッションクッキーの有効期間： Cognito quotas
• 機能プラン／ティアによる制限： Cognito feature plans
• 料金： Amazon Cognito pricing
• CLI リファレンス： aws cognito-idp および aws cognito-identity

このスキルの対象外

• Amplify Gen2 バックエンド（defineAuth、amplify/auth.ts、npx ampx sandbox）。
• IAM ポリシー／ロール／信頼ポリシーの作成、STS、IAM Identity Center コンソールの SSO。
• API Gateway のルート／統合の設定と Lambda 関数の実装（このスキルの対象は、Cognito／JWT オーソライザーの設定と Cognito Lambda トリガーの目的のみです）。