Authentication Mechanisms
Relevant source files
The following files were used as context for generating this wiki page:
GoGovSG employs a multi-layered authentication system to ensure that only authorized Singapore government officers, education officers, and healthcare professionals can create and manage short links. The system supports traditional One-Time Password (OTP) login via email, Single Sign-On (SSO) through one.gov.sg, and API Key authentication for programmatic access.
The authentication logic is primarily distributed between the AuthService, OneGovSgController, and specialized middleware. Sessions are managed using Redis for transient storage, ensuring scalability and persistence across server restarts.
Sources: README.md:31-40, src/server/index.ts:167-183
Email OTP Authentication
The primary authentication method for users is an email-based One-Time Password (OTP) flow. This mechanism validates that a user possesses a government-affiliated email address before granting access to the dashboard.
OTP Flow Logic
- Request OTP: You enter your email address on the login page. The system validates the email against a glob expression (e.g.,
*@gov.sg). - Generate & Send: If valid, the system generates a numeric OTP and sends it to your email using
nodemaileror a Postman fallback. - Verify OTP: You enter the received OTP. The system verifies the hash against the
REDIS_OTP_URIstore. - Session Creation: Upon successful verification, the server initializes an Express session and stores user details in Redis.
Sources: src/server/config.ts:145-155, test/end-to-end/LoginPageSessions.spec.ts:15-30, README.md:85-90
The diagram above illustrates the synchronous request-response cycle for the email OTP authentication flow.
Sources: src/server/config.ts:14-16, src/server/index.ts:167-175
One.Gov.Sg (SSO) Integration
GoGovSG supports OIDC-based Single Sign-On through the one.gov.sg issuer. This feature is controlled by the FF_ONE_GOV_SG_LOGIN feature flag.
Transaction Management
Because OIDC callbacks are cross-site top-level navigations, they do not carry SameSite=Strict session cookies. The system uses a dedicated, short-lived oneGovSgTransaction cookie with SameSite=Lax to maintain state (nonce, state, and PKCE verifier) during the redirect flow.
Sources: src/server/modules/auth/OneGovSgController.ts:14-20, src/server/config.ts:28-34
Callback Validation
The OneGovSgController performs several security checks during the callback:
- Issuer Validation: Ensures the
issparameter matches the configuredONE_GOV_SG_ISSUER. - Email Domain Gating: Even if authenticated by the IdP, the user's email must satisfy
isValidGovEmailbefore a local user record is provisioned. - Session Regeneration: The system calls
req.session.regenerate()upon successful login to prevent session fixation attacks.
Sources: src/server/modules/auth/OneGovSgController.ts:142-165, src/server/modules/auth/tests/OneGovSgController.test.ts:200-215
API Key Authentication
For programmatic access, GoGovSG provides an API Key mechanism. This allows external systems to interact with the link-shortening service without a browser-based session.
Key Characteristics
- Generation: Users generate keys through the "API Integration" page in the client dashboard.
- Storage: API keys are hashed using a salt (
API_KEY_SALT) before being stored in the database. - Validation: The
apiKeyAuthMiddlewareintercepts requests to protected/apiroutes, extracting the key from the request headers and validating it against the stored hash.
Sources: src/client/apiintegration/index.tsx:45-60, src/server/config.ts:222-230, README.md:120-125
| Configuration Variable | Type | Description |
|---|---|---|
API_KEY_SALT | String | Salt used for hashing API keys. |
API_KEY_VERSION | String | Versioning for key format (default: v1). |
ADMIN_API_EMAILS | String[] | List of emails granted administrative API access. |
Sources: src/server/config.ts:222-235
Infrastructure & Configuration
Authentication behavior is heavily influenced by the server environment variables and the underlying infrastructure.
Redis Session Store
The system uses multiple Redis databases to separate concerns:
- OTP Store: Stores transient OTP hashes (
REDIS_OTP_URI). - Session Store: Stores Express session data (
REDIS_SESSION_URI).
Sources: README.md:83-90, src/server/index.ts:167-175
Security Headers and Cookies
The application utilizes helmet for Content Security Policy (CSP) and configures session cookies with strict security attributes:
httpOnly: true: Prevents client-side scripts from accessing the cookie.sameSite: 'strict': Mitigates CSRF by ensuring the cookie is only sent on first-party requests.secure: true: (In production) Ensures cookies are only transmitted over HTTPS.
Sources: src/server/index.ts:114-150, src/server/config.ts:112-125
The flowchart describes the routing logic for determining if a request is authenticated via session or API Key.
Sources: src/server/index.ts:186-200, src/server/modules/user/UserController.ts:320-335
Summary
GoGovSG implements a robust authentication suite tailored for government environments. By combining email OTP for ease of use, OIDC for secure SSO, and hashed API keys for automation, the platform maintains a high security posture while remaining accessible to authorized officers. All mechanisms leverage Redis-backed sessions and strict cookie policies to protect against common web vulnerabilities.
Sources: README.md:15-25, src/server/index.ts:240-250