Multi-Tenant Architecture Skill

Comprehensive multi-tenant architecture patterns for the keycloak-alpha platform with organization-based isolation.

When to Use This Skill

Activate this skill when:

Implementing multi-tenant architecture with org_id claims
Setting up database isolation strategies
Configuring per-organization themes
Building tenant provisioning workflows
Ensuring data isolation and security
Implementing cross-tenant access controls
Managing organization-scoped resources

Multi-Tenant Architecture Overview

The keycloak-alpha platform uses shared database, isolated schema approach with org_id-based isolation:

┌─────────────────────────────────────────────┐
│          Keycloak (Identity Provider)        │
│  - Manages users across all organizations   │
│  - Issues JWT tokens with org_id claim      │
│  - Handles authentication & SSO             │
└─────────────────────────────────────────────┘
                    ↓ JWT with org_id
┌─────────────────────────────────────────────┐
│            API Gateway                       │
│  - Validates tokens                         │
│  - Extracts org_id claim                    │
│  - Routes to microservices                  │
└─────────────────────────────────────────────┘
                    ↓ org_id in headers
┌─────────────────────────────────────────────┐
│         Microservices (8 services)          │
│  - Enforce org_id filtering                 │
│  - Isolate data by organization             │
│  - Apply org-specific business logic        │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│    MongoDB / PostgreSQL                     │
│  - Shared database                          │
│  - org_id indexed on all collections/tables │
│  - Row-level security (PostgreSQL)          │
└─────────────────────────────────────────────┘

JWT Token Structure with Organization Context

Token Claims

{
  "sub": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "email": "john.doe@acme.com",
  "name": "John Doe",
  "given_name": "John",
  "family_name": "Doe",
  "org_id": "org_acme",
  "org_name": "ACME Corporation",
  "realm_access": {
    "roles": ["org_admin", "user"]
  },
  "resource_access": {
    "lobbi-web-app": {
      "roles": ["user"]
    }
  },
  "email_verified": true,
  "preferred_username": "john.doe@acme.com",
  "iss": "http://localhost:8080/realms/lobbi",
  "aud": "account",
  "exp": 1702000000,
  "iat": 1701999700,
  "jti": "unique-token-id"
}

Configure org_id Claim Mapper

# Add protocol mapper to include org_id in tokens
TOKEN=$(curl -X POST "http://localhost:8080/realms/master/protocol/openid-connect/token" \
  -d "username=admin&password=admin&grant_type=password&client_id=admin-cli" \
  | jq -r '.access_token')

CLIENT_UUID=$(curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8080/admin/realms/lobbi/clients?clientId=lobbi-web-app" \
  | jq -r '.[0].id')

curl -X POST "http://localhost:8080/admin/realms/lobbi/clients/$CLIENT_UUID/protocol-mappers/models" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "org_id_mapper",
    "protocol": "openid-connect",
    "protocolMapper": "oidc-usermodel-attribute-mapper",
    "config": {
      "user.attribute": "org_id",
      "claim.name": "org_id",
      "jsonType.label": "String",
      "id.token.claim": "true",
      "access.token.claim": "true",
      "userinfo.token.claim": "true"
    }
  }'

curl -X POST "http://localhost:8080/admin/realms/lobbi/clients/$CLIENT_UUID/protocol-mappers/models" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "org_name_mapper",
    "protocol": "openid-connect",
    "protocolMapper": "oidc-usermodel-attribute-mapper",
    "config": {
      "user.attribute": "org_name",
      "claim.name": "org_name",
      "jsonType.label": "String",
      "id.token.claim": "true",
      "access.token.claim": "true",
      "userinfo.token.claim": "false"
    }
  }'

Token Verification Middleware

// services/api-gateway/src/middleware/auth.js
import jwt from 'jsonwebtoken';
import jwksClient from 'jwks-rsa';
import { UnauthorizedError, ForbiddenError } from '../utils/AppError.js';

const client = jwksClient({
  jwksUri: `${process.env.KEYCLOAK_URL}/realms/${process.env.KEYCLOAK_REALM}/protocol/openid-connect/certs`,
  cache: true,
  rateLimit: true,
  jwksRequestsPerMinute: 10
});

