Chrome拡張機能パターン
重要なルール
- OAuth(Google、GitHubなど)およびSAMLは、ポップアップやサイドパネルではサポートされません —
syncHostを使用してWebアプリに認証を委任してください - メールリンク(マジックリンク)はポップアップで機能しません — ユーザーがポップアップ外をクリックするとポップアップが閉じ、サインイン状態がリセットされます
- サイドパネルは認証状態を自動的に更新しません — ユーザーはWebアプリでサインインした後、サイドパネルを閉じて再度開く必要があります
- サービスワーカーとコンテンツスクリプトはClerk Reactフックにアクセスできません —
createClerkClient()またはメッセージパッシングを使用してください - 拡張機能のURLは
chrome-extension://を使用し、http://は使用しません — すべてのリダイレクトURLはchrome.runtime.getURL('.')を使用する必要があります - 安定したCRX IDがない場合、ビルドのたびに認証が壊れます — デプロイ前にマニフェストで
keyを設定してください - オリジン制限により、コンテンツスクリプトはClerkを直接使用できません — Clerkは許可されたオリジンを厳格にチェックします
- Clerkダッシュボードでボット保護を無効にする必要があります — Cloudflareボット検出は拡張機能環境ではサポートされていません
認証オプション
| 方法 | ポップアップ | サイドパネル | syncHost(Webアプリ連携) |
|---|---|---|---|
| メール + 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ダッシュボードでネイティブ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 — Webアプリと認証を同期
OAuth、SAMLが必要な場合、または拡張機能がWebアプリからのサインイン状態を反映させたい場合に使用します。
仕組み: 拡張機能はhost_permissionsを介してWebアプリのドメインからClerkセッションCookieを読み取ります。
ステップ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プロパティを追加:
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をWebアプリの許可されたオリジンに追加:
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
Vanilla JS / サービスワーカー向け createClerkClient()
@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
ヘッドレス拡張機能(ポップアップ、サイドパネルなし)
完全にバックグラウンドで実行され、Webアプリと同期する拡張機能向け。
syncHost + createClerkClientをbackground: trueで使用し、WebアプリのCookieから認証状態を読み取ります。
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で同期ホストドメインのhost_permissionsが必要です。
完全なガイド: references/headless-extension.md
コンテンツスクリプト
コンテンツスクリプトは、Webページに注入された分離された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にアクセス
- 「Generate KeyPairs」をクリック — 秘密鍵を安全に保存し、公開鍵とCRX IDをコピーします
オプションB — OpenSSL:
openssl genrsa -out key.pem 2048
# Plasmo Iteroを使用して公開鍵を正しい形式に変換または抽出します
.env.chrome:
CRX_PUBLIC_KEY="<Iteroから取得した公開鍵>"
package.json:
{
"manifest": {
"key": "$CRX_PUBLIC_KEY",
"permissions": ["cookies", "storage"],
"host_permissions": [
"http://localhost/*",
"$CLERK_FRONTEND_API/*"
]
}
}
chrome-extension://YOUR_STABLE_CRX_IDをClerkダッシュボード > 許可されたオリジンに追加します。
トークンキャッシュ(ポップアップを閉じても保持)
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プロパティにCRX URLが欠落 | afterSignOutUrl、signInFallbackRedirectUrlを設定 |
| OAuthボタンが動作しない | OAuthはポップアップでサポートされていない | syncHostを使用してWebアプリに委任 |
| Webアプリサインイン後に認証状態が古い | syncHostが設定されていない | syncHostプロパティ + host_permissionsを追加 |
| Webサインイン後、サイドパネルにサインアウトと表示 | 既知の制限 | ユーザーはサイドパネルを閉じて再度開く必要がある |
| バックグラウンドが60秒後にトークンを取得できない | セッション期限切れ、バックグラウンド更新なし | createClerkClient({ background: true })を使用 |
| コンテンツスクリプトがClerkにアクセスできない | 分離された環境 + オリジン制限 | バックグラウンドサービスワーカーへのメッセージパッシングを使用 |
| ビルド後に認証が壊れる | CRX IDが変更された | .env.chromeで安定したキーを設定 |
PLASMO_PUBLIC_変数が未定義 | 間違ったenvファイル | .envではなく.env.developmentを使用 |
| ボット保護エラー | Cloudflareは拡張機能でサポートされていない | Clerkダッシュボードでボット保護を無効化 |
| トークンキャッシュが保持されない | ポップアップでlocalStorageを使用 | chrome.storage.localを使用するか、tokenCacheプロパティを渡す |
プラン要件
| 機能 | プラン |
|---|---|
| 基本的なポップアップ認証(メール/パスワード、OTP) | 無料 |
| パスキー | 無料 |
| syncHost | Pro(カスタムドメイン)が必要 |
| syncHost経由のOAuth | Pro + WebアプリでOAuth設定済み |
| syncHost経由のSAML | Enterprise |
| ボット保護 | なし — 拡張機能では無効にする必要があります |
関連項目
clerk-setup- Clerkの初期インストールclerk-custom-ui- カスタムフローと外観