🌐 웹 통합 트랙

Source: tracks/web.md · Live: https://docs.1pass.dev/tracks/web LLM-sanitized: internal links absolutized, VitePress containers → admonitions, line numbers in the Jump-to Index reference this rendered file (1-indexed).

📍 Jump-to Index

• L30-L43: ## 핵심 약속 4줄
• L44-L54: ## Step 1 · 앱 등록
• L55-L91: ## Step 2 · 통합 패턴
  • L57-L81: ### SPA / 클라이언트 사이드 (권장)
  • L82-L91: ### 서버 사이드 (Next.js / Rails / Express)
• L92-L121: ## Step 3 · 웹 특화 함정 피하기
• L122-L131: ## Step 4 · 빌드 전 체크
• L132-L141: ## 공통 레퍼런스 (트랙 무관)
• L142-L149: ## AI 에게 통째로 던지기

---

🌐 웹 통합 트랙

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

💡 Tip: 이 트랙이 맞나요?

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

핵심 약속 4줄

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

⚠️ Warning: client_id 를 분리하든 공유하든 — 사용자 식별 키는 canonical_sub surface 별로 client_id 를 분리하면 같은 사용자가 client 마다 다른 pairwise sub 을 받고, 하나의 client_id 를 공유하면 같은 sub 이 나옵니다. 어느 쪽을 택하든, RP 가 sub 으로 사용자를 키잉하면 분리 구성에서 두 번째 surface 로그인 시 AlreadyLinkedError 로 깨질 수 있습니다.

→ 사람 단위 식별은 항상 client 전체에서 동일한 canonical_sub(userinfo 가 항상 emit) 로 하세요. 상세: Sub 정책

---

Step 1 · 앱 등록

⚠️ Warning: 앱(RP) 등록 전 이메일 인증 필요 개발자 콘솔에서 앱(RP)을 등록하려면 먼저 이메일 인증이 필요합니다. 가입 후 인증 메일의 링크를 클릭하거나 콘솔 /account 에서 재발송하세요. 미인증 시 등록이 차단됩니다. → 앱 등록 가이드 · 사전 요건

• 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 (v1.0.1 이상) 사용:

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 · 웹 특화 함정 피하기

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

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

웹 빌드 시작 전 반드시:

# 현재 등록된 화이트리스트 확인
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 청정 패턴

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

• Authorization Code Flow · PKCE · Scope 레퍼런스
• 오류 코드 · Token Introspection & JWKS
• Refresh Token 정책
• 로그인 버튼 컴포넌트
• Webhook 연동 · HMAC 서명 검증

---

AI 에게 통째로 던지기

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

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

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