function getKey(header, callback) {
  client.getSigningKey(header.kid, (err, key) => {
    const signingKey = key.publicKey || key.rsaPublicKey;
    callback(null, signingKey);
  });
}

export async function authMiddleware(req, res, next) {
  const token = req.headers.authorization?.replace('Bearer ', '');

  if (!token) {
    return next(new UnauthorizedError('No token provided'));
  }

  jwt.verify(token, getKey, {
    audience: 'account',
    issuer: `${process.env.KEYCLOAK_URL}/realms/${process.env.KEYCLOAK_REALM}`,
    algorithms: ['RS256']
  }, (err, decoded) => {
    if (err) {
      return next(new UnauthorizedError('Invalid token'));
    }

    // CRITICAL: Verify org_id claim exists
    if (!decoded.org_id) {
      return next(new ForbiddenError('Missing org_id claim in token'));
    }

    // Attach user context to request
    req.user = {
      sub: decoded.sub,
      email: decoded.email,
      name: decoded.name,
      orgId: decoded.org_id,
      orgName: decoded.org_name,
      roles: decoded.realm_access?.roles || []
    };

    next();
  });
}

// Optional: Verify org_id matches resource being accessed
export function requireOrgAccess(req, res, next) {
  const resourceOrgId = req.params.orgId || req.query.org_id || req.body.org_id;

  if (resourceOrgId && resourceOrgId !== req.user.orgId) {
    // Allow super_admin to access any org
    if (!req.user.roles.includes('super_admin')) {
      return next(new ForbiddenError('Cannot access resources from different organization'));
    }
  }

  next();
}

Database Isolation Strategies

MongoDB Isolation with org_id

// services/user-service/src/models/User.js
import mongoose from 'mongoose';

const userSchema = new mongoose.Schema({
  keycloakId: {
    type: String,
    required: true,
    unique: true,
    index: true
  },
  email: {
    type: String,
    required: true,
    lowercase: true,
    trim: true
  },
  org_id: {
    type: String,
    required: true,
    index: true  // CRITICAL: Always index org_id
  },
  firstName: String,
  lastName: String,
  metadata: {
    type: Map,
    of: String
  }
}, {
  timestamps: true
});

// CRITICAL: Compound index for org-scoped queries
userSchema.index({ org_id: 1, email: 1 }, { unique: true });
userSchema.index({ org_id: 1, createdAt: -1 });

// Pre-query hook to enforce org_id filtering
userSchema.pre(/^find/, function(next) {
  // Only enforce if org_id is not already in query
  if (!this.getQuery().org_id && this.options.orgId) {
    this.where({ org_id: this.options.orgId });
  }
  next();
});

export const UserModel = mongoose.model('User', userSchema);

Repository Pattern with org_id Isolation

// services/user-service/src/repositories/user.repository.js
import { UserModel } from '../models/User.js';
import { ForbiddenError, NotFoundError } from '../utils/AppError.js';

export class UserRepository {

  constructor(orgId) {
    this.orgId = orgId;
  }

  async findAll(filter = {}, options = {}) {
    // ALWAYS enforce org_id filtering
    const query = {
      ...filter,
      org_id: this.orgId
    };

    const { page = 1, limit = 20, sort = { createdAt: -1 } } = options;

    const users = await UserModel.find(query)
      .select('-password')
      .limit(limit)
      .skip((page - 1) * limit)
      .sort(sort);

    const total = await UserModel.countDocuments(query);

    return {
      data: users,
      pagination: {
        page,
        limit,
        total,
        pages: Math.ceil(total / limit)
      }
    };
  }

  async findById(id) {
    const user = await UserModel.findOne({
      _id: id,
      org_id: this.orgId  // CRITICAL: Always filter by org_id
    }).select('-password');

    if (!user) {
      throw new NotFoundError('User');
    }

    return user;
  }

  async create(userData) {
    const user = new UserModel({
      ...userData,
      org_id: this.orgId  // CRITICAL: Always set org_id
    });

    await user.save();
    return user;
  }

  async update(id, updates) {
    // Prevent changing org_id
    delete updates.org_id;

    const user = await UserModel.findOneAndUpdate(
      { _id: id, org_id: this.orgId },  // CRITICAL: Filter by org_id
      updates,
      { new: true, runValidators: true }
    ).select('-password');

    if (!user) {
      throw new NotFoundError('User');
    }

    return user;
  }

