From 0b736230cd657d4ab04bebc68aff8e3ce803ac67 Mon Sep 17 00:00:00 2001 From: kyy Date: Thu, 15 Jan 2026 13:23:26 +0900 Subject: [PATCH] =?UTF-8?q?=EC=9E=91=EC=97=85=20=EA=B3=BC=EC=A0=95=20?= =?UTF-8?q?=EB=B0=8F=20=EB=A1=9C=EC=A7=81=20=EC=84=A4=EB=AA=85?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/wordpress_sso_integration.md | 83 +++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) create mode 100644 docs/wordpress_sso_integration.md diff --git a/docs/wordpress_sso_integration.md b/docs/wordpress_sso_integration.md new file mode 100644 index 0000000..723a751 --- /dev/null +++ b/docs/wordpress_sso_integration.md @@ -0,0 +1,83 @@ +# WordPress SSO 플러그인: 구현 및 동작 원리 + +이 문서는 Baron SSO와 WordPress를 연동하는 플러그인의 상세한 구현 과정과 핵심 동작 로직을 설명합니다. + +## 1. 프로젝트 목표 및 결과물 + +**목표:** 외부 SSO 인증을 통해 WordPress 사이트에 별도의 회원가입이나 로그인 절차 없이 자동으로 사용자를 인증하고, 실제 제품 데모처럼 보이는 세련된 UI/UX를 제공하는 WordPress 플러그인을 개발합니다. + +**핵심 결과물:** +- 팝업창을 이용한 비동기 방식의 SSO 로그인 연동 +- JWT `sub` 클레임을 이용한 안정적인 사용자 식별 및 자동 회원가입 +- WordPress Hook을 활용하여 최소한의 코드로 핵심 기능 및 UI 구현 + +--- + +## 2. 핵심 로그인 플로우 (Sequence Diagram) + +```mermaid +sequenceDiagram + actor User + participant WP Frontend (JS) + participant SSO Service (Popup) + participant WP Backend (PHP) + + User->>WP Frontend (JS): "Baron SSO 로그인" 버튼 클릭 + WP Frontend (JS)->>SSO Service (Popup): window.open() 팝업 실행 + SSO Service (Popup)-->>User: 로그인 UI 표시 + User->>SSO Service (Popup): 아이디/패스워드 입력 및 로그인 + SSO Service (Popup)->>SSO Service (Popup): 인증 처리 및 JWT 생성 + SSO Service (Popup)->>WP Frontend (JS): postMessage로 JWT 전송 + Note right of SSO Service (Popup): 팝업창 닫힘 + WP Frontend (JS)->>WP Frontend (JS): JWT 수신 후, `?token=[JWT]` 파라미터와 함께 페이지 새로고침 + + WP Frontend (JS)->>WP Backend (PHP): 페이지 요청 (GET /?token=...) + WP Backend (PHP)->>WP Backend (PHP): `init` hook에서 `token` 파라미터 감지 + WP Backend (PHP)->>WP Backend (PHP): JWT 디코딩하여 `sub` 추출 + WP Backend (PHP)->>WP Backend (PHP): `sub` 값으로 사용자 조회 (usermeta) + alt 사용자 없음 + WP Backend (PHP)->>WP Backend (PHP): 신규 사용자 생성 (wp_create_user) + WP Backend (PHP)->>WP Backend (PHP): `sso_subject_id` 메타 정보 저장 + end + WP Backend (PHP)->>WP Frontend (JS): 로그인 쿠키 생성 후 `token` 제거된 URL로 리다이렉트 + + WP Frontend (JS)->>WP Backend (PHP): 최종 페이지 요청 (GET /) + WP Backend (PHP)-->>WP Frontend (JS): 로그인된 페이지 렌더링 + WP Frontend (JS)-->>User: 로그인 완료된 화면 표시 +``` + +--- + +## 3. 상세 구현 내용 + +### A. 프론트엔드 (JavaScript) + +- **`sso_add_popup_script` 함수 (`wp_footer` hook)** + - **팝업 실행:** `openSsoPopup` 함수는 `window.open`을 사용해 정해진 크기의 팝업창을 화면 중앙에 띄웁니다. + - **토큰 수신:** `window.addEventListener('message', ...)`를 통해 다른 창으로부터 메시지를 안전하게 수신합니다. SSO 팝업창에서 `postMessage`로 보낸 데이터가 `type: 'LOGIN_SUCCESS'` 이고 `token`이 포함된 객체인지 검증합니다. + - **페이지 리로드:** 수신한 토큰을 쿼리 파라미터로 추가하여 현재 페이지를 다시 로드합니다. 이 리로드 과정이 백엔드 로직을 트리거하는 핵심 열쇠입니다. + +### B. 백엔드 (PHP) + +- **`sso_handle_jwt_login` 함수 (`init` hook)** + - WordPress가 초기화되는 시점에 실행되어, `$_GET['token']` 파라미터의 존재 여부를 가장 먼저 확인합니다. 이 방식을 통해 다른 어떤 콘텐츠보다 먼저 로그인 로직이 실행되도록 보장합니다. +- **`sso_process_jwt_and_login` 함수** + - **JWT 파싱:** 전달받은 JWT를 `.` 기준으로 분리하고, 두 번째 부분(Payload)을 Base64 디코딩하여 사용자 정보를 담은 객체를 얻습니다. + - **사용자 식별:** 기존의 이메일 방식 대신, `sub` 클레임을 `sanitize_text_field`로 안전하게 처리한 후 `get_users` 함수와 `meta_query`를 사용해 `sso_subject_id`와 일치하는 사용자를 찾습니다. 이 방식은 이메일이 없거나 변경되어도 동일 사용자를 식별할 수 있게 해줍니다. + - **자동 회원가입:** 일치하는 사용자가 없으면 `wp_create_user`를 호출합니다. 이때 WordPress의 필수 필드인 이메일은 `사용자명@sso.local`과 같이 고유한 가상 주소로 채워줍니다. + - **메타 데이터 저장:** 신규 생성된 사용자의 경우, `update_user_meta`를 통해 `sso_subject_id`를 저장해두어 다음 로그인 시 동일 사용자로 인식할 수 있게 합니다. + - **로그인 실행:** `wp_set_current_user`와 `wp_set_auth_cookie`를 통해 WordPress의 표준 로그인 상태를 만듭니다. + +### C. UI/UX 개선 + +- **`sso_custom_styles` 함수 (`wp_head` hook)** + - 하나의 함수에서 모든 CSS를 `