Doc Feedback: Misuse of Authorization Header in Custom Authentication Handler Example #10559
Description
Summary
The current documentation example for a custom API authentication handler uses the HTTP Authorization header to pass a plain username (e.g., Authorization: userName:xxx). This is not a valid or real-world authentication pattern and may mislead users into implementing insecure or non-standard solutions.
Problem Description
The documented example validates requests using logic similar to: Authorization: userName:janaka
This approach has several issues:
❌ Violates HTTP and OAuth2 standards
❌ Misuses the Authorization header, which is reserved for authentication schemes such as Bearer, Basic, etc.
❌ Can confuse users about recommended APIM security practices
In real-world systems, usernames are never sent in plain text via the Authorization header.
Why This Is an Issue
Developers may assume this is an acceptable production pattern
Encourages insecure implementations
Reduces documentation credibility
Proposed Improvement (Recommended)
If the intention of the example is to demonstrate custom request validation logic, the example should:
✅ Use a custom HTTP header instead of Authorization
Example:
X-User-Name: janaka
This:
- Keeps Authorization semantics intact
- Clearly signals that this is not authentication
- Aligns with common industry practices
- Avoids security misconceptions
Suggested Documentation Changes
- Update Code Example
private String getUserNameHeader(Map headers) {
return (String) headers.get("X-User-Name");
}
if (userName != null && !userName.isEmpty()) {
return true;
}
- Update Sample curl Command
curl -X GET http://localhost:8280/sample/1.0.0/test \
-H "X-User-Name: janaka"
- Add a Clear Note in Documentation
Note: This example is for demonstrating custom handler mechanics only.
It is not a replacement for OAuth2/JWT-based authentication, which is the recommended approach for production APIs.
Requested Action
Update the example to use a custom header
Add a clarification note about real-world authentication
Avoid using the Authorization header for non-standard purposes