Telegram Login for Spring Security

This project provides seamless integration of the Telegram Login Widget with Spring Security. It includes a Spring Boot starter for quick setup and dedicated Spring Security configurers for both Servlet and WebFlux applications.

Features

• Spring Security Integration: Native support for Telegram authentication in the Spring Security filter chain.
• Servlet and WebFlux Support: Comprehensive support for both traditional MVC and modern reactive applications.
• Spring Boot Auto-configuration: Automatic setup of security filters and validators with minimal configuration.
• Data Integrity Validation: Built-in HMAC-SHA256 validation of data received from Telegram.
• Expiration Check: Automatic validation of auth_date to prevent replay attacks (default 24h).
• User Enrichment & Authorities: Plug in TelegramUserService / ReactiveTelegramUserService to map Telegram users to your own principals and grant roles.
• Extensible Architecture: Custom validators and converters can be easily plugged in. Supports custom TelegramPrincipal implementations.

Prerequisites

• Java 17 or higher
• Spring Boot 4.0.2 or higher

Installation

Gradle

dependencies {
    implementation("io.github.razornd.telegramlogin:spring-boot-starter-telegram-login:0.3.0")
}

Maven

<dependency>
    <groupId>io.github.razornd.telegramlogin</groupId>
    <artifactId>spring-boot-starter-telegram-login</artifactId>
    <version>0.3.0</version>
</dependency>

Quick Start (Spring Boot)

1. Add the starter to your project.

2. Configure your Telegram Bot Token in application.yml:

   telegram:
     login:
       bot-token: YOUR_BOT_TOKEN

3. (Optional) If you have a custom security configuration, you can use the provided configurers:

   Spring MVC (Servlet)

   Use TelegramLoginConfigurer:

   @Configuration
   @EnableWebSecurity
   public class SecurityConfig {
   
       @Bean
       public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
           http.authorizeHttpRequests(authorize -> authorize
                       .requestMatchers("/login").permitAll()
                       .anyRequest().authenticated()
               )
               .with(new TelegramLoginConfigurer<>(), telegram -> telegram
                       .botToken("YOUR_BOT_TOKEN")
               )
               .exceptionHandling(ex -> ex.authenticationEntryPoint(new LoginUrlAuthenticationEntryPoint("/login")));
           return http.build();
       }
   }

   Spring WebFlux (Reactive)

   Use TelegramLoginServerSecurityConfigurer:

   @Configuration
   @EnableWebFluxSecurity
   public class SecurityConfig {
   
       @Bean
       public SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http) {
           return telegramLogin(http.authorizeExchange(exchanges -> exchanges
                           .pathMatchers("/login").permitAll()
                           .anyRequest().authenticated()
                   ),
                   telegram -> telegram.botToken("YOUR_BOT_TOKEN")
           )
           .exceptionHandling(ex -> ex.authenticationEntryPoint(new RedirectServerAuthenticationEntryPoint("/login")))
           .build();
       }
   }

4. Add the Telegram Login Widget to your login page:

   <script async src="https://telegram.org/js/telegram-widget.js?22" 
        data-telegram-login="<YOUR-BOT-NAME>" 
        data-size="large" 
        data-auth-url="/login/telegram">
   </script>

Configuration Properties

The following properties can be used to configure the Telegram Login integration:

Property	Description	Default
telegram.login.bot-token	Your Telegram Bot token used for hash validation.	-

Custom User Service

If you want to map a Telegram user to your local domain model or add authorities, implement one of the user services and register it via the configurer.

Spring MVC (Servlet)

@Bean
TelegramUserService telegramUserService() {
    return user -> new MyTelegramPrincipal(user, List.of(new SimpleGrantedAuthority("ROLE_USER")));
}

@Bean
SecurityFilterChain securityFilterChain(HttpSecurity http, TelegramUserService userService) throws Exception {
    http.authorizeHttpRequests(authorize -> authorize
                .requestMatchers("/login").permitAll()
                .anyRequest().authenticated()
        )
        .with(new TelegramLoginConfigurer<>(), telegram -> telegram
                .botToken("YOUR_BOT_TOKEN")
                .userService(userService)
        )
        .exceptionHandling(ex -> ex.authenticationEntryPoint(new LoginUrlAuthenticationEntryPoint("/login")));
    return http.build();
}

Spring WebFlux (Reactive)

@Bean
ReactiveTelegramUserService reactiveTelegramUserService() {
    return user -> Mono.just(new MyTelegramPrincipal(user, List.of(new SimpleGrantedAuthority("ROLE_USER"))));
}

@Bean
SecurityWebFilterChain springSecurityFilterChain(ServerHttpSecurity http,
                                                 ReactiveTelegramUserService userService) {
    return telegramLogin(http.authorizeExchange(exchanges -> exchanges
                    .pathMatchers("/login").permitAll()
                    .anyRequest().authenticated()
            ),
            telegram -> telegram
                    .botToken("YOUR_BOT_TOKEN")
                    .userService(userService)
    )
    .exceptionHandling(ex -> ex.authenticationEntryPoint(new RedirectServerAuthenticationEntryPoint("/login")))
    .build();
}

How it Works

1. The user clicks the Telegram Login Widget on your site.
2. Telegram redirects the user back to your site with authentication data as query parameters (id, first_name, last_name, username, photo_url, auth_date, hash).
3. TelegramAuthenticationConverter (or ReactiveTelegramAuthenticationConverter for WebFlux) extracts this data and creates a TelegramAuthenticationToken, extracting the hash separately for validation.
4. TelegramAuthenticationProvider (or ReactiveTelegramAuthenticationManager for WebFlux) validates the token:
   • HashValidator verifies the HMAC-SHA256 signature using your bot token and the hash from the token's credentials.
   • AuthDateExpirationValidator ensures the data is fresh.
5. If valid, a TelegramPrincipal is loaded (default: TelegramUser) and its authorities are propagated into TelegramAuthentication.

Samples

• samples/mvc-sample: A complete working example of a Spring Boot MVC application.
• samples/webflux-sample: A complete working example of a Spring Boot WebFlux application.

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.

---

Developed by Daniil Razorenov

© 2026 Daniil Razorenov