〜Version5 以降での認証セッションの注意点を詳しく解説～

はじめに

TP-LinkのOmadaシリーズでゲストWi-Fiに外部認証ポータルを導入しようとするとき、最大の落とし穴となるのが「Omada SDN v5のセッション認証仕様」です。

とくに初めて導入する方がネットの情報を頼りにしようとすると、v4以前やスタンドアロン時代の情報に惑わされ、正しく認証ができているのに通信が通らない…といったトラブルに直面します。

私もまさにその典型例で、「clientMacさえわかればいけるはず」、「なぜか接続できない」、「Controllerが応答しない」と、数日間も泥沼にハマってしまいました。どれも公式ドキュメントの読み込み不足で、APIの本質を理解せずに実装しようとしていたのが原因でした。

本記事では、そんな経験から学んだv5の落とし穴と正しい実装フローを、技術的にも実践的にも、できる限り詳しくお伝えします。

Omada外部ポータル認証の進化

バージョン 特徴
v3以前 EAPスタンドアロン構成、リダイレクトのみの簡易認証
v4.x SDN登場、APIベースのポータル連携（CSRFトークン + Cookie + JSON POST）
v5.x セキュリティ強化、Controller ID導入、CSRFトークンはHTTPヘッダーに移行

v4でもすでにトークンベースのセッション認証が導入されていましたが、v5では仕様が厳格化され、従来の柔軟性ある構成では動作しなくなっています。にもかかわらず、ネット上の多くの情報はv4やスタンドアロン時代のものが多く、私のように勘違いしたままハマる人も少なくないはずです。

  • 補足：Omada SDNとは？

    SDN ( Software-Defined Networking ) は、ネットワーク機器（ルーターやスイッチ、アクセスポイントなど）の設定や管理を、個別の機器ごとではなく、ソフトウェアコントローラ（＝Omada Controller）から一括制御できる仕組みです。

    TP-Linkは「エンタープライズクラスのネットワークを、誰でも簡単に導入・集中管理できる」ことを目的にOmada SDN Controllerをリリースしました。中・小・個人が安価に本格的なネットワーク構築する際には、最も優れた選択肢の1つになります。

v5 External Portal APIの仕様

Omada SDN v5では、外部ポータルの構成が大幅に近代化され、以下のような設計になっています：

  1. クライアントがPortal認証付きネットワーク（SSIDまたはVLAN）に接続すると、EAPまたはGatewayがHTTPリクエストをインターセプトし、クライアントをOmada Controllerにリダイレクトします。

  2. Controllerは、接続情報を含むURL（clientMac, apMac/gatewayMac, ssidName, site, time, radioId, redirectUrl など）を用いて、クライアントを外部ポータルサーバへ再リダイレクトします（HTTP 302）。

  3. クライアントはそのURLでポータルサーバへアクセスし、ポータルはクエリパラメータを取得・保持して認証ページを表示します。

  4. ユーザーがポータル上で認証を完了すると、ポータルはまずOmada Controllerにログインする必要があります。この際、operatorアカウント（管理画面で事前登録されたホットスポット運用用アカウント）の資格情報をJSONで送信します。

  5. ログイン成功時、Controllerは以下を返します：

    • TPOMADA_SESSIONID（v5.11以降）または TPEAP_SESSIONID（v5.11未満）のセッションクッキー

    • CSRFトークン（JSONレスポンスの result.token）

  6. 認証が成功したクライアントの情報を、ポータルは次の形式でControllerに送信します（HTTPS + JSON POST）：

