Skip to content

Feature 01: User Authentication and Session Management

Version Date Author Change Description Approval Status
1.0 2025-09-04 Senior Business Analyst Initial Draft (Local Authentication) Superseded
2.0 2025-09-11 Senior Systems Analyst Rewritten for Google Directory SSO Integration Pending Review

1.0 Introduction

1.1 Purpose

This document defines the business requirements for user authentication and session management. To enhance security and streamline user access, the system will delegate all user authentication to the corporate Google Directory via the OAuth 2.0 / OpenID Connect (OIDC) protocol. The application will not store or manage user passwords. It will be responsible for initiating the Single Sign-On (SSO) process, managing application-specific user sessions after successful authentication, and provisioning user profiles upon their first login. This decision is documented in the Architectural Decision Record for Single Sign-On.

  • For detailed user interaction flows, see the Use Case document.
  • For the quality assurance and validation strategy, see the Test Plan.

2.0 Business Requirements

2.1 Single Sign-On (SSO) with Google Directory

The application's primary and sole method of authentication will be through the corporate Google account. This provides a centralized and secure way to manage user identity.

  • 2.1.1 Login Interface: The application's login page will not contain username and password fields. Instead, it will prominently display a "Sign in with Google" button.
  • 2.1.2 Authentication Flow:
  • When a user clicks the "Sign in with Google" button, their browser will be redirected to Google's standard authentication page.
  • The user will authenticate with Google using their corporate credentials (including any multi-factor authentication required by Google).
  • Upon successful authentication with Google, the user will be redirected back to a designated callback URL within our application.
  • 2.1.3 Domain Restriction: Only users belonging to the authorized corporate Google Workspace domain (e.g., @our-company.com) shall be granted access. Attempts to log in with personal or non-corporate Google accounts will be rejected.

2.2 Just-In-Time (JIT) User Provisioning

To minimize administrative overhead, user accounts in this application will be created automatically upon their first successful login.

  • 2.2.1 First-Time Login: When a valid corporate user authenticates via Google for the first time, a corresponding user record will be created in the application's database.
  • 2.2.2 Profile Information: The newly created user record will be populated with essential, non-sensitive information retrieved from their Google profile, including their unique Google ID, full email address, and display name.
  • 2.2.3 Default State: Newly provisioned users will have a default status of "Active" and will be assigned a default set of "Standard User" roles/permissions.

2.3 Session Management

The application is responsible for creating, maintaining, and securely terminating its own user sessions after Google has confirmed the user's identity.

  • 2.3.1 Session Creation: A secure, server-side session will be established for the user immediately following a successful authentication callback from Google.
  • 2.3.2 Session Token: A secure, opaque session token will be generated and stored in a secure, HTTP-only cookie to prevent cross-site scripting (XSS) attacks. This token will be used to authorize subsequent API requests.
  • 2.3.3 Session Timeout: User sessions will automatically expire after a predefined period of inactivity (e.g., 60 minutes). This will require the user to re-authenticate via the Google SSO flow.
  • 2.3.4 Secure Logout: The application must provide a clear "Logout" function. When clicked, this function will invalidate the user's session on the server-side and clear the session cookie from the client's browser.

3.0 Business Rules

  • Rule 1.1: The login page must display a "Sign in with Google" button as the only means of initiating an authenticated session.
  • Rule 1.2: A user session must only be created after successful authentication with Google and verification that the user's account belongs to the authorized corporate domain.
  • Rule 1.3: If a user fails to authenticate with Google, or if their Google account is not part of the authorized domain, they must be redirected back to the login page with a generic "Authentication failed or access denied" error message.
  • Rule 1.4: The logout function must terminate the application-specific session. It is not required to log the user out of their global Google session.
  • Rule 1.5: An inactive session must be automatically terminated after the configured timeout period.

4.0 Scope

4.1 In Scope

  • Integration with Google Directory for user authentication using OAuth 2.0/OIDC.
  • Displaying a "Sign in with Google" button.
  • Handling the redirect flow to and from Google.
  • Automatic (Just-In-Time) provisioning of user accounts on first login.
  • Application-level session creation, timeout, and termination.

4.2 Out of Scope

  • Local user account management (username/password storage, password complexity rules, account lockout).
  • Password reset or recovery functionality.
  • Management of user accounts, groups, or credentials within Google Workspace itself.

5.0 Assumptions and Dependencies

  • 5.1: The organization maintains a Google Workspace account for all employees who require access.
  • 5.2: An OAuth 2.0 Client ID and Client Secret for this application will be generated from the Google Cloud Platform console and made available to the development team.
  • 5.3: The application will be registered in Google Cloud Platform with the correct and secure redirect URIs.