Handling authentication
~8 minFive steps, all standard Spring Security: login flow, token validation, scope-based access control, and back-channel logout. Spring Security is maintained by the Spring team; ThunderID maintains this guide and the configuration below.
Add Spring's OAuth2 starters
Both are Spring Boot artifacts: client for browser login, resource-server for bearer-token APIs. Versions come from the Spring Boot BOM. Drop whichever you do not need.implementation("org.springframework.boot:spring-boot-starter-oauth2-client")implementation("org.springframework.boot:spring-boot-starter-oauth2-resource-server")
Point the app at your ThunderID issuer
These are Spring's standard OIDC properties. There are no ThunderID-specific configuration keys to learn.
spring:security:oauth2:client:registration:thunderid:client-id: ${THUNDERID_CLIENT_ID}client-secret: ${THUNDERID_CLIENT_SECRET}scope: openid, profile, emailprovider:thunderid:issuer-uri: https://acme.thunderid.devresourceserver:jwt:issuer-uri: https://acme.thunderid.dev
Declaring both client and resourceserver lets one application serve browser sessions and bearer-token API calls. Omit either block if you only need one.
Secure your endpoints
An ordinary SecurityFilterChain bean. Scopes from the ThunderID token arrive prefixed with SCOPE_.
@Configuration@EnableWebSecuritypublic class SecurityConfig {@BeanSecurityFilterChain filterChain(HttpSecurity http) throws Exception {return http.authorizeHttpRequests(auth -> auth.requestMatchers("/actuator/health").permitAll().requestMatchers("/api/billing/**").hasAuthority("SCOPE_billing:read").anyRequest().authenticated()).oauth2Login(Customizer.withDefaults()).oauth2ResourceServer(rs -> rs.jwt(Customizer.withDefaults())).build();}}
Read the authenticated principal
Inject Spring's own OidcUser for session-based flows, or Jwt for bearer-token requests. Claims map straight through.
@RestControllerpublic class ProfileController {@GetMapping("/me")public Map<String, Object> me(@AuthenticationPrincipal OidcUser user) {return Map.of("sub", user.getSubject(),"email", user.getEmail(),"org", user.getClaimAsString("org_id"));}@PreAuthorize("hasAuthority('SCOPE_billing:read')")@GetMapping("/api/billing")public Invoice billing(@AuthenticationPrincipal Jwt jwt) {return service.forTenant(jwt.getClaimAsString("org_id"));}}
Enable @PreAuthorize with @EnableMethodSecurity on any configuration class.
Receive back-channel logout
Spring Security implements OpenID Connect Back-Channel Logout. These additions to the configuration above stand up the receiving endpoint and end the matching Spring session when ThunderID posts a logout token. Register the endpoint URL as the application's back-channel logout URI in ThunderID. They need Spring Security 6.4 or later, which Spring Boot 3.4 ships.
@BeanOidcSessionRegistry oidcSessionRegistry() {return new InMemoryOidcSessionRegistry();}@BeanOidcBackChannelLogoutHandler oidcLogoutHandler(OidcSessionRegistry oidcSessionRegistry) {return new OidcBackChannelLogoutHandler(oidcSessionRegistry);}// Removes a registry entry when its servlet session ends@BeanHttpSessionEventPublisher sessionEventPublisher() {return new HttpSessionEventPublisher();}// In the SecurityFilterChain, next to oauth2Login(...):.oidcLogout(logout -> logout.backChannel(Customizer.withDefaults()))
The endpoint is /logout/connect/back-channel/thunderid, where thunderid is the registration id. Spring correlates each login's sid to the servlet session in the OidcSessionRegistry, which this example keeps in memory. Several instances need a shared OidcSessionRegistry and a shared servlet session store, such as Spring Session, since the notification can reach an instance that does not hold the session. The handler sends the JSESSIONID cookie by default; with Spring Session's SESSION cookie, call setSessionCookieName("SESSION") on the handler.
Claim mapping
How ThunderID token claims arrive on the Spring side. This is the reference you will actually reach for, since there is no separate ThunderID API surface to learn.
Requirements
Where to get help
Two projects, two places to ask.
Something wrong in this guide?
The guide and the ThunderID configuration it documents are ours. We keep it current with each Spring Boot release.
Something wrong in Spring Security?
The library itself is maintained by the Spring team. Bugs and feature requests belong on their tracker, not ours.