IHNYC RC Platform Docs

ihnyc-rc-cal-landing Google OAuth Implementation (dev)

2 min read

This is a development-only implementation guide for a Google OAuth auto-sync integration. Not production.

Goals

  • Provide a “Connect Google Calendar” flow.
  • Create a dedicated Google calendar per user.
  • Sync ICS events into Google using Calendar API.
  • Keep legacy ICS subscriptions working unchanged.

OAuth Scopes

Recommended scopes:

  • https://www.googleapis.com/auth/calendar

(Use the minimal scope required for create/update/delete events.)

System Components

  • OAuth service (Pages Function or Worker)
  • Token store (D1)
  • Sync worker (cron)
  • Event mapping table (D1)

Data Model (suggested)

  • google_oauth_tokens
    • id, subscriber_id, calendar_id, refresh_token, created_at, revoked_at
  • google_calendar_map
    • id, subscriber_id, google_calendar_id, created_at
  • google_event_map
    • id, subscriber_id, ics_uid, google_event_id, updated_at

Endpoints (suggested)

  • GET /api/google-oauth/start
  • GET /api/google-oauth/callback
  • POST /api/google-oauth/disconnect

Flow (high level)

  1. User clicks “Connect Google Calendar”.
  2. Redirect to Google OAuth consent screen.
  3. On callback, exchange code for access+refresh tokens.
  4. Store refresh token (encrypted at rest).
  5. Create a dedicated calendar in the user account.
  6. Persist google_calendar_id mapping.
  7. Start sync job (cron) for the user.

Sync Strategy

  • Fetch ICS feed (existing token-gated URL).
  • Parse ICS; use UID as stable key.
  • Upsert events into Google:
    • If UID exists in google_event_map, update by google_event_id.
    • If not, create event and insert mapping.
  • Delete events removed from the feed.

Token Handling

  • Access tokens expire in ~1 hour.
  • Use refresh tokens for silent renewals.
  • If refresh token fails, mark token revoked and prompt re-auth.

Security Notes

  • Store refresh tokens encrypted (KMS if available).
  • Implement a revoke path and scrub tokens on request.
  • Rate limit OAuth and sync endpoints.

UI Changes (suggested)

  • Add a “Connect Google Calendar” CTA alongside Apple/Outlook.
  • Explain that Google login is required once.
  • Provide a disconnect option.

Open Questions

  • Desired sync interval (e.g. hourly vs daily).
  • Whether to sync to primary calendar or a dedicated one (recommended dedicated).
  • Long-term storage and retention of mapping tables.

Status

Development only. Not deployed.

Graph View

Backlinks