Chrome 확장 프로그램 패턴
중요 규칙
- OAuth(Google, GitHub 등) 및 SAML은 팝업이나 사이드패널에서 지원되지 않습니다.
syncHost를 사용하여 웹 앱에 인증을 위임하세요. - 이메일 링크(매직 링크)는 팝업에서 작동하지 않습니다. 사용자가 팝업 외부를 클릭하면 팝업이 닫혀 로그인 상태가 초기화됩니다.
- 사이드패널은 인증 상태를 자동으로 새로 고치지 않습니다. 사용자는 웹 앱에서 로그인한 후 사이드패널을 닫았다가 다시 열어야 합니다.
- 서비스 워커와 콘텐츠 스크립트는 Clerk React 훅에 접근할 수 없습니다.
createClerkClient()또는 메시지 전달을 사용하세요. - 확장 프로그램 URL은
chrome-extension://을 사용하며http://를 사용하지 않습니다. 모든 리디렉션 URL은chrome.runtime.getURL('.')을 사용해야 합니다. - 안정적인 CRX ID가 없으면 빌드할 때마다 인증이 깨집니다. 배포 전에 manifest에
key를 설정하세요. - 콘텐츠 스크립트는 출처 제한으로 인해 Clerk를 직접 사용할 수 없습니다. Clerk는 엄격한 허용 출처를 적용합니다.
- Clerk 대시보드에서 Bot protection을 비활성화해야 합니다. Cloudflare 봇 감지는 확장 프로그램 환경에서 지원되지 않습니다.
인증 옵션
| 방법 | 팝업 | 사이드패널 | syncHost (웹 앱 포함) |
|---|---|---|---|
| 이메일 + OTP | 예 | 예 | 예 |
| 이메일 + 링크 | 아니요 | 아니요 | 예 |
| 이메일 + 비밀번호 | 예 | 예 | 예 |
| 사용자 이름 + 비밀번호 | 예 | 예 | 예 |
| SMS + OTP | 예 | 예 | 예 |
| OAuth (Google, GitHub 등) | 아니요 | 아니요 | 예 |
| SAML | 아니요 | 아니요 | 예 |
| 패스키 | 예 | 예 | 예 |
| Google One Tap | 아니요 | 아니요 | 예 |
| Web3 | 아니요 | 아니요 | 예 |
빠른 시작 (Plasmo)
npx create-plasmo --with-tailwindcss --with-src my-extension
cd my-extension
npm install @clerk/chrome-extension
Clerk 대시보드에서 Native API를 활성화합니다. 모든 확장 프로그램 통합에 필요합니다.
.env.development:
PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://your-app.clerk.accounts.dev
src/popup.tsx:
import { ClerkProvider, Show, SignInButton, SignUpButton, UserButton } from '@clerk/chrome-extension'
const PUBLISHABLE_KEY = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY
const EXTENSION_URL = chrome.runtime.getURL('.')
if (!PUBLISHABLE_KEY) {
throw new Error('Missing PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY')
}
function IndexPopup() {
return (
<ClerkProvider
publishableKey={PUBLISHABLE_KEY}
afterSignOutUrl={`${EXTENSION_URL}/popup.html`}
signInFallbackRedirectUrl={`${EXTENSION_URL}/popup.html`}
signUpFallbackRedirectUrl={`${EXTENSION_URL}/popup.html`}
>
<Show when="signed-out">
<SignInButton mode="modal" />
<SignUpButton mode="modal" />
</Show>
<Show when="signed-in">
<UserButton />
</Show>
</ClerkProvider>
)
}
export default IndexPopup
SignInButton에 mode="modal"을 사용하세요. 별도 페이지로 이동하면 팝업 흐름이 깨집니다.
syncHost — 웹 앱과 인증 동기화
OAuth, SAML이 필요하거나 확장 프로그램이 웹 앱의 로그인 상태를 반영하도록 하려면 이 기능을 사용하세요.
작동 방식: 확장 프로그램이 host_permissions를 통해 웹 앱 도메인의 Clerk 세션 쿠키를 읽습니다.
1단계 — 환경 변수:
.env.development:
PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://your-app.clerk.accounts.dev
PLASMO_PUBLIC_CLERK_SYNC_HOST=http://localhost
.env.production:
PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_live_...
CLERK_FRONTEND_API=https://clerk.your-domain.com
PLASMO_PUBLIC_CLERK_SYNC_HOST=https://clerk.your-domain.com
2단계 — syncHost prop 추가:
const SYNC_HOST = process.env.PLASMO_PUBLIC_CLERK_SYNC_HOST
<ClerkProvider
publishableKey={PUBLISHABLE_KEY}
syncHost={SYNC_HOST}
afterSignOutUrl="/"
routerPush={(to) => navigate(to)}
routerReplace={(to) => navigate(to, { replace: true })}
>
3단계 — package.json에서 host_permissions 설정:
{
"manifest": {
"key": "$CRX_PUBLIC_KEY",
"permissions": ["cookies", "storage"],
"host_permissions": [
"$PLASMO_PUBLIC_CLERK_SYNC_HOST/*",
"$CLERK_FRONTEND_API/*"
]
}
}
4단계 — Clerk API를 통해 웹 앱의 허용 출처에 확장 ID 추가:
curl -X PATCH https://api.clerk.com/v1/instance \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-type: application/json" \
-d '{"allowed_origins": ["chrome-extension://YOUR_EXTENSION_ID"]}'
syncHost 사용 시 팝업에서 지원되지 않는 인증 방법 숨기기:
<SignIn
appearance={{
elements: {
socialButtonsRoot: 'plasmo-hidden',
dividerRow: 'plasmo-hidden',
},
}}
/>
전체 가이드: references/sync-host.md
createClerkClient() — Vanilla JS / 서비스 워커
@clerk/chrome-extension/client에서 가져옵니다(@clerk/chrome-extension이 아님).
백그라운드 서비스 워커 (src/background/index.ts):
import { createClerkClient } from '@clerk/chrome-extension/client'
const publishableKey = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY
async function getToken(): Promise<string | null> {
const clerk = await createClerkClient({
publishableKey,
background: true,
})
if (!clerk.session) return null
return await clerk.session.getToken()
}
chrome.runtime.onMessage.addListener((request, sender, sendResponse) => {
getToken()
.then((token) => sendResponse({ token }))
.catch((error) => {
console.error('[Background] Error:', JSON.stringify(error))
sendResponse({ token: null })
})
return true
})
background: true 플래그는 팝업/사이드패널이 닫혀도 세션을 새로 유지합니다. 이 플래그가 없으면 토큰이 60초 후에 만료됩니다.
Vanilla JS 팝업 (src/popup.ts):
import { createClerkClient } from '@clerk/chrome-extension/client'
const EXTENSION_URL = chrome.runtime.getURL('.')
const POPUP_URL = `${EXTENSION_URL}popup.html`
const clerk = createClerkClient({ publishableKey })
clerk.load({
afterSignOutUrl: POPUP_URL,
signInForceRedirectUrl: POPUP_URL,
signUpForceRedirectUrl: POPUP_URL,
allowedRedirectProtocols: ['chrome-extension:'],
}).then(() => {
clerk.addListener(render)
render()
})
전체 가이드: references/create-clerk-client.md
헤드리스 확장 프로그램 (팝업 없음, 사이드패널 없음)
백그라운드에서 완전히 실행되고 웹 앱과 동기화되는 확장 프로그램을 위한 것입니다.
syncHost + background: true와 함께 createClerkClient를 사용하여 웹 앱의 쿠키에서 인증 상태를 읽습니다.
import { createClerkClient } from '@clerk/chrome-extension/client'
const publishableKey = process.env.PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY
const syncHost = process.env.PLASMO_PUBLIC_CLERK_SYNC_HOST
async function getAuthenticatedUser() {
const clerk = await createClerkClient({
publishableKey,
syncHost,
background: true,
})
return clerk.user
}
package.json에서 sync 호스트 도메인에 대한 host_permissions가 필요합니다.
전체 가이드: references/headless-extension.md
콘텐츠 스크립트
콘텐츠 스크립트는 웹 페이지에 주입된 격리된 JavaScript 세계에서 실행됩니다. Clerk를 직접 사용할 수 없습니다 — 출처 제한으로 인해 사용이 불가능합니다.
메시지 전달을 사용하여 백그라운드 서비스 워커에 인증 상태를 요청하세요:
// content.ts
async function getToken(): Promise<string | null> {
return new Promise((resolve) => {
chrome.runtime.sendMessage({ type: 'GET_TOKEN' }, (response) => {
resolve(response?.token ?? null)
})
})
}
async function main() {
const token = await getToken()
if (!token) return
// 인증된 API 호출에 토큰 사용
}
main()
전체 가이드: references/content-scripts.md
안정적인 CRX ID
고정 키가 없으면 Chrome이 빌드 시 임의의 키에서 CRX ID를 파생합니다. 이는 빌드할 때마다 변경되어 허용된 출처가 깨집니다.
옵션 A — Plasmo Itero (권장):
- Plasmo Itero 키페어 생성 방문
- "Generate KeyPairs" 클릭 — Private Key를 안전하게 저장하고 Public Key와 CRX ID 복사
옵션 B — OpenSSL:
openssl genrsa -out key.pem 2048
# Plasmo Itero를 사용하여 올바른 형식으로 공개 키 변환 또는 추출
.env.chrome:
CRX_PUBLIC_KEY="<Itero에서 가져온 PUBLIC KEY>"
package.json:
{
"manifest": {
"key": "$CRX_PUBLIC_KEY",
"permissions": ["cookies", "storage"],
"host_permissions": [
"http://localhost/*",
"$CLERK_FRONTEND_API/*"
]
}
}
Clerk 대시보드 > 허용된 출처에 chrome-extension://YOUR_STABLE_CRX_ID를 추가하세요.
토큰 캐시 (팝업 닫힘 간 유지)
const tokenCache = {
async getToken(key: string) {
const result = await chrome.storage.local.get(key)
return result[key] ?? null
},
async saveToken(key: string, token: string) {
await chrome.storage.local.set({ [key]: token })
},
async clearToken(key: string) {
await chrome.storage.local.remove(key)
},
}
<ClerkProvider publishableKey={PUBLISHABLE_KEY} tokenCache={tokenCache}>
| 저장소 유형 | 범위 | 초기화 시점 |
|---|---|---|
chrome.storage.local | 기기 | 제거 또는 수동 삭제 |
chrome.storage.session | 세션 | 브라우저 종료 |
chrome.storage.sync | 모든 기기 | 제거 (크기 제한, 8KB) |
localStorage | 팝업만 | 팝업 닫힘 — 인증에 사용하지 마세요 |
일반적인 문제점
| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 로그인 시 리디렉션 루프 | ClerkProvider props에 CRX URL 누락 | afterSignOutUrl, signInFallbackRedirectUrl 설정 |
| OAuth 버튼이 작동하지 않음 | 팝업에서 OAuth 지원 안 함 | syncHost를 사용하여 웹 앱에 위임 |
| 웹 앱 로그인 후 인증 상태가 오래됨 | syncHost가 설정되지 않음 | syncHost prop + host_permissions 추가 |
| 웹 로그인 후 사이드패널에 로그아웃 상태 표시 | 알려진 제한 사항 | 사용자가 사이드패널을 닫았다가 다시 열어야 함 |
| 60초 후 백그라운드에서 토큰을 가져올 수 없음 | 세션 만료, 백그라운드 새로고침 없음 | createClerkClient({ background: true }) 사용 |
| 콘텐츠 스크립트가 Clerk에 접근할 수 없음 | 격리된 세계 + 출처 제한 | 백그라운드 서비스 워커에 메시지 전달 사용 |
| 빌드 후 인증이 깨짐 | CRX ID가 변경됨 | .env.chrome을 통해 안정적인 키 설정 |
PLASMO_PUBLIC_ 변수가 정의되지 않음 | 잘못된 환경 파일 | .env가 아닌 .env.development 사용 |
| Bot protection 오류 | Cloudflare가 확장 프로그램에서 지원되지 않음 | Clerk 대시보드에서 Bot protection 비활성화 |
| 토큰 캐시가 지속되지 않음 | 팝업에서 localStorage 사용 | chrome.storage.local 또는 tokenCache prop 사용 |
플랜 요구 사항
| 기능 | 플랜 |
|---|---|
| 기본 팝업 인증 (이메일/비밀번호, OTP) | 무료 |
| 패스키 | 무료 |
| syncHost | Pro 필요 (사용자 정의 도메인) |
| syncHost를 통한 OAuth | Pro + 웹 앱에서 OAuth 구성 |
| syncHost를 통한 SAML | Enterprise |
| Bot protection | N/A — 확장 프로그램에서는 비활성화해야 함 |
참고
clerk-setup— 초기 Clerk 설치clerk-custom-ui— 사용자 정의 흐름 및 외관