Building a Custom MFA and Secure Session Handoff Platform for Shared In-Store Devices

Santiago Cortés Fernández — Sat, 01 Aug 2026 06:51:43 +0000

This article describes an anonymized enterprise implementation. Company names, internal domains, repository identifiers, ticket numbers, and proprietary control names have been intentionally removed or generalized.

Multi-factor authentication is often described as a login problem: enter a password, receive a code, confirm identity.

That model was not enough for the system described in this case study.

The product ran in an in-store environment where the same tablet could be used by several people during a transaction:

an employee initiating the process;
a manager approving or supporting it;
a customer reviewing and signing on their own device.

The challenge was not simply to prove that a user knew a six-digit code. We needed to create a secure, short-lived handoff between a shared in-store session and the customer’s personal phone, without leaking the downstream signing session or allowing multiple devices to claim the same transaction.

This post explains the architecture, the security model, the trade-offs, and the production practices behind that platform.

The actual problem: secure device handoff

The workflow started on a shared tablet. At a certain point, the customer needed to continue part of the process on their own phone.

The platform therefore had to answer several questions:

How does the phone prove that it belongs to the customer currently standing in front of the employee?
How does the shared tablet know that the correct phone claimed the correct session?
What happens if the QR code is scanned twice?
How do we prevent session identifiers and tokens from appearing in URLs, browser history, logs, or referrer headers?
How do we notify the phone immediately when verification succeeds?
How do we ensure that a single-use signing URL is never exposed before verification?

Those constraints turned a seemingly small MFA feature into a distributed-system problem involving identity, real-time communication, concurrency, edge delivery, infrastructure, and operational controls.

High-level architecture

The solution used two main application components:

a React and TypeScript single-page application for the customer’s phone;
a serverless GraphQL API built with AWS AppSync, Lambda, and DynamoDB.

The infrastructure also included CloudFront, S3, API Gateway, Route 53, ACM, WAF, Terraform, centralized logging, APM, synthetic monitoring, and automated deployment workflows.

┌─────────────────────────────┐
│ Shared in-store tablet      │
│ Employee / manager workflow │
└──────────────┬──────────────┘
               │ create handoff session
               ▼
┌─────────────────────────────┐
│ GraphQL API                 │
│ AppSync + Lambda            │
└──────────────┬──────────────┘
               │ persist state
               ▼
┌─────────────────────────────┐
│ DynamoDB                    │
│ session + short-link data   │
└─────────────────────────────┘

Shared tablet displays QR
               │
               ▼
┌─────────────────────────────┐
│ Customer phone              │
│ React SPA via CloudFront    │
└──────────────┬──────────────┘
               │ claim + subscribe
               ▼
┌─────────────────────────────┐
│ GraphQL API                 │
│ verification + status push  │
└─────────────────────────────┘

The architecture was intentionally serverless. The workload was bursty, the user journey was short, and most operations were small state transitions rather than long-running computation.

The end-to-end session-handoff flow

1. Create the handoff session

The in-store application created a short-lived handoff record containing the transaction context, a downstream signing URL, expiration data, and a PENDING status.

The signing URL was treated as sensitive and single-use. It was stored internally but never returned to the customer-facing application while the handoff session remained pending.

2. Generate a short QR link

The API created a short code associated with the handoff record. The in-store tablet rendered that short link as a QR code.

The customer scanned it with their phone.

3. Bootstrap the phone session securely

The QR request passed through CloudFront and a small redirect endpoint.

Instead of placing the session identifier and token in query parameters, the redirect returned short-lived cookies configured with:

Secure;
SameSite=Strict;
a very short expiration time.

The phone application read the values, configured its GraphQL client, and continued the session-handoff flow.

This avoided exposing credentials through:

browser history;
access logs;
copied URLs;
analytics tools;
referrer headers.

4. Claim the handoff session

The phone called a claimSession mutation.

The backend generated:

a six-digit security code;
a unique session identifier.

The code was displayed on the customer’s phone and read back to the employee using the shared tablet.

The platform followed a last scanner wins model. If another phone scanned the same QR code, a new claim superseded the previous one.

This prevented two devices from holding the same active handoff session.

5. Verify the code

The employee entered the six-digit code into the in-store application.

The backend evaluated the verification as a state transition:

correct code: PENDING → VERIFIED;
incorrect code with attempts remaining: decrement attempts;
final incorrect attempt: PENDING → CANCELED;
timeout: PENDING → EXPIRED.

These transitions used DynamoDB conditional writes rather than read-modify-write sequences. The database became the concurrency primitive.

That was important because two verification requests, or two competing claims, could not both succeed.

6. Push the result in real time

The phone subscribed to handoff-status updates using GraphQL subscriptions.

When verification succeeded, AppSync pushed the new state to the phone immediately.

There was no polling loop.

The phone then performed a final authenticated read. Only at that point did the API expose the single-use signing URL.

The application redirected the customer to the signing experience and expired the handoff record.

Why GraphQL subscriptions instead of polling?

Polling would have been easier to explain, but it would also have introduced unnecessary traffic, slower feedback, and more lifecycle edge cases.

The product requirement was naturally event-driven:

Notify this phone when the in-store session verifies this exact handoff session.

GraphQL subscriptions provided:

low-latency status changes;
built-in filtering by handoff context;
managed WebSocket reconnection through the client library;
no custom polling interval or retry scheduler.

The frontend still handled one mobile-specific failure mode: operating systems frequently suspend browser tabs when users lock their phones or switch applications.

When the tab became visible again, the application re-fetched the handoff state. This covered the case where the WebSocket had been paused and the final event was missed.

The six-digit code served two purposes

One of the most important design decisions was to use the six-digit value as both:

the human-readable MFA challenge;
the server-side capability required to access handoff state.

