Skip to content

ADR-0001: Use Google Directory for Single Sign-On (SSO) Authentication

  • Status: Accepted
  • Date: 2025-09-11
  • Authors: Senior Systems Analyst

Context and Problem Statement

The application requires a secure, reliable, and user-friendly authentication system for its corporate users. Building and maintaining a proprietary, password-based authentication system presents significant challenges:

  • Security Risks: Storing user credentials requires robust hashing, salting, and protection against a wide range of attack vectors. A breach could have severe consequences.
  • Development Overhead: A local system necessitates building and maintaining features for password complexity, password resets, account lockout policies, and multi-factor authentication (MFA). This diverts development resources from core business features.
  • Poor User Experience: Corporate users already have a primary set of credentials (their Google Workspace account). Forcing them to create and remember a separate password for this application introduces unnecessary friction and increases the likelihood of password reuse or insecure practices.
  • Administrative Burden: A local system would require administrators to manually create and manage user accounts, increasing operational overhead.

Considered Options

Option 1: Build a Local, Password-Based Authentication System

  • Description: Implement a traditional authentication system within the AuthService. This would involve creating database tables to store user email addresses, password hashes, and salts.
  • Pros:
  • Full control over the authentication process and user data.
  • No external dependencies for the core login functionality.
  • Cons:
  • Significantly higher security burden and risk.
  • Large development and maintenance effort for features like password reset, MFA, etc.
  • Inferior user experience for corporate users.
  • Requires a manual user provisioning workflow.

Option 2: Use Google Directory for SSO Authentication (Chosen)

  • Description: Delegate all user authentication to the corporate Google Directory via the OAuth 2.0 / OpenID Connect (OIDC) protocol. The application will not handle or store user passwords. User accounts will be created automatically in our system on their first successful login (Just-In-Time Provisioning).
  • Pros:
  • Vastly Improved Security: Authentication, MFA, and credential storage are handled by Google's robust and battle-tested infrastructure. Our application's attack surface is significantly reduced.
  • Superior User Experience: Users can log in with a single click using their existing, familiar corporate account.
  • Reduced Development Scope: Eliminates the need to build, test, and maintain password-related features.
  • Automated User Provisioning: Just-In-Time (JIT) provisioning removes the need for manual account creation by administrators.
  • Cons:
  • Hard Dependency: Creates a critical dependency on Google's identity services. An outage at Google could prevent all users from logging in.
  • Less Control: The authentication flow itself (e.g., the look and feel of the login page) is controlled by Google, not by our application.
  • Configuration Overhead: Requires careful management of OAuth 2.0 client credentials and redirect URIs within the Google Cloud Platform console.

Decision

We will exclusively use Google Directory for Single Sign-On (SSO) Authentication (Option 2).

This decision aligns perfectly with our business objectives of enhancing security and streamlining user access. The security benefits of delegating authentication to a trusted identity provider like Google far outweigh the advantages of maintaining full control. Furthermore, the improved user experience and significant reduction in development and maintenance scope allow the team to focus on delivering core business value rather than reinventing a complex and high-stakes security component. The business requirements for this feature are detailed in the User Authentication and Session Management feature document.

Consequences

Positive

  • The application is inherently more secure by not storing passwords.
  • The login process is frictionless for our corporate users.
  • The AuthService becomes simpler, as it no longer needs to manage password hashing, password policies, or reset flows.
  • The administrative workflow is streamlined due to JIT provisioning, as detailed in ADR-0005.

Negative

  • The application's availability is now directly tied to the availability of Google's authentication services. This risk is deemed acceptable given Google's high reliability.
  • The system is now only usable by individuals with a valid corporate Google Workspace account, which is consistent with the application's intended audience.
  • We must implement robust security practices for managing the OAuth 2.0 Client ID and Client Secret, as they are highly sensitive credentials.