SDK セキュアアクセラレーション導入のよくある質問：Real IP、Proxy Protocol、カスタム Header はどう扱う？

SDK セキュアアクセラレーションの導入過程で最もつまずきやすいのは、通常、初期化関数ではなく、プロキシアーキテクチャがもたらす細部です。オリジンが見るのはノードの IP かプレイヤーの IP か？Real IP Header は使えるのか？SDK にカスタム Header を自動で付与させられるのか？切断後の再接続時に、元のプロキシアドレスをそのまま使い続けてよいのか？

これらの疑問を POC 段階で明確にしておかないと、SDK をアプリに正常にコンパイルできていても、ログイン認証、リスク制御、ログ分析、IP ブロック、ロードバランシングの各段階でずれが生じる可能性があります。以下、実際の導入フローに沿って順に説明します。

• オリジンが見るのはノード IP か、真のプレイヤー IP か？真の IP をどう渡すのか？
• Proxy Protocol、TOA、API とは何か？どれを選ぶべきか？
• SDK はカスタム Header（X-App-Version など）を自動で付与してくれるのか？
• 切断後の再接続でなぜプロキシアドレスを再取得する必要があるのか？再利用できないのか？

SDK はどのようにセキュアプロキシチャネルを確立するのか

統合が完了すると、クライアントはオリジンへ直接接続せず、まず SDK を通じてプロキシ IP とポートを取得し、エッジノードが接続をオリジンへ転送します。基本的な流れは次のとおりです。

1. クライアントが AccessKey とデバイス識別情報で SDK を初期化する。
2. SDK がスケジューリングプラットフォームに、利用可能なプロキシ IP とポートを要求する。
3. クライアントが取得したプロキシアドレスで接続を確立する。
4. エッジノードが元の業務リクエストを、コンソールで設定したオリジンへ転送する。

このモデルによりオリジン IP を隠蔽し、ネットワーク品質、ノードの健全性、リスクシグナルに応じて経路を調整できます。プロキシアドレスは動的に変わりうるため、新しいリクエスト、切断後の再接続、デバイスのロック画面からの復帰のたびに getServerIPAndPort を再度呼び出すべきであり、古い IP とポートを長期間保持してはいけません。

導入前にコンソールで設定すべき項目

お客様はコンソールで転送ルールをセルフ設定できます。正式な設定の前に、SDK で保護する必要がある業務ドメイン、ポート、プロトコル、オリジンアドレスを棚卸しし、オリジンを他の保護されていない業務から隔離しておくことをお勧めします。

Real IP Header に対応しているか：まず本当の要件を明確に

SDK がプロキシノード経由で接続を転送した後、オリジンがデフォルトで見るネットワークの送信元は、エンドユーザーの真の IP ではなくプロキシノードである可能性があります。そのため、ログインのリスク制御、地域判定、ログ監査、ブロックポリシーで真のクライアント IP を使う必要がある場合は、Real IP の伝達方式を別途設定しなければなりません。

現在、真のクライアント IP を取得する方式として、次の 3 つのモードをサポートしています。

したがって、「真の IP の取得に対応」は「SDK が任意に Real IP Header を追加する」という意味ではありません。実際にどの方式を採用するかは、オリジンサーバー、ロードバランサー、プロトコル種別、既存のログ／リスク制御システムに応じて決めるべきです。オリジンが Proxy Protocol に対応している場合は、Proxy Protocol を優先することをお勧めします。通常、アーキテクチャがより直接的になります。

補足：Nginx の設定例（Proxy Protocol）

オリジンが Nginx を使用し Proxy Protocol を有効にする場合は、listen ディレクティブに proxy_protocol を追加し、real_ip_header proxy_protocol で PROXY プロトコルヘッダーから真の IP を取得します。

http {
    # ログに真のクライアント IP を記録する
    log_format main '$proxy_protocol_addr - $remote_user [$time_local] "$request"';

    server {
        listen 80 proxy_protocol;
        listen 443 ssl proxy_protocol;

        # 信頼するプロキシの送信元（本番環境では SDK エッジノードの IP 範囲に限定することを推奨）
        set_real_ip_from 0.0.0.0/0;
        # PROXY プロトコルヘッダーから真の IP を取得し、$remote_addr を上書きする
        real_ip_header proxy_protocol;

        access_log /var/log/nginx/access.log main;
    }
}

カスタム Header のセルフ追加に対応しているか

現在、SDK のコンソールにはカスタム Header を追加する機能はありません。SDK の処理原則は、クライアントの元のリクエストに含まれる Header をそのままオリジンへ透過転送することであり、Header を自ら追加、変更、削除することはありません。

設計原則として、SDK はセキュアプロキシとトラフィックのスケジューリングに専念し、アプリケーション層の業務ロジックには介入しません。これにより SDK と業務 Header の名前の衝突を避け、その後の保守における結合度も下げられます。

業務で X-App-Version、X-Device-ID、X-Channel などのカスタムフィールドが必要な場合は、クライアントが元のリクエストを送信する際に自ら付与してください。SDK は既存の Header をリクエストとともに転送しますが、その内容を生成したり書き換えたりする責任は負いません。

混同を避けるために：Real IP の伝達はプロキシアーキテクチャにおける送信元識別の問題であり、カスタム Header はアプリケーションが自ら定義する業務データです。両者は責任を負う層も設定方法も異なります。

導入時に見落としやすいその他の事項

