# BARON-SSO 통합 로그인 연동 가이드 (자산관리 시스템)

이 문서는 Baron SSO(OpenID Connect IdP)를 자산관리 시스템에 통합 연동하기 위한 상세 가이드입니다. Headless 로그인 방식과 OIDC 표준을 기반으로 사용자 인증 및 정보 획득 과정을 설명하며, Baron SSO `devfront` 페이지에서의 애플리케이션 설정 방법과 연동 시 필요한 핵심 로직을 다룹니다.

---

## 1. 개요

자산관리 시스템에 Baron SSO를 연동하여 통합 로그인을 구현합니다. 이를 통해 사용자는 Baron SSO에서 인증하고, 자산관리 시스템은 사용자의 신원을 확인하고 필요한 정보를 획득하게 됩니다. 본 가이드는 주로 **Headless 로그인** 방식을 사용하며, 이는 사용자에게 Baron SSO의 로그인 화면을 직접 노출하지 않고 자산관리 시스템 내에서 인증 과정을 처리하는 방식입니다.

---

## 2. OIDC 핵심 개념

### 2.1. Headless Login
사용자가 IdP(Baron SSO)의 로그인 화면을 거치지 않고, RP(Relying Party, 자산관리 시스템) 내에서 직접 사용자 인증 정보를 입력받아 백채널(Back-channel)로 인증을 수행하는 방식입니다.

### 2.2. Client Assertion
보안 강화를 위해 RP가 자신이 신뢰할 수 있는 앱임을 증명하는 JWT(JSON Web Token)입니다. 이는 중요한 인증 요청 시 함께 전송됩니다.

### 2.3. 스코프 (Scopes)
사용자 정보에 접근하기 위한 권한 요청 단위입니다.
- `openid`: OIDC 인증 요청임을 명시하며 `id_token` 발급에 필수적입니다.
- `profile`: 사용자의 기본 프로필 정보(이름, 사번, 부서명 등) 접근 권한을 요청합니다.
- `email`: 사용자의 이메일 주소 정보 접근 권한을 요청합니다.

### 2.4. 자동 승인 (Auto-Consent)
Headless 환경에서 사용자의 정보 제공 동의 화면 없이, RP 서버가 백그라운드에서 동의 과정을 자동으로 처리하는 로직입니다.

---

## 3. Baron SSO (devfront) 애플리케이션 생성 및 설정

자산관리 시스템을 Baron SSO에 연동하기 위해 `devfront` 관리자 도구에서 Headless RP를 설정해야 합니다. 이때 IdP 서버가 RP의 JWKS 엔드포인트에 접속할 수 있어야 함을 유의하십시오.

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

1.  `devfront`에 접속하여 **연동 앱 > 연동 앱 추가**를 클릭합니다.
2.  **Name**: `asset-management-system` (또는 자산관리 시스템의 이름을 입력)
3.  **Redirect URIs**: 자산관리 시스템의 콜백 경로를 입력합니다.
    - 운영 예시: `https://[자산관리_시스템_도메인]/callback`
    - 내부망 테스트 예시: `http://[자산관리_시스템_IP_또는_도메인]:[포트]/callback`
    - **주의**: 실제 자산관리 시스템에서 요청하는 Redirect URI와 여기서 등록한 값이 **완전히 일치**해야 인증 거부 에러가 발생하지 않습니다.
4.  **Scopes**: `openid`, `profile`, `email`을 선택합니다.
5.  **Type**: 반드시 `pkce`를 선택합니다.

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

1.  `pkce` 하단의 **"Headless Login (자체 로그인 UI 사용)"** 토글을 활성화합니다.
2.  **JWKS URI**: **Baron SSO 서버에서 접근 가능한** 자산관리 시스템의 공개키 주소를 입력합니다.
    - 운영 예시: `https://[자산관리_시스템_도메인]/.well-known/jwks.json`
    - 내부망 테스트 예시: `http://[자산관리_시스템_IP_또는_도메인]:[포트]/.well-known/jwks.json`
    - **주의**: Baron SSO 서버에서 자산관리 시스템의 포트 또는 HTTPS 도메인으로 네트워크가 열려있어야 합니다.
    - **주의**: `JWKS URI`는 로그인 페이지나 사내 인증 게이트로 리다이렉트되면 안 됩니다. Baron SSO가 호출했을 때 이 경로는 반드시 `200 OK`와 `application/json`을 직접 반환해야 합니다.

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

