How govuk-one-login/authentication-frontend works
This is GOV.UK One Login’s authentication frontend: an Express web application that handles OIDC authorization and guides users through sign-in, account creation, verification, MFA, and related recovery journeys. Its state machine tracks journey transitions in the user session; controllers implement individual steps and shared services handle verification, notifications, and passkeys. The README also describes an orchestration stub used to initiate local OIDC flows. Some service integrations are represented as unverified because the sampled excerpts do not show their runtime calls.
Main entry points: state-machine-executor.ts Journey executor · app.ts Express app · send-notification-service.ts Notifications · authorize-controller.ts OIDC authorize
Components 24
Web entry
- Express app
src/app.ts - Session middleware
src/middleware/session-middleware.ts - Page templates
src/components/templates/pages.ts
Authentication journeys
- OIDC authorize
src/components/authorize/authorize-controller.ts - Journey state machine
src/components/common/state-machine/state-machine.ts - Journey executor
src/components/common/state-machine/state-machine-executor.ts - Email entry
src/components/enter-email/enter-email-controller.ts - Phone verification
src/components/check-your-phone/check-your-phone-controller.ts - Authenticator setup
src/components/setup-authenticator-app/setup-authenticator-app-controller.ts - Authenticator code
src/components/enter-authenticator-app-code/enter-authenticator-app-code-controller.ts - Passkey journeys
src/components/create-passkey/create-passkey-controller.ts - Identity callbacks
src/components/ipv-callback/ipv-callback-controller.ts - MFA reset
src/components/mfa-reset-with-ipv/mfa-reset-with-ipv-controller.ts - Account recovery
src/components/common/account-recovery/account-recovery-service.ts
Journey services
- MFA verification
src/components/common/verify-mfa-code/verify-mfa-code-service.ts - Notifications
src/components/common/send-notification/send-notification-service.ts - Passkey service
src/components/common/passkey/passkey-service.ts - HTTP utilities
src/utils/http.ts
User support
- Contact support
src/components/contact-us/contact-us-controller.ts
External systems
- Authentication API
- Notification service
- Session store
src/config/dynamodb-session.ts - Orchestration stub
Other components
- User
Connections 21
- User → Express app: starts journey
- Express app → Session middleware: installs middleware
src/app.ts - Session middleware → Session store: configures sessions
- Express app → OIDC authorize: routes requests
src/app.ts - OIDC authorize → Journey executor: updates journey
src/components/authorize/authorize-controller.ts - Journey executor → Journey state machine: gets next state
src/components/common/state-machine/state-machine-executor.ts - Journey executor → Session middleware: saves journey state
src/components/common/state-machine/state-machine-executor.ts - Journey executor → Passkey service: checks prompts
src/components/common/state-machine/state-machine-executor.ts - Email entry → Notifications: sends codes
src/components/enter-email/enter-email-controller.ts - Phone verification → Notifications: sends codes
src/components/check-your-phone/check-your-phone-controller.ts - Phone verification → MFA verification: verifies code
src/components/check-your-phone/check-your-phone-controller.ts - Authenticator setup → Notifications: sends codes
src/components/setup-authenticator-app/setup-authenticator-app-controller.ts - Authenticator setup → MFA verification: verifies code
src/components/setup-authenticator-app/setup-authenticator-app-controller.ts - Authenticator code → MFA verification: verifies code
src/components/enter-authenticator-app-code/enter-authenticator-app-code-controller.ts - Passkey journeys → Passkey service: uses passkeys
- Identity callbacks → Account recovery: handles recovery
- MFA reset → Identity callbacks: continues identity flow
- Contact support → Page templates: renders pages
src/components/contact-us/contact-us-controller.ts - OIDC authorize → Authentication API: requests authorization
- Notifications → Notification service: delivers messages
- Orchestration stub → Express app: initiates OIDC flow