1. 소셜 로그인 연동 설정 개요

DXCMS 관리자 패널의 [소셜 로그인 연동 설정] 메뉴는 카카오•네이버•구글•GitHub 4개 OAuth 2.0 서비스를 사이트에 연동하여 회원이 기존 계정으로 간편하게 로그인할 수 있도록 설정하는 도구입니다. 각 서비스별 API 키를 입력하고 활성화 토글을 ON으로 설정하면 즉시 소셜 로그인 버튼이 프론트엔드에 표시됩니다.

📌  접근 경로: 관리자 대시보드 → 소셜 로그인 연동 설정 (URL: /admin/social) DB 테이블: social_accounts, settings

1.1 지원 소셜 로그인 서비스 4종

서비스	주요 사용자층	콜백 URL	개발자 콘솔
카카오	국내 카카오톡 사용자	/auth/kakao_callback	developers.kakao.com
네이버	국내 네이버 사용자	/auth/naver_callback	developers.naver.com/apps
구글	글로벌 구글 계정 사용자	/auth/google_callback	console.cloud.google.com
GitHub	개발자·기술 사용자	/auth/github_callback	github.com/settings/developers

1.2 화면 구성

영역	설명
페이지 헤더	"소셜 로그인 연동 설정" 제목과 부제목.
메시지 배너	저장 성공(초록) / 오류(빨강) 메시지.
애플리케이션 기본 URL 배너	하늘색 배너. settings 테이블의 site_url 값 표시. 각 서비스 콜백 URL 조합에 사용.
서비스 카드 그리드 (2열)	카카오·네이버·구글·GitHub 4개 카드. 각 브랜드 색상 헤더, 활성화 토글, API 키 입력 필드, 콜백 URL 안내.
[모든 소셜 설정 저장하기] 버튼	하단 제출 버튼. 4개 서비스의 모든 설정을 한 번에 저장.
소셜 연동 계정 현황	social_accounts 테이블 집계. 서비스별 연동 회원 수 통계.

1.3 OAuth 2.0 동작 원리

DXCMS 소셜 로그인은 OAuth 2.0 Authorization Code Flow를 사용합니다.
 

단계	동작	처리 파일
①	사용자가 [카카오로 로그인] 버튼 클릭	프론트엔드 UI
②	DXCMS가 OAuth 인증 URL 생성 후 해당 서비스 로그인 페이지로 리다이렉트	DxSocialAuth::getAuthUrl()
③	사용자가 소셜 서비스에서 로그인 + 권한 동의	카카오/네이버/구글/GitHub 서버
④	서비스가 DXCMS 콜백 URL로 인증 코드(code) 전달	/auth/{provider}_callback
⑤	DXCMS가 code → access_token 교환	DxSocialAuth::fetchToken()
⑥	access_token으로 사용자 정보(이메일·이름·provider_id) 조회	DxSocialAuth::fetchUserInfo()
⑦	기존 연결 계정 조회 → 이메일 매핑 → 신규 회원 생성 중 해당 처리 후 DXCMS 세션 로그인	DxSocialAuth::loginOrRegister()

2. 서비스 카드 구성

각 소셜 서비스는 하나의 카드로 표시됩니다. 카드 헤더는 각 브랜드 색상으로 구분됩니다. 활성화된 카드는 테두리에 해당 브랜드 색상의 링(ring)이 표시됩니다.

2.1 카드 헤더 — 활성화 토글

카드 상단 헤더에 서비스 아이콘•이름과 함께 활성화/비활성화 토글 스위치가 있습니다.
 

토글 ON (Active)	체크박스가 체크 상태. 헤더 우측에 "Active" 텍스트. 슬라이더가 오른쪽으로 이동. 카드 전체에 브랜드 색상 테두리 + 링 효과.
토글 OFF	체크박스 미체크. "Off" 텍스트. 슬라이더가 왼쪽에 위치. 카드 테두리는 기본 회색.
즉시 반영	토글 변경 시 JavaScript onchange 이벤트로 UI가 즉시 업데이트됩니다. [저장] 버튼 클릭 전까지 DB에는 반영되지 않습니다.
저장 키	settings 테이블의 social_{provider}_enabled. 값: "1"(ON) 또는 "0"(OFF).

