핵심 개념

logi를 사용하기 전 5분만 투자해서 아래 개념을 이해하세요. 이후 모든 문서가 같은 용어를 씁니다.

역할 (Role)

logi는 OAuth 2.0의 세 주체를 구분합니다:

주체	logi에서 이름	하는 일
Identity Provider	logi	사용자를 인증하고 토큰을 발급
Relying Party / Client	제휴사 앱	logi로 로그인하도록 redirect, 토큰으로 userinfo 조회
Resource Owner	사용자	logi 앱/웹으로 자격 증명 입력, Consent 동의

추가로 logi는 users 테이블에 3단계 role을 관리합니다:

user — 일반 최종 사용자
developer — 제휴사 앱을 등록/관리
admin — 시스템 운영자 (승인, 감사)

식별자

client_id — 공개. logi_ prefix + 32자 hex. 제휴사 앱 식별.
client_secret — 비공개. logi_secret_ prefix + 64자 hex. 발급 시 1회 노출. DB에는 bcrypt digest만 저장.
device_uuid — 제휴사 앱/iOS 앱이 Keychain/SecureStorage에 저장하는 기기 식별자.
jti — 각 Access Token(JWT)의 고유 ID. revoke 조회용.
kid — 서명 키 식별자. JWKS rotation 시 구 키/신 키 공존 지원.

Scope

scope	userinfo 필드
`profile`	sub, email, email_verified, identity_verified_level
`email`	sub, email, email_verified
`phone`	sub, phone_number (Phase 2)
`openid`	id_token 발급 + sub

Scope는 콤마가 아닌 공백 구분 입니다 (OAuth 2.0 표준).

사용자가 제휴사 A에 profile email 동의한 이후,

같은 scope로 재인증 → UI 스킵, 즉시 code 발급
scope 확장 요청 (예: +phone) → "NEW" 배지 + 추가 동의 요구
사용자가 /settings에서 revoke → 다음 인증 시 Consent 화면 다시 표시

Google 로그인과 같은 UX입니다.

토큰 수명

토큰	만료	Revocation
Authorization Code	10분 · 1회 사용	자동 (consume!)
Access Token (JWT)	15분	`jwt_jti` DB 조회로 revoke 체크
Refresh Token	30일 · 사용 시 rotation	즉시 revoke + 재사용 시 체인 전체 revoke
Personal API Key	무기한 (사용자 설정 가능)	`last_used_at` 모니터링 + 수동 revoke

JWT 구조

Header:   { alg: "RS256", kid: "<active>", typ: "JWT" }
Payload:  { iss: "logi", sub: "<user_id>", aud: "<client_id>",
            exp: <15min>, iat: <now>, jti: "<uuid>", scope: "profile email" }
Signature: RS256 over header.payload

검증은 /.well-known/jwks.json 에서 공개 키를 받아 수행합니다.

인증 메커니즘 요약

메커니즘	용도	전달 방법
세션 쿠키	웹 UI (Developer Portal, Consent 화면)	`session_id=...; Secure; HttpOnly; SameSite=Lax`
OAuth AT (JWT)	제휴사가 userinfo 조회	`Authorization: Bearer <JWT>`
PAK (Personal API Key)	CLI/MCP, 사용자 직접 관리	`Authorization: Bearer logi_pak_...`
Client Basic	/oauth/token에서 제휴사 인증	`Authorization: Basic <client_id:secret>`
Passkey (WebAuthn)	패스워드리스 강인증	`ASAuthorization*` / `navigator.credentials`

2FA 상태 머신

[비활성] --setup_otp!--> [키 생성됨] --enable_otp!(code)--> [활성]
[활성] --disable_otp!(current_code)--> [비활성]
[활성] --login_with(otp_code)--> session.otp_verified_at = Time.current
[활성] --login_with(backup_code)--> 백업 1개 소진

Passkey 인증은 User Verification 포함 시 OTP와 동등한 강인증으로 간주되어 otp_verified_at을 자동 설정합니다.

다음 단계

OAuth 플로우 시퀀스 — 다이어그램으로 전체 그림 이해
PKCE 상세 — RFC 7636 벡터로 검증

핵심 개념 ​

역할 (Role) ​

식별자 ​

Scope ​

Consent 재사용 규칙 ​

토큰 수명 ​

JWT 구조 ​

인증 메커니즘 요약 ​

2FA 상태 머신 ​

다음 단계 ​