MyDoc/[요청과업1][산출물05] Baron-SSO 아키텍쳐 리뷰.md

# Baron SSO Architecture Review

## 문서 목적

본 문서는 Baron SSO 시스템의 전체 아키텍처를 이해하고, 팀 아키텍처 리뷰 시 설명할 수 있도록 작성한 분석 문서이다.


---

# 0. 작업 개요

| 항목  | 내용  |
|-----|-----|
| 작업명 | 요청과업1 - Baron-SSO Architecture Review |
| 작업일 | 2026-06-15 |
| 시작  | 09:30 |
| 종료  | 16:00 |
| 휴게시간 | 12:00 \~ 13:00 |
| 총 작업시간 | 약6시간 30분 |
| 작업자 | 문형석 책임연구원 |

---

# 1. 시스템 개요

Baron SSO는 그룹사 및 사내 시스템의 인증(Authentication)과 인가(Authorization)를 통합 관리하기 위한 IAM(Identity & Access Management) 플랫폼이다.

주요 목적

* 통합 로그인(SSO)
* OAuth2 / OIDC 제공
* 사용자 인증
* 권한 관리
* 조직 관리
* 개발자 애플리케이션 연동 지원

---

# 2. 전체 아키텍처

```mermaid
flowchart TD

    User[사용자]

    Gateway[Gateway]

    UF[UserFront]
    AF[AdminFront]
    DF[DevFront]
    OF[OrgFront]

    Backend[Backend<br>Go + Fiber]

    Kratos[Kratos]
    Hydra[Hydra]
    Keto[Keto]
    Oathkeeper[Oathkeeper]

    PG[(PostgreSQL)]
    Redis[(Redis)]
    CH[(ClickHouse)]

    User --> Gateway

    Gateway --> UF
    Gateway --> AF
    Gateway --> DF
    Gateway --> OF

    UF --> Backend
    AF --> Backend
    DF --> Backend
    OF --> Backend

    Backend --> Kratos
    Backend --> Hydra
    Backend --> Keto
    Backend --> Oathkeeper

    Backend --> PG
    Backend --> Redis

    Oathkeeper --> Hydra
    Oathkeeper --> Keto

    Backend --> CH
```

---

# 3. 상위 컴포넌트 역할

## Gateway

역할

* 모든 외부 요청 진입점
* Reverse Proxy
* URL Routing

예시

```text
/            → UserFront
/api/*       → Backend
/auth/*      → Kratos
/oidc/*      → Hydra
```

---

## Frontend

### UserFront

일반 사용자용

기능

* 로그인
* 회원가입
* 비밀번호 찾기
* QR 로그인
* 내 정보

### AdminFront

시스템 관리자용

기능

* 사용자 관리
* 권한 관리
* 시스템 관리

### DevFront

개발자 포털

기능

* OAuth Client 등록
* OIDC 설정
* API 연동

### OrgFront

조직도 관리 포털

대상

* 회사 내부 사용자

기능

* 조직도 관리
* 부서 관리
* 조직 구성원 관리

외부 사용자는 사용하지 않는 것으로 판단

---

# 4. Backend 구조

Backend는 Go 기반 Layered Architecture 구조

```mermaid
flowchart TD

    Handler[Handler]

    Service[Service]

    Repository[Repository]

    DB[(Database)]

    Handler --> Service
    Service --> Repository
    Repository --> DB
```

설명

Handler

* API 요청 수신

Service

* 업무 로직 수행

Repository

* DB 접근

Database

* 실제 데이터 저장

---

# 5. Ory Stack

```mermaid
flowchart LR

    Kratos[Kratos<br>Authentication]

    Hydra[Hydra<br>OAuth2/OIDC]

    Keto[Keto<br>Authorization]

    Oathkeeper[Oathkeeper<br>API Protection]

    Oathkeeper --> Hydra
    Oathkeeper --> Keto
```

## Kratos

인증

* 로그인
* 회원가입
* 세션

## Hydra

토큰 발급

* Access Token
* ID Token

## Keto

권한 판단

* 사용 가능 여부 확인

## Oathkeeper

문지기

* 토큰 검사
* 권한 검사


---

# 6. 로그인 인증 흐름 (Kratos 중심)

## 목적

사용자의 신원을 확인하고 로그인 세션을 생성한다.

## 담당 컴포넌트

```text
Kratos
```

---

## Mermaid

```mermaid
sequenceDiagram

    participant U as 사용자
    participant GW as Gateway
    participant FE as UserFront
    participant BE as Backend
    participant KRA as Kratos
    participant DB as PostgreSQL

    U->>GW: localhost:5000 접속

    GW->>FE: 로그인 화면 제공

    FE-->>U: Login Page

    U->>FE: ID / PW 입력

    FE->>GW: 로그인 요청

    GW->>BE: POST /api/v1/auth/password/login

    BE->>KRA: 사용자 인증 요청

    KRA-->>BE: 인증 성공

    KRA-->>BE: Session 생성

    BE->>DB: 로그인 이력 저장

    BE-->>FE: 로그인 성공

    FE-->>U: Dashboard 이동
```

---

## 생성되는 정보

Kratos

```text
Identity

Session
```

예시

