Spring Security OAuth2 login with Google and GitHub example — Complete Guide

A practical, in-depth guide to Spring Security OAuth2 login with Google and GitHub example with examples.

INTRO

Every time a new micro‑service or web app goes live, the first thing users ask for is a quick, frictionless way to sign in. Throwing together a home‑grown username/password system feels safe, but it instantly becomes a maintenance nightmare—password resets, credential leaks, and compliance headaches pile up. The real problem isn’t authentication itself; it’s the overhead of managing identities that you don’t own.

OAuth2 providers like Google and GitHub already handle the heavy lifting: they store passwords, enforce MFA, and keep security patches up to date. Spring Security makes it possible to delegate authentication to these providers with just a few lines of configuration. Yet many developers stumble over the exact steps—registering the app, wiring the ClientRegistration, handling the callback, and persisting the principal. The result is a half‑baked login flow that either breaks on refresh or leaks user data.

The guide linked below walks through a production‑ready setup from scratch. It shows how to let users pick Google or GitHub, how to map the provider’s user attributes onto your domain model, and how to keep the configuration clean and testable. If you’ve ever fought with spring-security-oauth2-client or tried to patch together a custom filter, this article will save you hours of debugging.

WHAT YOU'LL LEARN

• How to register OAuth2 clients on Google Cloud Console and GitHub Developer Settings and retrieve the necessary client IDs and secrets.
• The minimal Spring Boot configuration (application.yml, SecurityFilterChain) that enables both providers without code duplication.
• Mapping provider‑specific user attributes (email, avatar, login) to a unified OAuth2User implementation.
• Persisting or provisioning a local User entity the first time a social login occurs, using Spring Data JPA.
• Securing the callback endpoint, handling error scenarios, and customizing the post‑login redirect.
• Tips for testing the OAuth2 flow locally (using ngrok, mock providers, and Spring’s @WebMvcTest).

A SHORT CODE SNIPPET

@Configuration
@EnableWebSecurity
public class SecurityConfig {

@Bean
SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
http
.authorizeHttpRequests(auth -> auth
.requestMatchers("/", "/login**", "/error").permitAll()
.anyRequest().authenticated())
.oauth2Login(oauth -> oauth
.loginPage("/login")
.userInfoEndpoint(info -> info
.userService(customOAuth2UserService())));
return http.build();
}

@Bean
public OAuth2UserService<OAuth2UserRequest, OAuth2User> customOAuth2UserService() {
return new CustomOAuth2UserService(); // maps Google/GitHub attrs to our UserDetails
}
}

The snippet shows the core of the configuration: a SecurityFilterChain that opens the login page, enables OAuth2 for any provider defined in application.yml, and plugs in a custom OAuth2UserService to normalize the user data.

KEY TAKEAWAYS

• Delegate, don’t duplicate – Let Google and GitHub handle authentication; your app only needs to translate the returned profile into a domain object.
• Centralize provider configuration – Keep client IDs, secrets, and scopes in application.yml under spring.security.oauth2.client.registration to avoid hard‑coding values.
• Normalize user attributes early – A single OAuth2User implementation prevents scattered if (provider.equals("github")) checks throughout the codebase.
• Plan for the first‑login flow – Automatically create or link a local user record the first time a social account signs in, and store the provider key for future logins.

👉 Read the complete guide with step-by-step examples, common mistakes, and production tips:

Spring Security OAuth2 login with Google and GitHub example — Complete Guide