Skip to main content

Spring Security

Community
Integration guide

Spring Security is maintained by the Spring team, not by ThunderID. Because it already speaks OIDC, it works with ThunderID out of the box, and this guide shows the configuration. Token validation, session management, and access control are handled by Spring Security itself.

org.springframework.boot
SDK by the Spring team
Set up in 8 minutesSpring Security docs

Handling authentication

~8 min

Five 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.

1

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.

build.gradle.kts
kotlin
implementation("org.springframework.boot:spring-boot-starter-oauth2-client")
implementation("org.springframework.boot:spring-boot-starter-oauth2-resource-server")
2

Point the app at your ThunderID issuer

These are Spring's standard OIDC properties. There are no ThunderID-specific configuration keys to learn.

application.yml
yaml
spring:
security:
oauth2:
client:
registration:
thunderid:
client-id: ${THUNDERID_CLIENT_ID}
client-secret: ${THUNDERID_CLIENT_SECRET}
scope: openid, profile, email
provider:
thunderid:
issuer-uri: https://acme.thunderid.dev
resourceserver:
jwt:
issuer-uri: https://acme.thunderid.dev
Note

Declaring both client and resourceserver lets one application serve browser sessions and bearer-token API calls. Omit either block if you only need one.

3

Secure your endpoints

An ordinary SecurityFilterChain bean. Scopes from the ThunderID token arrive prefixed with SCOPE_.

SecurityConfig.java
java
@Configuration
@EnableWebSecurity
public class SecurityConfig {
@Bean
SecurityFilterChain 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();
}
}
4

Read the authenticated principal

Inject Spring's own OidcUser for session-based flows, or Jwt for bearer-token requests. Claims map straight through.

ProfileController.java
java
@RestController
public 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"));
}
}
Note

Enable @PreAuthorize with @EnableMethodSecurity on any configuration class.

5

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.

SecurityConfig.java
java
@Bean
OidcSessionRegistry oidcSessionRegistry() {
return new InMemoryOidcSessionRegistry();
}
@Bean
OidcBackChannelLogoutHandler oidcLogoutHandler(OidcSessionRegistry oidcSessionRegistry) {
return new OidcBackChannelLogoutHandler(oidcSessionRegistry);
}
// Removes a registry entry when its servlet session ends
@Bean
HttpSessionEventPublisher sessionEventPublisher() {
return new HttpSessionEventPublisher();
}
// In the SecurityFilterChain, next to oauth2Login(...):
.oidcLogout(logout -> logout.backChannel(Customizer.withDefaults()))
Note

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.

ThunderID claimSpring accessorNotes
subuser.getSubject()Stable ThunderID user identifier.
emailuser.getEmail()Present when the email scope is granted.
scopegetAuthorities()Each scope becomes a SCOPE_ authority.
org_idgetClaimAsString("org_id")Tenant context for multi-org applications.
actgetClaimAsMap("act")Present on agent tokens; identifies the acting agent.

Requirements

Spring Boot3.2 to 3.4supported
Spring Security>= 6.2supported
Java17, 21supported
Kotlin>= 1.9supported
Spring Boot 2.7 / Security 5legacyunsupported
Where to get help

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.

ThunderID LogoThunderID Logo

Product

DocsAPIsSDKs
© Copyright Linux Foundation Europe.For web site terms of use, trademark policy and other project policies please see https://linuxfoundation.eu/en/policies.