AppMan's Multi-Tenancy Architecture

At AppMan, our software is designed from the ground up to serve multiple clients from a single, unified infrastructure. This multi-tenant architecture allows for efficiency and rapid innovation, but its most critical design principle is tenant isolation. This document explains the multi-layered strategy we employ to guarantee that your data and operations are always secure and completely isolated from other tenants.

Our approach is built on three core pillars:

User Authentication & Tenant Identification: Securing who can access the system.
Permission & Configuration Management: Customizing what each user can see and do.
Backend Microservice Communication: Securing how our internal services communicate on your behalf.

User Authentication and Tenant Identification

We ensure that every user is securely tied to their designated tenant environment from the moment they log in. This is achieved through a centralised identity management system that embeds tenant identity into every user session.

Identity Provider: We utilise Keycloak as our central and secure identity provider to manage all user authentications.
Tenant Identification: When one of your users logs in, Keycloak validates their credentials and issues a secure access token (JWT). We enrich this token with a custom attribute, provider: 'your_company_name', which uniquely identifies the user as belonging to your organisation.
Application-Level Isolation: Our application is built to be "tenant-aware." It reads the provider attribute from the token and automatically applies it as a mandatory filter to every single database query. This creates a secure, logical "silo" around your data, making it impossible for a user to see or modify data belonging to another tenant.

Visualising the User Authentication Flow

Centralised Permission and Configuration Management

Beyond just identifying a tenant, we provide a unique and tailored experience for each client. This includes custom branding, feature sets, and user permissions, all managed centrally without altering the core application code.

Centralised Management: We use a headless Content Management System(CMS) as a central control panel. Here, we define the specific configuration for each tenant, from visual themes (logos and colours) to which product features are enabled.
Role-Based Permissions: When a user logs in, their access token contains their assigned roles (e.g., agent, client_admin). We use these roles in CMS to enforce permissions, ensuring users can only access the features and data appropriate for their position.
Dynamic Configuration: After a user is authenticated, the application makes a secure call to our Tenant Configuration API. This API, powered by CMS, returns a configuration file tailored specifically for that tenant. This allows each client to have a unique look and feel, with different features and workflows, all served from the same application.

Visualising the Configuration and Permission Flow

Backend Microservice Communication

Our commitment to isolation extends to the communication between our internal services, ensuring security is maintained throughout our entire backend.

Initial Setup: When a new client is onboarded, our mac-application-creator service generates tenant-specific configurations, including unique API keys. This configuration is then securely registered with each microservice, which stores it in its own respective database. This process links the unique provider name to a set of credentials and permissions for that client.
Runtime Isolation:During a live request, the provider and sub (user ID) are taken from the user's JWT. The initial microservice uses the provider to find the correct tenant configuration and then validates that the user is authorised by matching the sub from the token with the application.sub stored in its configuration. Once the user is authorised for the application, the service can use the tenant-specific API keys for any further internal requests. This dual-check model ensures that not only is the operation confined to the correct tenant (provider), but it is also initiated by an authorised user (sub).

Visualising the Backend Communication Flow

Conclusion

AppMan's multi-tenancy model is built on a foundation of security, isolation, and customization. By embedding a tenant identifier (provider) at the point of authentication and using it to drive data access, permissions, and configuration, we create a secure and private environment for each of our clients. This multi-layered strategy ensures your data is protected and your application experience is uniquely your own.