OAuth2 Refresh Token Flow - Implementation Guide
================================================

OVERVIEW
--------
OAuth2's refresh token mechanism is fundamentally different from OAuth 1.0:
- OAuth 1.0: Permanent tokens with request signatures
- OAuth2: Temporary access tokens + long-lived refresh tokens

This added complexity provides better security through token rotation.

THE REFRESH TOKEN FLOW
----------------------
1. Initial Authentication
   POST /oauth/token
   Request: grant_type=authorization_code&code=xxx&client_id=yyy
   Response: {
     "access_token": "short-lived-token",    // Expires in 1 hour
     "refresh_token": "long-lived-token",     // Expires in 30-90 days
     "expires_in": 3600,
     "token_type": "Bearer"
   }

2. Normal API Usage (with access token)
   GET /api/data
   Authorization: Bearer short-lived-token

3. Token Expiration (after expires_in seconds)
   GET /api/data
   Authorization: Bearer short-lived-token
   Response: 401 Unauthorized

4. Token Refresh (automatic via ASM)
   POST /oauth/token
   Request: grant_type=refresh_token&
           refresh_token=long-lived-token&
           client_id=yyy&
           client_secret=zzz
   Response: {
     "access_token": "new-short-lived-token",
     "expires_in": 3600,
     "token_type": "Bearer"
     // May include new refresh_token
   }

5. Resume API Usage (with new access token)
   GET /api/data
   Authorization: Bearer new-short-lived-token

ASM CONFIGURATION FOR REFRESH FLOW
----------------------------------
The detector files work together to handle this flow:

1. Initial Token Capture:
   - oauth2-access-token.properties → Captures access_token
   - oauth2-refresh-token.properties → Captures refresh_token
   - oauth2-token-expires.properties → Tracks expiration
   - oauth2-token-endpoint.properties → Captures refresh URL

2. Refresh Detection:
   - oauth2-grant-type-refresh.properties → Identifies refresh requests
   - oauth2-client-credentials.properties → Captures client credentials

3. Token Rotation:
   - ASM detects 401 responses
   - Automatically triggers refresh flow
   - Updates access_token variable with new value
   - Continues with refreshed token

COMPLEX SCENARIOS HANDLED
-------------------------
1. Rotating Refresh Tokens
   Some APIs return a new refresh_token with each refresh:
   {
     "access_token": "new-access",
     "refresh_token": "new-refresh",  // Replace old refresh token
     "expires_in": 3600
   }
   ASM updates both tokens automatically.

2. Multiple Token Scopes
   Different tokens for different API scopes:
   {
     "access_token": "read-token",
     "scope": "read",
     "refresh_token": "read-refresh"
   }
   Use equivalency families to separate tokens by scope.

3. Token Expiry Prediction
   ASM can proactively refresh before expiry:
   - Tracks expires_in value
   - Refreshes at 90% of lifetime
   - Avoids 401 errors entirely

CONFIGURATION BEST PRACTICES
----------------------------
1. Record the Complete Flow:
   - Initial authentication
   - Several API calls
   - Wait for token expiry (or force 401)
   - Let refresh happen
   - Continue API calls

2. Verify Variable Creation:
   - access_token variable
   - refresh_token variable
   - token_endpoint variable (if needed)
   - client_credentials (if needed)

3. Test Scenarios:
   - Normal refresh after expiry
   - Forced refresh (revoke token)
   - Multiple concurrent sessions
   - Network failures during refresh

AUTHENTICATION FRAMEWORK INTEGRATION
------------------------------------
IMPORTANT: Authorization headers are controlled by the authentication framework,
not regular ASM field assignments. This affects how tokens are injected:

1. Token Extraction (ASM Phase):
   - ASM detectors extract tokens into variables
   - Creates bearer_token[1], refresh_token[1], etc.
   - Standard ASM variable creation and management

2. Header Injection (Auth Framework Phase):
   - BearerTokenFieldDetector correlates variables with headers
   - Creates AuthenticationDataSource objects
   - Authentication framework controls Authorization header
   - "Server authentication header" datasource is NORMAL

3. Why This Matters:
   - StringDelimitedDetector won't work on Authorization headers
   - Regular ASM assignments are overridden for security
   - Must use AuthenticationDataSource for proper integration

TROUBLESHOOTING REFRESH ISSUES
------------------------------
1. Refresh token not captured:
   - Check oauth2-refresh-token.properties pattern
   - Verify JSON structure matches
   - Some APIs use different field names

2. Refresh request fails:
   - Verify all required parameters captured
   - Check client credentials included
   - Validate token endpoint URL

3. New token not used:
   - Ensure variable names consistent
   - Check Bearer auth configuration
   - Verify ASM correlation working
   - Look for "Server authentication header" - this is normal
   - Ensure AuthenticationDataSource is created

4. Infinite refresh loop:
   - Check if refresh token expired
   - Verify correct grant_type
   - Some APIs require re-authentication

5. Authorization header shows wrong datasource:
   - "Server authentication header" means auth framework control
   - This is CORRECT behavior for security headers
   - Solution requires AuthenticationDataSource integration

COMPARISON WITH OAUTH 1.0
-------------------------
OAuth 1.0:
- Permanent tokens
- Each request individually signed
- No refresh mechanism
- Complex signature calculation

OAuth2:
- Temporary access tokens
- Simple Bearer token in header
- Refresh token for renewal
- No per-request signatures
- Better security through rotation

The added complexity of refresh tokens in OAuth2 provides:
- Better security (limited token lifetime)
- Easier revocation (invalidate refresh token)
- Simpler request signing (just Bearer header)
- Support for different token scopes

This is why OAuth2 replaced OAuth 1.0 despite the added refresh complexity.