Traefik v3でBASIC認証ミドルウェアを設定する方法

1. Traefik のミドルウェア概念とリクエストフロー

Traefik は EntryPoints → Routers → Middlewares → Services の順にリクエストを処理します。
この章では、各コンポーネントの役割と、ミドルウェアがどのタイミングで介在するかを整理し、認証やヘッダー操作をサービス側コードから切り離すメリットを示します。

1.1 コンポーネント概要

• EntryPoints

• 外部から入ってくるトラフィックの受け口。web（HTTP）と websecure（HTTPS）が典型的です。

• Routers

• Host、Path、Headers などでリクエストをマッチングし、対象となる Service と Middleware を紐付けます。

• Middlewares

• 認証・ヘッダー付与・リトライ・IP 制限などの処理を実行する単位です。複数をチェーンでき、Router が選択された直後に適用されます。

• Services

• 実際にリクエストを転送するバックエンド（Docker コンテナ、Kubernetes Service、外部 API 等）です。

ポイント：ミドルウェアは「ルーティング結果」→「サービス呼び出し」の間で実行されるため、認証失敗時にサービスまでリクエストが届くことはありません。

2. Basic 認証ミドルウェア（Traefik v3 系）の正しい記述

Traefik v3 系では Basic 認証 を表すキー名が basicAuth に統一されました。
以下では必須項目・オプションを具体例とともに示し、よくある間違い（ラベル名や TLS 設定）を防止します。

2.1 基本構文

• basicAuth がミドルウェア種別を示す正しいキーです。
• usersFile か users のいずれか 必須 で、平文パスワードは絶対に記述しません。

2.2 users と usersFile の使い分け

• ハッシュ生成例（bcrypt）
  bash
htpasswd -nbB alice $(openssl rand -base64 12) | cut -d: -f2 > users.txt
users.txt は 1 行 1 ユーザー の形式で保存し、Traefik が読み込めるようにボリュームまたは Secret としてマウントします。

2.3 認証失敗時のエラーページは別ミドルウェアで実装

basicAuth 自体には errorPage フィールドは存在しません。認証エラー時にカスタムページを返したい場合は、Error Page Middleware を別途作成し、Basic 認証ミドルウェアの後ろにチェーンします。

Router の middlewares に basic-auth@docker,custom-error-page@docker と列挙すれば、認証失敗時に指定したサービスが応答します。

2.4 TLS 設定の注意点

• エントリーポイントでの TLS 有効化は不要です。TLS は Router レベルで tls: true（または tls.certResolver）を設定するだけで有効になります。
• entryPoints.websecure.tls=true のようなオプションは 存在しません。誤って記述すると起動エラーの原因となります。

3. 実装例 ― Docker Compose と Kubernetes

この章では、上記で説明した正しい構文をもとに、Docker Compose と Kubernetes の両環境で Basic 認証ミドルウェアをデプロイする手順を示します。セキュリティは外部ファイル／Secret にハッシュを保存し、平文がコードに残らないこと を前提としています。

3.1 Docker Compose（ラベル方式）

Docker Provider ではコンテナの labels にミドルウェア定義を書き込む必要があります。以下は Traefik v3.x (RC) が動作するイメージ を想定した例です。

ポイント解説

• basic-auth.basicAuth.* が正しいキー名です。以前の basicauth ではロードに失敗します。
• Router の middlewares はカンマ区切りで複数指定できます。認証 → エラーページ の順序が重要です。
• usersFile のパスはコンテナ内部から見た絶対パス（ここでは /etc/traefik/auth/users.txt）を記述します。

3.2 Kubernetes（CRD + Secret）

Kubernetes 環境では Traefik が提供する Custom Resource Definitions (CRD) を使ってミドルウェアを定義し、認証情報は Secret に格納します。

3.2.1 Secret の作成

• stringData に bcrypt ハッシュを プレーンテキスト で記載し、Kubernetes が自動的に base64 エンコードします。

3.2.2 Middleware CRD

3.2.3 Error Page Middleware（認証失敗時用）

3.2.4 IngressRoute と Volume マウント設定

3.2.5 IngressRoute 本体

ポイント解説

• Secret と ConfigMap の projected ボリュームで、users.txt をファイルとしてマウント。Traefik はこのパスを usersFile で参照します。
• エラーページは別ミドルウェア (custom-error-page) としてチェーンし、認証失敗時に独自の HTML を返せます。
• TLS 設定は IngressRoute の tls.certResolver により自動取得され、Router で tls: true が暗黙的に有効化されます。

4. セキュリティベストプラクティス

Basic 認証は 平文の資格情報が HTTP ヘッダーに乗る ため、TLS が必須です。ここでは、Traefik のミドルウェアだけで実装できる追加防御策をまとめます。

4.1 HTTPS と HSTS の組み合わせ

• HSTS ヘッダーを付与すると、ブラウザが 以降の HTTP 接続を自動的に HTTPS に切り替える ため、TLS ダウングレード攻撃を防げます。

4.2 IP 制限（社内限定アクセス）

• ipWhiteList ミドルウェアを Basic 認証の前にチェーンすれば、許可 IP 以外からは認証さえ試みられません。

4.3 ログレベルとデバッグ情報

• 本番環境では --log.level=INFO が推奨ですが、トラブル時には 一時的に
  bash
--log.level=DEBUG
  を有効化し、traefik.http.middlewares.basic-auth.basicAuth.debug=true（v3 のみ）でハッシュ比較の詳細を取得できます。

4.4 パスワード管理上の注意点

5. テスト・検証とトラブルシューティング

実装後は 認証が期待通りに動作するか を必ず確認しましょう。ここではコマンド例、ダッシュボードの見方、典型的な障害パターンと対処法をまとめます。

5.1 curl と Postman による基本チェック

• 200 OK → 認証成功
• 401 Unauthorized → 認証失敗（エラーページが設定されていればカスタム HTML が返ります）

Postman では Authorization → Basic Auth を選択し、同様に結果を確認できます。

5.2 Traefik ダッシュボードの活用

• URL: http://<traefik-host>:8080/dashboard/（api.insecure=true が有効な場合）
• Middlewares タブで basic-auth のステータスが Enabled: true か確認。
• Routers タブで対象 Router に紐付くミドルウェア一覧をチェックし、順序（認証 → エラーページ）が正しいか確認します。

5.3 主なトラブルと対処法

6. まとめ

• ミドルウェア は Traefik のリクエストフローに柔軟に介在でき、認証やヘッダー操作をサービスコードから切り離す中心的役割を担います。
• Traefik v3 系 では Basic 認証のキーが basicAuth に統一され、ラベル・CRD の記述はこの名前に合わせる必要があります（旧 basicauth はエラーになります）。
• TLS 必須 であり、entryPoints.websecure.tls=true といった無効なオプションは削除し、Router の tls: または certResolver に委ねます。
• 認証失敗時のカスタムエラーページは 別ミドルウェア（Error Page）で実装し、チェーン順序に注意してください。
• Docker Compose でも Kubernetes でも Secret / ConfigMap を利用してハッシュファイルを外部化し、平文がコードに残らない設計を徹底します。
• HTTPS＋HSTS、IP 制限、適切なログレベル設定で 平文パスワードの漏洩リスク を最小化できます。

これらのベストプラクティスと正しい構文を守ることで、Traefik v3 系においても安全かつ運用性の高い Basic 認証ミドルウェアを実装できるようになります。ぜひ本稿を手元に置きながら、実際の環境で試してみてください。