Clerk Authentication Skill

Clerk Authentication Skill

Comprehensive guide for implementing and testing Clerk authentication, with special focus on Astro SSR integration and Playwright E2E testing.

Key Concepts

Clerk Architecture in Astro

┌─────────────────────────────────────────────────────────────┐
│                    Browser (Client)                          │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  Clerk Frontend SDK (@clerk/​astro)                  │    │
│  │  - Manages client-side session state                │    │
│  │  - Provides <SignIn>, <UserButton> components       │    │
│  │  - Sets localStorage tokens                         │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                    Server (Astro SSR)                        │
│  ┌─────────────────────────────────────────────────────┐    │
│  │  clerkMiddleware (@clerk/​astro/​server)              │    │
│  │  - Validates HTTPOnly session cookies               │    │
│  │  - Runs BEFORE any custom middleware logic          │    │
│  │  - Sets Astro.locals.auth()                         │    │
│  └─────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────┘

Critical Understanding: Clerk's middleware validates sessions at the wrapper level BEFORE your callback executes. You cannot bypass authentication inside the middleware callback.

Session Types

E2E Testing with Playwright

The Problem

@clerk/​testing's programmatic clerk.signIn() creates client-side sessions only. These are NOT recognized by Clerk's server-side middleware in Astro/​Next.js SSR applications.

// ❌ This creates client-side session only - won't pass middleware
await clerk.signIn({
  page,
  signInParams: { strategy: 'password', identifier: email, password }
});
// User appears logged in (UserButton shows), but server redirects to /​sign-in

The Solution: UI-Based Sign-In with Test Emails

Use actual UI sign-in flow with Clerk's +clerk_test email feature:

// ✅ This creates real server-validated session
// 1. Navigate to sign-in with testing token (bypasses bot detection)
await page.goto(`/​sign-in?__clerk_testing_token=${testingToken}`);

// 2. Fill in email (MUST contain +clerk_test)
await page.fill('input[name="identifier"]', '[email protected]');
await page.click('button:has-text("Continue")');

// 3. Fill in password
await page.fill('input[type="password"]', password);
await page.click('button:has-text("Continue")');

// 4. Handle device verification with magic code
// See: clerk.com/​docs/​guides/​development/​testing/​test-emails-and-phones
await enterVerificationCode(page, CLERK_TEST_VERIFICATION_CODE);

Test Email Magic Code (CRITICAL for E2E/​CI)

⚠️ CRITICAL: Test user emails MUST contain +clerk_test for automated testing to work. Without this suffix, Clerk requires real email verification which breaks CI/​CD pipelines.

Any email with +clerk_test suffix is treated specially by Clerk:

• No actual email sent for verification
• Clerk's magic test code always works for any verification step
• Real users unaffected - normal verification for non-test emails
• Works in both development and production Clerk instances

Valid test email formats:

• [email protected] ✅
• [email protected] ✅
• [email protected] ✅

Invalid for automated testing:

• [email protected] ❌ (no clerk_test in address)
• [email protected] ❌ (must use + plus-addressing)
• [email protected] ❌ (must use +clerk_test suffix format)

Get the verification code: See Clerk's Test Emails Documentation for the magic verification code that works with +clerk_test emails.

💡 CI/​CD Tip: Store test user emails in environment variables/​secrets. Ensure all contain +clerk_test:

[email protected]
[email protected]

Testing Token

Get a testing token to bypass bot detection:

import { createClerkClient } from '@clerk/​backend';

const clerkClient = createClerkClient({
  secretKey: process.env.CLERK_SECRET_KEY,
});

const token = await clerkClient.testingTokens.createTestingToken();
// Use as: /​sign-in?__clerk_testing_token=${token.token}

Complete E2E Auth Setup

// tests/​e2e/​global-setup.ts
import { createClerkClient } from '@clerk/​backend';

const clerkClient = createClerkClient({
  secretKey: process.env.CLERK_SECRET_KEY,
});

async function authenticateUser(page, email, password, storagePath) {
  // 1. Get testing token
  const { token } = await clerkClient.testingTokens.createTestingToken();

  // 2. Navigate with token
  await page.goto(`/​sign-in?__clerk_testing_token=${token}`);

  // 3. Fill email (must have +clerk_test)
  await page.fill('input[name="identifier"]', email);
  await page.click('button:has-text("Continue")');

  // 4. Fill password
  await page.fill('input[type="password"]', password);
  await page.click('button:has-text("Continue")');

  // 5. Handle device verification (code from Clerk docs)
  // See: clerk.com/​docs/​guides/​development/​testing/​test-emails-and-phones
  await page.waitForTimeout(2000);
  if (page.url().includes('factor-two')) {
    const code = process.env.CLERK_TEST_CODE; // From Clerk docs
    const inputs = page.locator('input[inputmode="numeric"]');
    for (let i = 0; i < 6; i++) {
      await inputs.nth(i).fill(code[i]);
    }
  }

  // 6. Wait for redirect and save session
  await page.waitForURL(url => !url.includes('/​sign-in'));
  await page.context().storageState({ path: storagePath });
}

Middleware Configuration

Basic Protected Routes

// src/​middleware.ts
import { clerkMiddleware, createRouteMatcher } from "@clerk/​astro/​server";

const isPublicRoute = createRouteMatcher([
  "/",
  "/​sign-in(.*)",
  "/​sign-up(.*)",
  "/​api/​webhooks/(.*)",
]);

export const onRequest = clerkMiddleware((auth, context) => {
  const { userId } = auth();

  if (isPublicRoute(context.request)) {
    return; // Allow public routes
  }

  if (!userId) {
    return auth().redirectToSignIn();
  }
});

