Taehoon/ITAM

Fork 0

Files

SDI 933afb02b1

ITAM Code Check / build-and-config-check (push) Successful in 13s

Details

ITAM Docker Build Check / docker-build-check (push) Successful in 11s

Details

도커 컴포즈 파일 수정(bad gateway issue)

2026-06-26 09:37:58 +09:00

9.8 KiB

Raw Blame History

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

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

1. 개요

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

2. OIDC 핵심 개념

사용자가 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: 사용자의 이메일 주소 정보 접근 권한을 요청합니다.

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

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

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

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

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

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

pkce 하단의 "Headless Login (자체 로그인 UI 사용)" 토글을 활성화합니다.
JWKS URI: Baron SSO 서버에서 접근 가능한 자산관리 시스템의 공개키 주소를 입력합니다.
- 예: http://[자산관리_시스템_IP_또는_도메인]:[포트]/.well-known/jwks.json
- 주의: Baron SSO 서버에서 자산관리 시스템의 포트로 네트워크가 열려있어야 합니다.

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

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

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

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

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

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

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

자산관리 시스템은 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 연동 설정을 구성합니다.

# 애플리케이션 실행 포트 (자산관리 시스템의 포트)
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. 실행

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

npm install
npm start

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

9.8 KiB Raw Blame History