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: '<your-root-username>',
    rootPassword: '<your-root-password>',
  }),
});

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 metadata
• roles - Defines available roles and their associated permissions
• user_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 containing id, username, and email properties
• req — 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, KeyCloak, Okta, 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.