feat: add 'groups' namespace for managing OIDC groups

Author: bevzzz

src/groups/index.ts

@@ -0,0 +1,66 @@
+import ConnectionREST from '../connection/http.js';
+import { Role } from '../roles/types.js';
+import { Map } from '../roles/util.js';
+
+import { Role as WeaviateRole } from '../openapi/types.js';
+
+export interface Groups {
+  /** Manage roles of OIDC user groups. */
+  oidc: GroupsOIDC;
+}
+
+export interface GroupsOIDC {
+  /**
+   * Get the roles assigned to a group specific to the configured OIDC's dynamic auth functionality.
+   *
+   * @param groupID [string]  The group ID to get the roles for.
+   * @return A list of roles assigned tot he group.
+   */
+  getAssignedRoles(groupID: string, includePermissions?: boolean): Promise<Record<string, Role>>;
+
+  /**
+   * Assign roles to a group specific to the configured OIDC's dynamic auth functionality.
+   *
+   * @param group_id [string] The group to assign the roles to.
+   * @param role_names [string[]] The names of the roles to assign to the group.
+   */
+  assignRoles(groupID: string, roles: string | string[]): Promise<void>;
+  /**
+   * Revoke roles from a group specific to the configured OIDC's dynamic auth functionality.
+   *
+   * @param group_id [string] The group to assign the roles to.
+   * @param role_names [string[]] The names of the roles to assign to the group.
+   */
+  revokeRoles(groupID: string, roles: string | string[]): Promise<void>;
+  /**
+   * Get the known group names specific to the configured OIDC's dynamic auth functionality.
+   *
+   * @return A list of known group names.
+   */
+  getKnownGroupNames(): Promise<string[]>;
+}
+
+export const groups = (connection: ConnectionREST): Groups => ({
+  oidc: {
+    getAssignedRoles: (groupID, includePermissions) =>
+      connection
+        .get<WeaviateRole[]>(
+          `/authz/groups/${encodeURIComponent(groupID)}/roles/oidc${
+            includePermissions ? '?includeFullRoles=true' : ''
+          }`
+        )
+        .then(Map.roles),
+    assignRoles: (groupID: string, roles: string | string[]): Promise<void> =>
+      connection.postEmpty<any>(`/authz/groups/${encodeURIComponent(groupID)}/assign`, {
+        roles: Array.isArray(roles) ? roles : [roles],
+        groupType: 'oidc',
+      }),
+    revokeRoles: (groupID: string, roles: string | string[]): Promise<void> =>
+      connection.postEmpty<any>(`/authz/groups/${encodeURIComponent(groupID)}/revoke`, {
+        roles: Array.isArray(roles) ? roles : [roles],
+        groupType: 'oidc',
+      }),
+    getKnownGroupNames: (): Promise<string[]> => connection.get(`/authz/groups/oidc`),
+  },
+});
+export default groups;

src/groups/integration.test.ts

@@ -0,0 +1,75 @@
+import weaviate, { ApiKey, GroupAssignment } from '..';
+import { requireAtLeast } from '../../test/version.js';
+
+requireAtLeast(1, 32, 5).describe('Integration testing of the OIDC groups', () => {
+  const makeClient = (key: string = 'admin-key') =>
+    weaviate.connectToLocal({
+      port: 8091,
+      grpcPort: 50062,
+      authCredentials: new ApiKey(key),
+    });
+
+  it('should assign / get / revoke group roles', async () => {
+    const client = await makeClient();
+    const groupID = './assign-group';
+    const roles = ['viewer', 'admin'];
+
+    await client.groups.oidc.revokeRoles(groupID, roles);
+    await expect(client.groups.oidc.getAssignedRoles(groupID)).resolves.toEqual({});
+
+    await client.groups.oidc.assignRoles(groupID, roles);
+    const assignedRoles = await client.groups.oidc.getAssignedRoles(groupID, true);
+    expect(Object.keys(assignedRoles)).toEqual(expect.arrayContaining(roles));
+
+    await client.groups.oidc.revokeRoles(groupID, roles);
+    await expect(client.groups.oidc.getAssignedRoles(groupID)).resolves.toEqual({});
+  });
+
+  it('should get all known role groups', async () => {
+    const client = await makeClient();
+    const group1 = './group-1';
+    const group2 = './group-2';
+
+    await client.groups.oidc.assignRoles(group1, 'viewer');
+    await client.groups.oidc.assignRoles(group2, 'viewer');
+
+    await expect(client.groups.oidc.getKnownGroupNames()).resolves.toEqual(
+      expect.arrayContaining([group1, group2])
+    );
+
+    await client.groups.oidc.revokeRoles(group1, 'viewer');
+    await client.groups.oidc.revokeRoles(group2, 'viewer');
+
+    await expect(client.groups.oidc.getKnownGroupNames()).resolves.toHaveLength(0);
+  });
+
+  it('should get group assignments', async () => {
+    const client = await makeClient();
+    const roleName = 'test_group_assignements_role';
+    await client.roles.delete(roleName).catch((e) => {});
+    await client.roles.create(roleName, []).catch((e) => {});
+
+    await expect(client.roles.getGroupAssignments(roleName)).resolves.toHaveLength(0);
+
+    await client.groups.oidc.assignRoles('./group-1', roleName);
+    await client.groups.oidc.assignRoles('./group-2', roleName);
+    await expect(client.roles.getGroupAssignments(roleName)).resolves.toEqual(
+      expect.arrayContaining<GroupAssignment>([
+        { groupID: './group-1', groupType: 'oidc' },
+        { groupID: './group-2', groupType: 'oidc' },
+      ])
+    );
+
+    await client.groups.oidc.revokeRoles('./group-1', roleName);
+    await client.groups.oidc.revokeRoles('./group-2', roleName);
+    await expect(client.roles.getGroupAssignments(roleName)).resolves.toHaveLength(0);
+  });
+
+  it('cleanup', async () => {
+    makeClient().then((c) => {
+      c.groups.oidc.revokeRoles('./assign-group', ['viewer', 'admin']).catch((e) => {});
+      c.groups.oidc.revokeRoles('./group-1', 'viewer').catch((e) => {});
+      c.groups.oidc.revokeRoles('./group-2', 'viewer').catch((e) => {});
+    });
+  });
+});

