Introduction

If you are building a modern Spring application, the important architectural point is that Spring Security OAuth2 client support is the current integration path, while Spring Social is legacy technology. That means the real task is usually either migrating away from Spring Social or understanding how to replace its role with Spring Security's built-in OAuth2 login features.

The Modern Baseline

For new applications, the standard setup is based on Spring Security and Spring Boot's OAuth2 client support.

A typical dependency set looks like this:

1<dependency>
2  <groupId>org.springframework.boot</groupId>
3  <artifactId>spring-boot-starter-security</artifactId>
4</dependency>
5<dependency>
6  <groupId>org.springframework.boot</groupId>
7  <artifactId>spring-boot-starter-oauth2-client</artifactId>
8</dependency>

That gives you the framework pieces needed for provider registration, authorization redirect flow, token exchange, and authenticated user handling.

Basic OAuth2 Login Configuration

A minimal security configuration enables OAuth2 login and protects application routes.

1import org.springframework.context.annotation.Bean;
2import org.springframework.security.config.Customizer;
3import org.springframework.security.config.annotation.web.builders.HttpSecurity;
4import org.springframework.security.web.SecurityFilterChain;
5
6@Bean
7SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
8    http
9        .authorizeHttpRequests(auth -> auth
10            .requestMatchers("/", "/login**", "/error").permitAll()
11            .anyRequest().authenticated()
12        )
13        .oauth2Login(Customizer.withDefaults());
14
15    return http.build();
16}

This is the starting point for social login through providers such as GitHub, Google, or Facebook, depending on your registration setup.

Provider Registration

Client credentials and scopes are usually configured in application properties or YAML.

1spring:
2  security:
3    oauth2:
4      client:
5        registration:
6          github:
7            client-id: ${GITHUB_CLIENT_ID}
8            client-secret: ${GITHUB_CLIENT_SECRET}
9            scope: read:user,user:email

Never hardcode the secrets in source files. Use environment variables or a secrets manager.

Mapping Social Identity to a Local User

Most applications need more than successful authentication. They need to map the provider identity to a local user record.

1import org.springframework.security.oauth2.client.userinfo.DefaultOAuth2UserService;
2import org.springframework.security.oauth2.client.userinfo.OAuth2UserRequest;
3import org.springframework.security.oauth2.core.user.OAuth2User;
4import org.springframework.stereotype.Service;
5
6@Service
7public class CustomOAuth2UserService extends DefaultOAuth2UserService {
8    @Override
9    public OAuth2User loadUser(OAuth2UserRequest userRequest) {
10        OAuth2User oauthUser = super.loadUser(userRequest);
11        // map provider attributes to your local user model here
12        return oauthUser;
13    }
14}

This is the place where account linking, first-login provisioning, and attribute normalization usually happen.

Where Spring Social Fits Today

Spring Social used to fill that social-login and provider-integration role before Spring Security's OAuth2 support matured. In a modern application, Spring Social is mainly relevant as migration context.

If you already have a codebase built on Spring Social, the sensible approach is usually:

1. keep the old flow stable while migrating
2. introduce Spring Security OAuth2 login in parallel
3. move provider mapping and account-linking logic over gradually
4. remove the old integration after parity is verified

That is safer than trying a single large authentication rewrite.

The Important Non-Framework Decisions

The hardest part of social login is rarely the redirect flow. It is usually the account model.

You need to decide:

• how a social identity links to an existing local account
• whether provider email is trusted automatically
• what happens if provider attributes change later

Those are application rules, not framework defaults, and they deserve explicit design.

Common Pitfalls

The most common mistake is starting a new integration on top of Spring Social because old blog posts still mention it.

Another mistake is treating provider identity data as if it were automatically enough for safe local account linking. That policy needs to be deliberate.

It is also easy to mix authentication, provisioning, and business logic in one controller instead of keeping identity mapping in a dedicated user-service layer.

Summary

• For modern Spring applications, use Spring Security OAuth2 client support for social login.
• Treat Spring Social as legacy or migration context, not the preferred new design.
• Configure providers through Spring Boot properties and secure your client secrets.
• Implement explicit mapping from provider users to local application users.
• The difficult part is often account-linking policy, not the OAuth2 redirect itself.