  async delete(id) {
    const result = await UserModel.deleteOne({
      _id: id,
      org_id: this.orgId  // CRITICAL: Filter by org_id
    });

    if (result.deletedCount === 0) {
      throw new NotFoundError('User');
    }

    return true;
  }
}

// Usage in controller
export async function listUsers(req, res, next) {
  try {
    const repository = new UserRepository(req.user.orgId);
    const result = await repository.findAll(
      { status: 'active' },
      { page: req.query.page, limit: req.query.limit }
    );

    res.json(result);
  } catch (error) {
    next(error);
  }
}

PostgreSQL Row-Level Security

-- services/billing-service/migrations/001_create_subscriptions.sql

-- Enable row-level security
ALTER TABLE subscriptions ENABLE ROW LEVEL SECURITY;

-- Create policy for org isolation
CREATE POLICY org_isolation ON subscriptions
  USING (org_id = current_setting('app.current_org_id')::text);

-- Grant access to application role
GRANT SELECT, INSERT, UPDATE, DELETE ON subscriptions TO app_user;

-- Function to set org context
CREATE OR REPLACE FUNCTION set_org_context(p_org_id text)
RETURNS void AS $$
BEGIN
  PERFORM set_config('app.current_org_id', p_org_id, false);
END;
$$ LANGUAGE plpgsql;

// services/billing-service/src/config/postgres.js
import { Pool } from 'pg';

export class PostgresClient {

  constructor() {
    this.pool = new Pool({
      host: process.env.POSTGRES_HOST,
      port: process.env.POSTGRES_PORT,
      database: process.env.POSTGRES_DB,
      user: process.env.POSTGRES_USER,
      password: process.env.POSTGRES_PASSWORD,
      max: 20,
      idleTimeoutMillis: 30000
    });
  }

  async query(orgId, text, params) {
    const client = await this.pool.connect();

    try {
      // Set org context for row-level security
      await client.query('SELECT set_org_context($1)', [orgId]);

      // Execute query (RLS automatically filters by org_id)
      const result = await client.query(text, params);

      return result;
    } finally {
      client.release();
    }
  }
}

// Usage
const db = new PostgresClient();

export async function getSubscription(req, res, next) {
  try {
    const result = await db.query(
      req.user.orgId,
      'SELECT * FROM subscriptions WHERE id = $1',
      [req.params.id]
    );

    if (result.rows.length === 0) {
      throw new NotFoundError('Subscription');
    }

    res.json(result.rows[0]);
  } catch (error) {
    next(error);
  }
}

Theme Switching Per Organization

Theme Mapping Configuration

// services/keycloak-service/src/config/theme-mapping.js
export const themeMapping = {
  // Organization ID -> Theme name mapping
  org_acme: 'acme-custom',
  org_beta: 'beta-theme',
  org_gamma: 'gamma-dark',

  // Default theme for organizations without custom theme
  default: 'lobbi-base'
};

export function getThemeForOrg(orgId) {
  return themeMapping[orgId] || themeMapping.default;
}

export function getAllThemes() {
  const themes = new Set(Object.values(themeMapping));
  return Array.from(themes);
}

Dynamic Theme Application

// services/api-gateway/src/middleware/theme-redirect.js
import { getThemeForOrg } from '../config/theme-mapping.js';

export function themeRedirectMiddleware(req, res, next) {
  // Extract org_id from token or session
  const orgId = req.user?.orgId;

  if (!orgId) {
    return next();
  }

  // Get theme for organization
  const theme = getThemeForOrg(orgId);

  // If redirecting to Keycloak login, add theme parameter
  if (req.path.includes('/auth') || req.path.includes('/login')) {
    const keycloakUrl = new URL(process.env.KEYCLOAK_URL);
    keycloakUrl.pathname = `/realms/${process.env.KEYCLOAK_REALM}/protocol/openid-connect/auth`;

    keycloakUrl.searchParams.set('client_id', 'lobbi-web-app');
    keycloakUrl.searchParams.set('redirect_uri', req.query.redirect_uri);
    keycloakUrl.searchParams.set('response_type', 'code');
    keycloakUrl.searchParams.set('scope', 'openid profile email');
    keycloakUrl.searchParams.set('kc_theme', theme);  // Apply theme

    return res.redirect(keycloakUrl.toString());
  }

  // Store theme in session for frontend
  req.session.theme = theme;
  next();
}

