# Headless 로그인 데모 설정 가이드 (Baron SSO 연동)

이 문서는 `headless-login-demo` 프로젝트를 설치하고, **Baron SSO (OIDC IdP)** 관리자 도구(`devfront`)에서 **Headless RP**를 올바르게 생성 및 설정하는 방법을 단계별로 설명합니다.

---

## 1. Baron SSO (devfront) 설정

Headless RP는 일반 OIDC 클라이언트와 설정 방식이 다릅니다. 특히 **IdP 서버가 RP(데모 앱)의 JWKS 엔드포인트에 접속할 수 있어야 함**을 유의하십시오.

### Step 1: 클라이언트 기본 정보 입력

1.  `devfront` 접속 후 **연동 앱 > 연동 앱 추가**를 클릭합니다.
2.  **Name**: `headless-login` (또는 자유롭게 입력)
3.  **Redirect URIs**: 데모 앱에 접속할 주소의 콜백 경로를 입력합니다.
    - **통합 환경 (IdP와 RP가 같은 서버일 때)**: `http://localhost:3000/callback`
    - **분리 환경 (IdP는 원격 서버, RP는 내 PC일 때)**: `http://[내_PC_IP]:3000/callback`
    - _주의: 실제 앱에서 요청하는 Redirect URI와 여기서 등록한 값이 **완전히 일치**해야 인증 거부 에러가 발생하지 않습니다._
4.  **Scopes**: `openid`, `profile`, `email`을 선택합니다.
5.  **Type**: 반드시 `pkce`를 선택해야 합니다.

![Step 1 설정 예시](./images/setup-step1-example.png)

### Step 2: Headless 기능 및 보안 설정

1.  `pkce` 하단의 **"Headless Login (자체 로그인 UI 사용)"** 토글을 활성화합니다.
2.  **JWKS URI**: **Baron SSO 서버에서 접근 가능한** 데모 앱의 공개키 주소를 입력합니다.
    - **통합 환경 (IdP와 RP가 같은 서버일 때)**: `http://localhost:3000/.well-known/jwks.json`
    - **분리 환경 (IdP는 원격 서버, RP는 내 PC일 때)**: `http://[내_PC_IP]:3000/.well-known/jwks.json`
    - _주의: Baron SSO 서버(`172.16.10.175`)에서 사용자님의 로컬 PC 포트로 네트워크가 열려있어야 합니다._

![Step 2 설정 예시](./images/setup-step2-example.png)

### Step 3: 저장 및 확인 (JWKS 캐시 검증)

1. **앱 생성** 버튼을 클릭해 저장합니다.
2. 연동 앱 목록에서 해당 앱이 **PKCE (Headless Login)** 유형으로 생성됐는지 확인합니다.
3. 앱 상세 페이지 하단이나 설정 탭에서 **JWKS 캐시 상태**가 `Success`인지 반드시 확인합니다.
   - _팁: 캐시 상태가 비어있거나 실패인 경우, 데모 앱(내 PC)이 켜져 있는지 확인하고 **새로고침(Refresh)** 버튼을 눌러 수동으로 캐시를 갱신하세요. 캐싱이 정상적으로 이루어져야만 로그인이 작동합니다._

## ![Step 3 설정 예시](./images/setup-step3-example.png)

## 2. Headless Login 애플리케이션 로컬 설정 (.env)

`devfront`에서 설정한 값을 바탕으로 프로젝트 루트의 `.env` 파일을 구성합니다.

```env
# 애플리케이션 실행 포트
PORT=3000

# OIDC IdP 설정 (원격 서버 주소 입력)
CLIENT_ID=a9b64539-7242-4aa5-ad3d-13c7f1ef00f2
ISSUER=http://172.16.10.175/oidc

# 리다이렉트 및 보안 설정
# REDIRECT_URI는 DevFront에 등록한 Redirect URIs 중 하나와 정확히 일치해야 합니다.
REDIRECT_URI=http://[내_PC_IP]:3000/callback
# JWKS_URI는 Baron SSO 서버가 내 PC로 접속할 때 사용하는 주소와 일치해야 합니다.
JWKS_URI=http://[내_PC_IP]:3000/.well-known/jwks.json
```

---

## 3. 주의 사항 (네트워크 구성)

- **서버 간 통신 (Server-to-Server)**: Headless 로그인은 Baron SSO 서버가 직접 데모 앱의 `JWKS_URI`에 접속하여 서명을 검증합니다. 따라서 IdP 서버에서 내 로컬 PC의 포트(`3000`)로의 인바운드 통신이 허용되어야 합니다.
- **Redirect URI 일치**: 브라우저를 통해 접속할 주소가 IP라면, Redirect URI와 JWKS URI 모두 IP 기반 주소로 통일하는 것이 문제 발생 소지를 줄이는 가장 좋은 방법입니다.

---

## 4. 실행

```bash
npm install
npm start
```

> **💡 참고: 자동 키 생성 및 JWKS 엔드포인트 활성화**
> `npm start` 명령어로 서버를 실행하면, 프로젝트 내에 `keys.json` 파일이 자동으로 생성됩니다. 이 파일에는 서버가 자체적으로 발급한 RSA 보안 키 쌍(공개키/개인키)이 저장됩니다.
> 동시에, `.env`에 설정된 `JWKS_URI` 경로(또는 기본 경로)로 공개키가 서빙되어 Baron SSO가 검증에 사용할 수 있게 됩니다.