【ITニュース解説】Auth Your React Mini App with Telegram: InitData + JWT Validation

Telegram Mini Appを現代のウェブアプリケーションに組み込むことは、単にアプリをウェブページに埋め込む以上の複雑な課題を伴う。特にセキュリティが重視されるアプリケーションでは、受信したリクエストが本当に公式のMini Appから送られたものか、そしてそのリクエストを発したユーザーが正しく認証されているかを確認する必要がある。この課題を解決するために、Reactをフロントエンド、PHPをバックエンドとするシステムで、Telegramから送られてくるinitDataを読み取り、その整合性と出所を検証し、さらにJWT（JSON Web Token）を抽出して呼び出し元のユーザーIDを確認する認証フローを構築する方法を理解することは重要である。

この認証の主要な課題は、ブラウザで動作するReactフロントエンドと、実際の認証ロジックを処理するPHPバックエンドという、異なる技術スタックの橋渡しにある。この橋渡しの役割を果たすのが、ユーザーがMini Appを開いたときにTelegramが渡すinitDataパラメータである。initDataには、データの暗号化された署名が含まれており、さらにユーザーの身元や権限に関する情報を含むJWTを運ぶこともできる。バックエンド側でこの署名とJWTの両方を検証することで、多層的な防御メカニズムを構築し、なりすまし攻撃を防ぎ、正規のユーザーだけが保護された操作を実行できるようにするのだ。

Telegram Mini AppのinitDataを深く理解することは、この認証フローの基礎となる。ユーザーがTelegram Mini Appを起動すると、Telegramはディープリンクと呼ばれる特別なURLをユーザーに送信し、このURLにはinitDataクエリパラメータが含まれている。このinitDataは、base64エンコードされた文字列であり、その中にはいくつかの重要な情報が格納されている。

第一に、ユーザー識別子（id）が含まれる。これはMini Appのエコシステム内でユーザーに割り当てられた一意の数値IDである。第二に、init dataとして、セッショントークン、JWT、またはその他のメタデータなど、任意のキーと値のペアが含まれることがある。そして最も重要なのが、署名である。この署名は、initDataの非署名部分に対して計算されたHMAC-SHA256ダイジェストであり、Mini Appの秘密鍵で署名されている。この署名があることで、データが改ざんされていないこと、そして公式のTelegramクライアントから送信されたものであることを証明できる。

具体的なinitDataの構造は、ユーザーIDやJWTなどの情報に加えて、秘密鍵で署名されたデータが含まれる形式となる。バックエンドは、この署名を使ってinitDataが本当に登録されたTelegram Mini Appから来たものかを独立して検証できる。もし署名が一致しなければ、そのリクエストは改ざんされたか、偽造されたものと判断され、即座に拒否されるべきである。

署名検証に加えて、多くの実装ではinitDataの内部にJWTを埋め込んでいる。JWTは通常、sub（ユーザーID）、exp（有効期限）、そしてオプションでroleやpermissions（役割や権限）といったクレーム（主張）を含む構造化された情報である。バックエンドでこのJWTをデコードし、さらに検証することで、セキュリティに別の層を追加できる。たとえ攻撃者が何らかの方法で署名を偽造できたとしても（これは秘密鍵なしでは不可能だが）、彼らが持っているJWTには必要な権限が含まれていないため、特権的な操作にアクセスすることはできない。これにより、セキュリティがさらに強化される。

バックエンドでのinitDataとJWTの検証プロセスは、いくつかのステップで行われる。まず、PHPエンドポイントはフロントエンドから送信されたinitDataを含むリクエストパラメータを受信する。例えば、/api/miniapp/authへのPOSTリクエストとして、initDataとアプリケーションの秘密鍵が送られてくることを想定する。

バックエンドが最初に行うべきことは、受信したinitDataをデコードし、そこに含まれるすべての情報を解析することである。この際、最も重要で最初に行われるべきセキュリティチェックは、initDataの署名検証である。バックエンドは、自身が保持しているMini Appの秘密鍵を使用して、initDataの非署名部分から署名を再計算し、受信した署名と比較する。もし計算された署名が受信した署名と一致しない場合、そのinitDataは信頼できないものと判断され、リクエストは拒否される。これは、データが改ざんされたか、または不正なソースから来たことを意味するからである。

署名検証に成功し、initDataが信頼できると判断された後、次にinitData内に埋め込まれているJWTの検証を行う。JWTは、それ自体が署名されているため、バックエンドはその署名を検証し、JWTが改ざんされていないこと、有効期限が切れていないこと、そして信頼できる発行元から発行されたものであることを確認する。JWTが有効であれば、そこからユーザーIDや付与された役割、権限などの情報を安全に抽出し、その後のアプリケーションロジックに利用できる。例えば、特定のユーザーにのみ許可された操作である場合、JWTから抽出した権限情報に基づいて、その操作を許可するかどうかを判断する。

このように、Telegram Mini Appの認証フローでは、initDataの署名検証とJWTの検証という二段階のセキュリティチェックを組み合わせることで、強固な防御メカニズムを構築している。これにより、リクエストの出所が正当であることと、リクエストを発したユーザーの身元および権限が確実に認証されていることを保証し、現代のセキュアなウェブアプリケーション開発において不可欠なセキュリティ要件を満たすことができるのである。システムエンジニアを目指す上で、このような多層防御の考え方と具体的な実装方法は、非常に重要な知識となる。