Identity provider
Kottster includes a built-in identity provider for managing authentication, users, and roles. Built on SQLite, it works out of the box without requiring external services.
The identity provider comes pre-configured and ready to use. When you create a new Kottster project, all security keys and configuration are automatically generated.
Initial setup
On first launch, you'll set up the root administrator credentials by defining a username and password. These credentials are stored in your configuration file and used to authenticate the root user.
Configuration
Your Kottster app includes a pre-configured app/_server/app.js
file where the identity provider is already set up using the identityProvider
option and createIdentityProvider
function.
import { createApp, createIdentityProvider } from '@kottster/server';
import schema from '../../kottster-app.json';
export const app = createApp({
schema,
secretKey: '<auto-generated-secret-key>',
identityProvider: createIdentityProvider('sqlite', {
fileName: 'app.db',
passwordHashAlgorithm: 'bcrypt',
jwtSecretSalt: '<auto-generated-jwt-salt>',
// Root admin credentials (set on first launch)
rootUsername: '<set-on-first-launch>',
rootPassword: '<set-on-first-launch>',
}),
});
Configuration options
Setting | Default Value | Description |
---|---|---|
fileName | app.db | SQLite database file name |
passwordHashAlgorithm | bcrypt | Password hashing algorithm (bcrypt , argon2 , or sha256 ) |
jwtSecretSalt | Auto-generated | Random string for JWT token signing |
secretKey | Auto-generated | Application secret key |
rootUsername | Set on first launch | Root administrator username |
rootPassword | Set on first launch | Root administrator password |
rootCustomPermissions | [] | Optional array of custom permission strings |
All keys and salts are automatically generated as random strings during project initialization. While you can modify these values later, changing jwtSecretSalt
or secretKey
will invalidate all existing user sessions.
Before deploying to production, move secret keys and sensitive configuration to environment variables for better security.
Database schema
The identity provider stores data in the following tables:
users
- Stores user information, including hashed passwords and metadataroles
- Defines available roles and their associated permissionsuser_roles
- Maps users to their assigned roles (many-to-many relationship)login_attempts
- Tracks authentication attempts for rate limiting and monitoring
Root user best practices
We recommend against using the root account for everyday tasks. Instead, create specific roles with appropriate permissions for regular users.
The root user is automatically granted all permissions and roles, even if not explicitly listed in your roles and permissions configuration.
Enhanced security options
Custom validation middleware
For apps requiring additional security validation or custom authorization logic, implement the postAuthMiddleware
option in your app configuration.
The postAuthMiddleware
function allows you to add custom security checks after standard JWT validation but before requests reach your application logic. This function should perform additional validation and throw an error if validation fails.
The middleware function receives two parameters:
user
— The authenticated user object containingid
,username
, andemail
propertiesreq
— The Express request object with all standard properties and methods
The following example demonstrates how to implement custom middleware that validates the user's status using an external API:
import { createApp } from '@kottster/server';
import schema from '../../kottster-app.json';
import axios from 'axios';
export const app = createApp({
schema,
secretKey: process.env.SECRET_KEY,
postAuthMiddleware: async (user, req) => {
// Validate user status with your external API
const response = await axios.get(
`https://api.example.com/users/${user.id}/status`
);
if (!response.data.success) {
throw new Error('User not authorized by external service');
}
return true;
}
});
External identity providers
Organizations requiring integration with existing identity management systems can configure Kottster apps to work with alternative authentication providers, including self-hosted solutions, Clerk, Auth0, and other popular providers. SSO protocols like OpenID Connect and SAML are supported.
This option is available exclusively with the Enterprise plan and includes dedicated integration support.