1.  **앱 생성** 버튼을 클릭하여 설정을 저장합니다.
2.  연동 앱 목록에서 생성된 앱이 **PKCE (Headless Login)** 유형인지 확인합니다.
3.  앱 상세 페이지 하단이나 설정 탭에서 **JWKS 캐시 상태**가 `Success`인지 반드시 확인합니다. 캐시 상태가 비어있거나 실패인 경우, 자산관리 시스템이 켜져 있는지 확인하고 **새로고침(Refresh)** 버튼을 눌러 수동으로 캐시를 갱신해야 합니다.

---

## 4. 자산관리 시스템 연동 로직

### 4.1. 사번 로그인 (Headless Employee ID Login Flow)

사용자가 자산관리 시스템에서 사번과 비밀번호를 입력하여 로그인하는 시퀀스입니다.

1.  **신호 요청**: 자산관리 시스템은 Baron SSO의 Authorization Endpoint(`oauth2/auth`)에 요청하여 `login_challenge`를 획득합니다.
2.  **본인 인증**: 자산관리 시스템은 Private Key로 서명된 `client_assertion`(JWT)과 사용자의 사번, 비밀번호, `login_challenge`를 포함하여 Baron SSO의 Headless 로그인 API(`POST /api/v1/auth/headless/password/login`)를 호출합니다.
3.  **권한 획득 (자동 승인 포함)**: 인증 성공 후 Baron SSO가 반환하는 `redirectTo` 주소를 추적하며, 이 과정에서 `consent` 화면이 감지되면 자산관리 시스템은 백그라운드에서 동의 API(`POST /api/v1/auth/consent/accept`)를 호출하여 자동으로 승인합니다. 최종적으로 `Authorization Code`를 획득합니다.
4.  **인증키 발급**: 획득한 `Authorization Code`와 새로 생성한 `client_assertion`을 사용하여 Baron SSO의 Token Endpoint에 요청, `id_token`과 `access_token`을 발급받습니다.
5.  **로그인 완료**: `id_token`을 검증하고 사용자 정보를 추출하여 자산관리 시스템의 세션을 생성하고 로그인 완료 처리합니다.

### 4.2. 전화번호 인증 로그인 (Headless Phone Number Authentication Login Flow)

사용자가 자산관리 시스템에서 전화번호를 입력하여 인증 링크를 받고, 모바일에서 승인하여 로그인하는 시퀀스입니다.

1.  **신호 요청**: 사번 로그인과 동일하게 `login_challenge`를 획득합니다.
2.  **링크 발송 요청**: 자산관리 시스템은 `client_assertion`, `login_challenge`, 사용자의 전화번호(`loginId`)를 포함하여 Baron SSO의 인증 링크 발송 API(`POST /api/v1/auth/headless/link/init`)를 호출합니다. Baron SSO는 사용자에게 인증 링크를 발송하고 `pendingRef`를 반환합니다.
3.  **인증 상태 폴링**: 자산관리 시스템은 `pendingRef`와 `client_assertion`을 포함하여 Baron SSO의 상태 확인 API(`POST /api/v1/auth/headless/link/poll`)를 주기적으로 호출합니다. 사용자가 모바일에서 링크를 클릭하여 인증을 완료하면, Baron SSO는 `redirectTo` 정보를 반환하며 폴링이 종료됩니다.
4.  **이후 과정**: 폴링 결과로 받은 `redirectTo` 주소부터는 사번 로그인과 동일하게 표준 OIDC 흐름을 따릅니다 (자동 승인, `Authorization Code` 획득, `id_token` 발급, 세션 생성).

### 4.3. 자동 승인 및 스코프 처리 (Auto-Consent and Scope Handling)

