SSO 통합 가이드

개요

Modfolio Connect는 생태계 전체의 유니버설 SSO/OIDC 플랫폼입니다. login.modfolio.io에서 운영되며, 15개 이상의 앱이 하나의 계정으로 인증을 처리합니다.

프로토콜: OpenID Connect (OIDC) Authorization Code Flow + PKCE S256
구현: SvelteKit 5 + Better Auth + D1
엔드포인트: https://connect.modfolio.io

사용자는 한 번 로그인하면 생태계 내 모든 앱에 별도 인증 없이 접근할 수 있습니다.

OIDC Authorization Code + PKCE 플로우

PKCE(Proof Key for Code Exchange)는 public client에서 Authorization Code 가로채기 공격을 방지합니다.

1. 앱 → code_verifier(랜덤) 생성 → SHA-256 해시 → code_challenge
2. 앱 → GET /sso/authorize
        ?client_id=your-app
        &response_type=code
        &redirect_uri=https://your-app.com/auth/callback
        &scope=openid+profile+email
        &code_challenge=<hash>
        &code_challenge_method=S256
3. Connect → 사용자에게 로그인 UI 표시 → 인증 처리
4. Connect → redirect_uri?code=<authorization_code>
5. 앱 → POST /sso/token
        { code, code_verifier, redirect_uri, grant_type: "authorization_code" }
6. Connect → { access_token, id_token, refresh_token, token_type, expires_in }
7. 앱 → JWT 검증 후 세션 생성

Connect SDK를 사용하면 위 플로우가 자동으로 처리됩니다. 직접 구현할 필요가 없습니다.

인증 방식

Modfolio Connect는 5가지 인증 방식을 지원합니다.

방식	설명	비고
비밀번호	이메일 + 비밀번호	기본 인증
Kakao OAuth	카카오 소셜 로그인	한국 사용자 대상
Magic Link	이메일 일회용 링크	Resend로 발송
Passkey	WebAuthn/FIDO2 생체인증	기기 바인딩
TOTP 2FA	Google Authenticator 등	2차 인증

앱은 인증 방식을 선택할 필요가 없습니다. Connect 로그인 화면에서 사용자가 직접 선택합니다.

토큰 라이프사이클

access_token  ─── 15분 ───┐
                           ├── 만료 시 자동 갱신 (SDK 미들웨어)
refresh_token ─── 90일 ───┘

access_token (15분): API 요청 인증에 사용. 짧은 수명으로 탈취 위험 최소화.
refresh_token (90일): access_token 만료 시 새 토큰 쌍 발급에 사용.
SDK 미들웨어는 access_token 만료를 감지하고 refresh_token으로 자동 갱신합니다.
refresh_token마저 만료되면 사용자에게 재로그인을 요청합니다.

JWT Claims 구조

access_token을 디코딩하면 다음 클레임을 포함합니다.

interface ConnectJWTPayload {
  /** 발급자 — 항상 https://connect.modfolio.io */
  iss: "https://connect.modfolio.io";
  /** 사용자 고유 ID (UUID) */
  sub: string;
  /** 대상 앱의 client_id */
  aud: string;
  /** 만료 시각 (Unix timestamp) */
  exp: number;
  /** 발급 시각 (Unix timestamp) */
  iat: number;
  /** 사용자 ID (sub과 동일) */
  user_id: string;
  /** 이메일 주소 */
  email: string;
  /** 역할 목록 (예: ["user", "admin"]) */
  roles: string[];
  /** 연결된 앱 목록 (예: ["naviaca", "gistcore"]) */
  connected_apps: string[];
}

roles와 connected_apps는 생태계 내 권한 관리와 앱 간 연결 상태 확인에 사용됩니다.

Well-Known Endpoints

OIDC Discovery를 통해 클라이언트가 자동으로 설정을 가져올 수 있습니다.

엔드포인트	설명
`GET /.well-known/openid-configuration`	OIDC Discovery 문서
`GET /.well-known/jwks.json`	공개키 세트 (JWK Set, EC P-256)

주요 SSO 엔드포인트:

엔드포인트	메서드	설명
`/sso/authorize`	GET	OIDC Authorization 시작
`/sso/token`	POST	Authorization Code를 토큰으로 교환
`/sso/verify`	POST	JWT 서명 검증
`/sso/introspect`	POST	토큰 인트로스펙션 (RFC 7662)
`/sso/revoke`	POST	토큰 폐기 (RFC 7009)
`/sso/userinfo`	GET	사용자 정보 조회
`/sso/consent`	POST	사용자 동의 처리
`/logout`	POST	로그아웃 + Back-Channel Logout
`/health`	GET	서버 상태 확인

다음 단계

SDK 설치 – Connect SDK 설치 및 프레임워크별 초기 설정
미들웨어 설정 – 미들웨어 동작 원리와 체이닝 패턴
문제 해결 – SSO 연동 시 흔한 문제와 해결 방법