claude-skills-reference/product-team/saas-scaffolder/references/auth-billing-guide.md

Authentication & Billing Implementation Guide

Overview

Authentication and billing are foundational SaaS capabilities that affect every user interaction. This guide covers implementation patterns, security best practices, and common pitfalls for both systems.

Authentication

OAuth2 / OpenID Connect (OIDC) Flows

Authorization Code Flow (Recommended for Web Apps)

1. Redirect user to authorization server (/authorize)
2. User authenticates and consents
3. Authorization server redirects back with authorization code
4. Backend exchanges code for tokens (/token)
5. Store tokens server-side, issue session cookie

Use when: Server-rendered apps, traditional web applications

Authorization Code Flow + PKCE (Recommended for SPAs and Mobile)

1. Generate code verifier and code challenge
2. Redirect with code challenge
3. User authenticates
4. Exchange code + code verifier for tokens
5. Store tokens securely (memory for SPAs, secure storage for mobile)

Use when: Single-page applications, mobile apps, any public client

Client Credentials Flow

1. Service authenticates with client_id and client_secret
2. Receives access token for service-to-service calls

Use when: Backend service-to-service communication, no user context

JWT Best Practices

Token Structure:

• Access token: Short-lived (15-60 minutes), contains user claims
• Refresh token: Longer-lived (7-30 days), stored securely, used to get new access tokens
• ID token: Contains user identity claims, used by frontend only

Security Guidelines:

• Sign tokens with RS256 (asymmetric) for distributed systems
• Include iss, aud, exp, iat, sub standard claims
• Never store sensitive data in JWT payload (it is base64-encoded, not encrypted)
• Validate all claims on every request
• Implement token rotation for refresh tokens
• Maintain a deny-list for revoked tokens (or use short-lived access tokens)
• Set httpOnly, secure, sameSite=strict for cookie-stored tokens

Common Pitfalls:

• Using HS256 in distributed systems (shared secret)
• Storing JWTs in localStorage (XSS vulnerable)
• Not validating aud claim (token reuse attacks)
• Excessively long access token lifetimes

RBAC vs ABAC

Role-Based Access Control (RBAC)

• Assign users to roles (Admin, Editor, Viewer)
• Roles have fixed permission sets
• Simple to implement and understand
• Works well for most SaaS applications

Implementation:

User -> Role -> Permissions
john@acme.com -> Admin -> [create, read, update, delete, manage_users]
jane@acme.com -> Editor -> [create, read, update]
bob@acme.com -> Viewer -> [read]

Attribute-Based Access Control (ABAC)

• Decisions based on user attributes, resource attributes, environment
• More flexible but more complex
• Required for fine-grained access control

Use ABAC when:

• Access depends on resource ownership (users can edit their own posts)
• Multi-tenant isolation requires tenant-context checks
• Time-based or location-based access rules needed
• Regulatory compliance requires granular audit trails

Social Login Implementation

• Support Google, GitHub, Microsoft at minimum for B2B
• Map social identity to internal user record (by email)
• Handle account linking (same email, different providers)
• Always allow email/password as fallback
• Implement account deduplication strategy

Billing & Subscriptions

Stripe Integration Patterns

Setup Flow

1. Create Stripe Customer on user registration
2. Store stripe_customer_id in your database
3. Use Stripe Checkout for initial payment (PCI-compliant)
4. Store subscription_id for ongoing management
5. Sync plan status via webhooks (source of truth)

Key Stripe Objects

• Customer: Maps to your user/organization
• Product: Maps to your plan tier (Basic, Pro, Enterprise)
• Price: Specific pricing for a product (monthly, annual)
• Subscription: Active billing relationship
• Invoice: Generated per billing cycle
• PaymentIntent: Represents a payment attempt

Subscription Lifecycle

Trial Period

• Offer 7-14 day free trial (no credit card for PLG, card required for sales-led)
• Send reminder emails at 3 days and 1 day before trial ends
• Provide clear upgrade path within the product
• Track trial engagement to predict conversion

Active Subscription

• Sync plan features with entitlement system
• Handle plan upgrades (immediate proration) and downgrades (end of period)
• Support annual billing with discount (typically 15-20%)
• Send receipts and invoice notifications

Payment Failure / Dunning

1. First failure: Retry automatically, notify user
2. Second failure (3 days later): Retry, send warning email
3. Third failure (7 days later): Retry, restrict features
4. Final attempt (14 days): Cancel subscription, move to free tier
5. Win-back: Send recovery emails at 30, 60, 90 days

Churned

• Downgrade to free tier (maintain data for re-activation)
• Track churn reason (survey on cancellation)
• Implement cancellation flow with save offers
• Define data retention policy (90 days typical)

Reactivated

• Allow easy re-subscription from settings
• Restore previous plan and data
• Consider win-back offers (discount for first month back)

Webhook Handling

Critical Webhooks to Handle:

• customer.subscription.created - Activate plan
• customer.subscription.updated - Sync plan changes
• customer.subscription.deleted - Handle cancellation
• invoice.paid - Confirm payment, update status
• invoice.payment_failed - Trigger dunning flow
• checkout.session.completed - Complete signup flow

Webhook Best Practices:

• Verify webhook signature on every request
• Respond with 200 immediately, process asynchronously
• Implement idempotency (handle duplicate events)
• Log all webhook events for debugging
• Set up webhook failure alerts
• Use Stripe CLI for local development testing

PCI Compliance Basics

SAQ-A (Recommended for SaaS)

• Use Stripe.js / Stripe Elements for card collection
• Never touch raw card numbers on your servers
• Card data goes directly from browser to Stripe
• Your servers only handle tokens and customer IDs

Requirements

• Use HTTPS everywhere
• Never log card numbers or CVV
• Use Stripe-hosted payment forms or Elements
• Restrict access to Stripe dashboard (2FA required)
• Regularly rotate API keys
• Document your payment processing flow

Entitlement System Design

Feature Gating Pattern

Check flow:
1. User action requested
2. Look up user's subscription plan
3. Check plan's feature flags / limits
4. Allow or deny with appropriate message

Entitlement Types

• Boolean: Feature on/off (e.g., "SSO enabled")
• Numeric limit: Usage cap (e.g., "10 projects max")
• Tiered: Different capability levels (e.g., "basic/advanced analytics")

Implementation Tips

• Cache entitlements locally (refresh on plan change webhook)
• Show upgrade prompts at limit boundaries (not hard blocks)
• Provide grace periods for brief overages
• Track usage for plan recommendation engine