Authentication Architecture

​

Overview

​

Technology Stack

​

Core Components

​

Authentication Flow

​

Password-Based Authentication

​

Email Verification And Password Reset Link Flows

• code method: user receives a 6-digit code and submits it through the app.
• link method: user clicks an email link that always opens an InsForge backend endpoint first.
• redirectTo must be included in allowedRedirectUrls before link-based flows can use it.
• If allowedRedirectUrls is empty, InsForge allows all redirects for smoother development UX. Do not rely on that behavior in production.

• The email link opens GET /api/auth/email/verify-link?token=...
• InsForge verifies the token on the backend
• InsForge redirects the browser to the stored redirectTo
• Query params:
  • insforge_status: success or error
  • insforge_type: always verify_email
  • insforge_error: present only on error
• Recommended: use your sign-in page as redirectTo, then show a success message and ask the user to sign in with their email and password

• The email link opens GET /api/auth/email/reset-password-link?token=...
• InsForge validates the token on the backend
• InsForge redirects the browser to the stored redirectTo
• Query params:
  • token: present only when reset is ready
  • insforge_status: ready or error
  • insforge_type: always reset_password
  • insforge_error: present only on error
• Your app should render the reset form only when insforge_status=ready and token is present

​

Session Recovery

• Web clients store the refresh token in an httpOnly cookie
• For browser apps, call auth.getCurrentUser() during startup. The SDK will use the httpOnly refresh cookie automatically when it can refresh the session
• Server, mobile, and other non-browser clients do not get that automatic cookie-based refresh and should call the refresh endpoint explicitly

​

OAuth Flow

​

JWT Token Structure

​

Token Payload

{
  "sub": "user_id_uuid",
  "email": "user@example.com",
  "role": "authenticated",
  "iat": 1704067200,
  "exp": 1704672000,
  "iss": "insforge",
  "aud": "insforge-api"
}

​

Token Claims

​

Security Features

​

API Endpoints

​

Authentication Endpoints

​

OAuth Endpoints

​

Admin Endpoints

​

OAuth Provider Configuration

​

Custom OAuth Providers

• name (display label)
• key (unique lowercase key, e.g. okta-company)
• discovery endpoint (.well-known/openid-configuration URL)
• client ID
• client secret (stored through the existing secret-management flow)

​

Example: Google OAuth 2.0

• Authorization URL: https://accounts.google.com/o/oauth2/v2/auth
• Token URL: https://oauth2.googleapis.com/token
• Scopes: openid, email, profile
• Required: Client ID, Client Secret, Redirect URI

​

Example: GitHub OAuth

• Authorization URL: https://github.com/login/oauth/authorize
• Token URL: https://github.com/login/oauth/access_token
• Scopes: read:user, user:email
• Required: Client ID, Client Secret, Redirect URI

​

Token Validation

​

Validation Steps

1. Format Check: Verify JWT structure (header.payload.signature)
2. Signature Verification: Validate with RSA public key
3. Expiry Check: Ensure token hasn’t expired
4. Issuer/Audience: Verify iss and aud claims
5. User Lookup: Check user exists in auth.users table
6. User Status: Ensure user account is active

​

Middleware Flow

// Simplified validation flow (stateless)
async function validateToken(token) {
  // 1. Decode and verify JWT
  const decoded = jwt.verify(token, publicKey, {
    algorithms: ['RS256'],
    issuer: 'insforge',
    audience: 'insforge-api'
  });
  
  // 2. Check user exists (optional)
  const user = await db.query(
    'SELECT * FROM auth.users WHERE id = $1',
    [decoded.sub]
  );
  
  // 3. Return user context from JWT
  return {
    userId: decoded.sub,
    email: decoded.email,
    role: decoded.role
  };
}

​

Security Best Practices

​

Environment Variables

​

SDK References

​

UI Components (TypeScript)