2.2 API 키 입력 필드

필드명	입력 타입	저장 방식 및 특이사항
Client ID (API 키)	text	기존 저장값이 있으면 폼에 그대로 표시됩니다. 저장 키: social_{provider}_client_id.
Client Secret (시크릿)	password	보안상 폼에는 항상 빈 값으로 표시됩니다. 저장된 시크릿이 있으면 "✓ 설정됨 (변경 시에만 입력)" placeholder 표시 + 초록색 테두리. 빈 값으로 제출하면 기존 값 유지.

🔐  Client Secret 보안 처리: 시크릿 필드는 항상 빈 값으로 렌더링됩니다. 빈 값 또는 마스킹 문자(●)가 포함된 값으로 제출하면 기존 DB 저장값이 유지됩니다. 실제 시크릿은 변경 시에만 입력하세요.

2.3 OAuth 리디렉션 URI (콜백 URL)

각 카드 하단에 해당 서비스에 등록해야 하는 콜백 URL이 표시됩니다.
 

콜백 URL 형식	settings 테이블의 site_url + /auth/{provider}_callback. 예: https://mysite.com/auth/kakao_callback
[복사] 버튼	클릭 시 navigator.clipboard API로 전체 URL을 클립보드에 복사. 1.5초 후 "복사됨!"으로 변경 후 복원.
[콘솔 열기] 링크	각 서비스의 개발자 콘솔 페이지를 새 탭으로 엽니다.
중요성	이 URL을 각 서비스 개발자 콘솔에 Redirect URI(승인된 리디렉션 URI)로 정확하게 등록해야 합니다. 미등록 시 OAuth 인증이 실패합니다.

⚠️  콜백 URL은 site_url 설정값을 기준으로 생성됩니다. site_url이 정확하지 않으면 콜백 URL도 틀려집니다. 먼저 [관리자 → 기본 설정]에서 site_url을 올바르게 설정하세요.

3. 서비스별 상세 설정 가이드

3.1 카카오 로그인

대한민국 최대 메신저 서비스 카카오의 OAuth 2.0을 사용합니다.

카카오 API 키 발급 절차

1. https://developers.kakao.com/ 접속 → 로그인
2. [내 애플리케이션] → [애플리케이션 추가하기]
3. 앱 이름•사업자명 입력 후 저장
4. [앱 설정] → [앱 키]에서 REST API 키 복사 → DXCMS [Client ID] 필드에 입력
5. [제품 설정] → [카카오 로그인] → 활성화 ON
6. [Redirect URI] 등록: https://mysite.com/auth/kakao_callback
7. [동의항목] → 닉네임•이메일 필수 동의 설정 (이메일은 선택 동의 가능)
8. [보안] 탭에서 Client Secret 코드 발급 → DXCMS [클라이언트 시크릿] 필드에 입력

 

카카오 설정 항목	설명
Client ID (REST API 키)	앱 키 탭의 REST API 키. 32자리 영문소문자+숫자.
Client Secret	[보안] 탭에서 코드 활성화 후 발급. 선택 사항이지만 보안을 위해 설정 권장.
Redirect URI	/auth/kakao_callback. 카카오 로그인 메뉴의 Redirect URI에 정확히 등록.
동의항목	닉네임(필수), 이메일(선택 동의 권장). 이메일 없으면 자동 생성 이메일 사용.
플랫폼 등록	[앱 설정] → [플랫폼] → [Web] → 사이트 도메인 등록 필요.

3.2 네이버 로그인

국내 최대 포털 네이버의 OAuth 2.0을 사용합니다.

네이버 API 키 발급 절차

1. https://developers.naver.com/apps/ 접속 → 로그인
2. [Application 등록] 클릭
3. 애플리케이션 이름 입력, [사용 API]에서 "네이버 로그인" 선택
4. [환경 추가] → [PC 웹] 선택 → 서비스 URL•Callback URL 입력
5. Callback URL: https://mysite.com/auth/naver_callback
6. 등록 완료 후 [Client ID]•[Client Secret] 복사 → DXCMS에 입력

 