Frontend Theme Consumption

// apps/web-app/src/contexts/ThemeContext.jsx
import { createContext, useContext, useState, useEffect } from 'react';
import { useAuth } from '@hooks/useAuth';
import { getThemeForOrg } from '@/api/theme';

const ThemeContext = createContext(null);

export function ThemeProvider({ children }) {
  const { user } = useAuth();
  const [theme, setTheme] = useState('lobbi-base');
  const [themeConfig, setThemeConfig] = useState(null);

  useEffect(() => {
    if (user?.orgId) {
      loadTheme(user.orgId);
    }
  }, [user?.orgId]);

  async function loadTheme(orgId) {
    try {
      const config = await getThemeForOrg(orgId);
      setTheme(config.name);
      setThemeConfig(config);

      // Apply CSS variables
      if (config.branding) {
        document.documentElement.style.setProperty('--primary-color', config.branding.primaryColor);
        document.documentElement.style.setProperty('--secondary-color', config.branding.secondaryColor);
      }
    } catch (error) {
      console.error('Failed to load theme:', error);
    }
  }

  return (
    <ThemeContext.Provider value={{ theme, themeConfig }}>
      {children}
    </ThemeContext.Provider>
  );
}

export const useTheme = () => useContext(ThemeContext);

Tenant Provisioning Workflow

Organization Creation Service

// services/org-service/src/services/provisioning.service.js
import { OrganizationModel } from '../models/Organization.js';
import { KeycloakService } from './keycloak.service.js';
import { DatabaseService } from './database.service.js';
import { ThemeService } from './theme.service.js';
import { BillingService } from './billing.service.js';

export class ProvisioningService {

  async provisionOrganization(data) {
    const {
      name,
      domain,
      adminEmail,
      adminFirstName,
      adminLastName,
      plan = 'free'
    } = data;

    // Generate org_id
    const orgId = `org_${domain.replace(/[^a-z0-9]/gi, '_').toLowerCase()}`;

    try {
      // 1. Create organization in database
      const org = await this.createOrganization({
        orgId,
        name,
        domain,
        plan
      });

      // 2. Create Keycloak group for organization
      const keycloakService = new KeycloakService();
      const groupId = await keycloakService.createOrganizationGroup(orgId, name);

      // 3. Create admin user in Keycloak
      const adminUserId = await keycloakService.createUser({
        email: adminEmail,
        firstName: adminFirstName,
        lastName: adminLastName,
        orgId,
        roles: ['org_admin']
      });

      // 4. Add user to organization group
      await keycloakService.addUserToGroup(adminUserId, groupId);

      // 5. Initialize database schemas/collections
      const databaseService = new DatabaseService();
      await databaseService.initializeOrgCollections(orgId);

      // 6. Set up default theme
      const themeService = new ThemeService();
      await themeService.createOrgTheme(orgId, {
        parent: 'lobbi-base',
        branding: {
          logoUrl: null,
          primaryColor: '#3182ce',
          secondaryColor: '#805ad5'
        }
      });

      // 7. Create billing customer (if not free plan)
      if (plan !== 'free') {
        const billingService = new BillingService();
        await billingService.createCustomer({
          orgId,
          email: adminEmail,
          name,
          plan
        });
      }

      // 8. Send welcome email
      await this.sendWelcomeEmail(adminEmail, {
        orgName: name,
        loginUrl: process.env.APP_URL
      });

      return {
        orgId,
        organizationId: org._id,
        adminUserId,
        message: 'Organization provisioned successfully'
      };

    } catch (error) {
      // Rollback on failure
      await this.rollbackProvisioning(orgId);
      throw error;
    }
  }