{ "clientMac": "AA:BB:CC:DD:EE:FF", "apMac": "11:22:33:44:55:66", // または gatewayMac "ssidName": "MySSID", // Gateway構成では vid を指定 "radioId": 1, // 0=2.4GHz, 1=5GHz "site": "default", "time": 3600000000, // マイクロ秒単位の認証有効時間 "authType": 4 // 固定値：外部ポータル認証を意味する }

  • このPOSTには、必ず以下を含める必要があります：

    • HTTPヘッダー Csrf-Token: <取得したトークン>

    • クッキー TPOMADA_SESSIONID=<取得したセッションID> 7. 認証が受理されると、Controllerは {"errorCode": 0} を返し、その後クライアントは通信可能になります。

このように、Omada SDN v5の外部ポータル連携は、セッションベースの認証管理＋CSRF対策＋明示的なログイン・認可プロセスを備えた、堅牢かつセキュアな構成へと刷新されています。

実際に起きたトラブルと遠回り

私が最初に参考にしていたのはv4以前やスタンドアロン時代の情報ばかりで、以下のような典型的な勘違いと遠回りをしてしまいました：

  • clientMac や clientIp をGETパラメータで受け取って処理すれば十分だと思い込んだ
  • token もURLパラメータとして渡ってくるものだと思い込んでいた
  • Omada Controllerが認証完了を受け取るPOST APIを必要としていることに気づくのが遅れた
  • APIログインのための正しいURLを理解するのに時間がかかった

その結果、「認証はできているはずなのに通信が通らない」「Controllerが何も反応しない」といった状態に数日間悩まされました。

特に困惑したのは、TP-Link公式のFAQ 3231（External Portal API仕様）を読んでも、v5とv4の違いがあまり明示されていなかったことです。APIの形式としてはv5もv4も/hotspot/loginを使い、JSON形式も似ているため、「これは同じものだろう」と勘違いしてしまったのです。

また、v5以降はクラウド連携を前提としていますが、私自身はOmada Controllerをローカルで動かしていたため、ControllerIDの取得にも少し手間取りました。ローカルの管理画面の表向きなUIではこのIDが明示されていません。ブラウザの開発者ツールを使って通信のURLを確認することで、Controller IDの構造が分かりました。 これは、APIの公式資料に詳しい記載がないため、初見ではややつまずきやすいポイントだと思います。

外部ポータル開発の要点まとめ（v5用）

項目 内容
使用API /api/v2/hotspot/login
通信方式 HTTPS + JSON POST
必須ヘッダー Csrf-Token, Content-Type: application/json
必須パラメータ clientMac, access_token, ssidName, site など
セッション期限 数分程度（短命）
ポータル側の責務 トークンの検証・ログの保存・認証結果の送信

参考： v4 から v5 へ移行する開発者への注意喚起

  • v5では、トークン＋Cookie＋JSON POSTの渡し方が変更されており、旧コードでは動作しない

  • 特に注意すべき違い：

    • token は URLクエリではなく HTTPヘッダーに指定

    • URLパスに Controller ID が必要（UI非表示）

  • Controller IDの取得は、ブラウザでポータルにアクセスしたときのURLパターンをブラウザの開発者ツールで確認するのが現実的

情報はあった、それでも迷ってしまった

正直に言うと、外部ポータル開発に必要な情報の多くは、TP-Link公式の以下のドキュメントにすべて集約されていました：

👉 FAQ 3231 - External Portal API（Omada SDN v5対応）

👉 FAQ 2907 - Omada v4互換モード（Compatibility Mode）

ところが当初の私は、検索で見つかる他のブログ記事や過去の公式FAQ（v4やスタンドアロン向け）ばかりを参考にしてしまい、結果として**「全く異なる方式の認証ロジック」を前提に実装を進めてしまいました**。

今となっては少し恥ずかしい話ですが、同じような遠回りをする人が減ってくれたら嬉しいと思い、あえてここに記しておきます。

v5で導入されたセキュリティ強化ポイント

v5では開発の難易度が上がったと感じる場面も多くありますが、それは同時に次のようなセキュリティ面の大幅な改善によるものです：

ワンタイムのトークン認証：セッションの不正再利用を防止

CSRFトークン必須化：外部からの不正POSTをブロック

HTTPS通信が前提：中間者攻撃や盗聴のリスクを軽減

Controllerによる認証状態の集中管理：EAP/APではなくControllerが最終判断

これらの要素は「堅牢なゲストWi-Fi運用」のために必須であり、結果として信頼性の高いネットワーク構築が可能となります。

単なる仕様変更ではなく、より安全なWi-Fi認証環境への移行であることを理解しておくと、開発中に感じるハードルの意味合いが前向きに変わってくるはずです。

今後の公開予定

本記事の内容に関連して、近々「Raspberry Pi 1台とOmadaアクセスポイント1台だけで構成可能な、Omada Controller + 自前ポータル認証」のセキュアでお手軽な自前ポータル認証のセットアップ方法を公開予定です。

筆者が実装した、Omada v5以降に対応したFlask製の外部認証ポータルのコードもあわせて配布予定です。

  • Omada Controller（Dockerベース）
  • 外部ポータル（規約同意／メールアドレス認証等に対応）
  • SQLiteログ保存対応

小規模施設や自宅でのゲストWi-Fi提供にすぐに活用できる構成ですので、ぜひご期待ください。

おわりに

Omadaの外部ポータル認証は、Controllerの進化とともに大きく構造が変わっています。v5以降での開発では、「旧式のMACベース認証」から完全脱却しており、「トークンベースのセッション認証」へと設計を見直す必要があります。

この記事が、これからOmadaの外部ポータルを実装される方の参考となり、正しい情報に素早くたどり着く手助けになれば幸いです。

参考情報