{"record":{"id":"1f7ba985bc3b467d","repo":"apache/pulsar","slug":"this-operation-requires-super-user-access","errorCode":null,"errorMessage":"This operation requires super-user access","messagePattern":"This operation requires super-user access","errorType":"http","errorClass":"RestException","httpStatus":401,"severity":"error","filePath":"pulsar-broker/src/main/java/org/apache/pulsar/broker/web/PulsarWebResource.java","lineNumber":261,"sourceCode":"                                .isSuperUser(originalPrincipal, clientAuthData());\n                    }).thenAccept(originalPrincipalAuthorizationSuccess -> {\n                        if (!originalPrincipalAuthorizationSuccess){\n                            throw new RestException(Status.UNAUTHORIZED,\n                                    String.format(\"Original principal not authorized for super-user operation \"\n                                                    + \"(original:%s)\", originalPrincipal));\n                        }\n                            log.debug()\n                                    .attr(\"authorized\", originalPrincipal)\n                                    .attr(\"proxyAppId\", appId)\n                                    .log(\"Successfully authorized as super-user\");\n                                            });\n        } else {\n            return pulsar.getBrokerService()\n                    .getAuthorizationService()\n                    .isSuperUser(appId, clientAuthData())\n                    .thenAccept(proxyAuthorizationSuccess -> {\n                        if (!proxyAuthorizationSuccess) {\n                            throw new RestException(Status.UNAUTHORIZED,\n                                    \"This operation requires super-user access\");\n                        }\n                    });\n        }\n    }\n\n    /**\n     * Checks whether the user has Pulsar Super-User access to the system.\n     *\n     * @throws WebApplicationException\n     *             if not authorized\n     */\n    public void validateSuperUserAccess() {\n        sync(this::validateSuperUserAccessAsync);\n    }\n\n    /**\n     * Checks that the http client role has admin access to the specified tenant.","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker/src/main/java/org/apache/pulsar/broker/web/PulsarWebResource.java#L243-L279","documentation":"When the authenticated appId is NOT a proxy role, validateSuperUserAccessAsync performs a single isSuperUser(appId) check; if it returns false the admin call is rejected with HTTP 401 'This operation requires super-user access'. This guards super-user-only REST operations.","triggerScenarios":"Any non-proxy client calling a super-user-only admin endpoint (e.g. cluster/tenant management requiring super-user) without being listed in superUserRoles or granted super-user by the AuthorizationProvider.","commonSituations":"New admin clients onboarded without updating superUserRoles; authorization provider (e.g. custom or external store) lacking the role; token authenticating a different role than expected (audience/subject mismatch).","solutions":["Add the client's role to superUserRoles in broker.conf (or via your AuthorizationProvider)","Decode the client's credential/token to confirm which role is actually authenticated","Downgrade the operation to a tenant/namespace-scoped API that matches the client's permissions","Restart or wait for config reload after changing superUserRoles"],"exampleFix":"// before (broker.conf)\nsuperUserRoles=[admin]\n// after\nsuperUserRoles=[admin,monitoring-client]","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    admin.clusters().getClusters();\n} catch (PulsarAdminException e) {\n    if (e.getStatusCode() == 401 && e.getMessage().contains(\"requires super-user access\")) {\n        // add the authenticated role to superUserRoles or use a scoped API\n    }\n    throw e;\n}","preventionTips":["Confirm which role your token authenticates as before calling super-user endpoints","Keep superUserRoles in sync with operations clients during onboarding","Use least-privilege scoped APIs where possible instead of granting super-user"],"tags":["authorization","superuser","rest-api","pulsar"],"backgroundTag":"unauthorized-principal","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}