  async createOrganization(data) {
    const org = new OrganizationModel({
      org_id: data.orgId,
      name: data.name,
      domain: data.domain,
      settings: {
        theme: 'lobbi-base',
        features: new Map([
          ['sso', data.plan !== 'free'],
          ['advanced_analytics', data.plan === 'enterprise'],
          ['custom_branding', data.plan !== 'free']
        ])
      },
      subscription: {
        plan: data.plan,
        status: 'active',
        billingCycle: 'monthly'
      },
      status: 'active'
    });

    await org.save();
    return org;
  }

  async rollbackProvisioning(orgId) {
    console.error(`Rolling back provisioning for ${orgId}`);

    try {
      // Delete organization from database
      await OrganizationModel.deleteOne({ org_id: orgId });

      // Delete Keycloak group and users
      const keycloakService = new KeycloakService();
      await keycloakService.deleteOrganizationGroup(orgId);

      // Clean up database collections
      const databaseService = new DatabaseService();
      await databaseService.cleanupOrgCollections(orgId);

    } catch (rollbackError) {
      console.error('Rollback failed:', rollbackError);
    }
  }
}

Tenant Provisioning API Endpoint

// services/org-service/src/controllers/provisioning.controller.js
import { ProvisioningService } from '../services/provisioning.service.js';
import { asyncHandler } from '../middleware/errorHandler.js';

export const provisionOrganization = asyncHandler(async (req, res) => {
  const {
    name,
    domain,
    adminEmail,
    adminFirstName,
    adminLastName,
    plan
  } = req.body;

  const provisioningService = new ProvisioningService();

  const result = await provisioningService.provisionOrganization({
    name,
    domain,
    adminEmail,
    adminFirstName,
    adminLastName,
    plan
  });

  res.status(201).json(result);
});

export const deprovisionOrganization = asyncHandler(async (req, res) => {
  const { orgId } = req.params;

  // Only super_admin can deprovision
  if (!req.user.roles.includes('super_admin')) {
    throw new ForbiddenError('Insufficient permissions');
  }

  const provisioningService = new ProvisioningService();
  await provisioningService.deprovisionOrganization(orgId);

  res.json({ message: 'Organization deprovisioned successfully' });
});

Data Isolation Patterns

Query Middleware for Automatic org_id Filtering

// shared/middleware/org-scope.middleware.js
export function orgScopeMiddleware(Model) {
  // Pre-find hooks
  Model.schema.pre(/^find/, function(next) {
    if (this.options.skipOrgFilter) {
      return next();
    }

    // Automatically add org_id filter if not present
    if (!this.getQuery().org_id && this.options.orgId) {
      this.where({ org_id: this.options.orgId });
    }

    next();
  });

  // Pre-update hooks
  Model.schema.pre('updateOne', function(next) {
    if (this.options.skipOrgFilter) {
      return next();
    }

    if (!this.getQuery().org_id && this.options.orgId) {
      this.where({ org_id: this.options.orgId });
    }

    next();
  });

  // Pre-delete hooks
  Model.schema.pre('deleteOne', function(next) {
    if (this.options.skipOrgFilter) {
      return next();
    }

    if (!this.getQuery().org_id && this.options.orgId) {
      this.where({ org_id: this.options.orgId });
    }

    next();
  });
}

Service-Level Isolation

// services/user-service/src/services/user.service.js
export class UserService {

  constructor(orgId) {
    if (!orgId) {
      throw new Error('orgId is required for UserService');
    }
    this.orgId = orgId;
  }

  async findAll(filter = {}, options = {}) {
    // ALWAYS enforce org_id
    return await UserModel.find({
      ...filter,
      org_id: this.orgId
    }, null, {
      orgId: this.orgId,
      ...options
    });
  }

  async findById(id) {
    const user = await UserModel.findOne({
      _id: id,
      org_id: this.orgId
    });

    if (!user) {
      throw new NotFoundError('User');
    }

    return user;
  }

  // Prevent cross-org data leaks
  async bulkUpdate(userIds, updates) {
    // First verify all users belong to this org
    const count = await UserModel.countDocuments({
      _id: { $in: userIds },
      org_id: this.orgId
    });

    if (count !== userIds.length) {
      throw new ForbiddenError('Some users do not belong to this organization');
    }

    // Proceed with update
    return await UserModel.updateMany(
      {
        _id: { $in: userIds },
        org_id: this.orgId
      },
      updates
    );
  }
}

