Skip to content

Authentication and authorization

Jasper Report Services shares the Central browser session. It does not implement bearer tokens, JWTs, API keys, Basic authentication, or a login endpoint.

Central sets acugis_session. The value is the raw session token; Jasper SHA-256 hashes its exact bytes and looks up the lowercase hex digest in dashboard_sessions.token_hash. A session is accepted only when it is unexpired and its dashboard_users row is enabled. Clients should obtain the cookie through the Central login flow and send it on same-origin Jasper requests:

Cookie: acugis_session=<opaque-session-token>

The service never accepts the hash in place of the cookie.

When authentication is enabled

Authentication is enabled only when jrs_auth_central_dsn() resolves a Central PostgreSQL DSN. Resolution checks, in order:

  1. CENTRAL_DATABASE_URL, JRS_AUTH_DATABASE_URL, and their REDIRECT_ variants.
  2. central_database_url in config.php.
  3. The Jasper application DB when explicitly selected.
  4. By default, central_database_name on the application DB server, then the application DB itself.

If no DSN resolves, authentication is disabled. Login, service ACL, report ACL, and platform-admin checks then return successfully; jrs_require_login() installs a synthetic local-dev administrator. This is a local/deployment fallback, not anonymous authentication. Ensure a Central DSN resolves in protected environments.

If a DSN resolves but Central cannot be reached, guarded endpoints fail closed with 503. JSON-classified requests receive:

{"error":"central authentication store unavailable"}

Authorization layers

  • Runtime report access: viewer, config, definition, thumbnail, and execution use jasper_report:<report-key> view permission. They do not require login first. An anonymous caller is evaluated as user ID 0 with implicit membership in the Public group. A valid session adds the user's groups. Platform administrators and recognized administrator groups bypass the report ACL.
  • Discovery: requires a valid Central session, then returns only reports for which the user has view or higher. It is not anonymous even when reports are Public. When auth is disabled, the login check bypasses.
  • Report management UI: requires login plus the jasper_reports service permission (view, edit, or admin as appropriate). Editing and deletion additionally require report-level edit or admin.
  • Resource sync and scheduling actions: require a platform administrator. The scheduler pages also check jasper_reports:view.
  • Registry endpoints: /api/reports and /api/datasources have no method check and no authentication or authorization gate. They expose report names/titles/datasource names and enabled datasource names, respectively.
  • Report image proxy: unlike report execution, requires an authenticated session and report view; anonymous Public access is not supported.

Permission inheritance is admin → edit → view. Every authenticated user's effective permission groups also include Public.

Failure behavior

For API-classified requests (paths containing /api/, report config/definition, or requests accepting JSON):

  • Missing or invalid session where login is required: 401 {"error":"authentication required"}.
  • Insufficient report/service permission: 403 {"error":"Permission denied"}.
  • Non-admin caller at an admin gate: 403 {"error":"platform administrator required"}.
  • Unreachable configured Central store: 503 {"error":"central authentication store unavailable"}.

HTML requests that require login receive 303 to CENTRAL_LOGIN_URL (default /login) with next=<original-request-uri>. Other HTML authorization failures are 403 HTML or plain text.

Runtime report endpoints intentionally return 403 Permission denied rather than 401 when an anonymous caller lacks Public access. This avoids forcing login for genuinely public reports.

Browser and client guidance

  • Use HTTPS and let Central own cookie attributes and login/logout.
  • Preserve the cookie jar across discovery, config, and execution calls.
  • JavaScript must use credentials: "include" for cross-origin deployments or credentials: "same-origin" on the normal same-origin mount.
  • Do not place session tokens in query parameters, logs, examples, or report parameters.
  • There is no CSRF token validation in the form-backed mutation handlers. Keep them same-origin, protect cookies appropriately, and do not expose them as a general public API.

Debug probe

GET /jasper-report-services/debug/session.php is available only when JRS_AUTH_DEBUG=1 or JRS_AUTH_LOGIN_TRACE=1. It never sets cookies or redirects and returns session metadata without the token value. Disabled probes return 404 with:

{"error":"debug disabled (set JRS_AUTH_DEBUG=1)"}

The separate root debug.php contains hard-coded development database access and prints sensitive session diagnostics. It is not a supported endpoint and must not be exposed in production.