Deep Link / OAuth Redirect Handler
Component Detail
Description
Intercepts incoming deep links during OAuth flows for both Vipps and BankID. Registers the app's custom URI scheme, parses authorization code and state parameters from callback URLs, and routes the result to the appropriate auth service. Shared by all OAuth-based auth flows.
deep-link-handler
Summaries
The Deep Link / OAuth Redirect Handler is a foundational security component that enables seamless, trusted authentication through Norway's most widely adopted identity providers — Vipps and BankID. By securely intercepting and processing the return leg of OAuth login flows, this component ensures users experience smooth, uninterrupted sign-in journeys without being stranded on external screens. Its built-in CSRF protection (state parameter validation) directly reduces the risk of account takeover attacks, which are a growing source of regulatory liability and reputational damage in the fintech and identity space. Because this handler is shared across all OAuth-based authentication paths, its robustness directly multiplies security coverage across the entire platform without proportional cost increases.
The Deep Link / OAuth Redirect Handler is rated medium complexity and is a shared dependency across every OAuth-based authentication flow in the app. This means it sits on the critical path for Vipps login, BankID login, and any future OAuth integrations — delays or defects here block QA sign-off on all auth features simultaneously. Testing must cover deep link registration on both iOS (Universal Links + custom schemes) and Android (Intent Filters), plus edge cases like malformed URIs, missing state parameters, and network interruption mid-flow. Integration with go_router or uni_links requires platform-specific configuration that may add setup overhead.
Plan for at least one dedicated regression cycle before any auth-related release.
This component manages the full lifecycle of incoming OAuth redirect URIs on mobile, acting as the bridge between the OS-level deep link dispatch and the application's auth service layer. It wraps uni_links or go_router's redirect mechanism to expose an `incomingLinkStream()` for reactive handling and a `getInitialLink()` for cold-start link recovery. The `parseAuthCallback(uri)` method extracts `code`, `state`, and `error` query parameters from the callback URI, while `validateState()` performs constant-time comparison against the locally generated CSRF token stored during flow initiation. Parsed `OAuthCallback` objects are then routed to the appropriate service (VippsAuthService or BankIDAuthService).
Care must be taken to call `dispose()` on the stream subscription to prevent memory leaks between auth sessions.
Responsibilities
- Register and listen for app deep links via uni_links or go_router redirect
- Parse OAuth callback query parameters (code, state, error) from incoming URIs
- Validate state parameter to prevent CSRF in OAuth flows
- Route parsed callback data to the correct auth service handler
Interfaces
initialize(): Future<void>
incomingLinkStream(): Stream<Uri?>
getInitialLink(): Future<Uri?>
parseAuthCallback(uri: Uri): OAuthCallback
validateState(state: String, expected: String): bool
dispose(): void
Relationships
Dependents (2)
Components that depend on this component