Cross-Tenant Security Considerations

Preventing Cross-Org Data Access

// services/api-gateway/src/middleware/org-validation.middleware.js
export function validateOrgAccess(extractOrgId) {
  return (req, res, next) => {
    // Extract org_id from request (params, query, or body)
    const resourceOrgId = extractOrgId(req);

    if (!resourceOrgId) {
      return next();
    }

    // Verify user has access to this org
    if (resourceOrgId !== req.user.orgId) {
      // Super admins can access any org
      if (req.user.roles.includes('super_admin')) {
        return next();
      }

      // Log potential security violation
      console.warn('Cross-org access attempt:', {
        userId: req.user.sub,
        userOrgId: req.user.orgId,
        attemptedOrgId: resourceOrgId,
        path: req.path,
        method: req.method,
        ip: req.ip
      });

      return next(new ForbiddenError('Access denied to organization resources'));
    }

    next();
  };
}

// Usage in routes
router.get('/organizations/:orgId/users',
  validateOrgAccess(req => req.params.orgId),
  listUsers
);

Audit Logging for Cross-Org Access

// services/analytics-service/src/services/audit.service.js
export class AuditService {

  async logAccess(event) {
    const log = {
      timestamp: new Date(),
      userId: event.userId,
      userOrgId: event.userOrgId,
      resourceOrgId: event.resourceOrgId,
      action: event.action,
      resource: event.resource,
      resourceId: event.resourceId,
      success: event.success,
      ipAddress: event.ipAddress,
      userAgent: event.userAgent
    };

    // Flag suspicious cross-org access
    if (event.userOrgId !== event.resourceOrgId && !event.isSuperAdmin) {
      log.suspicious = true;
      log.severity = 'high';

      // Alert security team
      await this.sendSecurityAlert(log);
    }

    await AuditLogModel.create(log);
  }
}

Best Practices

ALWAYS include org_id in JWT tokens via Keycloak protocol mapper
NEVER trust client-provided org_id - always use token claim
INDEX org_id on ALL collections/tables for query performance
Use repository pattern to enforce org_id filtering
Implement row-level security in PostgreSQL for additional safety
Validate org_id in middleware before reaching controllers
Audit cross-org access attempts for security monitoring
Test isolation thoroughly with automated tests
Use compound indexes for org_id + frequently queried fields
Prevent org_id modification in update operations
Implement graceful tenant deprovisioning with cleanup
Version control theme mappings for traceability
Monitor query performance by org_id to detect issues
Implement rate limiting per org to prevent abuse
Use separate database connections per org for critical isolation (optional)

File Locations in keycloak-alpha

Path	Purpose
`services/org-service/`	Organization provisioning and management
`services/api-gateway/src/middleware/auth.js`	Token validation and org_id extraction
`services/keycloak-service/src/config/theme-mapping.js`	Theme per organization mapping
`shared/middleware/org-scope.middleware.js`	Automatic org_id filtering
`services/analytics-service/src/services/audit.service.js`	Cross-org access auditing

Testing Multi-Tenancy

Test Organization Isolation

// services/user-service/tests/isolation.test.js
describe('Multi-tenant isolation', () => {
  it('should prevent cross-org data access', async () => {
    // Create users in two different orgs
    const org1User = await createUser({ org_id: 'org_1', email: 'user1@org1.com' });
    const org2User = await createUser({ org_id: 'org_2', email: 'user2@org2.com' });

    // Try to access org_2 user with org_1 token
    const org1Token = generateToken({ org_id: 'org_1' });

    const response = await request(app)
      .get(`/api/users/${org2User._id}`)
      .set('Authorization', `Bearer ${org1Token}`)
      .expect(403);

    expect(response.body.error.message).toContain('Access denied');
  });

  it('should allow super_admin cross-org access', async () => {
    const org2User = await createUser({ org_id: 'org_2' });
    const superAdminToken = generateToken({
      org_id: 'org_1',
      roles: ['super_admin']
    });

    await request(app)
      .get(`/api/users/${org2User._id}`)
      .set('Authorization', `Bearer ${superAdminToken}`)
      .expect(200);
  });
});

multi-tenant