weseek__growi/apps/app/src/features/external-user-group/server/service/keycloak-user-group-sync.ts

import KeycloakAdminClient from '@keycloak/keycloak-admin-client';
import type GroupRepresentation from '@keycloak/keycloak-admin-client/lib/defs/groupRepresentation';
import type UserRepresentation from '@keycloak/keycloak-admin-client/lib/defs/userRepresentation';

import { configManager } from '~/server/service/config-manager';
import type { S2sMessagingService } from '~/server/service/s2s-messaging/base';
import loggerFactory from '~/utils/logger';
import { batchProcessPromiseAll } from '~/utils/promise';

import type {
  ExternalUserGroupTreeNode,
  ExternalUserInfo,
} from '../../interfaces/external-user-group';
import { ExternalGroupProviderType } from '../../interfaces/external-user-group';

import ExternalUserGroupSyncService from './external-user-group-sync';

const logger = loggerFactory('growi:service:keycloak-user-group-sync-service');

// When d = max depth of group trees
// Max space complexity of generateExternalUserGroupTrees will be:
// O(TREES_BATCH_SIZE * d)
const TREES_BATCH_SIZE = 10;

export class KeycloakUserGroupSyncService extends ExternalUserGroupSyncService {
  kcAdminClient: KeycloakAdminClient;

  realm: string | undefined; // realm that contains the groups

  groupDescriptionAttribute: string | undefined; // attribute to map to group description

  isInitialized = false;

  // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
  constructor(
    s2sMessagingService: S2sMessagingService | null,
    socketIoService,
  ) {
    super(
      ExternalGroupProviderType.keycloak,
      s2sMessagingService,
      socketIoService,
    );
  }

  init(authProviderType: 'oidc' | 'saml'): void {
    const kcHost = configManager.getConfig('external-user-group:keycloak:host');
    const kcGroupRealm = configManager.getConfig(
      'external-user-group:keycloak:groupRealm',
    );
    const kcGroupSyncClientRealm = configManager.getConfig(
      'external-user-group:keycloak:groupSyncClientRealm',
    );
    const kcGroupDescriptionAttribute = configManager.getConfig(
      'external-user-group:keycloak:groupDescriptionAttribute',
    );

    this.kcAdminClient = new KeycloakAdminClient({
      baseUrl: kcHost,
      realmName: kcGroupSyncClientRealm,
    });
    this.realm = kcGroupRealm;
    this.groupDescriptionAttribute = kcGroupDescriptionAttribute;
    this.authProviderType = authProviderType;
    this.isInitialized = true;
  }

  override syncExternalUserGroups(): Promise<void> {
    if (!this.isInitialized) {
      const msg = 'Service not initialized';
      logger.error(msg);
      throw new Error(msg);
    }
    return super.syncExternalUserGroups();
  }

  override async generateExternalUserGroupTrees(): Promise<
    ExternalUserGroupTreeNode[]
  > {
    await this.auth();

    // Type is 'GroupRepresentation', but 'find' does not return 'attributes' field. Hence, attribute for description is not present.
    logger.info('Get groups from keycloak server');
    const rootGroups = await this.kcAdminClient.groups.find({
      realm: this.realm,
    });

    return (
      await batchProcessPromiseAll(rootGroups, TREES_BATCH_SIZE, (group) =>
        this.groupRepresentationToTreeNode(group),
      )
    ).filter(
      (node): node is NonNullable<ExternalUserGroupTreeNode> => node != null,
    );
  }

  /**
   * Authenticate to group sync client using client credentials grant type
   */
  private async auth(): Promise<void> {
    const kcGroupSyncClientID = configManager.getConfig(
      'external-user-group:keycloak:groupSyncClientID',
    );
    const kcGroupSyncClientSecret = configManager.getConfig(
      'external-user-group:keycloak:groupSyncClientSecret',
    );

    await this.kcAdminClient.auth({
      grantType: 'client_credentials',
      clientId: kcGroupSyncClientID ?? '',
      clientSecret: kcGroupSyncClientSecret,
    });
  }

  /**
   * Convert GroupRepresentation response returned from Keycloak to ExternalUserGroupTreeNode
   */
  private async groupRepresentationToTreeNode(
    group: GroupRepresentation,
  ): Promise<ExternalUserGroupTreeNode | null> {
    if (group.id == null || group.name == null) return null;

    logger.info('Get users from keycloak server');
    const userRepresentations = await this.getMembers(group.id);

    const userInfos =
      userRepresentations != null
        ? this.userRepresentationsToExternalUserInfos(userRepresentations)
        : [];
    const description = (await this.getGroupDescription(group.id)) || undefined;
    const childGroups = group.subGroups;

    const childGroupNodesWithNull: (ExternalUserGroupTreeNode | null)[] = [];
    if (childGroups != null) {
      // Do not use Promise.all, because the number of promises processed can
      // exponentially grow when group tree is enormous
      for await (const childGroup of childGroups) {
        childGroupNodesWithNull.push(
          await this.groupRepresentationToTreeNode(childGroup),
        );
      }
    }
    const childGroupNodes: ExternalUserGroupTreeNode[] =
      childGroupNodesWithNull.filter(
        (node): node is NonNullable<ExternalUserGroupTreeNode> => node != null,
      );

    return {
      id: group.id,
      userInfos,
      childGroupNodes,
      name: group.name,
      description,
    };
  }

  private async getMembers(groupId: string): Promise<UserRepresentation[]> {
    let allUsers: UserRepresentation[] = [];

    const fetchUsersWithOffset = async (offset: number) => {
      await this.auth();
      const response = await this.kcAdminClient.groups.listMembers({
        id: groupId,
        realm: this.realm,
        first: offset,
      });

      if (response != null && response.length > 0) {
        allUsers = allUsers.concat(response);
        return fetchUsersWithOffset(offset + response.length);
      }
    };

    await fetchUsersWithOffset(0);

    return allUsers;
  }

  /**
   * Fetch group detail from Keycloak and return group description
   */
  private async getGroupDescription(groupId: string): Promise<string | null> {
    if (this.groupDescriptionAttribute == null) return null;

    await this.auth();
    const groupDetail = await this.kcAdminClient.groups.findOne({
      id: groupId,
      realm: this.realm,
    });

    const description =
      groupDetail?.attributes?.[this.groupDescriptionAttribute]?.[0];
    return typeof description === 'string' ? description : null;
  }

  /**
   * Convert UserRepresentation array response returned from Keycloak to ExternalUserInfo
   */
  private userRepresentationsToExternalUserInfos(
    userRepresentations: UserRepresentation[],
  ): ExternalUserInfo[] {
    const externalUserGroupsWithNull: (ExternalUserInfo | null)[] =
      userRepresentations.map((userRepresentation) => {
        if (
          userRepresentation.id != null &&
          userRepresentation.username != null
        ) {
          return {
            id: userRepresentation.id,
            username: userRepresentation.username,
            email: userRepresentation.email,
          };
        }
        return null;
      });

    return externalUserGroupsWithNull.filter(
      (node): node is NonNullable<ExternalUserInfo> => node != null,
    );
  }
}