RFC-002: GA4 Authentication Event Contract

RFC-002: GA4 Authentication Event Contract

Related Documents:

• RFC-001 (GA4 Event Contract & Reporting Alignment)]
• ADR-018 (Typed Analytics Architecture)

Abstract

This RFC specifies the GA4 authentication event contract for OneCMS. It defines the canonical authentication journey events, payload requirements, and trigger points for login, MFA, org selection, forgot/reset password, social login, logout, and session expiry.

The goal is to provide a stable, typed telemetry contract that supports product funnel analysis and operational diagnostics while remaining compact and implementation-ready.

1. Introduction

1.1 Background

OneCMS has a typed GA4 architecture but authentication analytics needs a dedicated, explicit contract so Product and Analytics can reason about drop-off and friction points across the auth journey.

1.2 Problem Statement

Without a specific auth contract, teams risk:

• inconsistent trigger points for the same user action,
• missing visibility into OTP and org-selection friction,
• mismatch between implemented auth flow and analytics payloads.

1.3 Goals

This RFC standardizes:

1. The canonical authentication event set.
2. Required payload fields for each event.
3. Where each event is fired in the current flow.
4. Outcome semantics (success / fail / cancel) for async actions.

2. Terminology

The key words "MUST", "MUST NOT", "REQUIRED", "SHOULD", "SHOULD NOT", "MAY", and "OPTIONAL" are to be interpreted as described in RFC 2119.

• Intent Event: Event fired when user initiates an action.
• Result Event: Event fired after backend/result is known.
• Outcome: Standardized result value from RFC-001 envelope.
• Auth Funnel: End-to-end path from sign-in intent to authenticated session.

3. Scope

3.1 In Scope

• Authentication category events under src/types/analytics/authentication.
• Login (credentials + social), MFA, forgot/reset password, org selection, logout, session expiry.
• Trigger contracts for current auth implementation in useAuth and auth modules.

3.2 Out of Scope

• UI-only micro-interactions not in contract (e.g., password visibility toggle).
• Dashboard design and KPI definitions.
• Backend telemetry pipeline changes.

4. Authentication Event Contract

4.1 Canonical Event Set

Authentication category includes:

• login
• forgot_password_click
• forgot_password
• reset_password
• logout
• session_expired
• mfa_required
• mfa
• otp_resend
• org_selection_view
• org_selection
• social_login_click
• social_login

Event Naming Rules

• Event names MUST be user-centric and action/state-oriented.
• Event names MUST use snake_case and align with existing authentication taxonomy.
• Result events MUST represent business outcomes, not technical implementation steps.
• Intent interaction events MAY use explicit interaction suffixes (for example, *_click) when user-intent capture is required.
• New authentication events MUST be reviewed against this RFC before adoption.

Authentication Lifecycle Events

The following events represent transitions that end an authenticated session:

• logout
• session_expired

4.2 Payload Requirements

4.3 Contract Constraints

• Provider values for social auth MUST be google | microsoft.
• OTP method values MUST use canonical auth method enum (otp | sms | email) and current flow SHOULD emit otp.
• For async auth actions, implementations SHOULD emit result events with explicit outcome.
• If an event represents completion of an asynchronous operation, it MUST be emitted only after the operation result is known.
• Authentication events MUST NOT include personally identifiable information (PII) such as email, phone number, access tokens, or tenant identifiers.

5. Event Trigger Matrix

5.1 Dual-Event Rationale for Timeout

Emitting both session_expired and logout for idle timeout is intentional:

• session_expired supports passive timeout analysis.
• logout preserves a unified session-termination metric across manual and automatic termination paths.

6. Responsibilities

• Engineering: emit typed events at agreed trigger points and preserve payload contracts.
• Product: define funnel and success metrics using this event set.
• Analytics: maintain reporting logic and validate schema-versioned payload compatibility.

7. Versioning and Change Management

• This contract inherits versioning policy from RFC-001.
• Adding optional auth payload fields SHOULD be a minor version change.
• Renaming/removing auth events or required payload fields MUST be a major contract change.
• Any contract-breaking change MUST be proposed via a new RFC referencing RFC-002.

8. Risks and Considerations

• Over-instrumentation can reduce readability and increase implementation drift.
• Inconsistent error_code mapping can break fail-path analysis.
• Missing result events for async steps can create funnel blind spots.

9. Open Questions

1. Should login_page_view and otp_page_view be added as first-class auth events?
2. Do we need explicit auth_back_to_login_click for abandonment analysis?
3. Should we standardize a strict internal error_code taxonomy in a follow-up RFC?

10. Decision Outcome

• Accepted and implemented by Engineering, Product, and Analytics.

11. References

• RFC-001: GA4 Event Contract & Reporting Alignment
• ADR-018: Typed Analytics (GA) Architecture
• src/types/analytics/index.ts
• src/types/analytics/authentication/index.ts
• src/hooks/auth/useAuth.ts

12. Document History