Chrome-Erweiterungs-Muster
KRITISCHE REGELN
- OAuth (Google, GitHub usw.) und SAML werden in Popups oder Sidepanels NICHT unterstützt – verwenden Sie
syncHost, um die Authentifizierung an Ihre Web-App zu delegieren - E-Mail-Links (Magic Links) funktionieren nicht in Popups – das Popup schließt, wenn der Nutzer außerhalb klickt, und setzt den Anmeldestatus zurück
- Side-Panels aktualisieren den Authentifizierungsstatus nicht automatisch – Nutzer müssen das Side-Panel nach der Anmeldung über die Web-App schließen und erneut öffnen
- Service Worker und Content Scripts haben KEINEN Zugriff auf Clerk React Hooks – verwenden Sie
createClerkClient()oder Message Passing - Erweiterungs-URLs verwenden
chrome-extension://, nichthttp://– alle Weiterleitungs-URLs müssenchrome.runtime.getURL('.')verwenden - Ohne eine stabile CRX-ID bricht die Authentifizierung bei jedem Neubau – konfigurieren Sie den
keyim Manifest VOR dem Deployment - Content Scripts können Clerk aufgrund von Origin-Restriktionen nicht direkt nutzen – Clerk erzwingt strenge erlaubte Ursprünge
- Bot-Schutz muss im Clerk-Dashboard DEAKTIVIERT werden – Cloudflare Bot Detection wird in Erweiterungsumgebungen nicht unterstützt
Authentifizierungsoptionen
| Methode | Popup | Side Panel | syncHost (mit Web-App) |
|---|---|---|---|
| E-Mail + OTP | Ja | Ja | Ja |
| E-Mail + Link | Nein | Nein | Ja |
| E-Mail + Passwort | Ja | Ja | Ja |
| Benutzername + Passwort | Ja | Ja | Ja |
| SMS + OTP | Ja | Ja | Ja |
| OAuth (Google, GitHub usw.) | NEIN | NEIN | JA |
| SAML | NEIN | NEIN | JA |
| Passkeys | Ja | Ja | Ja |
| Google One Tap | Nein | Nein | Ja |
| Web3 | Nein | Nein | Ja |
Schnellstart (Plasmo)
npx create-plasmo --with-tailwindcss --with-src my-extension
cd my-extension
npm install @clerk/chrome-extension
Aktivieren Sie die Native API im Clerk-Dashboard unter „Native applications“. Erforderlich für alle Erweiterungsintegrationen.
.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
Verwenden Sie mode="modal" für SignInButton – die Navigation zu einer separaten Seite unterbricht den Popup-Flow.
syncHost – Authentifizierung mit der Web-App synchronisieren
Verwenden Sie dies, wenn Sie OAuth, SAML benötigen oder die Erweiterung den Anmeldestatus Ihrer Web-App widerspiegeln soll.
So funktioniert es: Die Erweiterung liest das Clerk-Sitzungscookie von der Domain Ihrer Web-App über host_permissions.
Schritt 1 – Umgebungsvariablen:
.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
Schritt 2 – syncHost-Prop hinzufügen:
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 })}
>
Schritt 3 – host_permissions in package.json konfigurieren:
{
"manifest": {
"key": "$CRX_PUBLIC_KEY",
"permissions": ["cookies", "storage"],
"host_permissions": [
"$PLASMO_PUBLIC_CLERK_SYNC_HOST/*",
"$CLERK_FRONTEND_API/*"
]
}
}
Schritt 4 – Erweiterungs-ID zu den erlaubten Ursprüngen der Web-App über die Clerk-API hinzufügen:
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"]}'
Nicht unterstützte Authentifizierungsmethoden im Popup bei Verwendung von syncHost ausblenden:
<SignIn
appearance={{
elements: {
socialButtonsRoot: 'plasmo-hidden',
dividerRow: 'plasmo-hidden',
},
}}
/>
Vollständige Anleitung: references/sync-host.md
createClerkClient() für Vanilla-JS / Service Worker
Import aus @clerk/chrome-extension/client (nicht aus @clerk/chrome-extension).
Background Service Worker (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
})
Das Flag background: true hält Sitzungen frisch, auch wenn Popup/Sidepanel geschlossen sind. Ohne es laufen Token nach 60 Sekunden ab.
Popup mit 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()
})
Vollständige Anleitung: references/create-clerk-client.md
Headless-Erweiterung (kein Popup, kein Sidepanel)
Für Erweiterungen, die vollständig im Hintergrund laufen und mit einer Web-App synchronisieren.
Verwendet syncHost + createClerkClient mit background: true, um den Authentifizierungsstatus aus den Cookies der Web-App zu lesen.
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
}
Erfordert host_permissions für die Sync-Host-Domain in package.json.
Vollständige Anleitung: references/headless-extension.md
Content Scripts
Content Scripts laufen in einer isolierten JavaScript-Welt, die in Webseiten eingefügt wird. Clerk kann nicht direkt verwendet werden – Origin-Restriktionen verhindern dies.
Verwenden Sie Message Passing, um den Authentifizierungsstatus vom Background Service Worker anzufordern:
// 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
// Token für authentifizierte API-Aufrufe verwenden
}
main()
Vollständige Anleitung: references/content-scripts.md
Stabile CRX-ID
Ohne einen festen Schlüssel leitet Chrome die CRX-ID von einem zufälligen Schlüssel zur Build-Zeit ab. Dieser wechselt bei jedem Neubau, wodurch erlaubte Ursprünge brechen.
Option A – Plasmo Itero (empfohlen):
- Besuchen Sie Plasmo Itero Generate Keypairs
- Klicken Sie auf „Generate KeyPairs“ – speichern Sie den privaten Schlüssel sicher, kopieren Sie den öffentlichen Schlüssel und die CRX-ID
Option B – OpenSSL:
openssl genrsa -out key.pem 2048
# Verwenden Sie Plasmo Itero, um den öffentlichen Schlüssel im richtigen Format zu konvertieren oder zu extrahieren
.env.chrome:
CRX_PUBLIC_KEY="<PUBLIC KEY from Itero>"
package.json:
{
"manifest": {
"key": "$CRX_PUBLIC_KEY",
"permissions": ["cookies", "storage"],
"host_permissions": [
"http://localhost/*",
"$CLERK_FRONTEND_API/*"
]
}
}
Fügen Sie chrome-extension://YOUR_STABLE_CRX_ID im Clerk-Dashboard unter „Allowed Origins“ hinzu.
Token-Cache (über Popup-Schließen hinweg persistent)
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}>
| Speichertyp | Geltungsbereich | Wird gelöscht bei |
|---|---|---|
chrome.storage.local | Gerät | Deinstallation oder manuelles Löschen |
chrome.storage.session | Sitzung | Schließen des Browsers |
chrome.storage.sync | Alle Geräte | Deinstallation (größenbegrenzt, 8KB) |
localStorage | Nur Popup | Popup schließen – nicht für Authentifizierung verwenden |
Häufige Fallstricke
| Symptom | Ursache | Lösung |
|---|---|---|
| Weiterleitungsschleife bei Anmeldung | Fehlende CRX-URL in ClerkProvider-Props | afterSignOutUrl, signInFallbackRedirectUrl setzen |
| OAuth-Button funktioniert nicht | OAuth wird im Popup nicht unterstützt | syncHost verwenden, um an Web-App zu delegieren |
| Auth-Status nach Web-App-Anmeldung veraltet | syncHost nicht konfiguriert | syncHost-Prop + host_permissions hinzufügen |
| Sidepanel zeigt nach Web-Anmeldung „abgemeldet“ | Bekannte Einschränkung | Benutzer muss Sidepanel schließen und erneut öffnen |
| Hintergrund kann nach 60 Sekunden kein Token abrufen | Sitzung abgelaufen, kein Hintergrund-Refresh | createClerkClient({ background: true }) verwenden |
| Content Script kann nicht auf Clerk zugreifen | Isolierte Welt + Origin-Restriktionen | Message Passing zum Background Service Worker verwenden |
| Authentifizierung bricht nach Neubau | CRX-ID rotiert | Stabilen Schlüssel über .env.chrome konfigurieren |
PLASMO_PUBLIC_-Variable undefiniert | Falsche Umgebungsdatei | .env.development verwenden, nicht .env |
| Bot-Schutz-Fehler | Cloudflare wird in Erweiterungen nicht unterstützt | Bot-Schutz im Clerk-Dashboard deaktivieren |
| Token-Cache nicht persistent | Verwendung von localStorage im Popup | chrome.storage.local oder tokenCache-Prop verwenden |
Plananforderungen
| Funktion | Plan |
|---|---|
| Einfache Popup-Authentifizierung (E-Mail/Passwort, OTP) | Kostenlos |
| Passkeys | Kostenlos |
| syncHost | Erfordert Pro (benutzerdefinierte Domain) |
| OAuth über syncHost | Pro + OAuth in Web-App konfiguriert |
| SAML über syncHost | Enterprise |
| Bot-Schutz | N/V – muss für Erweiterungen deaktiviert werden |
Siehe auch
clerk-setup– Erste Clerk-Installationclerk-custom-ui– Benutzerdefinierte Abläufe und Erscheinungsbild