Engine Authentication & Identity Concept
The Niksphere Engine features a multi-tiered, enterprise-grade identity and authentication architecture designed to seamlessly bridge standalone edge deployments and large-scale corporate enterprise federations.
This guide explains how authentication works in Niksphere from an administrator and developer perspective, covering Actors, Identity methods, Client governance, and integration workflows for both interactive users and automated services.
1. Architectural Foundations: Actors vs. Identities vs. Clients
To maintain a secure, decoupled architecture, Niksphere strictly separates three fundamental concepts:
Core Definitions
- Actor (The Subject): The real-world entity (a human user or an autonomous service account) that owns data, holds permissions, and appears in audit trails.
- Identity (The Authentication Method): The specific credential or login provider (e.g., local password, Google SSO, Personal Access Token) used by an Actor to verify their identity.
- Client (The Application): The software application (CLI, Web frontend, VS Code, automated daemon) connecting to the Engine.
2. The Actor Model (User vs. Service)
Every operation performed in the Niksphere Engine is executed within the security context of an Actor. All authorization checks (RBAC) and database audit trails (system_created_by, system_modified_by) are linked directly to the Actor.
NOTE
Why Actor instead of Account?
In business applications and enterprise resource planning (ERP), Account specifically denotes financial accounts (General Ledger / Sachkonten). Actor provides a clean, domain-neutral term representing any entity capable of performing actions without colliding with accounting terminology.
Actor Types
Actors are uniformly managed and provisioned through the Web frontend or the CLI (nik env actor), regardless of their type:
| Actor Type | Description | Primary Use Cases | Management Interface |
|---|---|---|---|
User | Human individuals (developers, administrators, operators). | Interactive terminal sessions, Web frontend management, IDE extensions. | Web frontend & CLI (nik env actor) |
Service | Autonomous system accounts (daemons, ERP connectors, CI/CD runners). | Background synchronization, SAP integration, automated deployments. | Web frontend & CLI (nik env actor) |
Actors are managed using nik env actor [list|add|edit|delete]. Their associated authentication credentials (passwords, Personal Access Tokens, and external SSO links) are managed via nik env actor identity [list|password|pat|external]. Client applications are managed via nik env client [list|add|edit|toggle|delete].
3. The Identity Layer (Authentication Methods)
An Actor can possess multiple authentication methods across different providers. For example, an administrator might log in via their corporate Microsoft Entra ID account, use a local password as an offline fallback, and create a Personal Access Token for command-line scripts—all mapped to the same underlying Actor profile.
Supported Identity Types
1. Embedded Passwords (Local Login)
- Description: Traditional username and password authentication managed directly by the Engine's embedded identity provider.
- Security: Credentials are protected using salted password hashing (
bcrypt/argon2) with automatic rate limiting against brute-force attacks. - Use Case: Standalone installations, offline edge environments, or local administrative fallbacks.
2. Personal Access Tokens (PATs)
- Description: Static, scoped API tokens generated by users via the Web frontend or CLI for automated scripting, cURL, Postman, and CI/CD pipelines.
- Security: Tokens are hashed on the server; the plaintext token is displayed only once upon creation. Tokens can be restricted to specific permission scopes (e.g., read-only data access) and configured with explicit expiration dates.
- Use Case: Headless terminal commands, background scripts, and development testing.
3. External Single Sign-On (Enterprise OIDC)
- Description: Delegated authentication through corporate identity providers such as Microsoft Entra ID (Azure AD), Google Workspace, Keycloak, or Okta.
- Security: Enforces corporate compliance policies (e.g., mandatory MFA, conditional access). The Engine maps the verified external identity directly to the local Actor.
- Use Case: Centralized enterprise user management and corporate Single Sign-On.
4. Client Governance & Application Profiles
A Client represents a software application that connects to the Niksphere Engine API. Clients are governed through two distinct classification models:
4.1 Built-in vs. Custom Clients
| Attribute | Built-in Clients (First-Party) | Custom Clients (Third-Party) |
|---|---|---|
| Origin | Shipped out of the box by Niksphere (e.g., Niksphere CLI, Web frontend). | Created by administrators, partners, or external developers. |
| Provisioning | Pre-configured automatically when the Engine starts. | Registered dynamically via the Web frontend or CLI. |
| Trust Model | Pre-trusted (users log in directly without extra consent screens). | Shows an interactive authorization and consent screen during browser login. |
| Administration | Can be disabled (e.g., to restrict developer access exclusively to the Web frontend), but cannot be deleted. | Can be enabled, disabled, or permanently deleted at any time. |
4.2 Technical Client Profiles (Public vs. Confidential)
Clients operate under one of two standard OAuth 2.0 security profiles:
1. Interactive Public Clients (CLI, Web frontend, Mobile, IDE)
- Profile: Applications running directly on user workstations, mobile devices, or in web browsers where static secrets cannot be securely stored.
- Security: Client secrets are not used. Instead, security is enforced dynamically through PKCE (RFC 7636) in web browsers and the Device Code Flow (RFC 8628) in terminal environments.
- Redirect Protection: Restricted to authorized loopback addresses (
http://127.0.0.1:*,http://localhost:*) or explicit web domains.
2. Non-Interactive Confidential Clients (Machine-to-Machine / M2M)
- Profile: Backend daemons, ERP connectors, and automated server integrations running in secure hosting environments.
- Security: Uses a secure Client ID and Client Secret to authenticate directly via the OAuth 2.0 Client Credentials Grant.
- Actor Association: Directly associated with a designated Service Actor.
5. Authentication Matrix: Selecting the Right Method
Use the following reference matrix to determine the optimal authentication method for your use case:
| Integration Scenario | Recommended Method | Protocol / Flow | Client Category | Credentials Required |
|---|---|---|---|---|
| Developer Workstation (CLI) | nik auth login | OAuth 2.0 Device Code (RFC 8628) | Built-in Public Client | Browser confirmation (Passkey, SSO, or password) |
| Web frontend (Dashboard) | Browser Single Sign-On | Authorization Code + PKCE (RFC 7636) | Built-in Public Client | User credentials via local form or external IDP |
| Developer Testing & Postman | Personal Access Token (PAT) | Bearer Token (Authorization: Bearer niksphere_pat_...) | N/A | Static personal token with custom scopes |
| Automated CI/CD (GitHub Actions) | Environment Variable | Bearer Token (NIKSPHERE_CLI_TOKEN) | N/A | Injected repository secret (PAT or Service Token) |
| Production Daemon / ERP Integration | Client Credentials | OAuth 2.0 Client Credentials (RFC 6749 § 4.4) | Custom Confidential Client | Client ID + Client Secret |
| Realtime Monitoring WebSocket | WebSocket Ticket Handshake | Embedded IDP Ticket Extension (/auth/ws-ticket) | Public / Confidential | Single-use short-lived ticket token |
6. Deployment Topologies: Standalone vs. Enterprise Federation
The Niksphere Engine adapts to two primary operational topologies:
Topology 1: Standalone / Edge Deployment (Zero External Dependencies)
- How it works: The embedded identity provider manages user passwords, token generation, and cryptographic signing entirely on the local Engine instance.
- Best for: Local developer machines, edge servers, air-gapped networks, and single-node setups.
Topology 2: Enterprise SSO Federation (Central Directory Integration)
- How it works: Administrators register external identity providers (e.g.,
nik env idp external add). The Engine delegates login requests directly to Microsoft Entra ID, Google Workspace, or Keycloak, mapping authenticated corporate accounts to local Actor profiles. - Best for: Corporate environments requiring centralized user provisioning, corporate Multi-Factor Authentication (MFA), and automated employee offboarding.
7. Runtime Request Lifecycle
When a client makes a request to a protected API endpoint (such as /api/v1/admin/apps or application entity routes):
- Bearer Token Submission: The client attaches either a temporary JWT access token or a static Personal Access Token to the
Authorizationheader. - Context Resolution: The Engine validates the signature or token hash, verifies permissions, and establishes the active Actor Context.
- Execution & Auditing: The request executes. Any created or modified records automatically log the Actor's ID in standard system audit fields (
system_created_by,system_modified_by).
8. Admin Provisioning
Every Engine instance needs an initial administrative Actor before any other Actor, Client, or permission can be provisioned. Niksphere never ships a fixed, hardcoded administrative credential — instead, two independent mechanisms cover the two situations that actually require one: a genuinely fresh install with nobody watching the deployment configuration, and an operator who deliberately wants a specific, known administrative identity (for an emergency recovery, or for a fully automated pipeline).
8.1 Default Admin Provisioning
If the Engine starts against a completely empty Actor table and no configured admin (see below) is set up, it generates a permanent default admin account (username NikAdmin) with a randomly generated password and Personal Access Token, logged once at WARN level — capture these values immediately, since they are not shown again.
From that point on, this is an ordinary, permanent Actor like any other — it survives restarts, its password can be changed through the Web frontend or the CLI, and additional Actors can be created normally.
8.2 Configured Admin Provisioning
Three configuration values let an operator configure a specific, known administrative identity instead of relying on the randomly generated default admin. Like every other Engine setting, they can be provided as environment variables or in the Engine's own configuration file:
| Configuration Key | Environment Variable | Purpose |
|---|---|---|
admin_username | NIKSPHERE_ENGINE_ADMIN_USERNAME | Name of the configured admin Actor. Required for the other two to take effect. |
admin_password | NIKSPHERE_ENGINE_ADMIN_PASSWORD | Password for interactive login (minimum 16 characters). |
admin_pat | NIKSPHERE_ENGINE_ADMIN_PAT | A pre-chosen Personal Access Token value, must start with niksphere_pat_ and be at least 16 characters after that prefix. |
This mechanism serves two distinct scenarios:
- Self-hosted emergency access: An administrator who lost their credentials sets these values (typically as environment variables, the fastest way to override a running deployment) and restarts the Engine — whoever can restart the process already controls it, so this does not introduce a new trust boundary.
- Headless CI/CD provisioning: A pipeline that spins up an Engine instance (for automated tests, or for compiling and installing an app) sets
NIKSPHERE_ENGINE_ADMIN_PATon the Engine and the identical value asNIKSPHERE_CLI_TOKEN(see CLI Authentication Reference) for thenikCLI, letting the CLI authenticate immediately without any interactive login step.
The configured admin is fully reconciled on every Engine startup:
- Configuring
admin_usernamecreates or updates this Actor to match the current values. - Unsetting it (on a later restart) deletes the configured admin Actor again — it never lingers once the operator stops configuring it.
Because a value accidentally left set in a deployment's configuration would otherwise stay valid forever, the two credentials behave differently once used: interactive password login succeeds exactly once per Engine process lifetime — a further attempt is rejected until the Engine restarts, which re-arms it. The PAT is not subject to this restriction and stays valid for the entire process lifetime, since a CI/CD pipeline needs to make many consecutive CLI calls against the same running Engine instance.
Related Documentation
- Engine Database Concept — Overview of data storage isolation across engine subsystems.
- Engine API Concept — Architectural overview of Admin, Runtime, RPC, and WebSocket APIs.
- Engine API Consumption with Postman Quickstart — Step-by-step tutorial for consuming Engine APIs with cURL, Postman, and REST Client.
- Engine External IdP Setup with Auth0 Quickstart — Step-by-step tutorial for connecting an External SSO provider (Auth0) to the Engine.
- CLI Authentication Reference — Reference for terminal authentication commands and identity management.