From 365b3fc8dd9d301ac3c11daef4a5d96999f1944e Mon Sep 17 00:00:00 2001 From: kyy Date: Thu, 9 Apr 2026 15:06:09 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=ED=94=84=EB=A1=9C=EC=A0=9D=ED=8A=B8=20?= =?UTF-8?q?=EA=B0=9C=EC=9A=94=20=EB=B0=8F=20OIDC=20=EC=97=B0=EB=8F=99=20?= =?UTF-8?q?=EA=B0=80=EC=9D=B4=EB=93=9C=20README=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..274db42 --- /dev/null +++ b/README.md @@ -0,0 +1,69 @@ +# Headless Login Demo (OIDC Integration) + +이 프로젝트는 **baron-sso (OIDC IdP)**와 연동하여 백채널(Back-channel)을 통한 **Headless 인증**을 구현한 데모 애플리케이션입니다. + +## 주요 특징 + +- **Headless 인증**: IdP가 제공하는 UI를 거치지 않고, RP(데모 앱)가 사용자 자격 증명을 직접 받아 백채널로 인증을 수행합니다. +- **동적 UI 전환**: 입력값(숫자 vs 문자)을 실시간으로 분석하여 '전화번호 인증' 또는 '사번 로그인' 모드로 자동 전환됩니다. +- **Trusted RP 구현**: + - **OIDC Discovery**: `sso-test.hmac.kr`의 메타데이터를 동적으로 로드합니다. + - **JWKS Endpoint**: 서버 시작 시 생성된 RSA 공개키를 `/.well-known/jwks.json`을 통해 서빙하여 IdP와의 신뢰 관계를 형성합니다. +- **세션 유지**: 인증 완료 후 `express-session`을 통해 로그인 상태를 유지하고 사용자 정보를 관리합니다. +- **PM-fork 스타일 디자인**: 기존 프로젝트의 디자인 토큰(그라데이션, 라운드 처리 등)을 Vanilla CSS로 재현했습니다. + +## 기술 스택 + +- **Backend**: Node.js, Express, express-session +- **OIDC**: openid-client (v5.x), jose +- **Frontend**: Vanilla JS, Modern CSS (Flexbox, CSS Variables) + +## 시작하기 + +### 1. 환경 설정 +프로젝트 루트에 `.env` 파일을 생성하고 아래와 같이 설정합니다. + +```env +PORT=3000 +CLIENT_ID=15cfb85c-f75f-4b51-a13d-d04f87d39739 +ISSUER=https://sso-test.hmac.kr/oidc +REDIRECT_URI=http://localhost:3000/callback +JWKS_URI=http://localhost:3000/.well-known/jwks.json +``` + +### 2. 의존성 설치 +```bash +npm install +``` + +### 3. 서버 실행 +```bash +npm start +``` + +## 프로젝트 구조 + +```text +├── server.js # Express 서버 및 OIDC 로직 (Discovery, JWKS, API) +├── public/ # 프론트엔드 정적 파일 +│ ├── index.html # 로그인 화면 +│ ├── home.html # 인증 후 메인 화면 +│ ├── app.js # 입력값 분석 및 API 통신 로직 +│ └── styles.css # PM-fork 스타일 시트 +├── keys.json # (자동생성) 서비스용 RSA 키 쌍 +└── .env # 환경 변수 설정 +``` + +## 핵심 구현 로직 + +### 1. 입력값 분류 (Classify Input) +사용자가 입력한 값이 숫자만 포함되어 있으면 전화번호(`phone`) 모드로, 문자가 포함되어 있으면 사번(`employee`) 모드로 인식합니다. +- **Phone**: 인증 링크 발송 시뮬레이션 실행. +- **Employee**: 비밀번호 입력란 노출 및 OIDC Password Grant 요청 실행. + +### 2. OIDC Password Grant (Real Communication) +데모 앱은 사용자로부터 받은 `loginId`와 `password`를 SSO 서버의 토큰 엔드포인트로 직접 전달합니다. +- SSO 서버가 해당 방식을 허용하도록 설정되어 있어야 하며, 화이트리스트에 등록된 `REDIRECT_URI`와 일치해야 합니다. + +## 라이선스 +이 프로젝트는 내부 테스트 및 데모 목적으로 제작되었습니다.