Doc Feedback: Misuse of Authorization Header in Custom Authentication Handler Example

Location : https://apim.docs.wso2.com/en/4.5.0/reference/customize-product/extending-api-manager/extending-gateway/writing-custom-handlers/

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

1. Update Code Example

private String getUserNameHeader(Map headers) {
    return (String) headers.get("X-User-Name");
}

if (userName != null && !userName.isEmpty()) {
    return true;
}

2. Update Sample curl Command

curl -X GET http://localhost:8280/sample/1.0.0/test \
  -H "X-User-Name: janaka"

3. 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

Open the linked custom authentication handler documentation page and locate the Java example and sample curl command that use the Authorization header. Update the example to use X-User-Name, add the requested production-authentication clarification, and verify the page no longer presents the plain username header as an authentication pattern.