From 6ef68d6abd8cc15b5f263105a46539fc37cb112c Mon Sep 17 00:00:00 2001 From: Ozkan Pakdil Date: Sat, 3 Oct 2026 20:28:30 +0100 Subject: [PATCH 1/3] docs: fix OAuth2 SSO setup and sample project guidance The documented OAuth2 configuration pointed `oauth2Login` at Spring Boot Admin's own `/login` page. Because `httpBasic()` is enabled as well, Spring Security selects the HTTP-Basic entry point, so unauthenticated browser requests get a 401 challenge instead of a redirect to the identity provider, and `/login` keeps showing the local username/password form with no link to the provider. Verified by starting an Admin Server with an OIDC registration and issuing requests: `GET /` returned 401 and `/login` served the local form, while the corrected wiring returns a 302 to `/oauth2/authorization/{registrationId}` and still authenticates a client request carrying preemptive HTTP Basic credentials. Also redirect the OAuth2 sample reference away from the stale third-party `joshiste/spring-boot-admin-samples` repository (last updated in 2019) and clarify that new example projects belong in `spring-boot-admin-runtime-playground`. Refs #1195 --- .../src/site/docs/02-server/02-security.md | 8 +++-- .../05-security/10-server-authentication.md | 33 +++++++++++++++++-- .../src/site/docs/09-samples/index.md | 24 +++++++++----- 3 files changed, 51 insertions(+), 14 deletions(-) diff --git a/spring-boot-admin-docs/src/site/docs/02-server/02-security.md b/spring-boot-admin-docs/src/site/docs/02-server/02-security.md index 005947f1db3..2b38a2b0dee 100644 --- a/spring-boot-admin-docs/src/site/docs/02-server/02-security.md +++ b/spring-boot-admin-docs/src/site/docs/02-server/02-security.md @@ -134,9 +134,11 @@ credentials. :::tip When using this approach the SBA Server decides whether the user can access the registered applications. There are more -complex solutions possible (using OAuth2) to let the clients decide if the user can access the endpoints. For that -please have a look at the samples -in [joshiste/spring-boot-admin-samples](https://github.com/joshiste/spring-boot-admin-samples). +complex solutions possible (using OAuth2) to let the clients decide if the user can access the endpoints. Implement +this with your own `HttpHeadersProvider` that acquires a token and adds it as a bearer token. See +[Server Authentication](../05-security/10-server-authentication.md) for the server side and +[Actuator Security](../05-security/20-actuator-security.md) for the client side. Runnable example projects live in +[spring-boot-admin-runtime-playground](https://github.com/codecentric/spring-boot-admin-runtime-playground). ::: ### SBA Client diff --git a/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md b/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md index 1f1dc51e79f..715271eb562 100644 --- a/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md +++ b/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md @@ -436,6 +436,16 @@ spring: **Security Configuration**: +Spring Boot Admin serves its own username/password login page at `/login`, which knows nothing +about OAuth2. Do **not** configure it as the OAuth2 login page (i.e. avoid +`oauth2Login(oauth2 -> oauth2.loginPage(adminServer.path("/login")))`). That combination does not +produce a working SSO flow: because `httpBasic()` is also present, Spring Security selects the +HTTP-Basic entry point, so unauthenticated browser requests receive a `401` challenge instead of a +redirect to your identity provider, and `/login` keeps showing the local username/password form +with no link to the provider. + +Instead, leave the login page at its default and configure the entry point explicitly: + ```java @Bean public SecurityFilterChain filterChain(HttpSecurity http, @@ -450,9 +460,15 @@ public SecurityFilterChain filterChain(HttpSecurity http, .permitAll() .anyRequest().authenticated() ) - .oauth2Login(oauth2 -> oauth2 - .loginPage(adminServer.path("/login")) - ) + .oauth2Login(Customizer.withDefaults()) + // Keep HTTP-Basic so the Spring Boot Admin Client can still (de-)register itself. + // Clients send the "Authorization" header preemptively, so they never reach the + // entry point below - it only affects requests that carry no credentials at all. + .httpBasic(Customizer.withDefaults()) + .exceptionHandling(exceptions -> exceptions + .defaultAuthenticationEntryPointFor( + new LoginUrlAuthenticationEntryPoint("/oauth2/authorization/keycloak"), + AnyRequestMatcher.INSTANCE)) .logout(logout -> logout .logoutUrl(adminServer.path("/logout")) .logoutSuccessUrl(adminServer.path("/")) @@ -464,6 +480,17 @@ public SecurityFilterChain filterChain(HttpSecurity http, } ``` +The `keycloak` segment of `/oauth2/authorization/keycloak` is the registration id from the +configuration above. With the entry point in place, browsers are redirected straight to the +identity provider, while Spring Security's generated login page (shown at `/login`) still offers +a link to it. + +:::note +Without `httpBasic()` the Spring Boot Admin Client cannot register itself over the registration +API, so only drop it when your instances are picked up by service discovery instead. Used on its +own, `oauth2Login()` also redirects unauthenticated requests directly to the identity provider. +::: + --- ## Role-Based Access Control diff --git a/spring-boot-admin-docs/src/site/docs/09-samples/index.md b/spring-boot-admin-docs/src/site/docs/09-samples/index.md index 84e8178b595..531a58abbc8 100644 --- a/spring-boot-admin-docs/src/site/docs/09-samples/index.md +++ b/spring-boot-admin-docs/src/site/docs/09-samples/index.md @@ -31,7 +31,7 @@ patterns. These samples provide working examples you can use as starting points ## Repository Location -All samples are available in +The samples listed above live in the [Spring Boot Admin GitHub repository](https://github.com/codecentric/spring-boot-admin/tree/master/spring-boot-admin-samples): ``` @@ -47,6 +47,11 @@ spring-boot-admin-samples/ └── spring-boot-admin-sample-mcp/ ``` +Additional example projects covering specific use cases and infrastructure (discovery setups, proxies and similar) live +in the separate +[spring-boot-admin-runtime-playground](https://github.com/codecentric/spring-boot-admin-runtime-playground) +repository. + ## Running the Samples ### Prerequisites @@ -264,14 +269,17 @@ Update Spring Boot Admin version in parent POM and rebuild. ## Contributing -To add a new sample: +The samples in `spring-boot-admin-samples/` demonstrate core Spring Boot Admin features. New example projects for +specific use cases and infrastructure belong in +the [spring-boot-admin-runtime-playground](https://github.com/codecentric/spring-boot-admin-runtime-playground) +repository instead. + +To add a new example there: -1. Create directory under `spring-boot-admin-samples/` -2. Follow existing sample structure -3. Add `README.md` with specific instructions -4. Include `docker-compose.yml` if applicable -5. Add tests -6. Update samples documentation +1. Create a directory for your use case, following the structure of the existing examples +2. Add a `README.md` with step-by-step instructions +3. Include a `docker-compose.yml` if the example needs infrastructure +4. Add the example to the playground's `README.md` ## See Also From f7e3179025871f7148a5cb93c6fefa0f2d992912 Mon Sep 17 00:00:00 2001 From: ulrichschulte Date: Fri, 20 Nov 2026 08:26:10 +0100 Subject: [PATCH 2/3] docs: simplify OAuth2 security config per review Drop the catch-all LoginUrlAuthenticationEntryPoint and the /login permit, add CSRF exemptions for client registration, and warn against using SBA's local /login as OAuth2 login page. --- .../05-security/10-server-authentication.md | 78 +++++++++---------- 1 file changed, 36 insertions(+), 42 deletions(-) diff --git a/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md b/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md index 715271eb562..7e38084304b 100644 --- a/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md +++ b/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md @@ -436,59 +436,53 @@ spring: **Security Configuration**: -Spring Boot Admin serves its own username/password login page at `/login`, which knows nothing -about OAuth2. Do **not** configure it as the OAuth2 login page (i.e. avoid -`oauth2Login(oauth2 -> oauth2.loginPage(adminServer.path("/login")))`). That combination does not -produce a working SSO flow: because `httpBasic()` is also present, Spring Security selects the -HTTP-Basic entry point, so unauthenticated browser requests receive a `401` challenge instead of a -redirect to your identity provider, and `/login` keeps showing the local username/password form -with no link to the provider. - -Instead, leave the login page at its default and configure the entry point explicitly: - ```java @Bean public SecurityFilterChain filterChain(HttpSecurity http, AdminServerProperties adminServer) throws Exception { http - .authorizeHttpRequests(auth -> auth - .requestMatchers(PathPatternRequestMatcher.withDefaults() - .matcher(adminServer.path("/assets/**"))) - .permitAll() - .requestMatchers(PathPatternRequestMatcher.withDefaults() - .matcher(adminServer.path("/login"))) - .permitAll() - .anyRequest().authenticated() - ) - .oauth2Login(Customizer.withDefaults()) - // Keep HTTP-Basic so the Spring Boot Admin Client can still (de-)register itself. - // Clients send the "Authorization" header preemptively, so they never reach the - // entry point below - it only affects requests that carry no credentials at all. - .httpBasic(Customizer.withDefaults()) - .exceptionHandling(exceptions -> exceptions - .defaultAuthenticationEntryPointFor( - new LoginUrlAuthenticationEntryPoint("/oauth2/authorization/keycloak"), - AnyRequestMatcher.INSTANCE)) - .logout(logout -> logout - .logoutUrl(adminServer.path("/logout")) - .logoutSuccessUrl(adminServer.path("/")) - ); - - // CSRF and other configurations... - + .authorizeHttpRequests(auth -> auth + .requestMatchers(PathPatternRequestMatcher.withDefaults() + .matcher(adminServer.path("/assets/**"))) + .permitAll() + .anyRequest().authenticated() + ) + // No custom loginPage: Spring Security redirects browsers to the IdP. + .oauth2Login(Customizer.withDefaults()) + // Lets Spring Boot Admin Clients register with Basic credentials. + .httpBasic(Customizer.withDefaults()) + .logout(logout -> logout + .logoutUrl(adminServer.path("/logout")) + .logoutSuccessUrl(adminServer.path("/")) + ) + .csrf(csrf -> csrf + .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse()) + .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler()) + .ignoringRequestMatchers( + PathPatternRequestMatcher.withDefaults() + .matcher(POST, adminServer.path("/instances")), + PathPatternRequestMatcher.withDefaults() + .matcher(DELETE, adminServer.path("/instances/*")), + PathPatternRequestMatcher.withDefaults() + .matcher(adminServer.path("/actuator/**")))); + // Also add the CustomCsrfFilter from the CSRF Protection page. return http.build(); } ``` -The `keycloak` segment of `/oauth2/authorization/keycloak` is the registration id from the -configuration above. With the entry point in place, browsers are redirected straight to the -identity provider, while Spring Security's generated login page (shown at `/login`) still offers -a link to it. +:::warning +Do not set `oauth2Login(oauth2 -> oauth2.loginPage(adminServer.path("/login")))`: `/login` is Spring Boot Admin's +local username/password form and has no link to your identity provider. +::: + +Keep `httpBasic()`, otherwise Spring Boot Admin Clients cannot register with their Basic credentials. Keep the CSRF +exemptions for `POST /instances`, `DELETE /instances/*` and `/actuator/**`, otherwise client registration fails with +`401`. See [CSRF Protection](./30-csrf-protection.md). :::note -Without `httpBasic()` the Spring Boot Admin Client cannot register itself over the registration -API, so only drop it when your instances are picked up by service discovery instead. Used on its -own, `oauth2Login()` also redirects unauthenticated requests directly to the identity provider. +Browser requests (`Accept: text/html`) are redirected to the identity provider. Requests without `Accept: text/html`, +such as plain `curl` or XHR calls, get `401` by design. When a UI session expires, the UI lands on Spring Security's +generated login page, which links to the identity provider. ::: --- From e9d3ee81caa237861e435783b0e4642689ab3bde Mon Sep 17 00:00:00 2001 From: ulrichschulte Date: Fri, 20 Nov 2026 08:45:10 +0100 Subject: [PATCH 3/3] docs: fix OAuth2 snippet gaps from review With OAuth2 configured, Spring Boot no longer creates a user from spring.security.user.*, so the snippet now defines its own user bean for clients that register with Basic auth. It also registers CustomCsrfFilter. A failed CSRF check can show as 401 instead of 403 when the error page also requires login. The docs now mention both codes. When a context path is set, an expired UI session lands on SBA's own login form, not the identity provider. The docs now say so. --- .../05-security/10-server-authentication.md | 84 ++++++++++++------- .../docs/05-security/30-csrf-protection.md | 4 +- 2 files changed, 57 insertions(+), 31 deletions(-) diff --git a/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md b/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md index 7e38084304b..e3f7ffc3fbc 100644 --- a/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md +++ b/spring-boot-admin-docs/src/site/docs/05-security/10-server-authentication.md @@ -441,33 +441,55 @@ spring: public SecurityFilterChain filterChain(HttpSecurity http, AdminServerProperties adminServer) throws Exception { http - .authorizeHttpRequests(auth -> auth - .requestMatchers(PathPatternRequestMatcher.withDefaults() - .matcher(adminServer.path("/assets/**"))) - .permitAll() - .anyRequest().authenticated() - ) - // No custom loginPage: Spring Security redirects browsers to the IdP. - .oauth2Login(Customizer.withDefaults()) - // Lets Spring Boot Admin Clients register with Basic credentials. - .httpBasic(Customizer.withDefaults()) - .logout(logout -> logout - .logoutUrl(adminServer.path("/logout")) - .logoutSuccessUrl(adminServer.path("/")) + .authorizeHttpRequests(auth -> auth + .requestMatchers(PathPatternRequestMatcher.withDefaults() + .matcher(adminServer.path("/assets/**"))) + .permitAll() + .anyRequest().authenticated() + ) + // No custom loginPage: Spring Security redirects browsers to the IdP. + .oauth2Login(Customizer.withDefaults()) + // Lets Spring Boot Admin Clients register with Basic credentials. + .httpBasic(Customizer.withDefaults()) + .logout(logout -> logout + .logoutUrl(adminServer.path("/logout")) + .logoutSuccessUrl(adminServer.path("/")) + ) + .csrf(csrf -> csrf + .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse()) + .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler()) + .ignoringRequestMatchers( + PathPatternRequestMatcher.withDefaults() + .matcher(POST, adminServer.path("/instances")), + PathPatternRequestMatcher.withDefaults() + .matcher(DELETE, adminServer.path("/instances/*")), + PathPatternRequestMatcher.withDefaults() + .matcher(adminServer.path("/actuator/**")) ) - .csrf(csrf -> csrf - .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse()) - .csrfTokenRequestHandler(new CsrfTokenRequestAttributeHandler()) - .ignoringRequestMatchers( - PathPatternRequestMatcher.withDefaults() - .matcher(POST, adminServer.path("/instances")), - PathPatternRequestMatcher.withDefaults() - .matcher(DELETE, adminServer.path("/instances/*")), - PathPatternRequestMatcher.withDefaults() - .matcher(adminServer.path("/actuator/**")))); - // Also add the CustomCsrfFilter from the CSRF Protection page. + ); + + // CustomCsrfFilter: see "Custom CSRF Filter" above + http.addFilterAfter(new CustomCsrfFilter(), BasicAuthenticationFilter.class); + return http.build(); } + +// Spring Boot's UserDetailsServiceAutoConfiguration backs off once a +// ClientRegistrationRepository exists, so spring.security.user.* is ignored. +// Define the Basic-auth user for registering clients explicitly. +@Bean +public InMemoryUserDetailsManager userDetailsService(PasswordEncoder passwordEncoder) { + UserDetails client = User.withUsername("client") + .password(passwordEncoder.encode(System.getenv("SBA_CLIENT_PASSWORD"))) + .roles("CLIENT") + .build(); + return new InMemoryUserDetailsManager(client); +} + +@Bean +public PasswordEncoder passwordEncoder() { + return new BCryptPasswordEncoder(); +} ``` :::warning @@ -475,14 +497,18 @@ Do not set `oauth2Login(oauth2 -> oauth2.loginPage(adminServer.path("/login")))` local username/password form and has no link to your identity provider. ::: -Keep `httpBasic()`, otherwise Spring Boot Admin Clients cannot register with their Basic credentials. Keep the CSRF -exemptions for `POST /instances`, `DELETE /instances/*` and `/actuator/**`, otherwise client registration fails with -`401`. See [CSRF Protection](./30-csrf-protection.md). +Keep `httpBasic()` and the `userDetailsService` bean, otherwise Spring Boot Admin Clients cannot register with their +Basic credentials: with OAuth2 on the classpath, Spring Boot no longer creates a user from `spring.security.user.*`. +Keep the CSRF exemptions for `POST /instances`, `DELETE /instances/*` and `/actuator/**`, otherwise client +registration is rejected with `403` (or `401` when the error page itself requires authentication). See +[CSRF Protection](./30-csrf-protection.md). :::note Browser requests (`Accept: text/html`) are redirected to the identity provider. Requests without `Accept: text/html`, -such as plain `curl` or XHR calls, get `401` by design. When a UI session expires, the UI lands on Spring Security's -generated login page, which links to the identity provider. +such as plain `curl` or XHR calls, get `401` by design. When a UI session expires, the UI redirects to `login` relative +to the Admin Server's context path. Without a context path this is Spring Security's generated `/login` page, which +links to the identity provider. With `spring.boot.admin.context-path` set, it is Spring Boot Admin's own login form +instead; users then need to reload the UI to be redirected to the identity provider. ::: --- diff --git a/spring-boot-admin-docs/src/site/docs/05-security/30-csrf-protection.md b/spring-boot-admin-docs/src/site/docs/05-security/30-csrf-protection.md index 6241c42800f..dbe131a197a 100644 --- a/spring-boot-admin-docs/src/site/docs/05-security/30-csrf-protection.md +++ b/spring-boot-admin-docs/src/site/docs/05-security/30-csrf-protection.md @@ -478,9 +478,9 @@ server: .csrfTokenRepository(CookieCsrfTokenRepository.withHttpOnlyFalse()) ``` -### Issue: Client registration fails with 403 +### Issue: Client registration fails with 403 or 401 -**Cause**: `/instances` endpoint not exempted from CSRF. +**Cause**: `/instances` endpoint not exempted from CSRF. The `CsrfFilter` rejects the request with `403`; if the forwarded `/error` page also requires authentication, the client sees `401` instead. **Solution**: Add to `ignoringRequestMatchers`: