security-prompts-auth

name	security-prompts-auth
description	Authentication and authorization prompt templates for RBAC implementation, permissions systems, ownership verification, and authorization testing. Use when setting up roles, implementing access control, or testing authorization logic. Triggers include "RBAC", "role-based access", "permissions", "ownership", "authorization", "access control", "user roles", "auth testing".

Auth & Authorization Security Templates

Purpose

This skill provides authentication and authorization prompt templates for implementing secure access control systems. Use these templates to set up role-based access control (RBAC), granular permissions, ownership verification, and comprehensive authorization testing.

Available Templates

01: RBAC Implementation

File: 01_rbac_implementation.md When to use: First time adding roles (user, premium, admin) Time: 60 minutes

Implementation Coverage:

• Server-side role storage
• Clerk publicMetadata integration
• Webhook-based role assignment
• Role-based route protection
• Middleware enforcement
• Role checking utilities

Roles Implemented:

• user (default) - Basic authenticated access
• premium (paid) - Enhanced features via Clerk Billing
• admin (staff) - Full system access

Trigger keywords: "RBAC", "role-based access", "user roles", "implement roles", "setup roles", "add roles", "role system"

Use case: Initial authorization setup, multi-tier application, SaaS with subscription tiers

Output: Complete RBAC system with Clerk integration

---

02: Permissions System

File: 02_permissions.md When to use: Granular permission system beyond basic roles Time: 90 minutes

Implementation Coverage:

• Fine-grained permissions
• Permission groups
• Resource-level access
• Permission inheritance
• Dynamic permission checks
• Permission management UI

Permission Examples:

• users.read, users.write, users.delete
• posts.create, posts.edit, posts.publish
• admin.dashboard, admin.settings

Trigger keywords: "permissions", "permission system", "granular access", "fine-grained permissions", "permission management", "resource permissions"

Use case: Enterprise applications, complex access requirements, team collaboration tools

Output: Comprehensive permission system with management interface

---

03: Ownership Verification

File: 03_ownership.md When to use: Resource ownership checks (users can only modify their own data) Time: 30 minutes

Implementation Coverage:

• Ownership validation
• User-resource relationship checks
• Authorization errors
• Multi-owner scenarios
• Delegation patterns

Security Focus:

• Prevent horizontal privilege escalation
• Verify user owns the resource
• Handle shared resources
• Team/organization ownership

Trigger keywords: "ownership", "ownership check", "resource ownership", "user owns", "own data only", "verify ownership", "prevent user accessing others data"

Use case: Profile editing, document management, any user-specific resources

Output: Ownership verification utilities and endpoint protection

---

04: Authorization Testing

File: 04_auth_testing.md When to use: Comprehensive authorization testing Time: 60 minutes

Test Coverage:

• Role-based access tests
• Permission verification tests
• Ownership check tests
• Negative authorization tests
• Cross-user access prevention
• Privilege escalation tests

Test Scenarios:

• User cannot access admin routes
• User cannot modify other users' data
• Premium features blocked for free users
• Unauthenticated requests rejected
• Invalid role assignments rejected

Trigger keywords: "auth testing", "authorization tests", "test permissions", "test RBAC", "test access control", "authorization test suite"

Use case: Continuous testing, CI/CD integration, security validation

Output: Complete authorization test suite

---

Usage Pattern

1. Identify Authorization Need

First-time setup (no auth beyond Clerk): → 01_rbac_implementation.md

Need granular control: → 02_permissions.md

User-specific resources: → 03_ownership.md

Verify authorization: → 04_auth_testing.md

2. Sequential Implementation

Recommended order:

Step 1: RBAC (Foundation)
→ Use: 01_rbac_implementation.md

Step 2: Ownership (User Resources)
→ Use: 03_ownership.md

Step 3: Permissions (If Needed)
→ Use: 02_permissions.md

Step 4: Testing (Always)
→ Use: 04_auth_testing.md

3. Load Template

Read: .claude/skills/security/security-prompts/auth-authorization/[number]_[name].md

4. Customize for Application

Replace in template:

• [role names] with your roles
• [permission names] with your permissions
• [resource types] with your data models
• [access matrix] with your requirements

5. Present Implementation Plan

I'll implement [AUTHORIZATION_TYPE] using the auth template.

**What we'll set up**:
- [List from template]

**How it integrates with Clerk**:
- [Clerk-specific details]

**Testing strategy**:
- [Testing approach]

**Estimated time**: [From template]

Let me customize the template for your application...

Common Authorization Patterns

Pattern 1: Basic RBAC

Application: Blog with user/admin roles

Implementation:
→ 01_rbac_implementation.md

Role Matrix:
- user: Read posts, comment, manage own comments
- admin: All user access + create/edit/delete posts, moderate comments

Testing:
→ 04_auth_testing.md

Pattern 2: SaaS with Tiers

Application: SaaS tool with free/premium/enterprise

Implementation:
→ 01_rbac_implementation.md

Role Matrix:
- free: Basic features, 10 projects limit
- premium: Advanced features, unlimited projects
- enterprise: All features + team management

Integration:
→ Clerk Billing webhooks set role based on subscription

Testing:
→ 04_auth_testing.md

Pattern 3: User Resources

Application: Profile management

Implementation:
Step 1: RBAC for basic roles
→ 01_rbac_implementation.md

Step 2: Ownership for profile editing
→ 03_ownership.md

Verification:
- User A cannot edit User B's profile
- Admins can edit any profile
- Users can edit their own profile

Testing:
→ 04_auth_testing.md

Pattern 4: Enterprise Permissions

Application: Team collaboration tool

Implementation:
Step 1: RBAC for base roles
→ 01_rbac_implementation.md

Step 2: Granular permissions
→ 02_permissions.md

Step 3: Ownership for resources
→ 03_ownership.md

Permission Matrix:
- Owner: All permissions
- Admin: Most permissions, cannot delete workspace
- Member: View and edit, cannot manage team
- Guest: View only

Testing:
→ 04_auth_testing.md

Integration with Feature Templates

Authenticated Endpoints

Step 1: Setup RBAC
→ auth-authorization/01_rbac_implementation.md

Step 2: Implement feature with auth
→ prompt-engineering/02_authenticated_endpoint.md

Step 3: Add ownership checks
→ auth-authorization/03_ownership.md

Step 4: Test authorization
→ auth-authorization/04_auth_testing.md

Admin Features

Step 1: Setup RBAC (if not exists)
→ auth-authorization/01_rbac_implementation.md

Step 2: Implement admin endpoints
→ prompt-engineering/04_admin_action.md

Step 3: Test admin access
→ auth-authorization/04_auth_testing.md

Step 4: Review security
→ threat-modeling/04_code_review.md

Clerk Integration

All templates integrate with Clerk:

Role Storage: publicMetadata.role

// Read from session
const { sessionClaims } = auth();
const role = sessionClaims?.publicMetadata?.role;

Webhook Assignment:

// In convex/http.ts or app/api/webhooks/clerk/route.ts
await clerkClient.users.updateUserMetadata(userId, {
  publicMetadata: { role: "user" }
});

Middleware Protection:

// In middleware.ts
const role = auth().sessionClaims?.publicMetadata?.role;
if (role !== "admin" && pathname.startsWith("/admin")) {
  return Response.redirect("/unauthorized");
}

Permission Storage (if using 02_permissions.md):

publicMetadata: {
  role: "user",
  permissions: ["posts.read", "posts.create", "comments.create"]
}

Best Practices

1. Server-Side Only

Always verify on server:

// ✅ Good - server-side check
export async function DELETE(req: Request) {
  const { userId } = auth();
  const role = auth().sessionClaims?.publicMetadata?.role;

  if (role !== "admin") {
    return new Response("Forbidden", { status: 403 });
  }
  // Delete logic
}

// ❌ Bad - client could bypass
if (userRole === "admin") {
  deleteButton.disabled = false;
}

2. Default Deny

Require explicit permission:

// ✅ Good - default deny
if (role === "admin" || role === "moderator") {
  // Allow
} else {
  return new Response("Forbidden", { status: 403 });
}

// ❌ Bad - default allow
if (role === "guest") {
  return new Response("Forbidden", { status: 403 });
}
// Continues without check

3. Test Negative Cases

Always test rejection:

// Test user cannot access admin
test("non-admin cannot delete posts", async () => {
  const response = await DELETE("/api/posts/123", {
    headers: { Authorization: `Bearer ${userToken}` }
  });
  expect(response.status).toBe(403);
});

4. Log Authorization Failures

Audit access attempts:

if (role !== "admin") {
  await logSecurityEvent({
    event: "unauthorized_admin_access_attempt",
    userId,
    resource: pathname,
    timestamp: new Date()
  });
  return new Response("Forbidden", { status: 403 });
}

Agent Usage

When Implementing Features

Agent: "User needs to edit their profile"

Response: "First check if RBAC exists. If not, use:
.claude/skills/security/security-prompts/auth-authorization/01_rbac_implementation.md

Then for the profile endpoint, use:
.claude/skills/security/security-prompts/prompt-engineering/02_authenticated_endpoint.md

Add ownership verification with:
.claude/skills/security/security-prompts/auth-authorization/03_ownership.md"

When Reviewing Security

Agent: "Review authorization implementation"

Response: "Check against template:
.claude/skills/security/security-prompts/auth-authorization/04_auth_testing.md

Verify:
- All routes have role checks
- Server-side enforcement
- Default deny pattern
- Negative test cases exist"

Common Pitfalls

❌ Client-Side Only Checks

Problem: Hiding UI elements without server enforcement

// ❌ Bad
{role === "admin" && <DeleteButton />}

Solution: Always enforce server-side

// ✅ Good
{role === "admin" && <DeleteButton />}

// On server
export async function DELETE(req: Request) {
  const role = auth().sessionClaims?.publicMetadata?.role;
  if (role !== "admin") return Response.json({error: "Forbidden"}, {status: 403});
}

❌ Trusting Client Claims

Problem: Reading role from request body

// ❌ Bad
const { role } = await req.json();
if (role === "admin") { /* allow */ }

Solution: Read from server session

// ✅ Good
const role = auth().sessionClaims?.publicMetadata?.role;
if (role === "admin") { /* allow */ }

❌ Missing Ownership Checks

Problem: Only checking authentication

// ❌ Bad
export async function PATCH(req: Request, { params }: { params: { id: string } }) {
  const { userId } = auth();
  if (!userId) return Response.json({error: "Unauthorized"}, {status: 401});

  // Updates ANY post, even if user doesn't own it
  await db.posts.update(params.id, data);
}

Solution: Verify ownership

// ✅ Good
export async function PATCH(req: Request, { params }: { params: { id: string } }) {
  const { userId } = auth();
  if (!userId) return Response.json({error: "Unauthorized"}, {status: 401});

  const post = await db.posts.get(params.id);
  if (post.authorId !== userId) {
    return Response.json({error: "Forbidden"}, {status: 403});
  }

  await db.posts.update(params.id, data);
}

Testing Strategy

Unit Tests

Role checks:

describe("Role-based access", () => {
  test("admin can access admin routes", async () => {
    // Test with admin token
  });

  test("user cannot access admin routes", async () => {
    // Test with user token, expect 403
  });
});

Integration Tests

Full flow:

describe("Profile editing", () => {
  test("user can edit own profile", async () => {
    // Create user, edit profile, verify success
  });

  test("user cannot edit other user profile", async () => {
    // User A tries to edit User B, expect 403
  });
});

E2E Tests

Real scenarios:

• Sign up → assigned user role → verify limited access
• Subscribe → role changes to premium → verify enhanced access
• Admin promotes user → verify role change → verify new access

Related Skills

Parent Skill:

• security-prompts - Main directory with all template categories (engineering, threat-modeling, controls, auth)

Implementation Skills (referenced by templates):

• auth-security - Clerk authentication implementation
• clerk - Clerk integration patterns

Note: For other template categories (implementation, threat modeling, simple controls), see the parent security-prompts skill

Version History

v1.0 (2025-10-23): Initial skill creation

• Converted 4 auth/authorization templates
• Added Clerk integration guidance
• Added common pitfalls and best practices
• Integration patterns with other templates

---

Note: Authentication (who you are) is handled by Clerk. These templates focus on authorization (what you can do). Always implement both.