Manage groups

Added in v1.33

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

Create a group

Weaviate has no API to create a group, and groups are not stored in Weaviate. You create and populate a group in your identity provider, which then sends the user's group memberships to Weaviate in the OIDC token.

Weaviate becomes aware of a group the first time you assign a role to it. Until then the group name is unknown to Weaviate, even if your identity provider already uses it.

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.

PythonJavaScript/TypeScriptGoJavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

// Go support coming soon

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.

PythonJavaScript/TypeScriptGoJavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

// Go support coming soon

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.

PythonJavaScript/TypeScriptGoJavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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())}")

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

// Go support coming soon

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

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.

PythonJavaScript/TypeScriptGoJavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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

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

// Go support coming soon

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

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.

PythonJavaScript/TypeScriptGoJavaC#

  API docs

More infoCode snippets in the documentation reflect the latest client library and Weaviate Database version. Check the Release notes for specific versions.

If a snippet doesn't work or you have feedback, please open a GitHub issue.

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}")

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

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

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

Further resources

• RBAC: Overview
• RBAC: Configuration
• RBAC: Manage roles
• RBAC: Manage users

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.