SCIM users endpoint

app/gen-server/lib/homedb/HomeDBManager.ts

@@ -441,6 +441,10 @@ export class HomeDBManager extends EventEmitter {
     return this._usersManager.getUser(userId, options);
   }
 
+  public async getUsers() {
+    return this._usersManager.getUsers();
+  }
+
   public async getFullUser(userId: number) {
     return this._usersManager.getFullUser(userId);
   }
@@ -537,6 +541,10 @@ export class HomeDBManager extends EventEmitter {
     return this._usersManager.deleteUser(scope, userIdToDelete, name);
   }
 
+  public async overrideUser(userId: number, props: UserProfile) {
+    return this._usersManager.overrideUser(userId, props);
+  }
+
   /**
    * Returns a QueryResult for the given organization.  The orgKey
    * can be a string (the domain from url) or the id of an org.  If it is
@@ -3271,7 +3279,7 @@ export class HomeDBManager extends EventEmitter {
     // Get the user objects which map to non-null values in the userDelta.
     const userIds = Object.keys(userDelta).filter(userId => userDelta[userId])
       .map(userIdStr => parseInt(userIdStr, 10));
-    const users = await this._usersManager.getUsers(userIds, manager);
+    const users = await this._usersManager.getUsersByIds(userIds, manager);
 
     // Add unaffected users to the delta so that we have a record of where they are.
     groups.forEach(grp => {

app/gen-server/lib/homedb/UsersManager.ts

@@ -386,7 +386,7 @@ export class UsersManager {
         // Set the user's name if our provider knows it. Otherwise use their username
         // from email, for lack of something better. If we don't have a profile at this
         // time, then leave the name blank in the hopes of learning it when the user logs in.
-        user.name = (profile && (profile.name || email.split('@')[0])) || '';
+        user.name = (profile && this._getNameOrDeduceFromEmail(profile.name, email)) || '';
         needUpdate = true;
       }
       if (!user.picture && profile && profile.picture) {
@@ -561,6 +561,32 @@ export class UsersManager {
       .filter(fullProfile => fullProfile);
   }
 
+  /**
+   * Update users with passed property. Optional user properties that are missing will be reset to their default value.
+   */
+  public async overrideUser(userId: number, props: UserProfile): Promise<User> {
+    return await this._connection.transaction(async manager => {
+      const user = await this.getUser(userId, {includePrefs: true});
+      if (!user) { throw new ApiError("unable to find user to update", 404); }
+      const login = user.logins[0];
+      user.name = this._getNameOrDeduceFromEmail(props.name, props.email);
+      user.picture = props.picture || '';
+      user.options = {...(user.options || {}), locale: props.locale ?? undefined};
+      if (props.email) {
+        login.email = normalizeEmail(props.email);
+        login.displayEmail = props.email;
+      }
+      await manager.save([user, login]);
+
+      return (await this.getUser(userId))!;
+    });
+  }
+
+  public async getUsers() {
+    return await User.find({relations: ["logins"]});
+  }
+
+
   /**
    * ==================================
    *
@@ -660,7 +686,7 @@ export class UsersManager {
   /**
    * Returns a Promise for an array of User entites for the given userIds.
    */
