🌐 웹 통합 트랙

Next.js · Rails · Express 등 서버 사이드 웹 앱에서 logi 를 통합하는 가장 빠른 길.

이 트랙이 맞나요?

✅ 맞음: 백엔드가 있고, 사용자가 브라우저에서 접속하는 웹 서비스
❌ 모바일 앱 이라면 → 📱 모바일 앱 통합 트랙
❌ 순수 SPA (백엔드 없음) 이라면 → Public Client + PKCE. public-clients 참고
❌ 데스크톱 SSO (Apple / Google ID 토큰 직수신) 이라면 → Web SSO (데스크톱)

핵심 약속 4줄

Confidential client + client_secret 서버 보관. 절대 브라우저 번들에 노출 금지.
redirect_uri 는 https://... 또는 http://localhost — 서버 콜백 라우트 경로.
state + nonce 검증 + HttpOnly · Secure 쿠키 로 세션 발급.
앱 RP 와 웹 RP 는 분리 — 자세히: 공통/Public Clients · Surface 별 RP 분리

Step 1 · 앱 등록

SPA / 클라이언트 사이드 → client_type: public 으로 RP 등록 (PKCE-only, secret 없음).
서버 사이드 (Next.js / Rails / Express) → client_type: confidential 로 RP 등록 → client_id + client_secret 발급.
앱 등록 가이드
Public vs Confidential 결정

Step 2 · 통합 패턴

SPA / 클라이언트 사이드 (권장)

순수 SPA (백엔드 콜백 없이 브라우저에서 직접 토큰 교환) 라면 공식 SDK @logi-auth/browser@0.1.0 사용:

bash

npm install @logi-auth/browser

import { LogiAuth } from '@logi-auth/browser';

const auth = new LogiAuth({
  clientId: 'logi_xxx',
  redirectUri: window.location.origin + '/auth/callback',
});

// Page A — 로그인 시작
await auth.signIn();

// Page B — 콜백 페이지
const tokens = await auth.handleCallback();

자세한 API + 에러 분류 → SPA Quickstart

서버 사이드 (Next.js / Rails / Express)

서버에서 client_secret 보관 + 콜백 처리. logi 는 표준 OIDC discovery (https://api.1pass.dev/.well-known/openid-configuration) 를 제공하므로 일반 OIDC 라이브러리 — oauth4webapi, openid-client, next-auth, auth.js — 가 issuer: 'https://api.1pass.dev' 만으로 자동 설정됩니다.

스택	가이드	핵심
Next.js (App Router)	integrations/nextjs	Route Handler + iron-session 패턴
Rails 8	integrations/rails	Direct OAuth 클라이언트 (omniauth 미사용). ⚠️ Hotwire/Turbo 사용 시 `data-turbo="false"` 필수
Express.js	integrations/express	`cookieParser` + crypto PKCE

Step 3 · 웹 특화 함정 피하기

⚠️ 기존 모바일 RP 에 웹 surface 추가 시 redirect_uri 화이트리스트 갱신 필수

하나의 client_id 를 모바일 앱과 웹 surface 가 공유하면 (public + PKCE RP 라면 안전), 웹 콜백 URL 도 RP 의 redirect_uris 화이트리스트에 명시적으로 등록되어 있어야 합니다. 누락 시 logi 는 즉시 거절:

json

{ "error": "invalid_request", "error_description": "redirect_uri not registered" }

웹 빌드 시작 전 반드시:

bash

# 현재 등록된 화이트리스트 확인
logi app show $CLIENT_ID
# 누락이면 추가 (기존 URI 유지하고 append 함)
logi app update $CLIENT_ID --add-redirect-uri "https://app.example.dev/auth/1pass/callback"
# preview/staging 도메인이 있다면 같이 등록
logi app update $CLIENT_ID --add-redirect-uri "https://preview.example.dev/auth/1pass/callback"
# 검증
logi apps verify $CLIENT_ID -r "https://app.example.dev/auth/1pass/callback"

이 함정은 “이미 모바일로 등록된 RP 에 웹 흐름을 새로 붙일 때” 자주 발생합니다. 신규 RP 라면 앱 등록 가이드 의 redirect_uris 배열에 모든 surface 의 콜백을 처음부터 한 번에 등록하세요.

응답 헤더 / Body 시그널 — Set-Cookie SameSite 정책
Web SSO (데스크톱 Apple/Google) — 내부 동작 참고용. 신규 RP 통합의 시작점은 아니며, logi 가 Apple/Google upstream IdP 토큰을 어떻게 처리하는지 알고 싶을 때만 참고하세요
QR 로그인 (앱 푸시 승인) — 데스크톱 웹에서 모바일 앱으로 승인 위임
Widget SDK (iframe embed) — 로그인 화면을 iframe 으로 끼워넣는 패턴
첫 로그인 완료 폼 — 자체 회원가입 추가 필드 패턴

Step 4 · 빌드 전 체크

✅ redirect_uris 화이트리스트 검증 — 빌드/배포 직전 logi apps verify $CLIENT_ID -r "$WEB_CALLBACK_URL" 로 production / staging / preview 도메인 각각 확인. CI 에 박아두면 안전 (--json + exit code)
RP 통합 테스트
보안 Best Practices (RP 측) — state/nonce/CSRF
Troubleshooting
demo.1pass.dev/qr — 데스크톱 ↔ 모바일 QR 핸드오프 walking sample (시나리오 deep-link)
demo.1pass.dev/oauth — 데스크톱 OAuth (PKCE) walking sample
Demo 페이지 둘러보기 — 시나리오별 흐름 + CSP 청정 패턴

공통 레퍼런스 (트랙 무관)

AI 에게 통째로 던지기

@/llms-full.txt 를 Claude Code · Cursor · Codex 에 붙이고 다음 한 줄:

"logi 1pass 를 [Next.js / Rails / Express] 웹 앱에 RP 로 통합해줘. confidential client + 서버 보관 secret 기준."

→ env, route, controller, callback handler, 로그인 버튼 UI 까지 자동 생성됩니다.

🌐 웹 통합 트랙 ​

핵심 약속 4줄 ​

Step 1 · 앱 등록 ​

Step 2 · 통합 패턴 ​

SPA / 클라이언트 사이드 (권장) ​

서버 사이드 (Next.js / Rails / Express) ​

Step 3 · 웹 특화 함정 피하기 ​

Step 4 · 빌드 전 체크 ​

공통 레퍼런스 (트랙 무관) ​

AI 에게 통째로 던지기 ​