Skip to main content

Sign in with Telegram

XLADA can let an administrator into the panel through a Telegram account. Then no password is needed: the panel sends you to the Telegram page and, after confirmation, issues a regular JWT token. This is convenient for daily work and protects against password guessing.

Telegram sign-in is administrator-only sign-in for the panel. It has nothing to do with subscription users and is configured separately from the notifications bot.

What you need​

Setup lives in the panel, under Settings → Authentication → Telegram OAuth2. You will need four values:

FieldWhat it is
Enabledthe provider switch
Client IDTelegram application identifier
Client SecretTelegram application secret
Frontend Domainpanel domain without https://, for example panel.example.com
Allowed IDslist of numeric Telegram IDs of administrators

Client ID and Client Secret are issued by Telegram for your bot — they are separate data, not the TELEGRAM_BOT_TOKEN. The panel domain must be a real FQDN: the panel builds the callback address from it, and it must match what is registered for the bot.

The callback address you need to allow for the bot:

https://panel.example.com/api/auth/oauth2/callback/telegram
tip

Copy the callback address in full, together with /api/auth/oauth2/callback/telegram. If you specify only the domain, Telegram cannot return you to the panel.

In Allowed IDs, add the numeric IDs of administrators. The list is required: while it is empty, the provider cannot be enabled, and sign-in will not work for anyone. An ID is a number, not a username.

warning

If at least one of the fields is not filled in — Client ID, Client Secret, or Frontend Domain — the panel will not enable Telegram OAuth2. Save the settings and test sign-in right away so you do not lock yourself out.

How sign-in works​

  1. You click sign in with Telegram, and the panel opens the Telegram authorization page.
  2. The panel sends state and a PKCE check (code_verifier, method S256); the request uses the openid, profile, and telegram:bot_access scopes.
  3. Telegram returns a code to the callback address — the very /api/auth/oauth2/callback/telegram.
  4. The panel verifies state and the provider, exchanges the code for a token, and reads the numeric user ID from the ID token.
  5. If the ID is in Allowed IDs, the panel issues a super-administrator token and records the successful sign-in in the log.
note

After confirmation, the first administrator (super admin) signs in to the panel. Other administrators do not sign in through Telegram — this is intentional.

Limitations​

  • The provider works over HTTPS only: the panel does not start without a reverse proxy with TLS anyway.
  • Frontend Domain is set without a scheme and without a path. For local debugging, localhost and 127.0.0.1 are allowed.
  • Allowed IDs is the only access filter. If the list is empty or contains an extra ID, the wrong person can sign in.
  • The provider can be enabled together with the password and other sign-in methods — they do not conflict.

Security​

The panel protects sign-in with several mechanisms:

  • state is stored in Valkey and lives for a limited time — a Telegram response cannot be forged without it;
  • PKCE is used, so an intercepted code cannot be turned into a token;
  • access is decided by the ID list, not by an email address or a name;
  • failed sign-in attempts are recorded with the service.login_attempt_failed event and go to Telegram and webhooks;
  • the password is never included in such notifications.
danger

Client Secret is a full-fledged secret. It is stored in the panel settings and is never exposed in plain text. Do not publish it, do not forward it in messengers, and do not keep it in a repository. If it leaks, change the secret in Telegram and in the settings.

If you disabled password sign-in and lost access to Telegram, the rescue CLI will help you get back in: it can enable password sign-in again.

What's next​