OAuth2 Social Login Integration

Relevant source files

The following files were used as context for generating this wiki page:

• src/main/java/org/example/coding_convention/config/oauth/OAuth2AuthenticationSuccessHandler.java
• src/main/java/org/example/coding_convention/user/service/OAuth2UserService.java
• src/main/java/org/example/coding_convention/config/SecurityConfig.java
• src/main/resources/application.yml
• src/main/java/org/example/coding_convention/user/model/User.java
• src/main/java/org/example/coding_convention/user/model/UserDto.java

The OAuth2 Social Login Integration in the PhanesEditor-BE project provides a seamless authentication mechanism using third-party identity providers, specifically Kakao. This system allows users to authenticate without manual registration by leveraging their social media accounts, which are then mapped to internal user entities.

The integration is built upon Spring Security's OAuth2 client module, handling the full lifecycle from the initial authorization request to JWT token issuance upon successful authentication. Once authenticated, the system issues a secure HttpOnly cookie containing a JWT for subsequent stateful interactions.
Sources: src/main/java/org/example/coding_convention/config/SecurityConfig.java:68-75, src/main/java/org/example/coding_convention/config/oauth/OAuth2AuthenticationSuccessHandler.java:27-40

System Architecture and Configuration

The OAuth2 integration is configured within the application's security layer and property files. It defines the specific providers, credentials, and endpoints required for the handshake with external authorization servers.

OAuth2 Client Configuration

The system uses YAML-based configuration to define the Kakao provider and client registration details, including client IDs and redirect URIs.

Property	Description	Source
client-id	Unique identifier provided by the social platform	application.yml:8
client-secret	Secret key for server-to-server authentication	application.yml:9
authorization-grant-type	Set to authorization_code for the standard OAuth2 flow	application.yml:11
redirect-uri	The URI the user is sent to after authorization	application.yml:12
user-name-attribute	The attribute used as the unique identifier (set to id)	application.yml:22

Security Filter Chain Integration

The SecurityConfig class registers the OAuth2 login functionality. It specifies the custom user service and the success handler that executes after the identity provider validates the user.

http.oauth2Login(config -> {
            config.userInfoEndpoint(
                    endpoint -> endpoint.userService(oAuth2UserService)
            );
            config.successHandler(oAuth2AuthenticationSuccessHandler);
        }
);

Sources: src/main/java/org/example/coding_convention/config/SecurityConfig.java:68-75

Authentication Data Flow

The authentication process follows a standard sequence involving the User Interface, the Backend Server, and the Social Platform (Kakao).

Sequence Diagram: Social Login Flow

The following diagram illustrates how the system processes a social login request, from user authorization to JWT cookie issuance.

Core Components

OAuth2UserService

This service extends DefaultOAuth2UserService to process the user information returned by the provider. It extracts the nickname from the properties and uses the platform's unique id as the email identifier in the local database.

• Logic: It checks if a user with the provided id already exists. If not, it builds and saves a new User entity with a placeholder password.
• Mapping: The method loadUser converts the provider attributes into a local UserDto.AuthUser object.
  Sources: src/main/java/org/example/coding_convention/user/service/OAuth2UserService.java:18-43

OAuth2AuthenticationSuccessHandler

Once the user is successfully authenticated, this component handles the finalization of the session.

1. JWT Generation: It retrieves the user details (email, idx, nickname) and generates a JWT token using JwtUtil.
2. Cookie Management: It creates a cookie named SJB_AT with the following attributes:
   • Path=/
   • HttpOnly and Secure
   • SameSite=None
   • Max-Age=24 Hours
3. Redirection: Redirects the user to the frontend success route: https://www.gomorebi.kro.kr/oauth2/success.
   Sources: src/main/java/org/example/coding_convention/config/oauth/OAuth2AuthenticationSuccessHandler.java:27-41

User Data Model

Socially authenticated users are stored in the same users table as local users but are distinguished by their platform type.

Database Schema (Users Table)

Field	Type	Constraints	Description
idx	INT	PRIMARY KEY	Internal auto-increment ID
email	VARCHAR(120)	UNIQUE	Stores the Social ID for OAuth users
platform	ENUM	NOT NULL	Values: LOCAL, KAKAO, GOOGLE
platform_key	VARCHAR(200)	NULLABLE	Unique identifier from the platform
enabled	BOOLEAN		Account status (set to true for OAuth)

Sources: src/main/resources/data.sql:40-55, src/main/java/org/example/coding_convention/user/model/User.java:54-58

Class Relationship Diagram

The following diagram shows the relationship between the DTO used during authentication and the User entity.

Conclusion

The OAuth2 Social Login Integration provides a robust bridge between external identity providers and the PhanesEditor internal security context. By implementing a custom OAuth2UserService and AuthenticationSuccessHandler, the system ensures that social users are correctly persisted and granted secure access via JWT cookies, maintaining compatibility with the project's broader authorization requirements.