Solution Patterns

When you decide to add consumer identity to your app, you face a small set of architectural choices. This page describes them at a generic level, so you can compare options before mapping them to specific product features.

Where to Start

This page is a set of decisions. Start with the integration approach: you pick one option from three, and that choice shapes how the app and the identity product fit together. The other decisions stand on their own, so you can take them in whatever order your project drives them.

Integration Approaches

Pick one approach. The decision comes down to two questions: who shows the sign-in, sign-up, and recovery screens, and who decides what comes next in the journey.

Redirect-Based

Why This Matters

ThunderID hosts the identity screens. Your app redirects users there and gets them back signed in.

App-Native

Why This Matters

Your app renders every screen, but ThunderID owns the journey — step ordering, branching, and policy stay on the server.

Direct API

Why This Matters

Your app calls ThunderID's primitive APIs directly — low-level, single-purpose operations with no hosted pages and no journey to configure. You decide what to call, when to call it, and what to do with the result.

Who shows the screens	Who drives the journey	Approach
Identity product	Identity product	Redirect-based
App	Identity product	App-native
App	App	Direct API

Redirect-Based

When a user wants to sign in, the app sends them to the identity product. The product shows the sign-in, sign-up, and recovery screens, then sends the user back signed in. Because the app never sees the user's password, this is the simplest security posture and the quickest path to a working sign-in.

The pattern covers sign-in, sign-up, recovery, additional-permission requests with consent screens, hosted-page branding, and signing the user out. It fits web apps, single-page apps, and mobile apps. The main trade-off is that the user has to leave the app for a hosted page. This can feel disruptive inside a native mobile app or a heavily branded web experience, and UI customization is limited to what the hosted pages expose.

This pattern is typically built with a standard sign-in library or an SDK provided by the identity product. The underlying handshake is well-specified and not worth hand-rolling.

App-Native

The app renders every screen itself, but the journey lives on the identity product. This gives the app full control over what the user sees while keeping step ordering, branching, and policy on the server. The pattern is the best fit for native mobile and any "all in the app" experience.

The full set of journeys is covered with custom UI: sign-in, sign-up, recovery, profile changes that need re-verification, and invitation acceptance. The pattern handles multi-step prompts, multi-factor authentication, and steps that change based on the user or context. Branding is handled entirely in the app.

App-native has two flavors that trade UI granularity for app-side code:

• Step-by-step (verbose flow): the app sees every step the journey defines. After each step, it calls the identity product for the next step's details, renders the screen the server describes, captures the user's input, and posts it back.
• Managed (non-verbose flow): the identity product orchestrates the journey internally and only exposes outcomes to the app. The app says "the user wants to sign in" and reacts to whatever the product hands back. But the app decides how to render each screen and capture input.

This pattern is typically built using an SDK provided by the identity product. The SDK handles the per-step (step-by-step) or per-outcome (managed) calls and state so the app can focus on UI.

Direct API

Small, single-purpose API calls, for example "authenticate with username and password" or "send an OTP and verify it". The app strings these together itself, with no journey between the app and the primitive. This pattern fits two situations well. First, clients who want the simplest possible sign-in with no application or flow configuration on the identity product side. Second, headless or scripted scenarios where a guided journey isn't useful, such as server-to-server authentication, internal tools, and automation.

Coverage is typically limited to the primitives the identity product exposes, often authentication only. Because there is no journey, journey-level policies (multi-factor, conditional steps) are not applied; the app is fully responsible for getting the identity logic right.

This pattern is built by calling the APIs directly; an SDK adds little here.

Identity Sources and Data

Where consumer identities come from and where they live shape almost everything else about the system. Federation decides who can bring an existing identity to your app. User stores decide who owns the canonical record once they arrive.

Identity Federation

External identity providers, both social and enterprise, let users bring an identity they already have to your app, removing the need to manage a separate credential. Done well, federation creates one user record per real person regardless of how many sign-in methods they end up using. Most consumer apps adopt at least one social provider, and prosumer apps add enterprise OIDC.

Federation requires a few specific decisions. Should a user record be created the first time someone signs in via a provider (just-in-time provisioning), or only after an invitation? Should multiple federated identities link to one user, and what is the linking signal (verified email, explicit linking, or both)? Should signing out of your app sign the user out of the federated provider too? Should a user be routed to a specific provider automatically based on their email domain? Each of these is configurable independently.

Capabilities Involved

