Summary

This PR fixes an authorization issue where WebSocket connections through Pulsar proxy would fail when both authentication and authorization were enabled.

Here is the warning log from the broker

2025-07-17T18:11:50,346+0000 [pulsar-web-38-7] WARN  org.apache.pulsar.broker.authorization.AuthorizationService - [xxxx:46502] Illegal combination of role [proxy-role] and originalPrincipal [null]: originalPrincipal must be provided when connecting with a proxy role.

Problem

When WebSocket connections were made through a Pulsar proxy with both authentication and authorization enabled, the authorization logic would fail because:

1. The system detected the client role as a proxy role (e.g., "websocket_proxy")
2. For proxy roles, the system requires both the proxy role AND the original client role to be authorized
3. WebSocket connections didn't have a proper original principal set, causing authorization to fail

Solution

Introduced a "dummy original principal" concept specifically for WebSocket connections:

• WebSocket service sets a dummy original principal when creating its internal client since WebSocket already done the authorization
• Authorization service detects this dummy principal and skips dual authorization
• Only applies single authorization (just the proxy role) for WebSocket connections
• Maintains security by still authorizing the proxy role itself

Why not passing the original principle to broker for authorization, just keep it consistent with Pulsar proxy?

The Websocket proxy is working differently with Pulsar proxy

1. Avoiding Duplicated Authorization

The WebSocket proxy is already performing authorization when clients connect and attempt operations. Requiring the broker to re-authorize the same client would be Redundant and Inefficient.

2. Shared Pulsar Client Architecture

This is the crucial technical constraint. WebSocket proxy uses a single shared Pulsar client for all WebSocket connections.

To use original principals, we would need:
// This would require a completely different architecture
Map<String, PulsarClient> clientsPerPrincipal = new HashMap<>();

// For each WebSocket client with different principal
PulsarClient clientForPrincipal = PulsarClient.builder()
.authentication(clientPrincipal) // Different auth for each client
.build();

Why This Architectural Change is Problematic

Resource Overhead

• N WebSocket clients = N broker connections instead of 1 shared connection
• Connection pool explosion: Each client needs its own connection pool
• Memory usage: Each PulsarClient maintains its own resources (netty threads, connection pools, etc.)

Complexity

• Connection lifecycle management: Track and cleanup per-client connections
• Connection reuse: Need complex logic to share connections between clients with same principal
• Error handling: Handle individual client connection failures independently

Performance Impact

• Connection establishment overhead: Each new client principal requires broker handshake
• Broker resource consumption: Broker maintains many more connections
• Network overhead: More TCP connections, more heartbeats, more metadata exchanges

The Dummy Principal Solution

Given these constraints, the dummy principal approach:

1. Maintains the efficient shared client architecture
2. Avoids duplicated authorization (proxy already authorized the client)
3. Requires minimal code changes and maintains backward compatibility
4. Preserves performance characteristics of the current implementation

Security Considerations

The security model becomes:

• WebSocket proxy: Authorizes client access and operations
• Broker: Trusts the proxy's authorization decisions (via dummy principal detection)

This is actually a cleaner separation of concerns - the proxy handles client authorization, and the broker trusts the proxy's decisions.

A concern for client side to assign the dummy principle to get rid of the authorization?

• It's impossible since the broker will still authorize the auth data even if dummy principle is present.
• User can try to set dummy principle and connect to Pulsar proxy, but Pulsar proxy will not take the dummy principle from the client side, it will always get the original principle from the authenticated data.

Key Changes

Core Authorization Logic (AuthorizationService.java)

if (isProxyRole(authParams.getClientRole()) && !isWebsocketPrinciple(authParams.getOriginalPrincipal())) {
    // Apply dual authorization (proxy + original principal)
} else {
    // Apply single authorization (just the client role)
}

WebSocket Service (WebSocketService.java)

if (clientBuilder instanceof ClientBuilderImpl) {
    ((ClientBuilderImpl) clientBuilder).originalPrincipal(WEBSOCKET_DUMMY_ORIGINAL_PRINCIPLE);
}

Test Plan

• Added WebSocketProxyAuthIntegrationTest with JWT token authentication
• Tests WebSocket proxy with authentication and authorization enabled
• Validates produce/consume operations work correctly with different tokens:
  • ADMIN_TOKEN: Used by admin client for setup operations
  • PROXY_TOKEN: Used by WebSocket proxy's internal client
  • CLIENT_TOKEN: Used by WebSocket clients
• Ensures proper authorization flow with dummy principal handling

Verification

The integration test confirms:

• WebSocket connections can authenticate through proxy with proper tokens

• Authorization works correctly with the dummy principal approach

• Messages can be successfully produced and consumed

• No regression in existing proxy authorization behavior

• doc

• doc-required

• doc-not-needed

• doc-complete

🤖 Generated with Claude Code