Keycloak과 React 연동으로 구현하는 엔드투엔드 인증 아키텍처

Context

React 클라이언트와 .NET API 간의 통합 인증 체계 필요. Keycloak 기반의 Single Sign-On 구현을 통한 보안 강화 목적. 프론트엔드에서 발급받은 토큰의 API 서버 검증 과정 필수.

Technical Solution

• OpenID Connect 기반의 Public Client 설정을 통한 브라우저 환경의 인증 흐름 구축
• Audience Mapper 설정을 통해 Access Token의 aud 클레임에 API 서버 식별자 추가 및 401 Unauthorized 오류 해결
• keycloak-js 라이브러리를 활용한 클라이언트 사이드 인증 초기화 및 토큰 관리 로직 구현
• React Context API와 Provider 패턴을 적용한 인증 상태 및 Keycloak 인스턴스의 전역 공유 구조
• onTokenExpired 콜백과 updateToken 메서드를 연동한 Access Token 자동 갱신 메커니즘 설계
• LocalStorage 기반의 Token Service를 구축하여 세션 유지 및 API 요청 시 Bearer 토큰 주입 방식 적용

Key Takeaway

클라이언트와 리소스 서버가 분리된 환경에서 토큰의 Audience 검증은 보안의 핵심이며 이를 위한 IDP 수준의 매퍼 설정이 필수적임.