관리페이지 데이터 전송 구현

docs/관리페이지 md 파일/BARON-SSO server-side-app guide.md

@@ -0,0 +1,129 @@
+# Baron SSO Server-Side App Demo (Express.js)
+
+이 프로젝트는 `baron-sso`의 `server-side-app` RP를 테스트하기 위한 단순한 Express.js 데모입니다.
+
+## 목적
+
+이 데모는 다음을 확인하기 위한 용도입니다.
+
+1. confidential client 기반 OIDC Authorization Code 로그인
+2. RP 로컬 세션 생성 및 유지
+3. `Back-Channel Logout URI` 호출 수신
+4. `logout_token` 검증 후 로컬 세션 즉시 파기
+5. `BARON_SESSION_VALIDATION_ENABLED=false`일 때 access token 만료 후 refresh token 갱신으로 세션 종료 확인
+
+## 이 프로젝트 적용 원칙
+
+- BARON-SSO는 인증과 현재 테넌트 문맥 확인까지만 사용합니다.
+- 최종 권한 부여, 관리자 여부 판정, 프로젝트 접근 제어는 모두 내부 DB에서 처리합니다.
+- 따라서 OIDC 로그인 완료 후 RP 세션에는 최소한의 사용자 식별자와 `tenant_id` 만 저장하고, 이후 내부 사용자 매핑과 권한 조회를 별도 계층에서 수행하는 구성이 적합합니다.
+- 초기 운영 역할은 `PROJECT_MANAGER` 중심으로 두고, 채널 관리자 역할은 추후 필요 시 확장합니다.
+- 관리자 권한 설정 페이지는 관리자 콘솔 메뉴에 추가하는 방향을 기준으로 합니다.
+- 사용자 피드백에는 비밀글 기능을 추가하고, 조회 제한은 내부 DB 권한 정책으로 제어합니다.
+
+## 이 저장소 기준 BARON-SSO 연결값
+
+관리자 콘솔의 테넌트 OAuth 설정에는 아래 값을 기준으로 입력합니다.
+
+```text
+Login Type: OAuth 2.0
+Login Button Type: CUSTOM
+Login Button Name: BARON SSO 로그인
+Client ID: 838cd69d-e722-41da-9f79-b3c42a509ef2
+Client Secret: <BARON 관리자 콘솔에서 발급된 값>
+Authorization Code Request URL: https://sso.hmac.kr/oidc/oauth2/auth
+Access Token Request URL: https://sso.hmac.kr/oidc/oauth2/token
+User Profile Request URL: https://sso.hmac.kr/oidc/userinfo
+Scope: openid profile email
+Email Key in Response of User Profile: email
+Subject Key in Response of User Profile: sub
+Name Key in Response of User Profile: name
+Department Key in Response of User Profile: department
+Redirect URI: http://localhost:3003/api/auth/baron-sso/callback
+```
+
+설정 메모:
+
+- 내부 권한 매핑 기준 키는 전화번호가 아니라 `sub`입니다.
+- `name`, `department`는 BARON userinfo 응답에 실제로 존재할 때만 화면 표시용으로 사용합니다.
+- 테넌트 식별, 관리자 여부, 프로젝트 권한은 BARON에서 결정하지 않고 내부 DB에서 결정합니다.
+- `Client Secret`은 저장소에 하드코딩하지 말고 관리자 콘솔에서 직접 입력합니다.
+
+## 사전 준비
+
+1. `baron-sso` 프로젝트가 실행 중이어야 합니다.
+2. `baron_net` 네트워크가 생성되어 있어야 합니다.
+3. devfront에서 `server-side-app` 타입 RP를 생성해야 합니다.
+
+## 권장 RP 설정
+
+예시:
+
+```text
+Type: server-side-app
+Client ID: <생성된 client id>
+Client Secret: <생성된 secret>
+Redirect URI: http://localhost:4444/callback
+Back-Channel Logout URI: http://172.16.x.x:4444/backchannel-logout
+SID Claim Required: off
+```
+
+주의:
+
+- `Back-Channel Logout URI`는 브라우저 기준이 아니라 Baron backend가 실제로 접근 가능한 주소여야 합니다.
+- Docker 환경에서 `localhost`는 backend 컨테이너 자신을 가리킬 수 있으므로, 필요하면 사설 IP 또는 Docker 서비스명을 사용해야 합니다.
+
+## 실행
+
+```bash
+docker-compose up --build
+```
+
+## 환경 변수
+
+- `PORT`: 기본값 `4444`
+- `SESSION_SECRET`: Express session secret
+- `OIDC_ISSUER_URL`: Baron OIDC issuer URL
+- `OIDC_CLIENT_ID`: server-side-app client id
+- `OIDC_CLIENT_SECRET`: server-side-app client secret
+- `OIDC_REDIRECT_URI`: callback URL
+- `OIDC_CLIENT_AUTH_METHOD`: 기본값 `client_secret_basic`, 필요 시 `client_secret_post`
+- `BARON_API_BASE_URL`: Baron backend/public gateway URL
+- `BARON_BACKCHANNEL_JWKS_URL`: Baron Back-Channel Logout JWKS URL
+- `BARON_SESSION_VALIDATION_ENABLED`: `false`로 두면 Baron 세션 재검증을 끄고, access token 만료 후 refresh token 갱신으로 세션 종료를 확인합니다. 기본값은 `true`입니다.
+
+## 라우트
+
+```text
+GET  /
+GET  /login
+GET  /callback
+GET  /profile
+GET  /logout
+POST /backchannel-logout
+```
+
+## 동작 방식
+
+1. `/login`에서 state/nonce를 만들고 Baron authorize endpoint로 이동
+2. `/callback`에서 authorization code를 token으로 교환
+3. ID Token의 `sid/sub`를 현재 RP 세션 ID와 매핑
+4. `BARON_SESSION_VALIDATION_ENABLED=true`이면 요청마다 Baron `GET /api/v1/user/me`를 호출해 세션을 재검증
+5. `BARON_SESSION_VALIDATION_ENABLED=false`이면 access token 만료 후 Hydra token endpoint로 refresh token 갱신을 시도
+6. `invalid_grant`가 오면 로컬 세션을 파기
+7. Baron이 `/backchannel-logout`으로 `logout_token` 전송 시에도 세션을 즉시 파기
+
+## 테스트 포인트
+
+정상 동작 시 아래 로그 흐름이 보여야 합니다.
+
+```text
+[로그인 시작]
+[콜백] Authorization Code -> Token 교환 성공
+[세션 매핑] 등록 완료
+[백채널 로그아웃] 요청 수신
+[백채널 로그아웃] 토큰 검증 성공
+[백채널 로그아웃] 세션 파기 완료
+[백채널 로그아웃] 처리 완료
+[프로필] 비로그인 상태로 접근하여 루트로 이동
+```