開発環境でローカルHTTPSを有効にする方法

多くのフロントエンド開発者は、Service WorkerやGeolocationなどのブラウザAPIを使用するためにローカル環境でHTTPSが必要だと思い込んでいます。実はこれは誤解です。ブラウザはすでにlocalhostを安全なコンテキストとして扱っているため、これらのAPIは通常のHTTP上で問題なく動作します。しかし、本当にローカルHTTPSが必要な状況も存在します:OAuthコールバックURLのテスト、本番環境に近い条件でのCookieの動作確認、カスタムホスト名での開発、または本番環境の動作を正確に再現する場合などです。この記事では、それをクリーンにセットアップする方法を紹介します。

実際にローカルHTTPSが必要な場合

証明書に手を伸ばす前に、本当に必要かどうかを確認しましょう。http://localhostは、すべての主要ブラウザで潜在的に信頼できるオリジンとして扱われます。Service Worker、カメラアクセス、およびほとんどのセキュアコンテキストAPIは、HTTPSのセットアップなしで動作します。この動作はwebstatus.devのブラウザ互換性データで確認できます。

以下のような場合には、実際のローカルHTTPSが必要になる可能性があります:

• 本番環境と一致する条件でのCookieの動作をテストする場合、特にlocalhost以外のホスト名でSecure属性付きCookieを扱う場合
• 登録されたHTTPSオリジンと一致する必要があるOAuthまたはOIDCフローをテストする場合
• localhostではなくapp.localhostのようなカスタムホスト名で開発する場合
• 同じネットワーク上のモバイルデバイスでテストする必要がある場合
• フロントエンドとバックエンドの両方がローカルで実行され、本番環境の動作を再現するためにHTTPS経由で通信する必要がある場合

これらのいずれにも該当しない場合は、セットアップをスキップしてシンプルに保ちましょう。

自己署名証明書がうまく機能しない理由

最初に思いつくのは自己署名証明書を生成することです。問題は、ブラウザは既知の認証局によって署名されていない限り証明書を信頼しないことです。自己署名証明書は「接続がプライベートではありません」という警告を引き起こし、毎回クリックして進む必要があります。または証明書の検証を完全に無効にすることになりますが、これは悪い習慣につながります。

正しいアプローチは、システムとブラウザが信頼するローカル認証局を作成し、そのCAによって署名された証明書を発行することです。これがまさにmkcertが行うことです。

mkcertを使用した信頼されたローカル証明書のセットアップ

mkcertは、ローカルCAを作成し、システムの信頼ストアに登録し、それによって署名された証明書を発行するゼロコンフィギュレーションツールです。ブラウザは警告なしでこれらの証明書を信頼します。

ステップ1: mkcertのインストール

macOSの場合:

brew install mkcert
brew install nss  # Firefoxに必要

Linuxの場合は、パッケージマネージャーを使用するか、mkcertインストールガイドに従ってください。Windowsの場合は、ChocolateyまたはScoopを使用します。

ステップ2: ローカルCAの登録

mkcert -install

これによりルートCAが作成され、システムの信頼ストアに追加されます。マシンごとに一度だけ実行する必要があります。

ステップ3: ホスト名用の証明書を生成

mkcert localhost
# またはカスタムホスト名の場合:
mkcert app.localhost

これにより2つのファイルが生成されます:証明書(.pem)と秘密鍵(-key.pem)。これらはバージョン管理の対象外にしてください。.gitignoreに追加しましょう。

開発サーバーでHTTPSを使用するための設定

証明書を開発サーバーに渡す方法は、使用するツールによって異なります。

Vite — vite-plugin-mkcertを使用する最もシンプルな方法:

import mkcert from 'vite-plugin-mkcert'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [mkcert()]
})

プラグインが証明書の生成とサーバー設定を自動的に処理します。

Vite(手動設定):

import fs from 'fs'
import { defineConfig } from 'vite'

export default defineConfig({
  server: {
    https: {
      key: fs.readFileSync('./localhost-key.pem'),
      cert: fs.readFileSync('./localhost.pem'),
    }
  }
})

Next.js — 最近のバージョンで利用可能なnext dev --experimental-httpsフラグを使用するか、同じ証明書ファイルを使用してカスタムNode.js HTTPSサーバーを手動で設定します。

Node.js(任意のフレームワーク):

const https = require('https')
const fs = require('fs')

https.createServer({
  key: fs.readFileSync('localhost-key.pem'),
  cert: fs.readFileSync('localhost.pem'),
}, app).listen(3000)

重要: mkcertが生成するrootCA-key.pemファイルは絶対に共有またはコミットしないでください。誰かがそのファイルを入手すると、あなたのマシン上で任意のドメインに対して信頼された証明書を発行できてしまいます。mkcert -CAROOTを実行して保存場所を確認してください。

Node.jsに関するセキュリティ上の注意

ローカルバックエンドが他のローカルサービスにHTTPSリクエストを行う場合、Node.jsはmkcert CAを自動的には信頼しません。Node.jsはシステムの信頼ストアではなく、独自にバンドルされた信頼された認証局のリストを使用します。環境変数を設定することで修正できます:

export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"

これをシェルプロファイル(.bashrc、.zshrcなど)に追加して、セッション間で永続化させてください。

まとめ

ローカル環境でHTTPSを有効にすることは、すべてのプロジェクトで必要というわけではありません。しかし、必要な場合、自己署名証明書では不十分です。mkcertを使用すれば、ブラウザの警告や回避策なしに、数分で適切に信頼されたlocalhost証明書を取得できます。一度セットアップし、開発サーバーで生成されたファイルを指定すれば、ローカル環境は本番環境とまったく同じように動作します。

よくある質問

Gain control over your UX

See how users are using your site as if you were sitting next to them, learn and iterate faster with OpenReplay. — the open-source session replay tool for developers. Self-host it in minutes, and have complete control over your customer data. Check our GitHub repo and join the thousands of developers in our community.