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