자산관리 시스템은 `openid`, `profile`, `email`과 같은 스코프를 Baron SSO에 요청합니다. Headless 환경에서는 SSO 서버로부터 리다이렉트 주소에 `/consent`가 포함될 경우, 자산관리 시스템은 이를 감지하여 `consent_challenge`를 추출하고, 동의 상세 정보(`GET /api/v1/auth/consent`)를 요청하여 필요한 스코프를 확인합니다. 이후, 확인된 스코프를 모두 허용(`grant_scope`)한다고 Baron SSO의 동의 승인 API(`POST /api/v1/auth/consent/accept`)에 전송하여 자동으로 승인 과정을 처리합니다.

### 4.4. Tenant 접근 제한 예외 처리 (Tenant Access Restriction Exception Handling)

자산관리 시스템이 `tenant_access_restricted=true`로 설정되어 있고, 현재 사용자의 tenant가 허용된 `allowed_tenants`에 포함되지 않는 경우, Baron SSO는 `403` HTTP 상태 코드와 `code=tenant_not_allowed`를 응답합니다. 자산관리 시스템은 이 응답을 감지하여 사용자에게 적절한 에러 페이지(예: `/ko/error?error=tenant_not_allowed...`)로 리다이렉트하여 처리해야 합니다.

---

## 5. 자산관리 시스템 로컬 설정 (.env)

자산관리 시스템 프로젝트 루트의 `.env` 파일에 다음과 같이 Baron SSO 연동 설정을 구성합니다.

```env
# 애플리케이션 실행 포트 (자산관리 시스템의 포트)
PORT=3000 # 예시

# OIDC IdP 설정 (Baron SSO 서버 주소)
CLIENT_ID=... # devfront에서 발급받은 클라이언트 ID
ISSUER=https://[BARON_SSO_IP_또는_도메인]/oidc

# 리다이렉트 및 보안 설정
# REDIRECT_URI는 DevFront에 등록한 Redirect URIs 중 하나와 정확히 일치해야 합니다.
REDIRECT_URI=https://[자산관리_시스템_도메인]/callback
# JWKS_URI는 Baron SSO 서버가 자산관리 시스템으로 접속할 때 사용하는 주소와 일치해야 합니다.
JWKS_URI=https://[자산관리_시스템_도메인]/.well-known/jwks.json

# tenant 제한 시 이동시킬 userfront 에러 경로
ERROR_LOCALE_PATH=/ko/error
```

---

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

-   **서버 간 통신 (Server-to-Server)**: Headless 로그인은 Baron SSO 서버가 직접 자산관리 시스템의 `JWKS_URI`에 접속하여 서명을 검증합니다. 따라서 IdP 서버에서 자산관리 시스템의 포트 또는 HTTPS 도메인으로의 인바운드 통신이 허용되어야 합니다. 방화벽 및 네트워크 설정을 확인하십시오.
-   **운영 환경 HTTPS 권장**: 스테이징이나 내부망 테스트에서는 IP:포트 기반 HTTP가 통할 수 있지만, 운영에서는 Baron SSO가 접근 가능한 HTTPS 도메인을 사용하는 것이 안전합니다.
-   **JWKS 직접 응답 필수**: `/.well-known/jwks.json`은 사내 인증 포털이나 다른 로그인 페이지로 `302` 리다이렉트되면 안 됩니다. `curl -I https://[도메인]/.well-known/jwks.json` 결과가 `200`이어야 하며, Baron SSO가 읽을 수 있는 JWKS JSON 문서를 직접 반환해야 합니다.
-   **Redirect URI 일치**: 브라우저를 통해 접속할 주소가 IP라면, Redirect URI와 JWKS URI 모두 IP 기반 주소로 통일하는 것이 문제 발생 소지를 줄이는 가장 좋은 방법입니다. 도메인을 사용한다면 Redirect URI와 JWKS URI를 모두 같은 HTTPS 도메인 기준으로 일관되게 설정해야 합니다.

---

## 7. 실행

자산관리 시스템 프로젝트에서 다음 명령어를 실행하여 필요한 패키지를 설치하고 서버를 시작합니다.

```bash
npm install
npm start
```

서버 실행 시 `keys.json` 파일이 자동으로 생성되며, `.env`에 설정된 `JWKS_URI` 경로로 공개키가 서빙되어 Baron SSO가 이를 검증에 사용할 수 있게 됩니다.