• Social sign-in via Google, GitHub, and other social providers.
• Enterprise sign-in via OpenID Connect.
• Just-in-time (JIT) provisioning: create the user the first time they sign in this way.
• Single logout (SLO): sign the user out of every place they're signed in.
• Account linking: connect multiple sign-in methods to a single user.
• Home-realm discovery: route the user to the right provider based on their email domain.

User Stores

Where consumer identities live affects everything else: sign-in performance, recovery options, federation behavior, and migration paths. Most consumer apps run a directly-managed user directory inside the identity product. Other options are no local record at all (relying entirely on federation), an existing directory you own (LDAP or a custom backing store), or a mix.

The choice often comes down to source of truth: who owns the canonical user record. If the identity product owns it, you get the most features and the simplest operational model. If an external system owns it, you get integration with existing data flows and a single source of truth across the business. The trade-off is less flexibility on the identity side. A mixed deployment lets you move identities between stores at your own pace. This is useful during migrations or when different user segments have different requirements.

Capabilities Involved

• Directly-managed user directory.
• Federated-only, no local user record kept.
• External user directory (LDAP, custom backing store).
• Mixed: some users local, some federated.

Tokens, Sessions, and APIs

After sign-in, the application holds a token or session that represents the user, and your APIs need to know what it means. This section covers what is issued, how it lives, and how downstream services trust it.

Session and Token Strategy

Once a user signs in, the application holds a token or session that represents them. The shape of that credential decides how long the user stays signed in, how quickly access can be revoked when needed, and how much load lands on the identity product. Most B2C apps make this decision once and live with it for years, so it pays to pick deliberately.

Three patterns cover most consumer scenarios:

• Stateless tokens: short-lived access tokens backed by longer refresh tokens, with no server-side session record. Scales easily because no lookup is needed to validate a token. Revocation is best-effort and waits for the token to expire.
• Server-backed sessions: every refresh and session is backed by a server-side record the identity product can revoke instantly, which gives you true sign-out-everywhere.
• Sliding-expiry sessions: sessions extend on each use, so returning users rarely have to sign in again, in return for longer-lived credentials.

Many consumer apps combine the second and third into a long, sliding, revocable session.

The choice shapes other concerns. A revocable session is needed for "sign me out everywhere" to work reliably. Long-lived sessions should be paired with refresh-token rotation to limit the damage if a token leaks.

Capabilities Involved

• Stateless JWT access tokens with refresh tokens.
• Server-side session record backing each refresh.
• Instant token and session revocation.
• Refresh-token rotation on use.
• Sliding-expiry sessions for "stay signed in".
• Configurable access, refresh, and session lifetimes.
• Single logout across application surfaces.

Protect APIs the App Calls

Sign-in is one half of identity; the other is protecting the APIs your app calls after sign-in. The identity product issues tokens during sign-in, and the same tokens carry the user's permissions to your APIs. The API does not have to know who the user is; it only needs to validate the token and check the permissions inside.

Validation typically happens at the API edge, in a gateway or middleware that verifies JWT signatures or calls the identity product's introspection endpoint. Permissions are expressed as scopes (what the app may do) and audiences (which API the token is valid for). Grouping related APIs into a resource server lets multiple endpoints share one set of permission rules instead of each endpoint enforcing them ad-hoc.

Capabilities Involved

• Issue an OAuth2 access token to the app on sign-in.
• Validate the token at the API edge via JWT signature verification or introspection.
• Scope-based authorization checks.
• Bind a token to a specific API via audience / resource indicator.
• Group related APIs into a resource server so they share permission rules.

Run, Observe, and Integrate

Beyond the user-facing decisions, the identity product is a system you operate alongside the rest of your stack. These patterns cover how it is configured, deployed, watched, and connected to the wider business.

Identity-as-Code

Identity configuration spans many resources, such as user types, applications, roles, flows, federated providers, and branding, and it grows over time as the product evolves. Managing it by hand works for a single environment but breaks down as soon as you have separate dev, staging, and production tenants, or as soon as more than one person changes things. Identity-as-Code treats that configuration as versioned source files the team reviews, tests, and promotes.

The pattern centers on declarative configuration files that describe every identity resource the product needs, with environment-specific values supplied separately. The files are kept in version control, go through normal review, and are applied to each tenant by a deployment job. Changes flow from dev to staging to production along the same path other changes do, with the same approvals.

Capabilities Involved

