Modèles d'authentification pour extensions Chrome
RÈGLES CRITIQUES
- OAuth (Google, GitHub, etc.) et SAML ne sont PAS pris en charge dans les popups ou side panels — utilisez
syncHostpour déléguer l'authentification à votre application web - Les liens par e-mail (magic links) ne fonctionnent pas dans les popups — le popup se ferme lorsque l'utilisateur clique à l'extérieur, réinitialisant l'état de connexion
- Les side panels ne mettent pas à jour automatiquement l'état d'authentification — les utilisateurs doivent fermer et rouvrir le side panel après s'être connectés via l'application web
- Les service workers et les scripts de contenu n'ont PAS accès aux hooks React de Clerk — utilisez
createClerkClient()ou le passage de messages - Les URLs d'extension utilisent
chrome-extension://et nonhttp://— toutes les URLs de redirection doivent utiliserchrome.runtime.getURL('.') - Sans un ID CRX stable, chaque reconstruction brise l'authentification — configurez
keydans le manifeste AVANT de déployer - Les scripts de contenu ne peuvent pas utiliser Clerk directement en raison des restrictions d'origine — Clerk applique des origines autorisées strictes
- La protection anti-bot doit être DÉSACTIVÉE dans le tableau de bord Clerk — la détection de bot Cloudflare n'est pas prise en charge dans les environnements d'extension
Options d'authentification
| Méthode | Popup | Side Panel | syncHost (avec application web) |
|---|---|---|---|
| E-mail + OTP | Oui | Oui | Oui |
| E-mail + Lien | Non | Non | Oui |
| E-mail + Mot de passe | Oui | Oui | Oui |
| Nom d'utilisateur + Mot de passe | Oui | Oui | Oui |
| SMS + OTP | Oui | Oui | Oui |
| OAuth (Google, GitHub, etc.) | NON | NON | OUI |
| SAML | NON | NON | OUI |
| Passkeys | Oui | Oui | Oui |
| Google One Tap | Non | Non | Oui |
| Web3 | Non | Non | Oui |
Démarrage rapide (Plasmo)
npx create-plasmo --with-tailwindcss --with-src mon-extension
cd mon-extension
npm install @clerk/chrome-extension
Activez Native API dans le tableau de bord Clerk sous Applications natives. Requis pour toutes les intégrations d'extension.
.env.development :
PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://votre-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('PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY manquant')
}
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
Utilisez mode="modal" pour SignInButton — naviguer vers une page séparée brise le flux du popup.
syncHost — Synchroniser l'authentification avec l'application web
Utilisez ceci lorsque vous avez besoin d'OAuth, SAML, ou souhaitez que l'extension reflète la connexion depuis votre application web.
Comment ça fonctionne : L'extension lit le cookie de session Clerk du domaine de votre application web via host_permissions.
Étape 1 — Variables d'environnement :
.env.development :
PLASMO_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_...
CLERK_FRONTEND_API=https://votre-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.votre-domaine.com
PLASMO_PUBLIC_CLERK_SYNC_HOST=https://clerk.votre-domaine.com
Étape 2 — Ajoutez la propriété 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 })}
>
Étape 3 — Configurez host_permissions dans package.json :
{
"manifest": {
"key": "$CRX_PUBLIC_KEY",
"permissions": ["cookies", "storage"],
"host_permissions": [
"$PLASMO_PUBLIC_CLERK_SYNC_HOST/*",
"$CLERK_FRONTEND_API/*"
]
}
}
Étape 4 — Ajoutez l'ID de l'extension aux origines autorisées de l'application web via l'API Clerk :
curl -X PATCH https://api.clerk.com/v1/instance \
-H "Authorization: Bearer VOTRE_CLÉ_SECRÈTE" \
-H "Content-type: application/json" \
-d '{"allowed_origins": ["chrome-extension://VOTRE_ID_EXTENSION"]}'
Masquez les méthodes d'authentification non prises en charge dans le popup lors de l'utilisation de syncHost :
<SignIn
appearance={{
elements: {
socialButtonsRoot: 'plasmo-hidden',
dividerRow: 'plasmo-hidden',
},
}}
/>
Guide complet : references/sync-host.md
createClerkClient() pour Vanilla JS / Service Workers
Importez depuis @clerk/chrome-extension/client (pas @clerk/chrome-extension).
Service worker d'arrière-plan (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] Erreur :', JSON.stringify(error))
sendResponse({ token: null })
})
return true
})
Le drapeau background: true maintient les sessions à jour même lorsque le popup/side panel est fermé. Sans lui, les jetons expirent après 60 secondes.
Popup avec 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()
})
Guide complet : references/create-clerk-client.md
Extension Headless (sans popup, sans side panel)
Pour les extensions qui s'exécutent entièrement en arrière-plan et se synchronisent avec une application web.
Utilise syncHost + createClerkClient avec background: true pour lire l'état d'authentification depuis les cookies de l'application web.
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
}
Nécessite host_permissions pour le domaine du sync host dans package.json.
Guide complet : references/headless-extension.md
Scripts de contenu
Les scripts de contenu s'exécutent dans un monde JavaScript isolé injecté dans les pages web. Clerk ne peut pas être utilisé directement — les restrictions d'origine l'empêchent.
Utilisez le passage de messages pour demander l'état d'authentification au service worker d'arrière-plan :
// 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
// utiliser le jeton pour des appels API authentifiés
}
main()
Guide complet : references/content-scripts.md
ID CRX Stable
Sans clé épinglée, Chrome dérive l'ID CRX d'une clé aléatoire lors de la construction. Cela tourne à chaque reconstruction, brisant les origines autorisées.
Option A — Plasmo Itero (recommandé) :
- Visitez Plasmo Itero Generate Keypairs
- Cliquez sur "Generate KeyPairs" — sauvegardez la clé privée en toute sécurité, copiez la clé publique et l'ID CRX
Option B — OpenSSL :
openssl genrsa -out key.pem 2048
# Utilisez Plasmo Itero pour convertir ou extraire la clé publique au bon format
.env.chrome:
CRX_PUBLIC_KEY="<CLÉ PUBLIQUE d'Itero>"
package.json:
{
"manifest": {
"key": "$CRX_PUBLIC_KEY",
"permissions": ["cookies", "storage"],
"host_permissions": [
"http://localhost/*",
"$CLERK_FRONTEND_API/*"
]
}
}
Ajoutez chrome-extension://VOTRE_ID_CRX_STABLE dans le tableau de bord Clerk > Origines autorisées.
Cache de jetons (persister après la fermeture du popup)
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}>
| Type de stockage | Portée | Effacement |
|---|---|---|
chrome.storage.local | Appareil | Désinstallation ou effacement manuel |
chrome.storage.session | Session | Fermeture du navigateur |
chrome.storage.sync | Tous les appareils | Désinstallation (limité en taille, 8 Ko) |
localStorage | Popup uniquement | Fermeture du popup — ne pas utiliser pour l'authentification |
Pièges courants
| Symptôme | Cause | Correctif |
|---|---|---|
| Boucle de redirection lors de la connexion | URL CRX manquante dans les propriétés de ClerkProvider | Définissez afterSignOutUrl, signInFallbackRedirectUrl |
| Bouton OAuth ne fonctionne pas | OAuth non pris en charge dans le popup | Utilisez syncHost pour déléguer à l'application web |
| État d'authentification obsolète après connexion à l'application web | syncHost non configuré | Ajoutez la propriété syncHost + host_permissions |
| Side panel affiche déconnecté après connexion web | Limitation connue | L'utilisateur doit fermer et rouvrir le side panel |
| L'arrière-plan ne peut pas obtenir de jeton après 60 s | Session expirée, pas d'actualisation en arrière-plan | Utilisez createClerkClient({ background: true }) |
| Le script de contenu ne peut pas accéder à Clerk | Monde isolé + restrictions d'origine | Utilisez le passage de messages au service worker d'arrière-plan |
| L'authentification se brise après reconstruction | ID CRX changé | Configurez une clé stable via .env.chrome |
Variable PLASMO_PUBLIC_ non définie | Mauvais fichier d'environnement | Utilisez .env.development, pas .env |
| Erreurs de protection anti-bot | Cloudflare non pris en charge dans les extensions | Désactivez la protection anti-bot dans le tableau de bord Clerk |
| Le cache de jetons ne persiste pas | Utilisation de localStorage dans le popup | Utilisez chrome.storage.local ou passez la propriété tokenCache |
Exigences du plan
| Fonctionnalité | Plan |
|---|---|
| Authentification popup de base (e-mail/mot de passe, OTP) | Gratuit |
| Passkeys | Gratuit |
| syncHost | Nécessite Pro (domaine personnalisé) |
| OAuth via syncHost | Pro + OAuth configuré sur l'application web |
| SAML via syncHost | Enterprise |
| Protection anti-bot | N/A — doit être désactivée pour les extensions |
Voir aussi
clerk-setup— Installation initiale de Clerkclerk-custom-ui— Flux personnalisés et apparence