Manage Server Accounts and Security

When you run PSF Guard as a web server, you can enable user authentication. Authentication is disabled by default, and the desktop application does not use it. However, if the server is configured to accept remote connections, it requires authentication to restrict access to the catalog.

Understand how the bind address affects authentication

A loopback server is only accessible from the local host, so it does not require authentication. If the server is bound to any other network interface and has no accounts configured, it responds to all API requests, including read operations, with an HTTP 401 Unauthorized status.

The --allow-database-management flag imposes stricter security: if the server is bound to a network address, it will not start until at least one user account exists. This is because database management routes allow the server to read and write to filesystem paths. Once you create an account, only users with the editor role can access these routes.

Configure anonymous access for network servers

The --allow-anonymous-access flag allows all network connections without requiring user accounts or logins, similar to a localhost server, and logs all server activity.

psf-guard server --host 0.0.0.0 --allow-anonymous-access

You should only use this setting on fully trusted private networks or to perform zero-downtime server upgrades. This flag grants full editor permissions (including grading, imports, and, if --allow-database-management is enabled, registry modifications) to anyone who can connect to the server port. This should be treated as a temporary measure: you should add user accounts and then remove this flag.

Assign editor and read-only user roles

A user with the read-only role can view catalogs, images, quality results, exports, and cached analysis. By default, read-only users cannot start resource-intensive tasks, such as stack builds, plate solves, satellite predictions, or view generation, though they can access all previously cached results. You can set allow_read_only_compute = true in the configuration to allow read-only users to trigger these computations. This is suitable for trusted private servers, but is not recommended for public servers where concurrent jobs could exhaust CPU, network bandwidth, and cache storage.

An editor can grade images, edit projects and plans, initiate quality scans and imports, generate exports, and apply synchronization previews. If database management is enabled, an editor can also manage databases, remote clients, peers, catalogs, and calibration records.

The server enforces role permissions directly on the backend, which prevents unauthorized API clients from bypassing security. The user interface labels read-only sessions as Read only, hides the Settings panel, and disables grading controls.

Manage user accounts

An editor signed in to a web server can access the Users tab in Settings to add accounts, record optional email addresses, update roles or passwords, and delete accounts. All changes take effect immediately. Modifying account permissions or passwords terminates active sessions for that user, while updating only the email address does not. The user interface prevents you from deleting the account you are currently logged in with, and prevents you from removing the last editor account.

You can also perform these user management operations from the command-line interface, which prompts you twice for a password without echoing input if you do not specify a password file:

psf-guard users add viewer --role read-only --email viewer@example.com
psf-guard users add editor --role read-write --password-file /run/secrets/editor
psf-guard users list
psf-guard users remove viewer

Passwords are stored as salted Argon2 hashes in the auth.json file located next to the database registry, using file permissions 0600 on Unix systems. The raw password is never saved. You can use the --replace flag to update a user's role or password. You must restart the server after making user modifications through the command-line interface, as active sessions remain valid until the server restarts.

Sign in to the server

When the auth.json file contains at least one user account, the server displays a login page in the browser. A successful login sets an HttpOnly cookie with the SameSite=Strict attribute. Active sessions are stored in server memory, expire after the duration specified by session_hours, and are terminated if the server restarts.

[server.auth]
session_hours = 168
secure_cookie = true
allow_read_only_compute = false

Secure cookies are enabled by default. You should only set secure_cookie = false when running a local HTTP development server, as modern browsers will not transmit cookies marked as Secure over unencrypted HTTP connections.

Use bearer credentials for remote clients

Remote image uploads and scheduler synchronization utilize Authorization: Bearer token credentials that are scoped to a single catalog. These endpoints remain functional without requiring a browser session, which allows automated ingest servers to operate independently of the grading interface.

By default, pairing a remote client requires database management permissions. An editor can navigate to Settings → Databases, edit the catalog, and generate a Pair a client pairing code. This pairing code is single-use and expires after one hour. Once paired, the remote client receives the catalog ID and its unique credential. The PSF Guard server stores only the digest of the client credential, and the N.I.N.A. plugin stores the credential securely in Windows Credential Manager.

Each connected client installation is listed under Paired clients. Revoking a client credential only disables access for that specific installation. It does not affect active browser sessions, revoke other paired clients, or invalidate legacy manual API keys. Pairing enables scheduler synchronization, but image uploads remain controlled by a separate setting and require a configured receive directory.

Legacy clients can continue to connect using a manually generated Remote API key and the catalog ID. Replacing the manual key only invalidates the previous manual key, and does not affect paired client credentials. For more details on configuring these options, see the N.I.N.A. Sync Plugin setup section.

Scripts that drive the ordinary UI API log in with a cookie jar instead:

curl -c psf-guard.cookies -H "Content-Type: application/json" \
  -d '{"username":"editor","password":"..."}' \
  https://guard.example/api/auth/login

curl -b psf-guard.cookies https://guard.example/api/databases

Review deployment guidelines

• You should place any public server behind an HTTPS reverse proxy. Otherwise, login passwords will be transmitted across the network in plain text.
• You can seed a new account from an existing secret using the --password-file flag, which ensures that only the password hash is written to disk.
• You should keep the --allow-database-management flag disabled unless you specifically need browser-side database management. An editor login does not bypass this restriction, and the restriction does not bypass the login requirement. A server listening on a public network address requires both.
• Logging out terminates the active session. Restarting the server revokes all current browser sessions.