• Declarative configuration files for identity resources.
• Environment-specific values supplied separately from the configuration.
• Version control, review, and rollback through the application's existing workflow.
• Promotion of changes across dev, staging, and production tenants.
• Drift detection between the configuration files and the live tenant.

Resilience and Multi-Region Deployment

The identity product is on the critical path for every sign-in. If it is down, no one gets in. So the deployment shape needs to match the availability you have promised your users. The right pattern depends on your reliability target, latency budget, and where your users are.

Four patterns cover the common cases:

• Single-region: the simplest. Works well for products with regional audiences and modest availability targets.
• Active-passive: replicates user data to a second region that takes over on failure. Trades a recovery time window for cost.
• Active-active: runs every region live, routing each user to the nearest healthy region. Gives the lowest sign-in latency and the smallest blast radius for an outage, at the cost of replication complexity and the need to keep data consistent across regions.
• Regional sharding: pins specific users to specific regions, often to satisfy a data-residency rule, and routes them home wherever they sign in from.

These choices ripple through the rest of the architecture. Active-active typically demands a stateless or eventually-consistent session model so a user can complete sign-in even if their nearest region just changed. Regional sharding pairs naturally with the Data residency cross-cutting choice and a federation strategy that knows which region each user belongs to. Plan replication, failover testing, and on-call coverage as part of picking the pattern.

Capabilities Involved

• Single-region deployment.
• Active-passive deployment with failover.
• Active-active deployment with regional routing.
• Regional sharding pinned to data residency.
• User-data replication across regions.
• Health-checked routing and failover.
• Independent regional configuration and secrets.

Activity Monitoring and Audit

Identity events are some of the highest-signal data in your stack. Every sign-up, sign-in, recovery, and consent change is a row worth keeping. Three audiences consume this data, and a good pattern serves them all without forcing them into the same tool. Product teams want funnel and adoption metrics. Security teams want anomalies and incident detection. Compliance teams want a durable audit log they can hand to a regulator.

The pattern has three layers. First, the identity product records every event to a structured audit log with consistent fields (who, what, when, where, outcome). Second, dashboards surface the metrics product and security teams care about, either built into the identity product or exposed by streaming events into the analytics tool the business already uses. Third, security-relevant events trigger real-time alerts or feed an anomaly detection layer that catches brute-force, credential stuffing, impossible travel, and other patterns no single event reveals.

Storage and retention are part of the decision. Audit data for compliance is typically kept far longer than operational metrics, and may require write-once, tamper-evident storage. Decide retention windows per data class, since operational analytics, security signals, and compliance audit are not the same thing.

Capabilities Involved

• Structured audit log of every identity event with a consistent schema.
• Built-in dashboards for sign-up funnels, sign-in success rates, and method adoption.
• Per-user activity timelines for support investigation.
• Stream events to external analytics, data warehouse, or SIEM platforms.
• Anomaly detection: failed sign-in spikes, brute force, impossible travel.
• Real-time alerts for security-relevant events.
• Export audit logs for compliance reporting.

Connect to Other Systems

Identity is not an isolated system; it belongs to the business. New sign-ups should land in your CRM; password resets should trigger security event logs; failed sign-ins should surface in your monitoring. The identity product is the natural place to emit these signals because it sees every identity event.

Integration typically goes in two directions. Outbound: the identity product emits events to subscribers via webhooks, message queues, or a built-in event bus. Events include sign-up, password change, MFA enrollment, and federated link, so other systems can react. Inbound: identity flows can call out to your systems mid-journey for validation, data enrichment, or business checks. For example, an inbound check against a fraud service can decide whether to let a sign-up complete.

Capabilities Involved

• Emit identity events (sign-up, password change, and so on) to subscribers.
• Push new-user data to a CRM or marketing tool on sign-up.
• Send SMS and email notifications through providers you choose.
• Call out to your own systems mid-journey (validation, data lookup, and so on).
• Run checks before or after key identity actions.

Cross-Cutting Choices

Every implementation touches these regardless of which approach you pick.

• Application type: single-page web app, server-rendered web app, native mobile, or backend.
• Tokens: claim shape, lifetimes, and refresh strategy (access / ID / refresh tokens).
• Branding: applies to the identity product's hosted pages (redirect-based) and to the app's own screens (the app-native and direct-API approaches).
• Session model: token-based, or longer-lived "stay signed in" sessions.
• Data residency: where consumer identity data is stored (single region, per-region, or customer-chosen).

---

Next Steps

Choose an approach that fits your application, then see it running against the Wayfinder sample in Try It Out.