オリジン設定の注意点

• HTTP リクエストには正しい Host Header を保持する必要があります。そうしないと、オリジンの仮想ホストが対象サービスを判別できない可能性があります。
• SDK のノードは動的にスケジューリングされるため、固定ノード IP のホワイトリストだけでオリジンを制限すべきではありません。オリジンのファイアウォールポリシーは POC 段階で共同で設計する必要があります。
• ハートビートと業務のヘルスチェックはアプリケーション層で実装します。SDK が業務に代わってオリジンのサービス状態を判断することはありません。

Android の注意点

• ARM64-v8a、armeabi-v7a、x86 などのアーキテクチャと、他のサードパーティ SDK との互換性を確認する必要があります。
• 指定の ProGuard ルールを追加し、難読化によって SDK が異常動作しないようにする必要があります。

iOS の注意点

• Framework 方式で導入する場合は libz を導入する必要があります。
• ロック画面からの復帰やネットワーク切替の後は、getServerIPAndPort を再度呼び出してプロキシアドレスを取得してください。

HTTPS と証明書

• HTTPS と証明書検証のポリシーは、POC 段階で双方の技術チームが確認し、アプリの既存のセキュリティ設計に適合していることを確かめて、SSL ハンドシェイクの失敗を防ぐ必要があります。

テストと検収はどう進めるべきか

1. パケット解析ツールで、アプリの外部接続にオリジン IP が直接露出せず、プロキシアドレスが表示されることを確認する。
2. 業務システムとログで、取得したクライアント IP がプロキシノードの IP ではなく、実際のユーザーのアドレスであることを確認する。
3. Wi-Fi、4G/5G、ネットワーク切替、切断からの再接続、ロック画面とバックグラウンドからの復帰などのシナリオをテストする。
4. ログイン、長時間接続、API 応答、パケットの完全性、ロードバランシングの結果を確認する。
5. まず小規模なカナリアリリースを 2〜3 日実施し、異常ログとユーザーフィードバックを収集してから、段階的に全面リリースする。

まとめ：プロキシの責任分担を明確にしてこそ、導入はスムーズに進む

SDK セキュアアクセラレーションの核心は、保護されスケジューリング可能なプロキシチャネルを確立することであり、すべてのアプリケーション層ロジックを置き換えることではありません。Real IP、Header、ハートビート、証明書、オリジンのセキュリティポリシーは、いずれも SDK、クライアント、オリジンが共同で担う必要があります。

SDK の核心的な価値はセキュアプロキシチャネルの確立だけではなく、端末側で DNS 解決を迂回し、DNS ハイジャックが業務の接続に及ぼす影響を根本から回避することにあります。スケジューリングポリシーはリモートから即時に配信でき、アプリのリリースを待たずにルーティングを調整できます。しかし、これらの能力を十分に発揮できるかどうかは、導入段階のアーキテクチャ設計が完全かどうかにかかっており、Real IP、Header、オリジンのセキュリティポリシーはその中で最も見落とされやすい細部です。

企業が POC の前にプロトコル、オリジンアーキテクチャ、Real IP の用途、カスタム Header の要件を棚卸ししておけば、統合後になってリスク制御、ログ、認証フローとの非互換が判明する確率を大幅に下げられます。

よくある質問

オリジンが Proxy Protocol に対応している場合、どの Real IP モードを選ぶべきですか？

Proxy Protocol を優先することをお勧めします。接続層で元の送信元情報を伝達できますが、オリジンまたはロードバランサーで正しく有効化・解析されていることを確認する必要があります。

別の Header を指定して真の IP を渡すことはできますか？

SDK は真のクライアント IP の取得を支援できますが、標準でサポートする方式は Proxy Protocol、TOA、API です。SDK が任意の Header を自ら追加することはありません。アプリケーションにカスタム Header が必要な場合は、クライアントの元のリクエストで付与してください。

SDK は元の Header を削除・変更しますか？

しません。SDK はクライアントの元のリクエストに含まれる Header をそのままオリジンへ透過転送するだけで、追加、変更、削除のいずれも行いません。

なぜ接続のたびに getServerIPAndPort を再度呼び出す必要があるのですか？

プロキシアドレスは、ノードの健全性、ネットワーク品質、スケジューリングポリシーに応じて動的に調整されます。アドレスを再取得することで、すでに無効になった、あるいは適切でなくなったノードを使い続けることを避けられます。

SDK はハートビートやオリジンの健全性判断を自動で処理しますか？

しません。ハートビート機構と業務層のヘルスチェックはアプリケーション側で実装する必要があります。SDK が主に担うのはセキュアプロキシ、スケジューリング、接続の転送です。

SDK 導入後、HTTPS の証明書検証に影響はありますか？

SDK 自体が HTTPS 証明書を置き換えたり終端したりすることはなく、証明書の検証ロジックは引き続きクライアントの元のコードが処理します。ただし、オリジンが特定の送信元 IP からのアクセスのみを許可している場合は、SDK エッジノードの IP 範囲をホワイトリストに追加する必要があります（プラットフォームがリストを提供します）。具体的な証明書ポリシーは、POC 段階で双方の技術チームが共同で確認してください。

Android、iOS、PC、Flutter アプリへのSDK セキュアアクセラレーション導入を計画中の方は、ByteShield チームまでお問い合わせください。転送ルール、Real IP 方式、オリジンアーキテクチャ、カナリア検収フローの確認をお手伝いします。