apache/pulsar · error · RestException

Proxy not authorized for super-user operation (proxy:%s)

Error message

Proxy not authorized for super-user operation (proxy:%s)

What it means

In validateSuperUserAccessAsync, when the authenticated appId is one of the configured proxyRoles, the broker first checks whether the proxy itself is a super-user. If AuthorizationService.isSuperUser(proxy) returns false, the request is rejected with HTTP 401 before the original principal is even considered.

Source

Thrown at pulsar-broker/src/main/java/org/apache/pulsar/broker/web/PulsarWebResource.java:237

        String appId = clientAppId();
            log.debug()
                    .attr("requestUri", uri.getRequestUri())
                    .attr("authenticated", isClientAuthenticated(appId))
                    .attr("role", appId)
                    .log("Check super user access");
                String originalPrincipal = originalPrincipal();
        try {
            validateOriginalPrincipal(appId, originalPrincipal);
        } catch (RestException e) {
            return FutureUtil.failedFuture(e);
        }

        if (pulsar.getConfiguration().getProxyRoles().contains(appId)) {
            BrokerService brokerService = pulsar.getBrokerService();
            return brokerService.getAuthorizationService().isSuperUser(appId, clientAuthData())
                    .thenCompose(proxyAuthorizationSuccess -> {
                        if (!proxyAuthorizationSuccess){
                            throw new RestException(Status.UNAUTHORIZED,
                                    String.format("Proxy not authorized for super-user "
                                            + "operation (proxy:%s)", appId));
                        }
                        return pulsar.getBrokerService()
                                .getAuthorizationService()
                                .isSuperUser(originalPrincipal, clientAuthData());
                    }).thenAccept(originalPrincipalAuthorizationSuccess -> {
                        if (!originalPrincipalAuthorizationSuccess){
                            throw new RestException(Status.UNAUTHORIZED,
                                    String.format("Original principal not authorized for super-user operation "
                                                    + "(original:%s)", originalPrincipal));
                        }
                            log.debug()
                                    .attr("authorized", originalPrincipal)
                                    .attr("proxyAppId", appId)
                                    .log("Successfully authorized as super-user");
                                            });
        } else {

View on GitHub (pinned to 820761864e)

Solutions

1. Add the proxy role to superUserRoles in broker.conf (or grant super-user via your AuthorizationProvider)
2. Confirm the proxy's authenticated role matches exactly (case) the entry in proxyRoles/superUserRoles
3. If the proxy should not be a super-user, use the tenant-admin APIs instead of super-user endpoints

Example fix

// before (broker.conf)
proxyRoles=[proxy]
superUserRoles=[admin]
// after
proxyRoles=[proxy]
superUserRoles=[admin,proxy]

try {
    admin.clusters().getClusters();
} catch (PulsarAdminException e) {
    if (e.getStatusCode() == 401 && e.getMessage().contains("Proxy not authorized")) {
        // grant the proxy role super-user access
    }
    throw e;
}

When it happens

Trigger: A request forwarded by a Pulsar proxy whose role is not granted super-user access; calling super-user-only admin endpoints through a proxy whose role was never added to superUserRoles.

Common situations: Adding the proxy role to proxyRoles on the broker but forgetting to grant it super-user rights; changed/rotated proxy role not updated in superUserRoles; new deployments where authorization provider data wasn't synced.

Related errors

• Original principal not authorized for super-user operation (
• Invalid combination of Original principal cannot be empty if
• This operation requires super-user access
• Unauthorized to validateBothSuperuserAndBrokerOperation for
• Time-out while checking authorization

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/4a847d5eccd312a0. Report an issue: GitHub.