Auth Your React Mini App with Telegram: InitData + JWT Validation

To integrate a Telegram Mini App securely into a React web application, you must verify two critical factors: the origin of the request from the official mini app, and the authenticity of the user identity within that app. This guide details an authentication flow tailored for React front-ends communicating with PHP back-ends, leveraging Telegram's initData parameter as the bridge between these two systems.

The initData parameter is crucial as it carries a cryptographic signature over the data and can also include a JWT (JSON Web Token) for additional claims. This structure allows for a multi-layered security approach: first, confirming the request's legitimacy through the signature, then extracting and validating the JWT to ensure the user's identity and permissions meet the required access levels.

Initially, the mini app is launched via a Telegram link that includes an initData query parameter. This parameter is a base64-encoded string, structured as follows:

- User identifier (id): A unique numeric ID assigned to each user within the mini app ecosystem.

- Init data: Arbitrary key-value pairs which could represent session tokens, JWTs, or other metadata.

- Signature: An HMAC-SHA256 digest calculated over the non-signature portion of the initData string, using the app's secret key. This signature ensures the data has not been altered and is indeed from the registered Telegram Mini App.

To verify the integrity and source of the incoming data, the PHP backend should:

1. Receive and decode the initData string provided in the request parameters. If the request is a POST to /api/miniapp/auth, anticipate the initData parameter being sent as part of the request body.

2. Decode the base64-encoded string to extract its components: signature, user identifier, init data, and JWT.

The signature verification step is pivotal in establishing the request's authenticity. PHP's native HMAC functions can be used to compare the computed HMAC-SHA256 digest of the decoded initData (excluding the signature) with the provided signature. If these values do not match, the request should be immediately rejected to prevent potential impersonation attacks.

Beyond the signature, the presence of a JWT within the initData offers an additional security layer. A well-formed JWT typically includes claims such as:

- sub (user identifier): Corresponds to the user's unique ID within the mini app.

- exp (expiration): Indicates when the JWT expires.

- Optional claims like role or permissions: Define the user's access rights.

Decoding and validating this JWT on the server further secures the authentication process. Even if an attacker manages to forge the signature (which is practically impossible without the secret key), they would still lack the authority to execute privileged actions because their JWT would not contain the necessary permissions.

This approach ensures that only legitimate users, verified through both request origin and JWT claims, can perform protected operations within the web application. By bridging the React front-end with the PHP back-end via Telegram's initData mechanism, you achieve a robust defense-in-depth strategy against unauthorized access and tampering. The tutorial assumes basic proficiency in React development and familiarity with PHP web frameworks, providing actionable steps to implement a secure authentication flow.