ITAM/baron-sso_login_guide/BARONSSO_loginAPI_task.md

# 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**: 자산관리 시스템의 콜백 경로를 입력합니다.
    - 예: `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 서버에서 접근 가능한** 자산관리 시스템의 공개키 주소를 입력합니다.
    - 예: `http://[자산관리_시스템_IP_또는_도메인]:[포트]/.well-known/jwks.json`
    - **주의**: Baron SSO 서버에서 자산관리 시스템의 포트로 네트워크가 열려있어야 합니다.

### 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=http://[BARON_SSO_IP_또는_도메인]/oidc

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

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

---

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

-   **서버 간 통신 (Server-to-Server)**: Headless 로그인은 Baron SSO 서버가 직접 자산관리 시스템의 `JWKS_URI`에 접속하여 서명을 검증합니다. 따라서 IdP 서버에서 자산관리 시스템의 포트로의 인바운드 통신이 허용되어야 합니다. 방화벽 및 네트워크 설정을 확인하십시오.
-   **Redirect URI 일치**: 브라우저를 통해 접속할 주소가 IP라면, Redirect URI와 JWKS URI 모두 IP 기반 주소로 통일하는 것이 문제 발생 소지를 줄이는 가장 좋은 방법입니다. 도메인을 사용한다면 일관되게 도메인으로 설정해야 합니다.

---

## 7. 실행

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

```bash
npm install
npm start
```

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