はじめに

最近Herokuで運用しているアプリにカスタムドメインを設定する機会があったのですが、Heroku側のドメイン追加だけでなく、DNSのCNAME設定、SSL証明書の発行（ACM）、さらに認証サービスとの連携まで考慮する必要があって、何をどの順番で何をすればいいのか分からず何度もハマりました。

特にACMの有効化がDashboardからできずCLIが必要だったり、認証サービスの設定順序を間違えて「Callback URL mismatch」に悩まされたりと、公式ドキュメントだけでは辿り着きにくい落とし穴が多かったです。

同じような状況で困っている方の参考になればと思い、一連の手順をまとめました。
今回の例はyour-app.herokuapp.com → your-app.example.comに変更する想定で進めます。

前提

Heroku Dashboardからドメインを登録して、DNSターゲットを取得します。

ドメインを取得したDNS管理画面で、CNAMEレコードを追加します。

タイプ	名前（ホスト）	値（ターゲット）
CNAME	`your-app`	ステップ1でメモしたDNS Target

サブドメイン部分（上の例では your-app）は、登録したカスタムドメインに合わせてください。

DNS反映には数分〜最大48時間かかりますが、通常は数分〜30分程度で完了するようです。

カスタムドメインでHTTPSを使うには、HerokuのACMを有効にしてSSL証明書を自動発行させる必要があります。この設定はDashboardだとできないので、CLIを使います。

# Heroku CLIにログイン
heroku login

# ACMの状態を確認
heroku certs:auto --app your-app-name

# ACMを有効化
heroku certs:auto:enable --app your-app-name

数分待ってから再度確認して、Cert Issued と表示されればOKです。

heroku certs:auto --app your-app-name

heroku certs:auto:refresh --app your-app-name

ただし、このコマンドやACMの有効/無効切り替えを何度も繰り返すと、Let's Encryptのレート制限に引っかかって最大1週間待つハメになります。1回実行したら15分程待ってください。

Auth0等の認証サービスを使っている場合、ドメイン変更に伴って以下の設定更新も必要です。

サーバー側でオリジンチェックやCORS制御をしている場合は、環境変数も新ドメインに更新してください。

認証サービスの設定更新は、クライアントの再デプロイより前にやっておいてください。順序を間違えると「Callback URL mismatch」エラーが出ます。

エラー	原因	対処法
`ERR_SSL_UNRECOGNIZED_NAME_ALERT`	ACMが無効	ステップ3でACMを有効化
CORSエラー	オリジン設定が未更新	サーバーの環境変数・認証サービスのWeb Origins設定を確認
Callback URL mismatch	認証サービスにCallback URLが未登録	Allowed Callback URLsに新ドメインを追加
404 / ドメインが見つからない	DNS未反映	CNAMEレコードを確認して、時間を置いて再試行

やることは大きく3ステップ

認証サービスを使っている場合は、ドメイン変更前に許可URLの追加を忘れずに。