Skip to main content

ADR-003: OAuth Authentication Strategy

Status: Accepted Date: December 17, 2025 Deciders: CODITECT Architecture Team

Context​

Google APIs require OAuth 2.0 authentication. We need to decide on authentication patterns that support both individual users and organizational deployments.

Decision​

We will support two authentication modes:

1. User OAuth (Default)​

  • Standard OAuth 2.0 authorization code flow
  • User grants access to their calendar and meetings
  • Tokens stored securely per-user
  • Best for: Individual users, small teams

2. Service Account with Domain-Wide Delegation​

  • Service account authenticates on behalf of users
  • Requires Google Workspace admin approval
  • Single credential manages all users in domain
  • Best for: Enterprise deployments

Authentication Flow​

User OAuth:
User → Consent Screen → Auth Code → Token Exchange → Access Token

Service Account:
Service Account → Domain Delegation → Impersonation → Access Token

Token Management​

@dataclass
class TokenStorage:
    access_token: str
    refresh_token: str
    expires_at: datetime
    scopes: List[str]

    def needs_refresh(self) -> bool:
        return datetime.utcnow() >= self.expires_at - timedelta(minutes=5)

Security Requirements​

  1. Token Encryption: AES-256 at rest
  2. Refresh Token Protection: Stored separately from access tokens
  3. Scope Minimization: Request only required scopes
  4. Token Rotation: Refresh tokens rotated on use

Consequences​

Positive​

  • Supports both individual and enterprise use cases
  • Standard OAuth flow is well-understood
  • Service accounts enable automation

Negative​

  • Service account setup requires admin involvement
  • Token management adds complexity
  • Must handle token refresh failures gracefully

Required Scopes​

# Minimum required
https://www.googleapis.com/auth/calendar.events
https://www.googleapis.com/auth/meetings.space.readonly

# Full functionality
https://www.googleapis.com/auth/meetings.space.created
https://www.googleapis.com/auth/meetings.space.settings
https://www.googleapis.com/auth/drive.readonly

References​