네이버 설정 항목	설명
Client ID	애플리케이션 등록 후 발급되는 고유 키.
Client Secret	Client ID와 함께 발급. 노출 금지.
Callback URL	API 설정 탭의 "Callback URL" 항목에 등록.
제공 정보	이름·이메일·프로필 사진 등. 동의 항목에 따라 다름.

3.3 구글 로그인

Google의 OAuth 2.0을 사용합니다. 글로벌 서비스로 외국인 사용자 유입에 효과적입니다.

구글 API 키 발급 절차

1. https://console.cloud.google.com/ 접속 → Google 계정 로그인
2. 새 프로젝트 생성 또는 기존 프로젝트 선택
3. [API 및 서비스] → [사용자 인증 정보] → [사용자 인증 정보 만들기] → [OAuth 클라이언트 ID]
4. [OAuth 동의 화면] 먼저 구성: User Type(외부), 앱 이름•지원 이메일 입력
5. [승인된 도메인]에 mysite.com 추가
6. [범위 추가]: openid, email, profile 선택
7. [사용자 인증 정보] → [OAuth 클라이언트 ID 만들기] → 애플리케이션 유형: 웹 애플리케이션
8. [승인된 리디렉션 URI] 추가: https://mysite.com/auth/google_callback
9. 생성 후 [클라이언트 ID]•[클라이언트 보안 비밀번호] 복사 → DXCMS에 입력

 

구글 설정 항목	설명
Client ID	OAuth 클라이언트 ID. ...apps.googleusercontent.com 형식.
Client Secret	클라이언트 보안 비밀번호. GOCSPX-로 시작하는 경우도 있음.
승인된 리디렉션 URI	/auth/google_callback. 정확히 등록 필요. http/https 구분.
Scope	openid email profile. DXCMS가 자동으로 scope 파라미터에 포함하여 요청.
OAuth 동의 화면 검증	외부 앱이며 테스트 단계에서는 최대 100명만 사용 가능. 실서비스는 Google에 앱 검증 요청 필요.

⚠️  구글 OAuth 동의 화면을 "테스트" 상태로 두면 Google 계정 목록에 명시적으로 추가된 사용자(최대 100명)만 로그인 가능합니다. 모든 사용자가 로그인할 수 있도록 하려면 Google의 앱 검증(게시) 절차를 완료해야 합니다.

3.4 GitHub 로그인

GitHub의 OAuth Apps를 사용합니다. 개발자•기술 커뮤니티 사이트에 적합합니다.

GitHub API 키 발급 절차

1. GitHub 로그인 → 우측 상단 프로필 → [Settings]
2. 좌측 메뉴 하단 [Developer settings] → [OAuth Apps]
3. [New OAuth App] 클릭
4. Application name•Homepage URL•Authorization callback URL 입력
5. Authorization callback URL: https://mysite.com/auth/github_callback
6. [Register application] 클릭
7. 생성 후 [Client ID] 복사 → DXCMS [Client ID] 필드에 입력
8. [Generate a new client secret] 클릭 → Secret 복사 → DXCMS [Client Secret] 필드에 입력

 

GitHub 설정 항목	설명
Client ID	OAuth App 등록 후 부여되는 20자리 영문+숫자 키.
Client Secret	[Generate a new client secret]으로 발급. 한 번만 표시되므로 즉시 복사.
Authorization callback URL	/auth/github_callback. OAuth App 생성 시 입력.
Scope	user:email. 이메일 주소 접근 권한. DXCMS가 자동으로 포함.

💡  GitHub은 이메일이 비공개인 경우 emails API를 별도로 호출하여 primary•verified 이메일을 가져옵니다. DxSocialAuth가 자동으로 처리합니다.

4. 설정 저장 처리

하단 [모든 소셜 설정 저장하기] 버튼을 클릭하면 4개 서비스의 모든 설정이 한 번에 저장됩니다.

4.1 저장 처리 흐름

