Authentication

APSO follows a “Bring Your Own Auth” (BYOA) philosophy, giving you flexibility in how you implement authentication.

Overview

Authentication Flow

Key Concepts

Multi-Tenancy

APSO enforces organization-level data isolation:

// User context from authentication
interface UserContext {
  id: string;
  email: string;
  organizationId: string;  // Required for multi-tenancy
  roles?: string[];
}

JWT Tokens

APSO backends expect JWT tokens with specific claims:

{
  "sub": "user-uuid",
  "email": "user@example.com",
  "organizationId": "org-uuid",
  "iat": 1699000000,
  "exp": 1699086400
}

Auth Guard

All protected routes use the auth guard:

// src/common/guards/auth.guard.ts
@Injectable()
export class AuthGuard implements CanActivate {
  async canActivate(context: ExecutionContext): Promise<boolean> {
    const request = context.switchToHttp().getRequest();
    const token = this.extractToken(request);
 
    if (!token) {
      throw new UnauthorizedException();
    }
 
    const payload = await this.verifyToken(token);
    request.user = payload;
 
    return true;
  }
}

Recommended Approach

For New Projects

Use Better Auth for a complete, production-ready solution:

• User registration and login
• Password reset and email verification
• OAuth providers (Google, GitHub, etc.)
• Session management
• Two-factor authentication

For Existing Auth

Use BYOA to integrate your current authentication:

• Auth0
• Firebase Auth
• Supabase Auth
• Clerk
• Custom JWT issuers

For Service-to-Service

Use API Keys for machine clients:

• Background jobs
• External integrations
• Automated scripts

Quick Start

1. Choose an Approach

# Option A: Better Auth (recommended)
npm install better-auth
 
# Option B: Use existing auth
# Configure JWT verification

2. Configure Environment

# .env
JWT_SECRET=your-secret-key
# Or for external auth
AUTH_ISSUER=https://your-auth-provider.com
AUTH_AUDIENCE=your-api-identifier

3. Protect Routes

Routes are protected by default:

@Controller('projects')
@UseGuards(AuthGuard)  // Applied to all routes
export class ProjectsController {
  @Get()
  findAll(@CurrentUser() user: User) {
    // user.organizationId is automatically available
    return this.service.findAll(user.organizationId);
  }
}

Security Best Practices

Token Handling

• Store tokens securely (httpOnly cookies preferred)
• Use short expiration times (15-60 minutes)
• Implement token refresh mechanisms
• Never log or expose tokens

Organization Isolation

• Always scope queries by organizationId
• Validate organization access in services
• Use guards for role-based access

API Security

• Use HTTPS in production
• Implement rate limiting
• Enable CORS restrictions
• Validate all inputs

Related

• Better Auth →
• BYOA →
• API Keys →