-  public async getUsers(userIds: number[], optManager?: EntityManager): Promise<User[]> {
+  public async getUsersByIds(userIds: number[], optManager?: EntityManager): Promise<User[]> {
     if (userIds.length === 0) {
       return [];
     }
@@ -744,6 +770,10 @@ export class UsersManager {
     return id;
   }
 
+  private _getNameOrDeduceFromEmail(name: string, email: string) {
+    return name || email.split('@')[0];
+  }
+
   // This deals with the problem posed by receiving a PermissionDelta specifying a
   // role for both alice@x and Alice@x. We do not distinguish between such emails.
   // If there are multiple indistinguishabe emails, we preserve just one of them,

app/server/MergedServer.ts

@@ -161,6 +161,7 @@ export class MergedServer {
         await this.flexServer.addLandingPages();
         // todo: add support for home api to standalone app
         this.flexServer.addHomeApi();
+        this.flexServer.addScimApi();
         this.flexServer.addBillingApi();
         this.flexServer.addNotifier();
         this.flexServer.addAuditLogger();

app/server/lib/FlexServer.ts

@@ -87,6 +87,7 @@ import * as path from 'path';
 import * as serveStatic from "serve-static";
 import {ConfigBackendAPI} from "app/server/lib/ConfigBackendAPI";
 import {IGristCoreConfig} from "app/server/lib/configCore";
+import { buildScimRouter } from './scim';
 
 // Health checks are a little noisy in the logs, so we don't show them all.
 // We show the first N health checks:
@@ -887,6 +888,19 @@ export class FlexServer implements GristServer {
     new ApiServer(this, this.app, this._dbManager, this._widgetRepository = buildWidgetRepository(this));
   }
 
+  public addScimApi() {
+    if (this._check('scim', 'api', 'homedb', 'json', 'api-mw')) { return; }
+
+    const scimRouter = isAffirmative(process.env.GRIST_ENABLE_SCIM) ?
+      buildScimRouter(this._dbManager, this._installAdmin) :
+      () => {
+        throw new ApiError('SCIM API is not enabled', 501);
+      };
+
+    this.app.use('/api/scim', scimRouter);
+  }
+
+
   public addBillingApi() {
     if (this._check('billing-api', 'homedb', 'json', 'api-mw')) { return; }
     this._getBilling();

app/server/lib/scim/index.ts

@@ -0,0 +1,14 @@
+import * as express from 'express';
+
+import { buildScimRouterv2 } from './v2/ScimV2Api';
+import { HomeDBManager } from 'app/gen-server/lib/homedb/HomeDBManager';
+import { InstallAdmin } from '../InstallAdmin';
+
+const buildScimRouter = (dbManager: HomeDBManager, installAdmin: InstallAdmin) => {
+  const v2 = buildScimRouterv2(dbManager, installAdmin);
+  const scim = express.Router();
+  scim.use('/v2', v2);
+  return scim;
+};
+
+export { buildScimRouter };

app/server/lib/scim/v2/ScimTypes.ts

@@ -0,0 +1,6 @@
+export interface RequestContext {
+  path: string;
+  isAdmin: boolean;
+  isScimUser: boolean;
+}
+

app/server/lib/scim/v2/ScimUserController.ts

@@ -0,0 +1,164 @@
+import { ApiError } from 'app/common/ApiError';
+import { HomeDBManager, Scope } from 'app/gen-server/lib/homedb/HomeDBManager';
+import SCIMMY from 'scimmy';
+import { toSCIMMYUser, toUserProfile } from './ScimUserUtils';
+import { RequestContext } from './ScimTypes';
+
+class ScimUserController {
+  private static _getIdFromResource(resource: any) {
+    const id = parseInt(resource.id, 10);
+    if (Number.isNaN(id)) {
+      throw new SCIMMY.Types.Error(400, 'invalidValue', 'Invalid passed user ID');
+    }
+    return id;
+  }
+
+  constructor(
+    private _dbManager: HomeDBManager,
+    private _checkAccess: (context: RequestContext) => void
+  ) {}
+
+  /**
+   * Gets a single user with the passed ID.
+   *
+   * @param resource The SCIMMY user resource performing the operation
+   * @param context The request context
+   */
+  public async getSingleUser(resource: any, context: RequestContext) {
+    return this._runAndHandleErrors(context, async () => {
+      const id = ScimUserController._getIdFromResource(resource);
+      const user = await this._dbManager.getUser(id);
+      if (!user) {
+        throw new SCIMMY.Types.Error(404, null!, `User with ID ${id} not found`);
+      }
+      return toSCIMMYUser(user);
+    });
+  }
+
+  /**
+   * Gets all users or filters them based on the passed filter.
+   *
+   * @param resource The SCIMMY user resource performing the operation
+   * @param context The request context
+   */
+  public async getUsers(resource: any, context: RequestContext) {
+    return this._runAndHandleErrors(context, async () => {
+      const { filter } = resource;
+      const scimmyUsers = (await this._dbManager.getUsers()).map(user => toSCIMMYUser(user));
+      return filter ? filter.match(scimmyUsers) : scimmyUsers;
+    });
+  }
+
+  /**
+   * Creates a new user with the passed data.
+   *
+   * @param data The data to create the user with
+   * @param context The request context
+   */
+  public async createUser(data: any, context: RequestContext) {
+    return this._runAndHandleErrors(context, async () => {
+      await this._checkEmailCanBeUsed(data.userName);
+      const userProfile = toUserProfile(data);
+      const newUser = await this._dbManager.getUserByLoginWithRetry(userProfile.email, {
+        profile: userProfile
+      });
+      return toSCIMMYUser(newUser);
+    });
+  }
+
+  /**
+   * Overrides a user with the passed data.
+   *
+   * @param resource The SCIMMY user resource performing the operation
+   * @param data The data to override the user with
+   * @param context The request context
+   */
+  public async overrideUser(resource: any, data: any, context: RequestContext) {
+    return this._runAndHandleErrors(context, async () => {
+      const id = ScimUserController._getIdFromResource(resource);
+      await this._checkEmailCanBeUsed(data.userName, id);
+      const updatedUser = await this._dbManager.overrideUser(id, toUserProfile(data));
+      return toSCIMMYUser(updatedUser);
+    });
+  }
+
+  /**
+   * Deletes a user with the passed ID.
+   *
+   * @param resource The SCIMMY user resource performing the operation
+   * @param context The request context
+   */
+  public async deleteUser(resource: any, context: RequestContext) {
+    return this._runAndHandleErrors(context, async () => {
+      const id = ScimUserController._getIdFromResource(resource);
+      const fakeScope: Scope = { userId: id };
+      // FIXME: deleteUser should probably better not requiring a scope.
+      await this._dbManager.deleteUser(fakeScope, id);
+    });
+  }
+
+  /**
+   * Runs the passed callback and handles any errors that might occur.
+   * Also checks if the user has access to the operation.
+   * Any public method of this class should be run through this method.
+   *
+   * @param context The request context to check access for the user
+   * @param cb The callback to run
+   */
+  private async _runAndHandleErrors<T>(context: RequestContext, cb: () => Promise<T>): Promise<T> {
+    try {
+      this._checkAccess(context);
+      return await cb();
+    } catch (err) {
+      if (err instanceof ApiError) {
+        if (err.status === 409) {
+          throw new SCIMMY.Types.Error(err.status, 'uniqueness', err.message);
+        }
+        throw new SCIMMY.Types.Error(err.status, null!, err.message);
+      }
+      if (err instanceof SCIMMY.Types.Error) {
+        throw err;
+      }
+      // By default, return a 500 error
+      throw new SCIMMY.Types.Error(500, null!, err.message);
+    }
+  }
+
+  /**
+   * Checks if the passed email can be used for a new user or by the existing user.
+   *
+   * @param email The email to check
+   * @param userIdToUpdate The ID of the user to update. Pass this when updating a user,
+   * so it won't raise an error if the passed email is already used by this user.
+   */
+  private async _checkEmailCanBeUsed(email: string, userIdToUpdate?: number) {
+    const existingUser = await this._dbManager.getExistingUserByLogin(email);
+    if (existingUser !== undefined && existingUser.id !== userIdToUpdate) {
+      throw new SCIMMY.Types.Error(409, 'uniqueness', 'An existing user with the passed email exist.');
+    }
+  }
+}
+
+export const getScimUserConfig = (
+  dbManager: HomeDBManager, checkAccess: (context: RequestContext) => void
+) => {
+  const controller = new ScimUserController(dbManager, checkAccess);
+
+  return {
+    egress: async (resource: any, context: RequestContext) => {
+      if (resource.id) {
+        return await controller.getSingleUser(resource, context);
+      }
+      return await controller.getUsers(resource, context);
+    },
+    ingress: async (resource: any, data: any, context: RequestContext) => {
+      if (resource.id) {
+        return await controller.overrideUser(resource, data, context);
+      }
+      return await controller.createUser(data, context);
+    },
+    degress: async (resource: any, context: RequestContext) => {
+      return await controller.deleteUser(resource, context);
+    }
+  };
+};

app/server/lib/scim/v2/ScimUserUtils.ts

@@ -0,0 +1,46 @@
+import { normalizeEmail } from "app/common/emails";
+import { UserProfile } from "app/common/LoginSessionAPI";
+import { User } from "app/gen-server/entity/User.js";
+import SCIMMY from "scimmy";
+
+/**
+ * Converts a user from your database to a SCIMMY user
+ */
+export function toSCIMMYUser(user: User) {
+  if (!user.logins) {
+    throw new Error("User must have at least one login");
+  }
+  const locale = user.options?.locale ?? "en";
+  return new SCIMMY.Schemas.User({
+    id: String(user.id),
+    userName: user.loginEmail,
+    displayName: user.name,
+    name: {
+      formatted: user.name,
+    },
+    locale,
+    preferredLanguage: locale, // Assume preferredLanguage is the same as locale
+    photos: user.picture ? [{
+      value: user.picture,
+      type: "photo",
+      primary: true
+    }] : undefined,
+    emails: [{
+      value: user.logins[0].displayEmail,
+      primary: true,
+    }],
+  });
+}
+
+export function toUserProfile(scimUser: any, existingUser?: User): UserProfile {
+  const emailValue = scimUser.emails?.[0]?.value;
+  if (emailValue && normalizeEmail(emailValue) !== normalizeEmail(scimUser.userName)) {
+    throw new SCIMMY.Types.Error(400, 'invalidValue', 'Email and userName must be the same');
+  }
+  return {
+    name: scimUser.displayName ?? existingUser?.name,
+    picture: scimUser.photos?.[0]?.value,
+    locale: scimUser.locale,
+    email: emailValue ?? scimUser.userName ?? existingUser?.loginEmail,
+  };
+}