Security & Access
Nanosync ships a complete enterprise-security surface: per-org tenancy (org → workspace → project), local + OIDC + SAML login, custom roles with fine-grained (verb, resource) permissions, scoped API tokens, encrypted-at-rest secrets, and a pluggable audit subsystem.
Auth is opt-in via --auth-mode=enabled. The default none keeps existing single-binary dev workflows working unchanged — useful for laptop development, CI pipelines, and trusted-network deployments where you don’t need user accounts.
When to enable auth
Turn on --auth-mode=enabled when any of the following is true:
- More than one human runs
nanosynccommands or hits the API - You need an audit trail of who changed what (compliance, SOC 2, internal review)
- You’re exposing the API beyond a trusted network
- You need SSO so users sign in with their existing IdP (Okta, Google, Azure AD)
- You want per-project resource isolation (different teams, different environments)
Stay on --auth-mode=none when:
- A single operator owns the box, behind a trusted network
- You’re running on a laptop or in CI for development
- You want zero-config bring-up and don’t mind everyone-is-admin semantics
Architecture at a glance
org
│
▼
workspaces
│
▼
projects ← pipelines, connections, runs scoped here- org — top-level tenant boundary. Most deployments have one.
- workspace — division within an org (typically a team or environment).
- project — the leaf scope. Every pipeline and connection lives in exactly one project.
A default org/workspace/project is seeded by migration; you don’t need to create the tree by hand to get started.
Roles are bound to a subject (user or service account) at one of these scopes. A binding at the workspace level applies to every project inside it (containment, not hierarchy).
Sessions are server-side opaque IDs in a nanosync_session cookie — no JWTs, so revocation is instant. API tokens look like ns_<prefix>_<secret>; only the sha256(secret) is stored.
Read next
What --auth-mode=none vs enabled actually does, and how to choose.
Operator runbook for creating the first admin user on a fresh install.
Built-in roles, the permission matrix, and custom role recipes.
OIDC and SAML configuration with Okta, Google Workspace, and Azure AD examples.
File, OTLP, and object-storage sinks for shipping audit events to your SIEM.
Upgrade an existing deployment from --auth-mode=none to enabled, safely.
Feature summary
| Capability | Status |
|---|---|
| Local password login (argon2id) | ✅ Available |
| OIDC SSO (Okta, Google, Azure AD, Auth0…) | ✅ Available |
| SAML 2.0 SSO | ✅ Available |
| Custom roles + role bindings | ✅ Available |
| Scoped API tokens with traceable usage | ✅ Available |
| AES-256-GCM at-rest encryption (versioned frame) | ✅ Available |
| Audit log — local NDJSON file sink | ✅ Available |
| Audit log — OTLP (Splunk / Datadog / Honeycomb) | ✅ Available |
| Audit log — S3 / GCS object storage sink | ⏳ v1.1 |
| Org → workspace → project tenancy | ✅ Available |
| Project-scoped resource isolation (writes + reads) | ✅ Available |
| First-run admin bootstrap | ✅ Available |
| SCIM 2.0 user provisioning | ⏳ v2 |
| ABAC / attribute conditions on bindings | ⏳ v2 |
| 4-eyes approval workflows | ⏳ v2 |
| CMEK / customer-managed KMS keys | ⏳ v2 |
| Dynamic field masking by role | ⏳ v2 |
The schema and code seams for the v2 features are already in place — they’re deferred for scope, not for technical debt.