Authentication

Summary

Mechanism	Supported in GeoVault?	Notes
Central session cookie acugis_session	Yes	Primary; validated against dashboard_sessions
Authorization: Bearer personal access token (agp_…)	No	Shared middleware contains a PAT branch, but GeoVault supplies no TokenStore; bearer requests are unauthenticated and must not be used as an API security mechanism
API keys (dedicated GeoVault keys)	No	None in source
JWT	No	TokenClaims exists in shared auth for future use; not used by GeoVault
OAuth / OIDC login in GeoVault	No	Login is owned by Central
Mutual TLS client auth	No	Not implemented

GeoVault never serves /login or /logout. Under federation Apache configs those routes proxy to Central (:8888).

Authentication flow

flowchart TD
  R[Incoming request] --> C{Cookie acugis_session?}
  C -->|valid| U[Attach user]
  C -->|missing/invalid| N[Unauthenticated]
  U --> S[Service ACL geovault]
  S --> H[Handler / dataset ACL]
  N --> BR{Accepts HTML?}
  BR -->|yes| L[303 /login?next=...]
  BR -->|no| E[401 authentication required]

Middleware registration (main.go):

1. api.RequireLogin → shared/auth.RequireLogin
2. api.RequireGeoVaultServiceAccess

Headers and cookies

Name	Direction	Purpose
Cookie acugis_session	Request	Session token (HttpOnly, SameSite=Lax, Secure when HTTPS/X-Forwarded-Proto=https)
Authorization: Bearer <token>	Request	Not a supported GeoVault credential; it does not authenticate
X-Forwarded-Proto	Request	Marks secure requests; applied to URL scheme
X-Forwarded-Prefix	Request	Overrides path prefix for links (/geovault)

Authorization model

Platform service ACL

Resource: resource_type=service, resource_key=geovault.

Permissions: view, edit, admin (admin implies lower levels in permission checks).

Traffic	Required service permission
Connections UI/API, database-services	admin
Uploads	edit
Mutating methods (non-GET/HEAD)	edit
Other GET/HEAD	view

Administrators group / is_admin bypasses service ACL.

On startup, GeoVault ensures platform service catalog resources exist and grants Administrators admin on newly inserted service rows. Public and Editors do not receive automatic service-level access.

Dataset ACL

Resource: resource_type=geovault_dataset, resource_key=<dataset name>, service=geovault.

Permission	Typical use
view	Open dataset pages, metadata, preview, list visibility
edit	Upload new versions, transforms, archive, rename metadata, etc.
admin	Satisfies view/edit checks; used where admin is required

Default grants when a new dataset resource is registered:

Group	Permission
Administrators	admin
Editors	edit
Public	view

Permission hierarchy in SQL checks: admin satisfies any; edit satisfies view.

Roles / groups

Groups live in Central (auth_groups / auth_group_members). GeoVault does not create users or groups (ErrCentralOwned on mutating auth store methods). Common group names referenced in code: Administrators, Editors, Public.

Folder access uses the optional group_name: administrators can access every folder, an ungrouped folder is accessible to any authenticated user, and a grouped folder requires membership in that group. Folder ownership is displayed but is not part of the access decision.

Dataset visibility column

datasets.visibility is public or restricted. UI surfaces badges; authorization still relies on Central resource permissions (admins bypass).

API keys / JWT / OAuth

Not implemented for GeoVault:

• No GeoVault-issued API keys
• No JWT validation middleware
• No OAuth client credentials flow inside this service

CLI documentation may describe platform-wide PAT login for Central; that does not authenticate GeoVault handlers. The API contract advertises cookie security only.

Known authorization caveats (verified)

Issue	Effect
geovaultServiceRequiredPermission matches paths without stripping BASE_PATH	Under a nonempty BASE_PATH, intended admin on /api/connections* / /connections* and edit on /upload may incorrectly classify as view/edit
GET /api/esri/jobs/{id} and GET /api/geoserver/jobs/{id}	Service view only; no job-owner or dataset ACL check; job payload may include ESRI tokens
GET /api/datasets/{name}/geoserver-publications	Service view only; does not call RequireDatasetView
Unregistered PostGIS table browse/edit	Dataset ACL applies only after registration; connection-route service ACL is the intended backstop (subject to BASE_PATH caveat)
GeoServer password encryption	Without a valid secrets key, passwords may be stored as plain:...

Security best practices

1. Terminate TLS at the reverse proxy; send X-Forwarded-Proto: https. Strip client-supplied X-Forwarded-* at the edge.
2. Keep Central session cookie Secure/HttpOnly; avoid expanding ACUGIS_SESSION_COOKIE_DOMAIN unless required.
3. Grant service/geovault permissions intentionally—new platforms only auto-grant Administrators at the service level.
4. Prefer metadata DB + encrypted GeoServer secrets (GEOVAULT_SECRETS_KEY).
5. Treat pg_connections.password as sensitive plaintext at rest; restrict DB access.
6. Do not expose :8085 directly on the public internet without auth-aware proxying.
7. Keep GDAL binaries and write paths minimal (ProtectSystem=full in the sample unit).
8. Treat job IDs as sensitive; anyone with service view can poll job payloads.

Permission failures

Condition	Typical response
Not logged in (API)	401 plain text authentication required
Not logged in (browser HTML)	303 to /login?next=...
Service ACL denied	Permission-denied helper (WritePermissionDenied)
Dataset ACL denied	403 permission required
Auth DB errors	503 / 500 authentication/authorization unavailable