🔑 Telegram Unified Auth

A minimal PHP solution for authenticating users via Telegram Login Widget and Mini Apps with a single unified flow.

Overview

Telegram Unified Auth is a lightweight PHP implementation that handles Telegram authentication for both the Login Widget and Mini Apps (WebApp). It automatically validates signatures, checks expiration, detects the authentication source, and extracts user data in a unified format — all inside a single lightweight PHP class.

What This Project Offers

• Unified authentication flow for both Widget and Mini Apps
• Automatic detection of authentication source
• Caches Mini App / Widget source detection
• Supports retrieving detected auth source
• Signature verification with hash_equals
• Auth date expiration check (5 minutes)
• Stores the validated authentication payload internally
• Extracts user data via a unified API
• Application example stores user data into PHP session
• No external dependencies — only jQuery required on frontend

File Structure

index.php    # Entry point, shows login UI or user info
webapp.php   # Mini App automatic authentication
auth.php     # TelegramUnifiedAuth class
logout.php   # Session logout

How Authentication Works

1. index.php — Entry Point

• If the user is not authenticated, the page automatically detects the environment:
  • Outside Telegram → shows Telegram Login Widget
  • Inside Telegram Mini App → shows “Log in via Telegram Mini App” button
• If the user is authenticated, basic user info from the session is displayed

2. Telegram Login Widget Flow

1. User clicks the Telegram Login Widget
2. Telegram sends user data to the JavaScript callback
3. AJAX sends the data to webapp.php
4. TelegramUnifiedAuth validates the signature and expiration
5. User data is extracted from the validated payload
6. User info is stored in PHP session
7. Page reloads with user info displayed

3. Telegram Mini App (WebApp) Flow

Two methods are supported:

Manual (via button)

• User opens the site inside Telegram
• Clicks “Log in via Telegram Mini App”
• Redirects to webapp.php

Automatic (recommended)

• User opens webapp.php directly via your bot link
• Authentication happens automatically
• User is redirected back to /

Version 1.1.0

Version 1.1.0 changes the internal behavior of the authentication class.

Main improvements:

• check() now stores the normalized validated payload internally
• get() now returns user data from the last successfully validated payload
• get() no longer requires Telegram data as an argument
• Invalid or expired authentication data clears the stored payload
• Mini App / Widget source detection is cached
• is_miniapp_get() exposes the detected authentication source

Old usage:

$is_check = $auth->check($_POST['user']);
$data = $auth->get($_POST['user']);

New usage:

$is_check = $auth->check($_POST['user']);
$data = $auth->get();

Important: call get() only after successful check().

initData (Telegram Mini App)

Mini Apps provide authentication data via:

Telegram.WebApp.initData

Important:

• Data is a query string, not JSON
• Automatically converted into an array by the class
• Signature verification follows Telegram’s official documentation
• Expiration time is 5 minutes

Send it as-is via AJAX:

$.post('/webapp.php', { user: Telegram.WebApp.initData });

Session Data Format

$_SESSION['tg_user'] = [
  'id'         => int,
  'first_name' => string,
  'last_name'  => string,
  'username'   => string,
  'photo_url'  => string
];

Format is identical for both Widget and Mini App.

Security Notes

• Signature verification uses hash_equals
• Expired data is rejected
• Invalid signatures return HTTP 403
• Authentication payload is cleared after failed validation
• User data can only be retrieved after successful validation
• No third-party backend dependencies
• Frontend only requires jQuery

Requirements

• PHP 8.0+
• HTTPS (required by Telegram)
• Telegram Bot token

License & Author

MIT License — see LICENSE file

Author: Nipaa
GitHub: https://github.com/Makareene/Telegram-Unified-Auth

This implementation is intentionally minimal and readable — perfect for learning, audits, or integrating into your PHP project with a unified Telegram authentication flow.