src/index.ts

@@ -41,6 +41,7 @@ import weaviateV2 from './v2/index.js';
 import alias, { Aliases } from './alias/index.js';
 import filter from './collections/filters/index.js';
 import { ConsistencyLevel } from './data/replication.js';
+import groups, { Groups } from './groups/index.js';
 import users, { Users } from './users/index.js';
 
 export type ProtocolParams = {
@@ -108,6 +109,7 @@ export interface WeaviateClient {
   cluster: Cluster;
   collections: Collections;
   oidcAuth?: OidcAuthenticator;
+  groups: Groups;
   roles: Roles;
   users: Users;
 
@@ -230,6 +232,7 @@ async function client(params: ClientParams): Promise<WeaviateClient> {
     backup: backup(connection),
     cluster: cluster(connection),
     collections: collections(connection, dbVersionSupport),
+    groups: groups(connection),
     roles: roles(connection),
     users: users(connection),
     close: () => Promise.resolve(connection.close()), // hedge against future changes to add I/O to .close()

src/openapi/types.ts

@@ -71,6 +71,8 @@ export type Action = definitions['Permission']['action'];
 export type WeaviateUser = definitions['UserOwnInfo'];
 export type WeaviateDBUser = definitions['DBUserInfo'];
 export type WeaviateUserType = definitions['UserTypeOutput'];
+export type WeaviateGroupType = definitions['GroupType'];
+export type WeaviateGroupAssignment = operations['getGroupsForRole']['responses']['200']['schema'][0];
 export type WeaviateUserTypeInternal = definitions['UserTypeInput'];
 export type WeaviateUserTypeDB = definitions['DBUserInfo']['dbUserType'];
 export type WeaviateAssignedUser = operations['getUsersForRole']['responses']['200']['schema'][0];

src/roles/index.ts

@@ -1,6 +1,7 @@
 import { ConnectionREST } from '../index.js';
 import {
   WeaviateAssignedUser,
+  WeaviateGroupAssignment,
   Permission as WeaviatePermission,
   Role as WeaviateRole,
 } from '../openapi/types.js';
@@ -10,6 +11,7 @@ import {
   ClusterPermission,
   CollectionsPermission,
   DataPermission,
+  GroupAssignment,
   NodesPermission,
   Permission,
   PermissionsInput,
@@ -102,6 +104,14 @@ export interface Roles {
    * @returns {Promise<boolean>} A promise that resolves to true if the role has the permissions, or false if it does not.
    */
   hasPermissions: (roleName: string, permission: Permission | Permission[]) => Promise<boolean>;
+
+  /**
+   * Get the IDs and group type of groups that assigned this role.
+   *
+   * @param {string} roleName The name of the role to check.
+   * @return {Promise<GroupAssignment[]>} A promise that resolves to an array of group names assigned to this role.
+   */
+  getGroupAssignments: (roleName: string) => Promise<GroupAssignment[]>;
 }
 
 const roles = (connection: ConnectionREST): Roles => {
@@ -147,6 +157,10 @@ const roles = (connection: ConnectionREST): Roles => {
             connection.postReturn<WeaviatePermission, boolean>(`/authz/roles/${roleName}/has-permission`, p)
           )
       ).then((r) => r.every((b) => b)),
+    getGroupAssignments: (roleName: string) =>
+      connection
+        .get<WeaviateGroupAssignment[]>(`/authz/roles/${roleName}/group-assignments`)
+        .then(Map.groupsAssignments),
   };
 };
 

src/roles/types.ts

@@ -1,4 +1,4 @@
-import { Action, WeaviateUserType } from '../openapi/types.js';
+import { Action, WeaviateGroupType, WeaviateUserType } from '../openapi/types.js';
 
 export type AliasAction = Extract<
   Action,
@@ -31,6 +31,11 @@ export type UserAssignment = {
   userType: WeaviateUserType;
 };
 
+export type GroupAssignment = {
+  groupID: string;
+  groupType: WeaviateGroupType;
+};
+
 export type AliasPermission = {
   alias: string;
   collection: string;

src/roles/util.ts

@@ -1,6 +1,7 @@
 import {
   WeaviateAssignedUser,
   WeaviateDBUser,
+  WeaviateGroupAssignment,
   Permission as WeaviatePermission,
   Role as WeaviateRole,
   WeaviateUser,
@@ -17,6 +18,7 @@ import {
   CollectionsPermission,
   DataAction,
   DataPermission,
+  GroupAssignment,
   NodesAction,
   NodesPermission,
   Permission,
@@ -157,6 +159,12 @@ export class Map {
       {} as Record<string, Role>
     );
 
+  static groupsAssignments = (groups: WeaviateGroupAssignment[]): GroupAssignment[] =>
+    groups.map((g) => ({
+      groupID: g.groupId || '',
+      groupType: g.groupType,
+    }));
+
   static users = (users: string[]): Record<string, User> =>
     users.reduce(
       (acc, user) => ({