Problem
The current documentation and examples don't cover a critical requirement for web applications using the authorization code flow with PKCE: persisting and restoring the OAuth state parameter when reconstructing flows after redirects.
Current Documentation Gap
The examples in the README show simple authentication flows, but they don't address the common web scenario where:
App creates OIDC flow and redirects user to IdP
User authenticates and gets redirected back to app
New page load occurs - original Flow object is lost
App must reconstruct the flow to handle the callback
What's Missing
The documentation doesn't mention that you must:
Extract and persist the state parameter from the flow's authentication URL
Restore this state when reconstructing the flow
Pass the stored state to Flow.authorizationCodeWithPKCE(state: storedState)
Real-World Impact
Without this knowledge, developers get cryptic callback failures because the reconstructed flow generates a new random state that doesn't match the callback's state parameter.
Example of What Developers Need to Do
// Step 1: Create flow and extract state
final flow = Flow.authorizationCodeWithPKCE(client, scopes: scopes);
final authUrl = flow.authenticationUri;
final stateParam = authUrl.queryParameters['state']; // Extract this!
localStorage['oauth_state'] = stateParam; // Persist this!
// Step 2: After redirect, reconstruct with stored state
final storedState = localStorage['oauth_state'];
final reconstructedFlow = Flow.authorizationCodeWithPKCE(
client,
scopes: scopes,
codeVerifier: storedCodeVerifier,
state: storedState, // This is critical but undocumented!
);
Suggested Documentation Enhancement
Add a "Web Application Redirect Scenario" example to the README showing:
How to extract and persist the state parameter
How to reconstruct flows with the persisted state
Why this is necessary for web apps
This would complement the existing examples and help developers avoid a common but hard-to-debug integration issue.
Problem
The current documentation and examples don't cover a critical requirement for web applications using the authorization code flow with PKCE: persisting and restoring the OAuth state parameter when reconstructing flows after redirects.
Current Documentation Gap
The examples in the README show simple authentication flows, but they don't address the common web scenario where:
App creates OIDC flow and redirects user to IdP
User authenticates and gets redirected back to app
New page load occurs - original Flow object is lost
App must reconstruct the flow to handle the callback
What's Missing
The documentation doesn't mention that you must:
Extract and persist the state parameter from the flow's authentication URL
Restore this state when reconstructing the flow
Pass the stored state to Flow.authorizationCodeWithPKCE(state: storedState)
Real-World Impact
Without this knowledge, developers get cryptic callback failures because the reconstructed flow generates a new random state that doesn't match the callback's state parameter.
Example of What Developers Need to Do
Suggested Documentation Enhancement
Add a "Web Application Redirect Scenario" example to the README showing:
How to extract and persist the state parameter
How to reconstruct flows with the persisted state
Why this is necessary for web apps
This would complement the existing examples and help developers avoid a common but hard-to-debug integration issue.