Login com Telegram via OIDC: Desvendando o Fluxo do oauth.telegram.org com Python
Explore o novo fluxo de login do Telegram utilizando OpenID Connect (OIDC) e aprenda a implementá-lo em Python. Este artigo detalha o processo, desde a configuração do bot até a validação de tokens JWT, oferecendo um guia prático para desenvolvedores.
MundiX News·13 de maio de 2026·9 min de leitura·👁 11 views
O login via Telegram passou por uma transformação significativa, migrando de um sistema baseado em HMAC para um fluxo OpenID Connect (OIDC) robusto, utilizando oauth.telegram.org. Se você se deparou com tutoriais antigos que mencionam HMAC, /setdomain no BotFather e campos de usuário brutos no callback, é hora de esquecê-los. A abordagem moderna é mais padronizada e segura, alinhando o Telegram com outros provedores de identidade OIDC.
O novo fluxo OIDC oferece diversas vantagens. O Telegram agora atua como um provedor OpenID completo, com endpoints para configuração (/.well-known/openid-configuration) e chaves de assinatura pública (JWKS). O ID Token emitido é um JWT autêntico, cuja assinatura pode ser verificada usando as chaves públicas do Telegram. Isso elimina a necessidade de verificações manuais de HMAC e permite a integração com qualquer biblioteca OIDC padrão. A principal contrapartida é a exigência de HTTPS no domínio de origem e uma nova configuração no BotFather. O processo de login agora pode ocorrer de duas formas: através de uma biblioteca JavaScript (telegram-login.js) que gerencia um popup de autorização com PKCE, retornando um ID Token já validado para o backend, ou através de um fluxo de código de autorização manual, onde o backend lida diretamente com a troca de código por tokens. Este artigo foca no primeiro método, mais simples e adequado para a maioria das aplicações web.
Para implementar o login via Telegram OIDC em Python, o processo envolve algumas etapas cruciais. Primeiro, configure seu bot no BotFather, adicionando o domínio do seu aplicativo em Trusted Origins na seção Web Login. É essencial que este domínio utilize HTTPS; para testes locais, ferramentas como ngrok são indispensáveis para criar um túnel seguro. Em seguida, o backend deve ser configurado para receber o ID Token enviado pelo JavaScript do Telegram. Este token JWT precisa ser validado rigorosamente: a assinatura deve ser verificada com as chaves públicas do Telegram (obtidas via JWKS), e os claims como iss (issuer), aud (audience - seu Client ID), exp (expiration time) e iat (issued at) devem ser conferidos. Bibliotecas como PyJWT facilitam essa validação. Após a validação bem-sucedida do ID Token, o backend pode criar ou atualizar o registro do usuário e estabelecer uma sessão, seja através de cookies para páginas HTML ou emitindo tokens de acesso e refresh para APIs JSON. O código de exemplo fornecido utiliza Litestar, mas os princípios do fluxo OIDC são agnósticos à framework, podendo ser replicados em FastAPI, Django ou outras.
O fluxo de login começa com o usuário clicando em um botão "Sign In with Telegram" na sua aplicação. Isso aciona o script telegram-login.js, que abre um popup do Telegram. Dentro deste popup, o Telegram realiza o fluxo OAuth completo, incluindo PKCE, e retorna um ID Token assinado para a sua página via postMessage. O seu backend recebe este ID Token e, em seguida, realiza as verificações de segurança mencionadas. Uma vez validado, o usuário é autenticado e pode receber um cookie de sessão para navegação no site e/ou tokens de acesso e refresh para interagir com APIs. Para logins subsequentes, se um cookie de sessão válido existir, o usuário é reconhecido sem a necessidade de interagir novamente com o Telegram, proporcionando uma experiência de usuário fluida. A implementação detalhada envolve a configuração do bot no BotFather, o uso de um túnel HTTPS como ngrok, e a escrita de código Python para a validação do JWT e gerenciamento de sessão. O repositório tg-auth no GitHub oferece um exemplo prático e testado para guiar o desenvolvedor nesse processo.
🛡️⚡
Pare de pesquisar. Comece a hackear.
O MundiX é seu copiloto de pentest com IA: comandos exatos, análise de outputs e próximo passo na kill chain — em segundos.
Sem cartão para começar · Planos a partir de R$49/mês
O login via Telegram passou por uma transformação significativa, migrando de um sistema baseado em HMAC para um fluxo OpenID Connect (OIDC) robusto, utilizando oauth.telegram.org. Se você se deparou com tutoriais antigos que mencionam HMAC, /setdomain no BotFather e campos de usuário brutos no callback, é hora de esquecê-los. A abordagem moderna é mais padronizada e segura, alinhando o Telegram com outros provedores de identidade OIDC.
O novo fluxo OIDC oferece diversas vantagens. O Telegram agora atua como um provedor OpenID completo, com endpoints para configuração (/.well-known/openid-configuration) e chaves de assinatura pública (JWKS). O ID Token emitido é um JWT autêntico, cuja assinatura pode ser verificada usando as chaves públicas do Telegram. Isso elimina a necessidade de verificações manuais de HMAC e permite a integração com qualquer biblioteca OIDC padrão. A principal contrapartida é a exigência de HTTPS no domínio de origem e uma nova configuração no BotFather. O processo de login agora pode ocorrer de duas formas: através de uma biblioteca JavaScript (telegram-login.js) que gerencia um popup de autorização com PKCE, retornando um ID Token já validado para o backend, ou através de um fluxo de código de autorização manual, onde o backend lida diretamente com a troca de código por tokens. Este artigo foca no primeiro método, mais simples e adequado para a maioria das aplicações web.
Para implementar o login via Telegram OIDC em Python, o processo envolve algumas etapas cruciais. Primeiro, configure seu bot no BotFather, adicionando o domínio do seu aplicativo em Trusted Origins na seção Web Login. É essencial que este domínio utilize HTTPS; para testes locais, ferramentas como ngrok são indispensáveis para criar um túnel seguro. Em seguida, o backend deve ser configurado para receber o ID Token enviado pelo JavaScript do Telegram. Este token JWT precisa ser validado rigorosamente: a assinatura deve ser verificada com as chaves públicas do Telegram (obtidas via JWKS), e os claims como iss (issuer), aud (audience - seu Client ID), exp (expiration time) e iat (issued at) devem ser conferidos. Bibliotecas como PyJWT facilitam essa validação. Após a validação bem-sucedida do ID Token, o backend pode criar ou atualizar o registro do usuário e estabelecer uma sessão, seja através de cookies para páginas HTML ou emitindo tokens de acesso e refresh para APIs JSON. O código de exemplo fornecido utiliza Litestar, mas os princípios do fluxo OIDC são agnósticos à framework, podendo ser replicados em FastAPI, Django ou outras.
O fluxo de login começa com o usuário clicando em um botão "Sign In with Telegram" na sua aplicação. Isso aciona o script telegram-login.js, que abre um popup do Telegram. Dentro deste popup, o Telegram realiza o fluxo OAuth completo, incluindo PKCE, e retorna um ID Token assinado para a sua página via postMessage. O seu backend recebe este ID Token e, em seguida, realiza as verificações de segurança mencionadas. Uma vez validado, o usuário é autenticado e pode receber um cookie de sessão para navegação no site e/ou tokens de acesso e refresh para interagir com APIs. Para logins subsequentes, se um cookie de sessão válido existir, o usuário é reconhecido sem a necessidade de interagir novamente com o Telegram, proporcionando uma experiência de usuário fluida. A implementação detalhada envolve a configuração do bot no BotFather, o uso de um túnel HTTPS como ngrok, e a escrita de código Python para a validação do JWT e gerenciamento de sessão. O repositório tg-auth no GitHub oferece um exemplo prático e testado para guiar o desenvolvedor nesse processo.
📤 Compartilhar & Baixar
🧰 Ferramentas recomendadas
Divulgação: alguns links são patrocinados. Podemos receber comissão se você comprar — sem custo extra para você. Só indicamos o que faz sentido para a comunidade.