This document is a high-level overview of the Identity module, helpful for maintainers, contributors, and developers who want to understand its architecture and design or contribute to it.
This module is part of the Fonoster project. It does not do much by itself. It is intended to be combined with other modules to create a complete solution. For more information about the project, please visit https://github.com/fonoster/fonoster.
About Identity
The Fonoster Identity Module provides the cornerstone for secure user management, authentication, and authorization within the Fonoster Ecosystem. It is designed with flexibility and scalability to accommodate the diverse and evolving needs of the various Fonoster projects.
Key Features
This module offers comprehensive identity management functionality, including creating, reading, updating, and deleting user and workspace entities. Users may represent individual accounts or service accounts. Workspaces organize users and streamline permission administration; a user can belong to multiple workspaces.
- Authentication via JSON Web Tokens (JWTs) — username/password, Multi-Factor Authentication (MFA), OAuth2, and token exchange.
- Authorization via Role-Based Access Control (RBAC) with predefined and custom roles.
- Resource ownership keyed by
accessKeyId(US…for users,WO…for workspaces).
Running standalone
fonoster-identity (or the fonoster/identity image) serves Identity without the
telephony stack. It reads identity.json (or .jsonc/.yaml), found via
--config <path>, /opt/fonoster/identity.json or ./config/identity.json, and
reads no environment variables. Fields sit at the root of the file:
{
"database": { "url": "postgresql://postgres:postgres@postgres:5432/fnidentity" },
"encryptionKey": "change-me",
"issuer": "https://id.acme.com",
"keys": {
"privateKeyPath": "/opt/fonoster/keys/private.pem",
"publicKeyPath": "/opt/fonoster/keys/public.pem"
},
"smtp": { "host": "smtp.acme.com", "port": 587, "sender": "[email protected]", "auth": { "user": "ops", "pass": "secret" } },
"auth": { "methods": ["password"], "signup": "invite" },
"defaultUser": { "name": "Admin", "email": "[email protected]", "password": "changeme" }
}
npm run db:deploy -- --config <path> applies the migrations using the same file.
Every key is described in docs/configuration.md.
Specification
The normative specification for this module — entities and resource ownership, the RBAC model, the
id/access/refresh token model, token exchanges, RS256 verification via GetPublicKey, and security
practices — lives in OpenSpec and is the source of truth:
➡️ openspec/specs/identity/spec.md
Proposed changes to this capability live under openspec/changes/.