feat(ee): SCIM (#1347)

* SCIM - init (EE)

* accept db transaction

* sync

* Content parser support for scim+json

* patch scimmy

* sync

* return early if userIds is empty

* sync

* SCIM db table

* fixes

* scim tokens

* backfill

* feat(audit): add scim token events

* rename scim migration

* fix

* fix translation

* cleanup

apps/server/package.json

@@ -111,6 +111,7 @@
     "reflect-metadata": "^0.2.2",
     "rxjs": "^7.8.2",
     "sanitize-filename": "1.6.3",
+    "scimmy": "1.3.5",
     "socket.io": "^4.8.3",
     "stripe": "^17.7.0",
     "tlds": "^1.261.0",

apps/server/src/common/events/audit-events.ts

@@ -23,6 +23,11 @@ export const AuditEvent = {
   API_KEY_UPDATED: 'api_key.updated',
   API_KEY_DELETED: 'api_key.deleted',
 
+  // SCIM Tokens
+  SCIM_TOKEN_CREATED: 'scim_token.created',
+  SCIM_TOKEN_UPDATED: 'scim_token.updated',
+  SCIM_TOKEN_DELETED: 'scim_token.deleted',
+
   // Space
   SPACE_CREATED: 'space.created',
   SPACE_UPDATED: 'space.updated',
@@ -119,6 +124,7 @@ export const AuditResource = {
   COMMENT: 'comment',
   SHARE: 'share',
   API_KEY: 'api_key',
+  SCIM_TOKEN: 'scim_token',
   SSO_PROVIDER: 'sso_provider',
   WORKSPACE_INVITATION: 'workspace_invitation',
   ATTACHMENT: 'attachment',

apps/server/src/common/helpers/utils.ts

@@ -110,7 +110,7 @@ export function extractBearerTokenFromHeader(
   request: FastifyRequest,
 ): string | undefined {
   const [type, token] = request.headers.authorization?.split(' ') ?? [];
-  return type === 'Bearer' ? token : undefined;
+  return type?.toLowerCase() === 'bearer' ? token : undefined;
 }
 
 /**

apps/server/src/core/group/services/group-user.service.ts

@@ -7,7 +7,7 @@ import {
 } from '@nestjs/common';
 import { PaginationOptions } from '@docmost/db/pagination/pagination-options';
 import { GroupService } from './group.service';
-import { KyselyDB } from '@docmost/db/types/kysely.types';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
 import { InjectKysely } from 'nestjs-kysely';
 import { GroupUserRepo } from '@docmost/db/repos/group/group-user.repo';
 import { SpaceMemberRepo } from '@docmost/db/repos/space/space-member.repo';
@@ -20,6 +20,7 @@ import {
   AUDIT_SERVICE,
   IAuditService,
 } from '../../../integrations/audit/audit.service';
+import { dbOrTx } from '@docmost/db/utils';
 
 @Injectable()
 export class GroupUserService {
@@ -54,17 +55,23 @@ export class GroupUserService {
     userIds: string[],
     groupId: string,
     workspaceId: string,
+    trx?: KyselyTransaction,
   ): Promise<void> {
-    await this.groupService.findAndValidateGroup(groupId, workspaceId);
+    const db = dbOrTx(this.db, trx);
+    await this.groupService.findAndValidateGroup(groupId, workspaceId, trx);
+
+    if (userIds.length === 0) return;
 
     // make sure we have valid workspace users
-    const validUsers = await this.db
+    const validUsers = await db
       .selectFrom('users')
       .select(['id', 'name'])
       .where('users.id', 'in', userIds)
       .where('users.workspaceId', '=', workspaceId)
       .execute();
 
+    if (validUsers.length === 0) return;
+
     // prepare users to add to group
     const groupUsersToInsert = [];
     for (const user of validUsers) {
@@ -75,7 +82,7 @@ export class GroupUserService {
     }
 
     // batch insert new group users
-    await this.db
+    await db
       .insertInto('groupUsers')
       .values(groupUsersToInsert)
       .onConflict((oc) => oc.columns(['userId', 'groupId']).doNothing())

apps/server/src/core/group/services/group.service.ts

@@ -216,8 +216,11 @@ export class GroupService {
   async findAndValidateGroup(
     groupId: string,
     workspaceId: string,
+    trx?: KyselyTransaction,
   ): Promise<Group> {
-    const group = await this.groupRepo.findById(groupId, workspaceId);
+    const group = await this.groupRepo.findById(groupId, workspaceId, {
+      trx,
+    });
     if (!group) {
       throw new NotFoundException('Group not found');
     }

apps/server/src/core/workspace/dto/update-workspace.dto.ts

@@ -41,6 +41,10 @@ export class UpdateWorkspaceDto extends PartialType(CreateWorkspaceDto) {
   @IsBoolean()
   mcpEnabled: boolean;
 
+  @IsOptional()
+  @IsBoolean()
+  isScimEnabled: boolean;
+
   @IsOptional()
   @IsBoolean()
   aiChat: boolean;

apps/server/src/core/workspace/services/workspace.service.ts

@@ -331,7 +331,8 @@ export class WorkspaceService {
       typeof updateWorkspaceDto.trashRetentionDays !== 'undefined' ||
       typeof updateWorkspaceDto.mcpEnabled !== 'undefined' ||
       typeof updateWorkspaceDto.restrictApiToAdmins !== 'undefined' ||
-      typeof updateWorkspaceDto.allowMemberTemplates !== 'undefined'
+      typeof updateWorkspaceDto.allowMemberTemplates !== 'undefined' ||
+      typeof updateWorkspaceDto.isScimEnabled !== 'undefined'
     ) {
       const ws = await this.db
         .selectFrom('workspaces')
@@ -351,6 +352,14 @@ export class WorkspaceService {
         }
       }
 
+      if (typeof updateWorkspaceDto.isScimEnabled !== 'undefined') {
+        if (!this.licenseCheckService.hasFeature(ws.licenseKey, Feature.SCIM, ws.plan)) {
+          throw new ForbiddenException(
+            'This feature requires a valid license',
+          );
+        }
+      }
+
       if (
         typeof updateWorkspaceDto.disablePublicSharing !== 'undefined' ||
         typeof updateWorkspaceDto.trashRetentionDays !== 'undefined' ||
@@ -535,6 +544,7 @@ export class WorkspaceService {
         'enforceSso',
         'enforceMfa',
         'emailDomains',
+        'isScimEnabled',
       ],
       updateWorkspaceDto,
       workspaceBefore,

apps/server/src/database/migrations/20260501T092214-scim.ts

@@ -0,0 +1,110 @@
+import { Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('scim_tokens')
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    .addColumn('name', 'varchar', (col) => col.notNull())
+    .addColumn('token_hash', 'varchar', (col) => col.notNull())
+    .addColumn('token_last_four', 'varchar(4)', (col) => col.notNull())
+    .addColumn('last_used_at', 'timestamptz')
+    .addColumn('is_enabled', 'boolean', (col) => col.notNull().defaultTo(true))
+    .addColumn('creator_id', 'uuid', (col) =>
+      col.references('users.id').onDelete('set null'),
+    )
+    .addColumn('workspace_id', 'uuid', (col) =>
+      col.references('workspaces.id').onDelete('cascade').notNull(),
+    )
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addColumn('updated_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addColumn('deleted_at', 'timestamptz')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_scim_tokens_token_hash')
+    .ifNotExists()
+    .on('scim_tokens')
+    .column('token_hash')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_scim_tokens_workspace_id')
+    .ifNotExists()
+    .on('scim_tokens')
+    .column('workspace_id')
+    .execute();
+
+  await db.schema
+    .alterTable('users')
+    .addColumn('scim_external_id', 'text')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_users_workspace_scim_external_id')
+    .ifNotExists()
+    .on('users')
+    .columns(['workspace_id', 'scim_external_id'])
+    .where('scim_external_id', 'is not', null)
+    .unique()
+    .execute();
+
+  await db.schema
+    .alterTable('groups')
+    .addColumn('scim_external_id', 'text')
+    .execute();
+
+  await db.schema
+    .createIndex('idx_groups_workspace_scim_external_id')
+    .ifNotExists()
+    .on('groups')
+    .columns(['workspace_id', 'scim_external_id'])
+    .where('scim_external_id', 'is not', null)
+    .unique()
+    .execute();
+
+  await db.schema
+    .alterTable('groups')
+    .addColumn('is_external', 'boolean', (col) =>
+      col.notNull().defaultTo(false),
+    )
+    .execute();
+
+  // Backfill: mark all non-default groups as external in workspaces with SSO group sync enabled
+  await sql`
+    UPDATE groups SET is_external = true
+    WHERE is_default = false
+    AND workspace_id IN (
+      SELECT workspace_id FROM auth_providers WHERE group_sync = true
+    )
+  `.execute(db);
+
+  await db.schema
+    .alterTable('workspaces')
+    .addColumn('is_scim_enabled', 'boolean', (col) =>
+      col.notNull().defaultTo(false),
+    )
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('scim_tokens').execute();
+
+  await db.schema.dropIndex('idx_users_workspace_scim_external_id').execute();
+  await db.schema.alterTable('users').dropColumn('scim_external_id').execute();
+
+  await db.schema.dropIndex('idx_groups_workspace_scim_external_id').execute();
+  await db.schema.alterTable('groups').dropColumn('scim_external_id').execute();
+
+  await db.schema.alterTable('groups').dropColumn('is_external').execute();
+
+  await db.schema
+    .alterTable('workspaces')
+    .dropColumn('is_scim_enabled')
+    .execute();
+}

apps/server/src/database/repos/group/group.repo.ts

@@ -9,7 +9,7 @@ import {
 } from '@docmost/db/types/entity.types';
 import { ExpressionBuilder, sql } from 'kysely';
 import { PaginationOptions } from '../../pagination/pagination-options';
-import { DB } from '@docmost/db/types/db';
+import { DB, Groups } from '@docmost/db/types/db';
 import { DefaultGroup } from '../../../core/group/dto/create-group.dto';
 import { executeWithCursorPagination } from '@docmost/db/pagination/cursor-pagination';
 
@@ -17,16 +17,34 @@ import { executeWithCursorPagination } from '@docmost/db/pagination/cursor-pagin
 export class GroupRepo {
   constructor(@InjectKysely() private readonly db: KyselyDB) {}
 
+  private baseFields: Array<keyof Groups> = [
+    'id',
+    'name',
+    'description',
+    'isDefault',
+    'isExternal',
+    'creatorId',
+    'workspaceId',
+    'createdAt',
+    'updatedAt',
+    'deletedAt',
+  ];
+
   async findById(
     groupId: string,
     workspaceId: string,
-    opts?: { includeMemberCount?: boolean; trx?: KyselyTransaction },
+    opts?: {
+      includeMemberCount?: boolean;
+      includeScimExternalId?: boolean;
+      trx?: KyselyTransaction;
+    },
   ): Promise<Group> {
     const db = dbOrTx(this.db, opts?.trx);
     return db
       .selectFrom('groups')
-      .selectAll('groups')
+      .select(this.baseFields)
       .$if(opts?.includeMemberCount, (qb) => qb.select(this.withMemberCount))
+      .$if(opts?.includeScimExternalId, (qb) => qb.select('scimExternalId'))
       .where('id', '=', groupId)
       .where('workspaceId', '=', workspaceId)
       .executeTakeFirst();
@@ -35,13 +53,18 @@ export class GroupRepo {
   async findByName(
     groupName: string,
     workspaceId: string,
-    opts?: { includeMemberCount?: boolean; trx?: KyselyTransaction },
+    opts?: {
+      includeMemberCount?: boolean;
+      includeScimExternalId?: boolean;
+      trx?: KyselyTransaction;
+    },
   ): Promise<Group> {
     const db = dbOrTx(this.db, opts?.trx);
     return db
       .selectFrom('groups')
-      .selectAll('groups')
+      .select(this.baseFields)
       .$if(opts?.includeMemberCount, (qb) => qb.select(this.withMemberCount))
+      .$if(opts?.includeScimExternalId, (qb) => qb.select('scimExternalId'))
       .where(sql`LOWER(name)`, '=', sql`LOWER(${groupName})`)
       .where('workspaceId', '=', workspaceId)
       .executeTakeFirst();
@@ -51,8 +74,11 @@ export class GroupRepo {
     updatableGroup: UpdatableGroup,
     groupId: string,
     workspaceId: string,
+    trx?: KyselyTransaction,
   ): Promise<void> {
-    await this.db
+    const db = dbOrTx(this.db, trx);
+
+    await db
       .updateTable('groups')
       .set({ ...updatableGroup, updatedAt: new Date() })
       .where('id', '=', groupId)
@@ -68,7 +94,7 @@ export class GroupRepo {
     return db
       .insertInto('groups')
       .values(insertableGroup)
-      .returningAll()
+      .returning(this.baseFields)
       .executeTakeFirst();
   }
 
@@ -80,7 +106,7 @@ export class GroupRepo {
     return (
       db
         .selectFrom('groups')
-        .selectAll()
+        .select(this.baseFields)
         // .select((eb) => this.withMemberCount(eb))
         .where('isDefault', '=', true)
         .where('workspaceId', '=', workspaceId)
@@ -106,7 +132,7 @@ export class GroupRepo {
   async getGroupsPaginated(workspaceId: string, pagination: PaginationOptions) {
     let baseQuery = this.db
       .selectFrom('groups')
-      .selectAll('groups')
+      .select(this.baseFields)
       .select((eb) => this.withMemberCount(eb))
       .where('workspaceId', '=', workspaceId);
 

apps/server/src/database/repos/user/user.repo.ts

@@ -44,6 +44,7 @@ export class UserRepo {
     opts?: {
       includePassword?: boolean;
       includeUserMfa?: boolean;
+      includeScimExternalId?: boolean;
       trx?: KyselyTransaction;
     },
   ): Promise<User> {
@@ -53,6 +54,7 @@ export class UserRepo {
       .select(this.baseFields)
       .$if(opts?.includePassword, (qb) => qb.select('password'))
       .$if(opts?.includeUserMfa, (qb) => qb.select(this.withUserMfa))
+      .$if(opts?.includeScimExternalId, (qb) => qb.select('scimExternalId'))
       .where('id', '=', userId)
       .where('workspaceId', '=', workspaceId)
       .executeTakeFirst();
@@ -64,6 +66,7 @@ export class UserRepo {
     opts?: {
       includePassword?: boolean;
       includeUserMfa?: boolean;
+      includeScimExternalId?: boolean;
       trx?: KyselyTransaction;
     },
   ): Promise<User> {
@@ -73,6 +76,7 @@ export class UserRepo {
       .select(this.baseFields)
       .$if(opts?.includePassword, (qb) => qb.select('password'))
       .$if(opts?.includeUserMfa, (qb) => qb.select(this.withUserMfa))
+      .$if(opts?.includeScimExternalId, (qb) => qb.select('scimExternalId'))
       .where(sql`LOWER(email)`, '=', sql`LOWER(${email})`)
       .where('workspaceId', '=', workspaceId)
       .executeTakeFirst();

apps/server/src/database/repos/workspace/workspace.repo.ts

@@ -34,6 +34,7 @@ export class WorkspaceRepo {
     'plan',
     'enforceMfa',
     'trashRetentionDays',
+    'isScimEnabled',
   ];
   constructor(@InjectKysely() private readonly db: KyselyDB) {}
 

apps/server/src/database/types/db.d.ts

@@ -213,7 +213,9 @@ export interface Groups {
   description: string | null;
   id: Generated<string>;
   isDefault: boolean;
+  isExternal: Generated<boolean>;
   name: string;
+  scimExternalId: string | null;
   updatedAt: Generated<Timestamp>;
   workspaceId: string;
 }
@@ -338,6 +340,7 @@ export interface Users {
   name: string | null;
   password: string | null;
   role: string | null;
+  scimExternalId: string | null;
   settings: Json | null;
   timezone: string | null;
   updatedAt: Generated<Timestamp>;
@@ -381,6 +384,7 @@ export interface Workspaces {
   enforceMfa: Generated<boolean | null>;
   enforceSso: Generated<boolean>;
   hostname: string | null;
+  isScimEnabled: Generated<boolean>;
   id: Generated<string>;
   licenseKey: string | null;
   logo: string | null;
@@ -410,6 +414,20 @@ export interface Notifications {
   createdAt: Generated<Timestamp>;
 }
 
+export interface ScimTokens {
+  createdAt: Generated<Timestamp>;
+  deletedAt: Timestamp | null;
+  id: Generated<string>;
+  isEnabled: Generated<boolean>;
+  lastUsedAt: Timestamp | null;
+  name: string;
+  tokenHash: string;
+  tokenLastFour: string;
+  creatorId: string | null;
+  updatedAt: Generated<Timestamp>;
+  workspaceId: string;
+}
+
 export interface Watchers {
   id: Generated<string>;
   userId: string;
@@ -558,6 +576,7 @@ export interface DB {
   pageVerifications: PageVerifications;
   pageVerifiers: PageVerifiers;
   pages: Pages;
+  scimTokens: ScimTokens;
   shares: Shares;
   spaceMembers: SpaceMembers;
   spaces: Spaces;

apps/server/src/database/types/entity.types.ts

@@ -29,6 +29,7 @@ import {
   UserMfa as _UserMFA,
   UserSessions,
   ApiKeys,
+  ScimTokens,
   Watchers,
   Audit as _Audit,
   Templates,
@@ -159,6 +160,11 @@ export type ApiKey = Selectable<ApiKeys>;
 export type InsertableApiKey = Insertable<ApiKeys>;
 export type UpdatableApiKey = Updateable<Omit<ApiKeys, 'id'>>;
 
+// Scim Tokens
+export type ScimToken = Selectable<ScimTokens>;
+export type InsertableScimToken = Insertable<ScimTokens>;
+export type UpdatableScimToken = Updateable<Omit<ScimTokens, 'id'>>;
+
 // Page Embedding
 export type PageEmbedding = Selectable<PageEmbeddings>;
 export type InsertablePageEmbedding = Insertable<PageEmbeddings>;

apps/server/src/main.ts

@@ -50,6 +50,22 @@ async function bootstrap() {
   await app.register(fastifyMultipart);
   await app.register(fastifyCookie);
 
+  app
+    .getHttpAdapter()
+    .getInstance()
+    .addContentTypeParser(
+      'application/scim+json',
+      { parseAs: 'string' },
+      (_, body, done) => {
+        try {
+          const json = JSON.parse(body.toString());
+          done(null, json);
+        } catch (err: any) {
+          done(err);
+        }
+      },
+    );
+
   app
     .getHttpAdapter()
     .getInstance()