Manage groups

When using OIDC for authentication, you can leverage user groups defined in your identity provider (like Keycloak, Okta, or Auth0) to manage permissions in Weaviate. The user's group memberships are passed to Weaviate in the OIDC token.

You can then assign Weaviate roles directly to these OIDC groups. Any user who is a member of that group will automatically inherit the permissions of the assigned roles. This is a powerful way to manage access for large teams without assigning roles to each user individually.

On this page, you will find examples of how to programmatically manage OIDC groups and their associated roles.

Group management

Assign roles to an OIDC group

You can assign one or more Weaviate roles to an OIDC group. Any user belonging to this group will inherit the roles' permissions.

This example assigns the testRole and viewer roles to the /admin-group.

Python

admin_client.groups.oidc.assign_roles(
    group_id="/admin-group", role_names=["testRole", "viewer"]
)

JavaScript/TypeScript

await adminClient.groups.oidc.assignRoles(
    "/admin-group", ["testRole", "viewer"]
);

// Go support coming soon

Java

client.groups.assignRoles(testGroup, testRole, "viewer");

await client.Groups.Oidc.AssignRoles(testGroup, new[] { testRole, "viewer" });

Revoke roles from an OIDC group

You can revoke one or more roles from a specific OIDC group.

This example removes the testRole and viewer roles from the /admin-group.

Python

admin_client.groups.oidc.revoke_roles(
    group_id="/admin-group", role_names=["testRole", "viewer"]
)

JavaScript/TypeScript

await adminClient.groups.oidc.revokeRoles(
    "/admin-group", ["testRole", "viewer"]
);

// Go support coming soon

Java

client.groups.revokeRoles(testGroup, testRole, "viewer");

await client.Groups.Oidc.RevokeRoles(testGroup, new[] { testRole, "viewer" });

List roles assigned to an OIDC group

Retrieve a list of all roles that have been assigned to a specific OIDC group.

Python

group_roles = oidc_admin_client.groups.oidc.get_assigned_roles(
    group_id="/admin-group", include_permissions=True
)
print(f"Roles assigned to '/admin-group': {list(group_roles.keys())}")

JavaScript/TypeScript

const groupRoles = await oidcAdminClient.groups.oidc.getAssignedRoles(
    "/admin-group", true
);
console.log(`Roles assigned to '/admin-group': ${Object.keys(groupRoles)}`);

// Go support coming soon

Java

List<Role> groupRoles = client.groups.assignedRoles(testGroup,
    g -> g.includePermissions(true));
for (Role role : groupRoles) {
  System.out.println(role.name());
}

var groupRoles = await client.Groups.Oidc.GetRoles(testGroup, includeFullRoles: true);
foreach (var role in groupRoles)
{
    Console.WriteLine(role.Name);
}

Example results

text

Roles assigned to '/admin-group': ['testRole', 'viewer']

List all known OIDC groups

This example shows how to get a list of all OIDC groups that Weaviate is aware of. Weaviate learns about a group when a role is first assigned to it.

Python

known_groups = admin_client.groups.oidc.get_known_group_names()
print(f"Known OIDC groups ({len(known_groups)}): {known_groups}")

JavaScript/TypeScript

const knownGroups = await adminClient.groups.oidc.getKnownGroupNames();
console.log(`Known OIDC groups (${knownGroups.length}): ${knownGroups}`);

// Go support coming soon

Java

List<String> knownGroups = client.groups.knownGroupNames();
System.out.println("Known OIDC groups (" + knownGroups.size() + "): " + knownGroups);

var knownGroups = await client.Groups.Oidc.GetKnownGroupNames();
Console.WriteLine($"Known OIDC groups ({knownGroups.Count()}): {string.Join(", ", knownGroups)}");

Example results

text

Known OIDC groups (3): ['/viewer-group', '/admin-group', '/my-test-group']

List groups assigned to a role

Retrieve a list of all groups that have been assigned a specific role.

This example shows which groups have the testRole assigned to them.

Python

group_assignments = admin_client.roles.get_group_assignments(role_name="testRole")
print(f"Groups assigned to role 'testRole':")
for group in group_assignments:
    print(f"  - Group ID: {group.group_id}, Type: {group.group_type}")

JavaScript/TypeScript

const groupAssignments = await adminClient.roles.getGroupAssignments("testRole");
console.log("Groups assigned to role 'testRole':");
for (const group of groupAssignments) {
    console.log(`  - Group ID: ${group.groupID}, Type: ${group.groupType}`);
}

// Go support coming soon

Java

List<GroupAssignment> groupAssignments = client.roles.groupAssignments(testRole);
System.out.println("Groups assigned to role '" + testRole + "':");
for (GroupAssignment assignment : groupAssignments) {
  System.out.println("  - Group ID: " + assignment.groupId() + ", Type: "
      + assignment.groupType());
}

var groupAssignments = await client.Roles.GetGroupAssignments(testRole);
Console.WriteLine($"Groups assigned to role '{testRole}':");
foreach (var assignment in groupAssignments)
{
    Console.WriteLine($"  - Group ID: {assignment.GroupId}, Type: {assignment.GroupType}");
}

Example results

text

Groups assigned to role 'testRole':
  - Group ID: /admin-group, Type: oidc

Further resources

Questions and feedback

Have a question or feedback? Here's how to reach us.

Community Forum

Ask questions and connect with other developers on our Community forum.

Support

Weaviate Cloud user or customer? Find the right channel on the Support page.