1. CSRF 토큰 검증
2. 4개 서비스(kakao/naver/google/github) 순서로 순회
3. 각 서비스의 enabled•client_id•client_secret POST 값 수집
4. client_secret 보안 처리: 빈 값("")이거나 마스킹 문자(●, chr(0xe2)+chr(0x97)+chr(0x8f)) 포함 시 기존 DB 저장값 유지
5. settings 테이블에 UPSERT: social_{provider}_enabled, social_{provider}_client_id, social_{provider}_client_secret 3개 키
6. dx_set_config()로 현재 요청의 설정 캐시도 즉시 갱신
7. DxCache::flush() — 전체 설정 캐시 초기화
8. "소셜 로그인 설정이 저장되었습니다." 성공 메시지 표시

4.2 settings 테이블 저장 키

setting_key	설명
social_{provider}_enabled	"1"(활성) 또는 "0"(비활성). 예: social_kakao_enabled.
social_{provider}_client_id	API Client ID 문자열. 예: social_kakao_client_id.
social_{provider}_client_secret	API Client Secret. 평문 저장. 예: social_kakao_client_secret.

💡  저장된 설정은 사이트 전체에 즉시 적용됩니다. 프론트엔드 로그인 페이지에서 활성화된 서비스의 소셜 로그인 버튼이 자동으로 표시됩니다.

5. 소셜 로그인 처리 내부 동작 (DxSocialAuth)

사용자가 소셜 로그인을 시도하면 DxSocialAuth 클래스가 다음 3단계 중 하나의 로직으로 처리합니다.

5.1 로그인 처리 3단계 분기

단계	조건	처리 내용
① 기존 연결	social_accounts 테이블에 provider+provider_id 일치 레코드가 있는 경우	해당 회원 조회(status=1 활성 확인) → members.last_login·last_ip 업데이트 → social_accounts.last_login 갱신 → DXCMS 세션 로그인.
② 이메일 매핑	기존 연결 없고 소셜 이메일과 일치하는 members 레코드가 있는 경우	기존 회원에 소셜 계정 연결(social_accounts INSERT) → DXCMS 세션 로그인. 비밀번호 없이 소셜로 기존 계정 로그인 가능.
③ 신규 생성	위 두 경우에 해당하지 않는 신규 사용자	members 테이블에 신규 INSERT(이름·이메일·랜덤 login_id·임시 비밀번호) → social_accounts INSERT → 가입 포인트/경험치 지급 → DXCMS 세션 로그인.

5.2 신규 회원 자동 생성 정보

이름 (name)	소셜 서비스에서 제공한 이름. 없으면 "{provider}_user" 자동 생성.
이메일 (email)	소셜 서비스에서 제공한 이메일. 없으면 "{provider}_{provider_id}@social.dxcms" 형식 자동 생성.
로그인 ID (login_id)	"{provider}_{provider_id 앞 8자리}" 형식. 중복 시 임의 숫자 추가.
비밀번호 (password)	dx_random_hex(24)로 생성한 랜덤 문자열을 BCRYPT 해시. 소셜 로그인 전용 계정은 비밀번호로 로그인 불가(직접 로그인 차단 의도 아님).
역할 (role)	member(일반 회원). 기본값.
가입 포인트/경험치	DxPoint::add()로 signup 유형 포인트·경험치 자동 지급.

5.3 social_accounts 테이블 구조

컬럼	타입	설명
id	INT UNSIGNED	자동 증가 기본 키.
member_id	INT UNSIGNED	연결된 members.id. 외래 키.
provider	VARCHAR(20)	소셜 서비스명. kakao/naver/google/github.
provider_id	VARCHAR(191)	소셜 서비스에서 제공하는 고유 사용자 ID.
provider_email	VARCHAR(191)	소셜 서비스에서 제공한 이메일.
provider_name	VARCHAR(191)	소셜 서비스에서 제공한 이름.
access_token	TEXT	OAuth 액세스 토큰. 갱신 시 업데이트.
last_login	DATETIME	마지막 소셜 로그인 일시.
created_at	DATETIME	최초 소셜 연결(가입) 일시.

5.4 State 검증 (CSRF 방지)

소셜 로그인 요청 시 보안을 위해 OAuth state 파라미터를 사용합니다.
 

