> ## Documentation Index
> Fetch the complete documentation index at: https://docs.viamoss.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 인증

> Moss가 SDK 요청 및 대시보드 사용자를 인증하는 방법

## 개요

Moss는 컨텍스트에 따라 여러 인증 메커니즘을 사용합니다:

| 컨텍스트     | 방법        | 설명                         |
| -------- | --------- | -------------------------- |
| **SDK**  | JWT 토큰    | 애플리케이션별 키로 서명된 단기 토큰       |
| **대시보드** | Clerk SSO | 조직 지원이 포함된 OAuth 기반 싱글 사인온 |

***

## JWT 인증

JWT(JSON Web Token) 인증은 SDK 통합에 가장 높은 보안을 제공합니다.

### 작동 방식

1. 백엔드가 각 사용자 세션에 대해 서명된 JWT를 생성
2. SDK가 API 요청에 이 토큰을 포함
3. Moss가 서명, 만료 및 클레임을 검증
4. 모든 검사가 통과된 경우에만 접근 허용

### 토큰 구조

Moss JWT에는 다음 클레임이 포함됩니다:

| 클레임   | 설명          |
| ----- | ----------- |
| `sub` | 사용자 ID (주체) |
| `app` | 애플리케이션 ID   |
| `exp` | 만료 타임스탬프    |
| `iat` | 발급 타임스탬프    |

### 보안 기능

* **HS256 서명** - 기본적으로 애플리케이션의 비밀 키를 사용하여 HMAC-SHA256으로 토큰 서명
* **만료 적용** - 토큰에 유효한 `exp` 클레임 필수
* **키 로테이션 지원** - 예정된 폐기가 있는 여러 활성 서명 키
* **상수 시간 검증** - 타이밍에 안전한 비교를 사용한 서명 검증

### 서명 방식

Moss는 애플리케이션별로 두 가지 서명 방식을 지원합니다:

| 방식               | 알고리즘         | Moss가 저장하는 것        |
| ---------------- | ------------ | ------------------- |
| **공유 비밀 키** (기본) | HS256        | 토큰 검증에 사용하는 공유 비밀 키 |
| **비대칭 키**        | RS256, ES256 | 공개 키만 저장            |

비대칭 서명을 사용하면 키 쌍을 직접 생성하고 공개 키만 Moss에 등록합니다.
개인 키는 고객 인프라를 벗어나지 않으므로, Moss는 고객을 대신해 토큰을 발급할 수
있는 자료를 보유하지 않습니다. 등록된 각 키는 해당 알고리즘에 고정되며, 로테이션
시에는 폐기된 키를 다시 등록하는 것이 아니라 새 키 쌍을 등록해야 합니다.

<Info>
  보안 정책상 대칭 비밀 키를 외부 업체와 공유할 수 없는 경우 비대칭 서명이
  적합합니다. 그 외의 경우에는 HS256이 더 간단한 기본 선택지입니다.
</Info>

### 키 관리

각 애플리케이션은 여러 JWT 서명 키를 가질 수 있습니다:

* **키 ID (`kid`)** - 토큰 헤더에 포함된 고유 식별자
* **활성 상태** - 삭제 없이 키 비활성화 가능
* **예정된 폐기** - 원활한 로테이션을 위한 향후 폐기 날짜 설정
* **마지막 사용 추적** - 보안 감사를 위한 키 사용량 모니터링

<Info>
  구현 세부 사항 및 코드 예시는 [SDK 인증 가이드](/ko/sdk/authentication)를
  참조하세요.
</Info>

***

## 대시보드 인증 (Clerk)

Moss 대시보드는 엔터프라이즈급 SSO 기능을 제공하는 Clerk를 인증에 사용합니다.

### 기능

* **OAuth 통합** - Google, GitHub 또는 이메일로 로그인
* **조직 지원** - 역할 기반 권한이 있는 멀티테넌트 접근
* **세션 관리** - 자동 갱신이 있는 보안 세션 토큰
* **MFA 지원** - 선택적 다중 인증

### 조직 기반 접근

모든 대시보드 작업은 조직으로 범위가 지정됩니다:

* 애플리케이션은 조직에 속함
* 사용자는 여러 조직의 구성원이 될 수 있음
* 조직 전환 시 표시되는 애플리케이션 변경
* 대시보드의 API 호출에 JWT의 조직 컨텍스트 포함

***

## 멀티테넌시 보안

Moss는 모든 계층에서 엄격한 테넌트 격리를 적용합니다:

### 데이터베이스 수준

모든 쿼리는 요청한 조직 범위로 제한되므로 다른 조직에 속한 레코드는 반환되지 않습니다.

### API 수준

* JWT 토큰에 클레임의 조직 ID 포함
* API 엔드포인트가 접근 전 조직 소유권 확인
* 교차 조직 요청은 403 Forbidden으로 거부

### 감사 수준

* 다른 조직에 대한 접근 시도 로깅
* 의심스러운 패턴에 대한 보안 알림 구성 가능

***

## 세션 권한 부여

인증 외에도 Moss는 모든 요청에 대해 권한 부여를 확인합니다:

### 세션 검증

1. **사용자 소유권** - 세션은 특정 사용자에게 속함
2. **애플리케이션 범위** - 세션은 애플리케이션에 바인딩
3. **복합 키** - 외래 키 제약 조건으로 데이터 무결성 적용

### 접근 패턴

| 요청        | 검증                 |
| --------- | ------------------ |
| 세션 생성     | 사용자 + 애플리케이션 인증    |
| 메시지 전송    | 세션 소유권 + 애플리케이션 일치 |
| 히스토리 가져오기 | 세션 소유권 + 사용자 일치    |

***

## 보안 권장 사항

### SDK 통합용

1. 프로덕션 배포에 **JWT 인증 사용**
2. 만료 전 **토큰 갱신 구현**
3. **짧은 토큰 수명 설정** (15-60분 권장)
4. 모든 API 통신에 **HTTPS 사용**

### 대시보드 접근용

1. 모든 팀 구성원에게 **MFA 활성화**
2. **조직 구성원 정기 검토**
3. 조직에서 사용 가능한 경우 **SSO 사용**
4. **접근 로그 주기적 감사**

***

## 다음 단계

<CardGroup cols={2}>
  <Card title="SDK 인증 설정" icon="code" href="/ko/sdk/authentication">
    애플리케이션에서 JWT 인증 구현
  </Card>

  <Card title="데이터 보호" icon="lock" href="/ko/security/data-protection">
    암호화 및 데이터 처리에 대해 알아보기
  </Card>
</CardGroup>