```json
{
  "identity_id":"user-123",
  "session_id":"session-456"
}
```

---

# 7. 로그인 후 토큰 발급 흐름 (Hydra 중심)

## 목적

인증된 사용자를 SSO 사용자로 전환

다른 시스템에서도 사용할 수 있는 Token 발급

---

## 담당 컴포넌트

```text
Hydra
```

---

## Mermaid

```mermaid
sequenceDiagram

    participant BE as Backend
    participant HYD as Hydra

    BE->>HYD: Token 발급 요청

    HYD-->>BE: Access Token

    HYD-->>BE: ID Token

    HYD-->>BE: Refresh Token
```

---

## 생성되는 정보

### Access Token

```text
API 접근용
```

---

### ID Token

```text
사용자 정보 전달
```

---

### Refresh Token

```text
Access Token 재발급
```

---

## 예시

```json
{
  "access_token":"eyJhbGciOi...",
  "id_token":"eyJhbGciOi...",
  "refresh_token":"eyJhbGciOi..."
}
```

---

# 8. 토큰 보유 상태 접근 흐름

## 상황

```text
이미 로그인 완료

Session 존재

또는

Access Token 존재
```

---

## Mermaid

```mermaid
sequenceDiagram

    participant U as 사용자
    participant GW as Gateway
    participant FE as Frontend
    participant OAT as Oathkeeper
    participant HYD as Hydra
    participant KET as Keto
    participant BE as Backend
    participant DB as PostgreSQL

    U->>GW: 서비스 접속

    GW->>FE: 화면 제공

    U->>FE: 내 정보 클릭

    FE->>GW: GET /api/v1/me

    GW->>OAT: API 요청 전달

    OAT->>HYD: 토큰 검증

    HYD-->>OAT: active=true
    HYD-->>OAT: sub=user-123

    OAT->>KET: 권한 확인

    KET-->>OAT: allowed=true

    OAT->>BE: 인증 완료 요청

    BE->>DB: 사용자 조회

    DB-->>BE: 사용자 정보

    BE-->>FE: 응답 반환

    FE-->>U: 화면 표시
```

---

## 단계별 이동 데이터

Frontend → Gateway

```http
GET /api/v1/me
```

포함

```text
Session Cookie

또는

Access Token
```

---

Hydra 응답

```json
{
  "active": true,
  "sub":"user-123"
}
```

---

Keto 응답

```json
{
  "allowed": true
}
```

---

# 9. 토큰 없는 상태 접근 흐름

## 상황

```text
최초 접속

로그인 안됨

세션 없음

토큰 없음
```

---

## Mermaid

```mermaid
sequenceDiagram

    participant U as 사용자
    participant GW as Gateway
    participant FE as Frontend
    participant OAT as Oathkeeper
    participant BE as Backend
    participant KRA as Kratos
    participant HYD as Hydra

    U->>GW: 보호된 페이지 접근

    GW->>FE: 페이지 요청

    FE->>OAT: API 요청

    OAT-->>FE: 인증 필요

    FE-->>U: 로그인 페이지 이동

    U->>FE: ID/PW 입력

    FE->>BE: 로그인 요청

    BE->>KRA: 사용자 인증

    KRA-->>BE: 인증 성공

    BE->>HYD: Token 발급 요청

    HYD-->>BE: Access Token

    BE-->>FE: 로그인 성공

    FE-->>U: Dashboard 이동
```

---

# 10. OIDC 인증 흐름

## 목적

다른 시스템이 Baron SSO를 로그인 서버로 사용

---

## Mermaid

```mermaid
sequenceDiagram

    participant User
    participant ClientApp
    participant Hydra
    participant Kratos

    User->>ClientApp: 서비스 접속

    ClientApp->>Hydra: 인증 요청

    Hydra->>Kratos: 로그인 필요

    Kratos-->>User: 로그인 화면

    User->>Kratos: ID/PW 입력

    Kratos-->>Hydra: 인증 성공

    Hydra-->>ClientApp: ID Token

    Hydra-->>ClientApp: Access Token

    ClientApp-->>User: 로그인 완료
```

---

# 11. Ory Stack 역할 정리

```mermaid
flowchart LR

    User[사용자]

    Kratos[Kratos<br>인증]

    Hydra[Hydra<br>토큰]

    Oathkeeper[Oathkeeper<br>검문소]

    Keto[Keto<br>권한]

    Backend[Backend]

    User --> Kratos
    Kratos --> Hydra
    Hydra --> Oathkeeper
    Oathkeeper --> Keto
    Keto --> Backend
```

---

## 한 줄 요약

### Kratos

```text
누구인가?
```

### Hydra

```text
인증 증명서 발급
```

### Oathkeeper

```text
토큰 확인
```

### Keto

```text
권한 확인
```

### Backend

```text
업무 처리
```

---

# 현재 검증 상태

완료

```text
WSL 구축

Docker 구축

Ory Stack 기동

Backend 기동

Frontend 기동

로그인 성공

로그아웃 성공

재로그인 성공

회원가입 화면 진입 성공
```

예정

```text
회원가입 완료 테스트

비밀번호 찾기 테스트

QR 로그인 테스트

AdminFront 테스트

DevFront 테스트

OIDC 인증 테스트

API 호출 테스트
```