Contents
前提条件と IAM 権限
このセクションでは、Cognito のカスタムドメインを設定するために最低限必要な環境と 最小権限 の IAM ポリシーについてまとめます。適切な権限がないと API 呼び出しでエラーが発生し、作業が途中で止まってしまうので、事前にロールやユーザーへ付与しておくことが重要です。
必要な IAM アクション（概要）
| 対象サービス | 主なアクション | 目的 |
|---|---|---|
| Amazon Cognito IDP | cognito-idp:CreateUserPoolDomain、cognito-idp:UpdateUserPool、cognito-idp:DescribeUserPool |
カスタムドメインの作成・更新・状態取得 |
| AWS Certificate Manager (ACM) | acm:RequestCertificate、acm:DescribeCertificate、acm:AddTagsToCertificate |
DNS 検証用の公開証明書を発行 |
| Amazon Route 53（DNS を管理する場合） | route53:ChangeResourceRecordSets、route53:GetHostedZone |
CNAME レコードの作成・変更 |
最小権限で記述したポリシー例
以下は リソースごとに ARN を限定 したサンプルです。実際に使用する際は <user-pool-id>、<certificate-arn>、<hosted-zone-id> の部分を自環境の値に置き換えてください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 |
{ "Version": "2012-10-17", "Statement": [ { "Sid": "CognitoCustomDomainManagement", "Effect": "Allow", "Action": [ "cognito-idp:CreateUserPoolDomain", "cognito-idp:UpdateUserPool", "cognito-idp:DescribeUserPool" ], "Resource": "arn:aws:cognito-idp:*:<account-id>:userpool/<user-pool-id>" }, { "Sid": "ACMCertificateManagement", "Effect": "Allow", "Action": [ "acm:RequestCertificate", "acm:DescribeCertificate", "acm:AddTagsToCertificate" ], "Resource": "<certificate-arn>" // 例: arn:aws:acm:us-east-1:<account-id>:certificate/xxxx }, { "Sid": "Route53RecordManagement", "Effect": "Allow", "Action": [ "route53:ChangeResourceRecordSets", "route53:GetHostedZone" ], "Resource": [ "arn:aws:route53:::hostedzone/<hosted-zone-id>" ] } ] } |
このポリシーは Resource: "*" を使用せず、対象のユーザープール・証明書・Hosted Zone のみを許可しています。最小権限の原則に沿った安全な構成です。
ドメイン種別と DNS 設定
この章では「独自ドメイン」と「サブドメイン」の選択基準と、主要 DNS プロバイダーで必要となる CNAME レコード の設定手順を解説します。正しいレコードがないと ACM の検証や Cognito が内部で生成する CloudFront ディストリビューションへのエイリアスに失敗します。
独自ドメイン vs. サブドメインの選択ポイント
独自ドメインはブランド統一感が高く、将来的なサービス拡張にも柔軟です。一方、サブドメインは既存ドメインを流用できるため導入コストと管理工数が低減します。
| 項目 | 独自ドメイン（例: auth.example.com） |
サブドメイン（例: login.myapp.com） |
|---|---|---|
| 取得費用 | 新規取得が必要 | 既存ゾーンにレコード追加だけで済む |
| DNS 管理範囲 | 完全コントロール可能 | 親ドメインの権限が前提 |
| ブランド印象 | 高（独立したエンドポイント） | 中（親サービスと紐付く） |
| 将来の拡張性 | ★★★★★ | ★★☆☆☆ |
結論：短期的に手軽さを求めるならサブドメイン、長期的にブランド戦略や複数エンドポイントを想定するなら独自ドメインが適しています。
CNAME 設定の注意点
Cognito が内部で作成する CloudFront ディストリビューションは *.cloudfront.net ではなく、ユーザープール固有のエンドポイント <user-pool-id>.auth.<region>.amazoncognito.com にエイリアスされます。したがって CNAME の ターゲット は CloudFront ではなくこの Cognito エンドポイントです。
| プロバイダー | レコード種別 | ホスト名（レコード名） | ターゲット（値） |
|---|---|---|---|
| Route 53 | CNAME | auth.example.com |
<user-pool-id>.auth.ap-northeast-1.amazoncognito.com |
| Cloudflare | CNAME | login.myapp.com |
<user-pool-id>.auth.ap-northeast-1.amazoncognito.com |
設定手順（共通）
- DNS 管理コンソールにログインし、対象ドメインのレコード一覧へ移動。
- 「CNAME」レコードを新規作成し、ホスト名 と ターゲット を上表のとおり入力する。
- TTL はデフォルト（300 秒）で問題ないが、検証中は短め（60 秒）に設定しても可。
- 保存後、
dig auth.example.com CNAMEなどで正しく解決できることを確認し、伝搬が完了するまで待つ（通常数分～30 分）。
ACM 証明書の取得と DNS 検証
Cognito カスタムドメインは HTTPS が必須です。ここでは us-east-1 でパブリック証明書を発行し、DNS 検証を完了させる手順を示します。
証明書のリクエスト（コンソール）
- AWS マネジメントコンソール → Certificate Manager を開く。
- 「証明書のリクエスト」→「パブリック証明書」を選択。
- ドメイン名にカスタムドメイン（例:
auth.example.com）を入力し、必要ならワイルドカード*.example.comも追加。 - 検証方法は DNS 検証 を選び、表示された CNAME レコード情報をコピーする。
- 「次へ」→「確認」→「リクエスト」を完了する。
証明書のリクエスト（CLI）
|
1 2 3 4 5 6 |
aws acm request-certificate \ --domain-name auth.example.com \ --validation-method DNS \ --subject-alternative-names *.example.com \ --region us-east-1 |
実行結果に返ってくる CertificateArn をメモしておきます。
DNS 検証レコードの作成
ACM が提示した CNAME（例: _a1234567abcdef.auth.example.com → _b9876543zxyw.acm-validations.aws.）を、上記 CNAME 設定手順 と同様に DNS に追加します。レコードが正しく反映されると ACM コンソールのステータスが ISSUED へ遷移し、証明書が利用可能になります。
ポイント：検証用 CNAME は CloudFront のエイリアス先とは無関係です。混同しないように「ACM 用」「Cognito 用」の2つの CNAME が必要になることがあります。
Cognito ユーザープールへのカスタムドメイン登録
証明書と DNS が整ったら、実際に ユーザープール にカスタムドメインを紐付けます。コンソール操作と IaC（CLI / CloudFormation）それぞれの手順を示します。
コンソールでの設定フロー
- Amazon Cognito コンソール → 対象のユーザープールを選択。
- 左メニューの 「ドメイン名」 をクリックし、タブから 「カスタムドメイン」 を開く。
- 「ドメインの追加」ボタンを押し、
auth.example.com（取得したドメイン）を入力。 - 「証明書 ARN」のプルダウンから先ほど発行した ACM 証明書の ARN を選択。
- 保存 → Cognito が自動的に CloudFront ディストリビューションを作成し、ステータスが
Enabledになるまで待つ（数分）。
CLI／CloudFormation による自動化
CLI コマンド例
|
1 2 3 4 5 |
aws cognito-idp create-user-pool-domain \ --domain auth.example.com \ --user-pool-id us-east-1_AbcDefGhi \ --custom-domain-config CertificateArn=arn:aws:acm:us-east-1:<account-id>:certificate/xxxxxxx |
CloudFormation テンプレート例
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
Resources: CognitoCustomDomain: Type: AWS::Cognito::UserPoolDomain Properties: Domain: auth.example.com UserPoolId: !Ref UserPool CustomDomainConfig: CertificateArn: arn:aws:acm:us-east-1:<account-id>:certificate/xxxxxxx UserPool: Type: AWS::Cognito::UserPool # 必要な属性は別途記述 |
重要：
CertificateArnがus-east-1のものか必ず確認してください。リージョンが異なると「Invalid certificate ARN for region」のエラーになります。
動作確認とトラブルシューティング
設定完了後は、ブラウザだけでなく OAuth フロー全体をテストして正常にトークンが取得できるか確認します。よくある障害パターンと対処法もまとめました。
基本的な動作確認手順
- サインインページの表示
https://auth.example.com/login?client_id=xxxxx&response_type=code&scope=openid+profile&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallbackにアクセスし、Cognito のログイン画面が正しく表示されるか確認。 - アクセストークン取得テスト（curl）
|
1 2 3 4 5 6 7 8 9 10 |
# まずは認可コードを取得（実際にはブラウザでの手順になることが多い） CODE=$(curl -s -L "https://auth.example.com/login?...省略..." | grep -o 'code=[^&]*' | cut -d= -f2) # トークンエンドポイントへ POST TOKEN_RESPONSE=$(curl -s -X POST https://auth.example.com/oauth2/token \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=authorization_code&client_id=xxxxx&code=${CODE}&redirect_uri=https%3A%2F%2Fapp.example.com%2Fcallback") echo "$TOKEN_RESPONSE" | jq . |
access_token が JSON に含まれていれば、カスタムドメインの設定は成功です。
よくあるエラーと対処法
| エラーメッセージ | 主な原因 | 修正手順 |
|---|---|---|
| Certificate not validated | ACM の CNAME が DNS に未反映、またはタイプミス | DNS コンソールでレコード名・値を再確認し、TTL を短くして再度 dig で検証 |
Domain not found (CNAME 未伝搬) |
レコード作成直後にチェックした | dig auth.example.com CNAME で結果が出るまで待つ（最大30分） |
| Invalid certificate ARN for region | 証明書を us-east-1 以外で取得 | ACM のリージョンオプション --region us-east-1 で再作成し、ARN を更新 |
| Domain name already in use (CloudFront エイリアス衝突) | 同一ドメインが別 CloudFront に割り当て済み | 既存ディストリビューションを削除または別名に変更後、再度 Cognito に登録 |
| Cognito status stuck on Creating | DNS 検証が完了していないか ACM が PENDING_VALIDATION のまま |
ACM コンソールでステータス確認し、検証レコードを正しく設定 |
ベストプラクティス
- HTTPS を強制：OAuth クライアントのリダイレクト URI は必ず
https://から始める。 - 証明書ローテーション：ACM の自動更新は有効にしておき、ARN が変わらないよう CloudFormation のパラメータ化で管理。
- 監視とアラート：CloudWatch メトリクス
4XXError・5XXErrorに基づく SNS アラートを設定し、障害発生時に即座に通知できるようにする。 - UI カスタマイズ：Cognito のカスタム UI（CSS/HTML）でブランドカラーに統一し、ユーザー体験の向上を図る。
まとめ
- 最小権限ポリシー を作成し、
cognito-idp:*・acm:*・route53:*の各アクションを対象リソースに限定して付与する。 - ドメイン選択：ブランド重視は独自ドメイン、導入コスト削減はサブドメインが適切。
- DNS 設定：CNAME のターゲットは
<user-pool-id>.auth.<region>.amazoncognito.comであり、CloudFront 用ではないことを明示する。TTL は短めに設定し、伝搬を確認する。 - ACM 証明書 は必ず
us-east-1で DNS 検証方式の公開証明書を取得し、検証レコードが正しく反映されたらISSUEDを待つ。 - Cognito への登録：コンソール・CLI・CloudFormation のいずれかで
create-user-pool-domainを実行し、証明書 ARN を紐付ける。 - 動作確認：サインインページ表示と OAuth トークン取得をテストし、エラーは DNS・リージョン・証明書の不一致が主因であることが多い。
- 運用上の留意点：HTTPS 強制、証明書自動更新、CloudWatch アラート、UI カスタマイズを組み合わせて安定した認証基盤を構築する。
これらの手順とポイントを守れば、Cognito のカスタムドメイン設定 を安全かつ迅速に導入でき、ユーザーに統一感のあるサインイン体験を提供できます。