# Headless Login Demo (OIDC Integration)

이 프로젝트는 **baron-sso (OIDC IdP)**와 연동하여 백채널(Back-channel)을 통한 **Headless 인증**을 구현한 데모 애플리케이션입니다.

## 주요 특징

- **Headless 인증**: IdP가 제공하는 UI를 거치지 않고, RP(데모 앱)가 사용자 자격 증명을 직접 받아 백채널로 인증을 수행합니다.
- **동적 UI 전환**: 입력값(숫자 vs 문자)을 실시간으로 분석하여 '전화번호 SSO 인증' 또는 '사번 로그인' 모드로 자동 전환됩니다.
- **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
# 필요 시 전화번호용 headless link endpoint를 별도로 덮어쓸 수 있음
PHONE_HEADLESS_LINK_INIT_ENDPOINT=
PHONE_HEADLESS_LINK_POLL_ENDPOINT=
BARON_API_BASE_URL=
BARON_BACKCHANNEL_JWKS_URL=
```

### 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**: 전화번호를 SSO headless 인증 흐름에 전달합니다.
- **Employee**: 비밀번호 입력란 노출 및 OIDC Password Grant 요청 실행.

### 2. SSO Headless 인증 (Real Communication)

데모 앱은 사용자로부터 받은 식별자와 자격 증명을 SSO 서버의 headless 인증 엔드포인트로 직접 전달합니다.

- SSO 서버가 해당 방식을 허용하도록 설정되어 있어야 하며, 화이트리스트에 등록된 `REDIRECT_URI`와 일치해야 합니다.
- 기존 자동 전화번호 로그인은 `POST /api/v1/auth/headless/link/init`로 링크를 발송한 뒤 `POST /api/v1/auth/headless/link/poll`로 승인 완료를 기다리는 흐름입니다.
- 새 전화번호 로그인 탭은 `POST /api/v1/auth/headless/phone-login`으로 직접 전송합니다.
- 필요하면 `PHONE_HEADLESS_LINK_INIT_ENDPOINT`, `PHONE_HEADLESS_LINK_POLL_ENDPOINT`, `PHONE_HEADLESS_LOGIN_ENDPOINT`로 오버라이드할 수 있습니다.

### 3. Tenant 접근 제한 처리

Headless RP도 일반 로그인과 동일하게 RP metadata의 `tenant_access_restricted`, `allowed_tenants` 설정 영향을 받습니다.

- headless password login 자체는 성공해도, 후속 consent 단계에서 tenant 제한이 걸릴 수 있습니다.
- 이 경우 Baron SSO는 `403 tenant_not_allowed`를 반환합니다.
- 데모 앱은 이 응답을 소비해 `userfront`의 locale 포함 에러 화면으로 이동시킵니다.
- 기본 경로: `/ko/error?error=tenant_not_allowed&error_description=...&details=...`
- locale 경로를 바꾸고 싶으면 `.env`에 `ERROR_LOCALE_PATH`를 추가해 덮어쓸 수 있습니다.

### 4. Back-Channel Logout

이 데모는 Baron SSO가 발행한 `logout_token`을 받아 RP 세션을 즉시 파기할 수 있습니다.

- `POST /backchannel-logout` 엔드포인트가 필요합니다.
- Baron이 서명한 `logout_token`은 `BARON_BACKCHANNEL_JWKS_URL`의 공개키로 검증합니다.
- 로그인 성공 시 `id_token`의 `sid` 또는 `sub`를 기준으로 RP 세션이 메모리에 바인딩됩니다.
- Baron에서 back-channel logout이 발생하면 해당 `sid` 또는 `sub`에 연결된 세션이 삭제됩니다.
- 기본 JWKS 주소는 `BARON_API_BASE_URL` 기준으로 `<BARON_API_BASE_URL>/api/v1/auth/backchannel/jwks.json` 입니다.

예시:

```env
ERROR_LOCALE_PATH=/ko/error
```

### 4. 테스트 체크리스트

다른 사용자가 headless login 작업을 검증할 때는 아래 순서로 확인하는 것이 가장 빠릅니다.

1. tenant 제한 없이 로그인해 headless 기본 흐름이 성공하는지 먼저 확인합니다.
2. RP에 `tenant_access_restricted=true`, `allowed_tenants=[...]`를 설정합니다.
3. 허용된 tenant 계정으로 로그인해 정상 성공 여부를 확인합니다.
4. 허용되지 않은 tenant 계정으로 로그인해 `userfront` 에러 화면으로 이동하는지 확인합니다.
5. 실패 시 `docker logs --tail 100 headless-login-demo`, `docker logs --tail 100 baron_backend`를 같이 확인합니다.

### 5. 장애 분석 포인트

- `Invalid URL`이 보이면 대부분 consent `403`을 RP가 처리하지 못한 경우입니다.
- `audience mismatch`가 보이면 `client_assertion`의 `aud` 또는 Baron SSO의 expected audience 구성이 어긋난 상태입니다.
- `tenant_not_allowed`가 backend 로그에 보이면 Baron SSO의 tenant 제한은 정상 동작 중이며, 이후 처리 위치는 RP 쪽입니다.

## 라이선스

이 프로젝트는 내부 테스트 및 데모 목적으로 제작되었습니다.