pyTelegramOIDC

pyTelegramOIDC — is a modern, fully asynchronous Python library for integrating the official Telegram Login (OpenID Connect) into your web applications.

It strictly follows standard OIDC specifications, supports PKCE (Proof Key for Code Exchange), and natively extracts all user data (including phone numbers) directly from cryptographically signed ID Tokens.

Features

• Fully Async: Uses httpx for non-blocking HTTP requests.
• Secure: Validates JWT signatures automatically using Telegram's official JWKS keys.
• Pydantic Models: Strict typing for user profiles and tokens out of the box.
• Phone Number Support: Easily extract requested user phone numbers.

Installation

You can install the library via pip:

pip install pyTelegramOIDC

Note: Although you install it via pyTelegramOIDC, the module is imported as teleoidc (similar to how pyTelegramBotAPI is imported as telebot).

Quickstart (JS Widget Flow)

If you are using the official Telegram JS Popup Widget, your frontend will receive an id_token. Use teleoidc to validate it and get the user's data safely.

from teleoidc import TelegramAsyncOIDCClient

# 1. Initialize the client
client = TelegramAsyncOIDCClient(
    client_id="YOUR_BOT_ID",        # From @BotFather
    client_secret="YOUR_BOT_SECRET", # From @BotFather
    redirect_uri="https://yoursite.com/auth/callback"
)

# 2. Validate the token received from the frontend
id_token = "eyJhbGciOiJSUzI1NiIs..." # Token from Telegram JS

try:
    user = client.validate_id_token(id_token)
    
    print(f"Logged in as: {user.name} (@{user.preferred_username})")
    print(f"Telegram ID: {user.id}")
    
    if user.phone_number:
        print(f"Phone: {user.phone_number}")

except Exception as e:
    print(f"Invalid token: {e}")

Manual OAuth2 Redirect Flow

If you are doing a full backend redirect instead of the JS widget, pyTelegramOIDC provides native methods to generate auth links and exchange codes for tokens (get_auth_request and exchange_code_for_token).

License

MIT License