State 생성	DxSocialAuth::generateState(): md5(uniqid(mt_rand(), true)) + microtime 기반 랜덤 문자열. 세션에 저장.
State 검증	콜백에서 받은 state와 세션의 dx_oauth_state를 비교.
불일치 시	세션이 살아있는데 state가 다르면 CSRF 가능성으로 판단 → "OAuth state 불일치" 오류 반환.
세션 만료 시	sessionState가 비어있으면 경고 로그만 남기고 진행 (세션 만료 환경 대응).

6. 소셜 연동 계정 현황 요약

관리자 화면 하단에 social_accounts 테이블을 provider별로 GROUP BY 집계한 연동 회원 수가 표시됩니다.

6.1 현황 카드 구성

집계 쿼리	SELECT provider, COUNT(*) as cnt FROM social_accounts GROUP BY provider
카드 구성	서비스 아이콘(브랜드 배경색) + 서비스명(provider 값) + 연동 회원 수.
값 없음	해당 서비스로 연동한 회원이 없으면 0명 표시.
social_accounts 없을 때	테이블 조회 실패(Exception) 시 모든 서비스 0명으로 표시(오류 화면 없음).
활용 방법	어떤 소셜 서비스로 가입한 회원이 가장 많은지 파악하여 마케팅·이벤트 전략 수립에 활용.

7. 전체 설정 절차

7.1 카카오 로그인 활성화 절차

