Introduction

If you have encountered the error "Consider defining a bean of type 'org.springframework.security.oauth2.client.registration.ReactiveClientRegistrationRepository' in your configuration," you are not alone. This is one of the most common Spring Boot startup failures when integrating OAuth2 with a reactive (WebFlux) application. It means Spring's dependency injection container cannot find a bean that implements ReactiveClientRegistrationRepository, and your security configuration or an auto-configured component requires one.

This article explains what the repository does, why the error occurs, and how to fix it with working configuration examples.

What Is ReactiveClientRegistrationRepository?

ReactiveClientRegistrationRepository is the reactive counterpart of ClientRegistrationRepository in Spring Security's OAuth2 client module. It stores ClientRegistration objects, each of which holds the details needed to perform an OAuth2 flow: client ID, client secret, authorization URI, token URI, scopes, and redirect URI.

In a WebFlux application, all I/O should be non-blocking. The reactive version of the repository returns Mono<ClientRegistration> instead of a plain ClientRegistration, fitting naturally into the reactive pipeline.

Why the Error Occurs

Spring Boot auto-configures a ReactiveClientRegistrationRepository bean when it finds spring.security.oauth2.client.registration.* properties in your configuration. The error appears when one of these conditions is true:

1. You added spring-boot-starter-oauth2-client to your dependencies but did not provide any client registration properties.
2. Your application.yml or application.properties has a typo in the property path.
3. You are using a custom security configuration that references the repository, but you removed or never added the auto-configuration properties.

Fixing the Error with Application Properties

The simplest fix is to define at least one client registration in your application.yml.

1spring:
2  security:
3    oauth2:
4      client:
5        registration:
6          google:
7            client-id: your-client-id
8            client-secret: your-client-secret
9            scope: openid, profile, email
10        provider:
11          google:
12            authorization-uri: https://accounts.google.com/o/oauth2/v2/auth
13            token-uri: https://oauth2.googleapis.com/token
14            user-info-uri: https://openidconnect.googleapis.com/v1/userinfo

Spring Boot reads these properties at startup and automatically creates an InMemoryReactiveClientRegistrationRepository bean. No additional Java configuration is needed for this approach.

Defining the Bean Manually

When you need more control, for example loading registrations from a database or a remote config service, you can define the bean explicitly in a configuration class.

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import org.springframework.security.oauth2.client.registration.ClientRegistration;
4import org.springframework.security.oauth2.client.registration.InMemoryReactiveClientRegistrationRepository;
5import org.springframework.security.oauth2.client.registration.ReactiveClientRegistrationRepository;
6import org.springframework.security.oauth2.core.AuthorizationGrantType;
7
8@Configuration
9public class OAuth2ClientConfig {
10
11    @Bean
12    public ReactiveClientRegistrationRepository clientRegistrationRepository() {
13        ClientRegistration registration = ClientRegistration
14            .withRegistrationId("github")
15            .clientId("your-client-id")
16            .clientSecret("your-client-secret")
17            .authorizationGrantType(AuthorizationGrantType.AUTHORIZATION_CODE)
18            .redirectUri("{baseUrl}/login/oauth2/code/{registrationId}")
19            .authorizationUri("https://github.com/login/oauth2/authorize")
20            .tokenUri("https://github.com/login/oauth2/access_token")
21            .userInfoUri("https://api.github.com/user")
22            .userNameAttributeName("login")
23            .clientName("GitHub")
24            .build();
25
26        return new InMemoryReactiveClientRegistrationRepository(registration);
27    }
28}

This explicit approach is useful when you need to register multiple providers programmatically or pull credentials from a secrets manager like AWS Secrets Manager or HashiCorp Vault.

Using the Repository in a WebFlux Security Configuration

Once the bean exists, you can wire it into your security filter chain.

1import org.springframework.context.annotation.Bean;
2import org.springframework.context.annotation.Configuration;
3import org.springframework.security.config.web.server.ServerHttpSecurity;
4import org.springframework.security.web.server.SecurityWebFilterChain;
5
6@Configuration
7public class SecurityConfig {
8
9    @Bean
10    public SecurityWebFilterChain securityFilterChain(ServerHttpSecurity http) {
11        return http
12            .authorizeExchange(exchanges -> exchanges
13                .pathMatchers("/public/**").permitAll()
14                .anyExchange().authenticated()
15            )
16            .oauth2Login(oauth2 -> {})
17            .build();
18    }
19}

Spring will automatically inject the ReactiveClientRegistrationRepository into the OAuth2 login configuration. You do not need to pass it manually.

Common Pitfalls

1. Mixing servlet and reactive dependencies. If your project includes both spring-boot-starter-web and spring-boot-starter-webflux, Spring Boot defaults to servlet mode. The reactive repository will not be auto-configured. Remove spring-boot-starter-web if you intend to run a WebFlux application.
2. Forgetting the registration ID. Every ClientRegistration must have a unique registrationId. This ID is used in redirect URIs and in the repository lookup. Omitting it causes a build-time error on the ClientRegistration.Builder.
3. Storing secrets in plain text. Never commit client-secret values to version control. Use environment variables, Spring Cloud Config with encryption, or a secrets manager. You can reference environment variables in application.yml with ${GITHUB_CLIENT_SECRET}.
4. Using the wrong repository type. ClientRegistrationRepository (non-reactive) works with Spring MVC. ReactiveClientRegistrationRepository works with Spring WebFlux. Using the wrong one produces a bean-not-found error that can be confusing, because both have similar names.

Summary

The "consider defining a bean" error for ReactiveClientRegistrationRepository is a configuration issue, not a code bug. It is resolved either by providing OAuth2 client properties in application.yml (which triggers auto-configuration) or by defining the bean manually in a @Configuration class. Make sure your project uses the reactive web starter, keep secrets out of source control, and verify that each registration has a unique ID. With these steps, the error disappears and your reactive OAuth2 flow works as expected.