はじめに
最近Herokuで運用しているアプリにカスタムドメインを設定する機会があったのですが、Heroku側のドメイン追加だけでなく、DNSのCNAME設定、SSL証明書の発行（ACM）、さらに認証サービスとの連携まで考慮する必要があって、何をどの順番で何をすればいいのか分からず何度もハマりました。
特にACMの有効化がDashboardからできずCLIが必要だったり、認証サービスの設定順序を間違えて「Callback URL mismatch」に悩まされたりと、公式ドキュメントだけでは辿り着きにくい落とし穴が多かったです。
同じような状況で困っている方の参考になればと思い、一連の手順をまとめました。
今回の例はyour-app.herokuapp.com → your-app.example.comに変更する想定で進めます。
前提
- Herokuアプリがデプロイ済み
- 独自ドメインを取得済み（例:
example.com） - DNSの管理画面にアクセスできる
- Heroku CLIがインストール済み（未導入なら
brew tap heroku/brew && brew install heroku）
ステップ1: Herokuにカスタムドメインを追加
Heroku Dashboardからドメインを登録して、DNSターゲットを取得します。
- Heroku Dashboardで対象アプリを開く
- Settings → Domains セクションへスクロール
- 「Add domain」をクリック
- カスタムドメイン（例:
your-app.example.com）を入力して追加 - 表示される DNS Target（
xxx.herokudns.com）をメモしておく
ステップ2: DNSにCNAMEレコードを設定
ドメインを取得したDNS管理画面で、CNAMEレコードを追加します。
| タイプ | 名前（ホスト） | 値（ターゲット） |
|---|---|---|
| CNAME | your-app |
ステップ1でメモしたDNS Target |
サブドメイン部分（上の例では your-app）は、登録したカスタムドメインに合わせてください。
DNS反映には数分〜最大48時間かかりますが、通常は数分〜30分程度で完了するようです。
ステップ3: ACM（自動SSL証明書管理）を有効化
カスタムドメインで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
ACMがうまくいかない場合
heroku certs:auto:refresh --app your-app-name
ただし、このコマンドやACMの有効/無効切り替えを何度も繰り返すと、Let's Encryptのレート制限に引っかかって最大1週間待つハメになります。1回実行したら15分程待ってください。
ステップ4: 動作確認
- ブラウザで
https://your-app.example.comにアクセスできる - アドレスバーに鍵マークが表示される（SSL有効）
認証サービスを使っている場合の注意点
Auth0等の認証サービスを使っている場合、ドメイン変更に伴って以下の設定更新も必要です。
-
Allowed Callback URLs に
https://新ドメイン/callbackを追加 -
Allowed Logout URLs に
https://新ドメインを追加 -
Allowed Web Origins に
https://新ドメインを追加
サーバー側でオリジンチェックや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ステップ
- Herokuにカスタムドメインを追加 → DNS Targetを取得
- DNSにCNAMEレコードを設定 → ドメインをHerokuに向ける
- ACMを有効化 → SSL証明書を自動発行
認証サービスを使っている場合は、ドメイン変更前に許可URLの追加を忘れずに。