Engine Authentication & Identity Architecture
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 identity), 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 identity) |
Service | Autonomous system accounts (daemons, ERP connectors, CI/CD runners). | Background synchronization, SAP integration, automated deployments. | Web frontend & CLI (nik env identity) |
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 nik_pat_...) | N/A | Static personal token with custom scopes |
| Automated CI/CD (GitHub Actions) | Environment Variable | Bearer Token (NIKSPHERE_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).
Related Documentation
- Engine Database Architecture — Overview of data storage isolation across engine subsystems.
- Engine API Architecture — Architectural overview of Admin, Runtime, RPC, and WebSocket APIs.
- Consuming the Engine API Quickstart — Step-by-step tutorial for consuming Engine APIs with cURL, Postman, and REST Client.
- CLI Authentication Reference — Reference for terminal authentication commands and identity management.