Role-Based Access

// Check role inside middleware callback
export const onRequest = clerkMiddleware(async (auth, context) => {
  const { userId } = auth();

  if (!userId) {
    return auth().redirectToSignIn();
  }

  // Check admin routes
  if (context.request.url.includes('/​admin')) {
    const member = await memberQueries.findByClerkId(userId);
    if (member?.role !== 'admin') {
      return context.redirect('/​unauthorized');
    }
  }
});

Common Patterns

Get Current User in Astro Pages

// src/​pages/​dashboard.astro
---
const auth = Astro.locals.auth();
const { userId, sessionClaims } = auth;

if (!userId) {
  return Astro.redirect('/​sign-in');
}

// Get user data from your database
const member = await memberQueries.findByClerkId(userId);
---

Client-Side Auth Check

// For pre-rendered pages that need client-side auth
<script>
  function checkAuth() {
    if (window.Clerk?.loaded && !window.Clerk.user) {
      window.Clerk.redirectToSignIn({ redirectUrl: window.location.href });
    }
  }

  // Poll until Clerk loads
  const interval = setInterval(() => {
    if (window.Clerk?.loaded) {
      clearInterval(interval);
      checkAuth();
    }
  }, 100);
</​script>

Webhook Handling

// src/​pages/​api/​webhooks/​clerk.ts
import { Webhook } from 'svix';

export const POST: APIRoute = async ({ request }) => {
  const payload = await request.text();
  const headers = Object.fromEntries(request.headers);

  const wh = new Webhook(process.env.CLERK_WEBHOOK_SECRET);
  const event = wh.verify(payload, headers);

  switch (event.type) {
    case 'user.created':
      // Create member record
      break;
    case 'user.updated':
      // Sync user data
      break;
  }

  return new Response('OK', { status: 200 });
};

Troubleshooting

"Session not recognized by server"

Cause: Using @clerk/​testing programmatic sign-in which only creates client-side sessions.

Fix: Use UI-based sign-in flow with testing tokens:

await page.goto(`/​sign-in?__clerk_testing_token=${token}`);
// Then fill in the actual form

"Bot traffic detected"

Cause: Clerk's bot protection blocking automated requests.

Fix: Include testing token in URL:

const token = await clerkClient.testingTokens.createTestingToken();
await page.goto(`/​sign-in?__clerk_testing_token=${token.token}`);

"Device verification required"

Cause: Clerk requires email verification from new devices.

Fix: Use +clerk_test email suffix with Clerk's magic test code:

// Email MUST contain +clerk_test for magic code to work
const email = '[email protected]';
// Get the code from: clerk.com/​docs/​guides/​development/​testing/​test-emails-and-phones

Common mistake: Using emails like [email protected] without clerk_test - the magic code won't work!

"redirectToSignIn not working"

Cause: Page is pre-rendered (SSG) so server-side redirect doesn't work.

Fix: Use client-side redirect:

// In page frontmatter
export const prerender = true; // or remove for SSR

// In client script
if (!window.Clerk?.user) {
  window.Clerk?.redirectToSignIn();
}

Middleware Not Running

Cause: Route might be pre-rendered or middleware configuration issue.

Fix: Ensure SSR mode for protected routes:

// astro.config.mjs
export default defineConfig({
  output: 'server', // or 'hybrid'
});

CI/​CD Integration

GitHub Actions Setup

# .github/​workflows/​e2e-auth.yml
- name: Run authenticated E2E tests
  env:
    CLERK_SECRET_KEY: ${{ secrets.TEST_CLERK_SECRET_KEY }}
    # CRITICAL: Emails MUST contain +clerk_test
    TEST_ADMIN_EMAIL: ${{ secrets.TEST_ADMIN_EMAIL }}
    TEST_ADMIN_PASSWORD: ${{ secrets.TEST_ADMIN_PASSWORD }}
  run: npx playwright test

Secret Configuration Checklist

1. ✅ Create test users in Clerk with +clerk_test emails
2. ✅ Set passwords for test users (Clerk Dashboard → Users)
3. ✅ Store email/​password pairs as GitHub Secrets
4. ✅ Verify emails contain +clerk_test substring
5. ✅ Test locally before pushing to CI

Syncing Local to CI

If your local .env works but CI fails, sync your secrets:

# Script to update GitHub Secrets from .env
source .env
gh secret set TEST_ADMIN_EMAIL --body "$TEST_ADMIN_EMAIL"
gh secret set TEST_ADMIN_PASSWORD --body "$TEST_ADMIN_PASSWORD"
# Repeat for other test users...

Common CI Failure: "Verification code failed"

Symptom: Local tests pass, CI tests fail at device verification step.

Root Cause: GitHub Secrets have emails WITHOUT +clerk_test:

# ❌ Wrong - magic code won't work
[email protected]

# ✅ Correct - magic code will work
[email protected]

Fix: Update GitHub Secrets with correctly formatted emails.

Environment Variables

# Required for Clerk
PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxx
CLERK_SECRET_KEY=sk_test_xxx
CLERK_WEBHOOK_SECRET=whsec_xxx

# For E2E testing - MUST contain +clerk_test
[email protected]
TEST_ADMIN_PASSWORD=xxx
[email protected]
TEST_MEMBER_PASSWORD=xxx

Package Reference

References

• Clerk Astro Integration
• Clerk Testing with Playwright
• Test Emails and Phones
• Testing Tokens
• Clerk Middleware

---

Last updated: December 22, 2025 Added: CI/​CD integration patterns and +clerk_test email requirements