The code was required on reads and subscription filters. It was never returned to a superseded device, and the downstream signing URL remained hidden until the state reached VERIFIED.

This removed the need for a second opaque session token while preserving field-level authorization.

It also reduced the number of credentials that had to be generated, stored, synchronized, and invalidated.

A layered security model

The platform used defense in depth rather than treating the MFA code as the only control.

Edge protection

CloudFront and regional endpoints were protected by AWS WAF. Managed rule groups were introduced in stages, with higher-risk rules enforced first and false-positive-prone groups initially left in monitoring mode.

Transport and identity

All traffic used HTTPS. The GraphQL API used a custom Lambda authorizer that validated OAuth/JWT tokens, issuer, signature, expiration, operation-level scopes, and authorization weights.

Unknown operations failed closed.

Contract hardening

The GraphQL surface disabled introspection in deployed environments and limited query depth and resolver count.

Field-level authorization

Resolvers checked the security code before returning handoff state.

The signing URL was only included when the handoff session was verified.

For superseded subscriptions, the resolver returned no data rather than revealing why the session had changed.

Credential hygiene

Sensitive handoff credentials were not passed in URLs. Logging excluded personally identifiable information and authentication secrets. Correlation identifiers were preserved for debugging without leaking session data.

Keeping the frontend intentionally small

The customer-facing application was a single-purpose flow, so the frontend avoided unnecessary framework complexity.

It used:

React;
TypeScript in strict mode;
Vite;
React Context and local hooks;
a managed GraphQL client;
a shared enterprise design system.

There was no router and no global state library.

The application had only a few states:

loading or claiming;
showing the MFA code;
displaying an error or terminal status;
redirecting after verification.

That simplicity reduced bundle size, attack surface, upgrade burden, and cognitive overhead.

Infrastructure as code from day one

All infrastructure was defined in Terraform.

The API repository provisioned not only the backend but also the shared infrastructure required by the frontend:

AppSync;
Lambda functions;
DynamoDB;
S3;
CloudFront;
API Gateway;
DNS and certificates;
WAF;
monitoring resources.

The frontend repository produced an immutable build artifact but did not own a separate infrastructure stack.

This created a single source of truth for the platform topology while allowing the application and API to evolve independently.

Build once, deploy many

The frontend did not embed environment-specific configuration at build time.

Instead, it derived the environment from the deployed hostname. The same artifact could therefore be promoted unchanged through development, QA, pre-production, and production.

That pattern provided two benefits:

production received the exact artifact previously tested;
configuration remained a deployment concern rather than a build concern.

The delivery pipeline included:

linting and automated tests;
static analysis;
infrastructure validation;
security scanning;
semantic versioning;
immutable artifact publishing;
environment approvals;
production change-management integration.

Observability was part of the product

Operational visibility was not added after launch.

The platform included:

structured JSON logs;
correlation identifiers;
named business events;
centralized log forwarding;
APM instrumentation;
dashboards for Lambda, GraphQL, and transaction health;
latency, error-rate, and throttle alerts;
synthetic health checks;
environment-specific escalation rules.

The monitoring configuration lived in an independent Terraform state so it could be changed without modifying the main application infrastructure.

This separation was useful because alerting often evolves at a different pace than application resources.

A real trade-off: compliance over the cheaper API option

One of the more instructive decisions involved API Gateway.

The first implementation used the newer HTTP API because it was simpler and cheaper. During compliance work, the team confirmed that the required WAF association was not supported for that API type.

The available choices were:

keep the newer API and request an exception;
redesign the edge flow;
move to REST API v1, which supported the required WAF attachment.

The platform moved to REST API v1.

That increased the per-request cost, but observed traffic was low enough that the monthly impact was negligible. The security and compliance benefit was more important than the small infrastructure savings.

The lesson was not that REST API v1 is always better. The lesson was to evaluate cloud-service choices against the full production constraint set, not only developer convenience or headline pricing.

Delivery in vertical slices

The product moved from an empty repository to production through incremental phases:

foundational API, database, and Terraform modules;
edge delivery, DNS, certificates, and the first mobile UI;
custom authorization and scoped access;
expiration, short links, QR redirects, and secure session bootstrap;
exclusive claiming and real-time subscriptions;
structured logging, dashboards, alerts, and synthetic monitoring;
WAF enforcement and compliance rollout;
production automation and lifecycle maintenance.

Each phase delivered a complete architectural capability rather than a disconnected set of files.

This made integration risks visible earlier and allowed the design to evolve as platform constraints were discovered.

Patterns worth reusing

Use conditional writes for small distributed state machines

For workflows with simple transitions, DynamoDB condition expressions can replace application locks and read-before-write logic.

Treat rejected designs as valuable documentation

Several implementation paths failed because of platform constraints. Recording why they failed prevented future engineers from repeating the same experiments.

Push authorization as close to the data as practical

Field-level checks in resolvers ensured that both queries and subscriptions followed the same rules.

Ship security controls gradually

The WAF configuration was introduced in monitoring mode, analyzed, then selectively enforced with rollback flags and a production canary.

Keep single-purpose frontends single-purpose

The absence of a router or complex state library was a deliberate architectural choice, not missing sophistication.

Build production readiness into the initial architecture

Authentication, CI/CD, observability, security scanning, health checks, and rollback mechanisms should not be postponed until after feature completion.

Final takeaway

The hardest part of this platform was not generating a six-digit code.

The real engineering challenge was creating a trustworthy handoff between a shared device and a customer-owned device while handling concurrency, real-time status, short-lived credentials, single-use downstream sessions, production security, and enterprise delivery controls.

A custom MFA flow becomes valuable when it is treated as a complete distributed system rather than a small authentication widget.

DEV Community: Santiago Cortés Fernández