Security and authentication

Nona is self-hosted, so basic security and authentication decisions belong to your deployment process, not only to the application code. In practice, the security model has a few distinct layers:

admin authentication for people
API-key authentication for config reads
project access control for what each user can change
auditability for sensitive actions

First production steps

For a real deployment, pin JWT settings if that is your operating model, create individual user accounts instead of shared credentials, create narrow API keys for each app or service, keep project access limited to the teams that need it, and use short-lived share links when temporary access is enough.

API keys

Use narrow API keys whenever possible.

Good habits:

create separate keys for separate apps or services
scope keys to client, server, or all deliberately
scope keys to the specific environment they need when possible
keep keys in environment variables or a secrets system
copy a new secret immediately because Nona shows it only once
create and verify a replacement before deleting an old key when uninterrupted access matters

Nona stores uppercase SHA-256 hashes for API-key verification. Requests are hashed before lookup, and the plaintext secret is never returned by list endpoints or retained in API-key records. Existing plaintext keys are hashed automatically during the storage migration and continue to authenticate with the same client-side secret.

Key lists expose only an eight-character fingerprint for identification. To replace a credential, create a new key, update and verify its consumers, then delete the old key. Deletion permanently invalidates a key immediately, and Nona keeps no recoverable secret history.

API keys protect the runtime config API. They are not replaced by SSO.

Basic API-key workflow

In admin:

open the project
use the API Keys section
create a key per app or service
choose the narrowest scope that works
limit the key to one environment when possible

JWT settings

Nona can generate and persist JWT settings automatically, but production deployments are easier to reason about when those values are pinned explicitly.

The deployment guides show these settings:

Jwt__Key
Jwt__Issuer
Jwt__Audience

Keep Jwt__Key in a real secret store or controlled .env workflow for production.

If you rotate or change these values unexpectedly, treat that as a meaningful auth-impacting maintenance event.

User authentication

The repo supports multiple admin authentication paths:

email and password
Google SSO
Microsoft SSO
invitation-based onboarding

That matters because a self-hosted admin surface should not depend on shared operator credentials.

Good admin-access pattern

Prefer one account per operator, invitations for onboarding, SSO where it fits your identity workflow, and project-level access instead of broad shared admin access.

Parameter share links are powerful because they allow narrow temporary access, but that also means the token itself should be treated like a secret.

Remember:

anyone with the token can use the public share-link endpoint until the link expires or is revoked
short-lived links are safer than long-lived ones
link creation and revocation are written to the audit log

That makes share links useful for narrow collaboration, but not a replacement for real user and project access.

SSO and user access

The repo shows support for:

Google SSO
Microsoft SSO

Combined with per-project access, this gives teams a cleaner model than sharing one broad admin credential across every environment.

SSO is used for admin sign-in and invitation completion. Config consumers still authenticate with API keys.

For implementation details and config keys, see Single sign-on (SSO).

Project-level permissions

Authentication and authorization are different concerns.

A user may be able to sign in successfully but still only have access to a limited set of projects. That is the safer operating model for one Nona deployment serving multiple apps, teams, or environments.

Use project access to avoid:

broad cross-team visibility
accidental edits in unrelated projects
one shared admin account becoming a bottleneck or risk

Auditability

Security controls are stronger when identity changes and config changes are visible after the fact.

The repo includes audit-log support, which is especially relevant for:

access changes
config edits
rollback actions
share-link creation and revocation

FAQ

Does SSO replace API keys for runtime reads?

No.

SSO is for admin access. Runtime config consumers still authenticate with API keys.

What should I lock down first in production?

Start with admin access, narrow API keys, limited project access, and stable JWT settings if you pin them.

No.

One account per operator is a safer and more auditable operating model.

No.

Share links are useful for narrow temporary collaboration, but they are not a replacement for normal user and project access control.

Session and project credential revocation

Changing or resetting a password invalidates all previously issued sessions, including the current session. Sign in again using the new password. JWTs issued before credential binding was introduced are also rejected after upgrading.

Deleting a project removes its API keys and parameter share links. Recreating a project with the same name requires new credentials.

Resource deletion and CLI authorization

Deleting an environment revokes its environment-scoped API keys and all parameter share links. Deleting an individual parameter revokes its share links, including during bulk deletion. Recreating the same names does not restore these capabilities; issue new credentials for the replacement resources. Project-wide API keys retain their project-wide scope.

CLI browser login requires an explicit Authorize CLI confirmation showing the account and local callback destination, including after signing in. Approve it only when you initiated login from your terminal. The CLI callback protocol is unchanged.

Session transitions clear cached administration data and reject responses started under the previous session. Initial administrator registration atomically allows only one successful bootstrap request.