1. [관리자 → 기본 설정]에서 site_url이 올바르게 설정되어 있는지 확인 (https://mysite.com 형식)
2. [관리자 → 소셜 로그인 연동 설정] 접속
3. 카드 하단 "OAuth 리디렉션 URI" 복사: https://mysite.com/auth/kakao_callback
4. developers.kakao.com → 내 애플리케이션 → 해당 앱 → 카카오 로그인 → Redirect URI 등록
5. 앱 키 탭에서 REST API 키 복사
6. DXCMS 카카오 카드의 [REST API 키] 필드에 붙여넣기
7. 보안 탭에서 Client Secret 생성 후 복사 → [클라이언트 시크릿] 필드에 붙여넣기
8. 카카오 카드 헤더의 토글을 ON으로 전환
9. [모든 소셜 설정 저장하기] 버튼 클릭
10. 사이트 로그인 페이지에서 카카오 로그인 버튼 표시 확인
11. 실제 카카오 계정으로 테스트 로그인

7.2 여러 서비스 동시 활성화

1. 위 절차를 각 서비스(네이버•구글•GitHub)별로 반복 수행
2. 모든 서비스 API 키를 DXCMS에 입력 후 각 토글 ON
3. [모든 소셜 설정 저장하기] 한 번으로 전체 저장 가능
4. 설정 카드 하단 현황 통계로 각 서비스별 연동 수 확인

8. 자주 묻는 질문 (FAQ)

Q1. 소셜 로그인 버튼이 프론트엔드에 표시되지 않습니다.

A. ① 관리자에서 해당 서비스 토글이 ON으로 설정되고 [저장]되었는지 확인. ② 캐시가 있다면 브라우저 강력 새로고침(Ctrl+Shift+R) 시도. ③ 테마 파일에서 DxSocialAuth::enabledProviders()를 호출하여 활성화된 서비스 버튼을 렌더링하는 코드가 있는지 확인.

Q2. 소셜 로그인 시 "토큰 획득 실패" 오류가 발생합니다.

A. 콜백 URL이 각 서비스 개발자 콘솔에 정확히 등록되어 있는지 확인하세요. http와 https, www 유무, 슬래시(/) 유무가 완전히 일치해야 합니다. site_url 설정도 확인하세요.

Q3. 구글 로그인 시 "액세스 차단됨" 오류가 표시됩니다.

A. 구글 OAuth 동의 화면이 "테스트" 상태이고 해당 계정이 테스트 사용자 목록에 없는 경우입니다. Google Cloud Console에서 OAuth 동의 화면을 "게시됨"으로 변경하거나, 테스트 사용자에 해당 계정을 추가하세요.

Q4. 소셜 로그인 후 기존 계정이 아닌 새 계정이 생성됩니다.

A. 소셜 이메일이 DXCMS 기존 회원 이메일과 정확히 일치하면 자동으로 기존 계정에 연결됩니다. 이메일이 다르거나 소셜 서비스에서 이메일을 제공하지 않으면 신규 회원이 생성됩니다. 카카오는 이메일 동의 항목을 "필수"로 설정하거나, 사용자가 이메일 동의를 해야 이메일이 제공됩니다.

Q5. Client Secret을 변경하려면?

A. 소셜 로그인 설정 화면에서 해당 서비스 카드의 [Client Secret] 필드에 새 시크릿을 입력하고 [저장]하면 됩니다. 빈 값으로 저장하면 기존 시크릿이 유지됩니다.

Q6. 연동된 소셜 계정을 특정 회원에서 해제하려면?

A. 관리자 DB에서 social_accounts 테이블의 해당 레코드를 직접 삭제하거나, 별도의 회원 소셜 연동 관리 UI를 구현해야 합니다. 현재 v8.1.0 관리자 UI에는 개별 소셜 연동 해제 기능이 없습니다.

Q7. GitHub 이메일이 비공개 설정이면 어떻게 됩니까?

A. DxSocialAuth의 GitHub fetchUserInfo()가 GitHub emails API(api.github.com/user/emails)를 추가로 호출하여 primary•verified 이메일을 가져옵니다. 이마저도 없으면 자동 생성 이메일({provider_id}@social.dxcms)이 사용됩니다.

9. 용어 정리

용어	설명
OAuth 2.0	외부 서비스 계정으로 인증하는 개방형 표준 프로토콜. DXCMS는 Authorization Code Flow를 사용.
Authorization Code	OAuth 인증 완료 후 서비스가 콜백 URL로 전달하는 일회용 인증 코드. Access Token 교환에 사용.
Access Token	Authorization Code를 교환하여 얻는 인증 토큰. 사용자 정보 API 호출에 사용.
provider	소셜 서비스 식별자. kakao/naver/google/github 중 하나.
provider_id	소셜 서비스가 각 사용자에게 부여하는 고유 ID. DXCMS 내 소셜 계정 식별에 사용.
Redirect URI (콜백 URL)	OAuth 인증 완료 후 서비스가 사용자를 리다이렉트하는 URL. 개발자 콘솔에 사전 등록 필요.
social_accounts	소셜 계정 연결 정보 DB 테이블. member_id·provider·provider_id·access_token 등 컬럼.
DxSocialAuth	소셜 로그인 통합 처리 PHP 클래스. getAuthUrl·handleCallback·loginOrRegister 등 메서드.
getAuthUrl($provider)	해당 서비스의 OAuth 인증 URL 생성 메서드. state 파라미터 포함.
handleCallback($provider, $code, $state)	콜백 code를 받아 token·사용자 정보 획득 후 결과 반환.
loginOrRegister($provider, $userInfo)	소셜 사용자 정보로 기존 연결/이메일 매핑/신규 생성 분기 처리.
enabledProviders()	활성화된 소셜 서비스 목록 반환. 프론트엔드 버튼 렌더링에 사용.
social_{provider}_enabled	소셜 서비스 활성화 여부 settings 키. "1"=ON, "0"=OFF.
social_{provider}_client_id	API Client ID settings 저장 키.
social_{provider}_client_secret	API Client Secret settings 저장 키.
dx_oauth_state	CSRF 방지용 OAuth state 값을 저장하는 PHP 세션 키.
generateState()	CSRF 방지용 랜덤 state 문자열 생성 메서드.
is_new	loginOrRegister() 반환값의 키. true=신규 회원 생성, false=기존 회원 로그인.
linkAccount()	기존 회원에 소셜 계정을 연결하는 메서드. social_accounts INSERT.
마스킹 문자 (●)	secret 필드에 기존 값이 있음을 표시하는 유니코드 문자(chr(0xe2)+chr(0x97)+chr(0x8f)). 이 문자가 포함된 secret은 기존 값 유지로 처리.