OAuth2 Token Detector Configuration Files
=========================================

This directory contains detector configuration files for automatic OAuth2 token detection
and extraction in the ASM (Automatic State Management) system.

OVERVIEW
--------
These detectors work with the existing Bearer token infrastructure to automatically:
1. Detect OAuth2 tokens in various response formats
2. Extract tokens into user state variables
3. Inject tokens into subsequent API requests as Authorization headers

DETECTOR FILES
--------------
- oauth2-access-token.properties    - Standard access_token in JSON responses
- oauth2-refresh-token.properties   - Refresh tokens for token renewal
- oauth2-jwt-token.properties       - JWT-specific token format validation
- oauth2-token-expires.properties   - Token expiration time capture
- oauth2-token-type.properties      - Token type validation (Bearer)
- oauth2-xml-token.properties       - XML/SOAP response token extraction
- oauth2-bearer-header.properties   - Tokens returned in response headers
- oauth2-custom-field.properties    - Non-standard token field names

HOW IT WORKS
------------
1. Record your OAuth2 authentication flow in Web Performance Tester
2. ASM analyzes responses and applies these detector patterns
3. When tokens are found, ASM creates user state variables (e.g., bearer_token[1])
4. The Bearer authentication system correlates these variables with Authorization headers
5. Creates AuthenticationDataSource objects that work WITH the authentication framework
6. Subsequent API requests automatically include the Bearer token

IMPORTANT: Authorization headers are controlled by the authentication framework, not regular
ASM field assignments. The system uses a two-phase approach where ASM extracts tokens and
the authentication framework controls header injection.

CUSTOMIZATION
-------------
To add support for custom OAuth2 implementations:
1. Copy oauth2-custom-field.properties to a new file
2. Modify the search.pattern to match your API's field names
3. Update the detector.name and equivalency.name.family
4. Save in this directory - no compilation needed

ENABLING/DISABLING
------------------
Each detector file has a "detector=" line at the bottom.
- To disable: Change to "detector=disabled: sread" (or appropriate type)
- To enable: Change to "detector=sread" (or appropriate type)

COMMON OAUTH2 RESPONSE FORMATS
------------------------------
Standard JSON:
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "8xLOxBtZp8..."
}

JWT in custom field:
{
  "id_token": "eyJhbGciOiJSUzI1NiIs...",
  "user": {"name": "John", "email": "john@example.com"}
}

XML response:
<TokenResponse>
  <AccessToken>eyJhbGciOiJSUzI1NiIs...</AccessToken>
  <ExpiresIn>3600</ExpiresIn>
</TokenResponse>

Header response:
HTTP/1.1 200 OK
Authorization: Bearer eyJhbGciOiJSUzI1NiIs...
Content-Type: application/json

TROUBLESHOOTING
---------------
1. Tokens not detected:
   - Check content_type.pattern matches your response
   - Verify search.pattern matches your JSON structure
   - Enable debug logging in ASM

2. Wrong token extracted:
   - Make pattern more specific
   - Use field validation patterns
   - Check equivalency.name.family

3. Token not used in requests:
   - Verify Bearer authentication is configured
   - Check user state variable creation
   - Look for "Server authentication header" - this means authentication framework control

4. "Server authentication header" datasource appears:
   - This is NORMAL - authentication framework owns Authorization headers
   - ASM extracts tokens into variables
   - BearerTokenFieldDetector creates AuthenticationDataSource for injection
   - Do NOT try to use StringDelimitedDetector on Authorization headers

5. ASM assignments ignored for Authorization headers:
   - This is BY DESIGN for security reasons
   - Solution requires AuthenticationDataSource, not regular ASM assignments
   - Use the two-phase approach: extract tokens, then integrate with auth framework

For more information, see the ASM documentation or contact support.