Groups

Specific Field Requirements

• Name: Name of the group. This must be unique with respect to ALL other groups.
• Users: The users of the group. At any given time, at least ONE of these users must have the role of Owner.

Creating New Groups

To create a group, first navigate to the "Groups" page in the upper right-hand corner of the screen.

Then, click on the "Create New Group" button to bring up the group creation modal.

After filling out all the fields, click "Save" to create your new group. You should now see your new group present in the table.

NOTE: Group names must be unique.

Deleting Groups

To delete a group, simply click on the "Delete" icon indicated in the screenshot below:

This will activate a popup which asks for user confirmation. Click "OK" to remove your group from the table.

Adding Users to Groups

Users can be added to a group at any time. To add a user, bring up the groups modal by either creating a new group (See Creating New Groups for more info) or by clicking the "Edit" icon indicated in the screenshot below:

Then, click the "Add Users" dropdown and select the desired users.

Generating Group API Keys

For instructions on how to generate an API key for a group, see "How to Generate API Keys for Groups"

Management Details

• System administrators will have read/write access to ALL groups through the Admin Panel, regardless of their membership.
• If the sole owner of a group decides to remove themselves, they must promote another member to Owner before doing so. (In the screenshot below, "Admin" - the only owner of the group - attempts to demote themselves to a member)

---

Users

Management Details

• System administrators will have read/write access to ALL users.
• In the event a user is forcibly removed from the system (i.e. through API or by a system administrator), groups that belonged solely to the user will have their ownership transferred to the default system administrator. If a system administrator is not specified in .env, ownership will be transferred to the earliest-created administrator.

OIDC_EXTERNAL_GROUPS

When OIDC_EXTERNAL_GROUPS is set to true, Heimdall will sync users' group membership from the configured OIDC provider. There are a few limitations of this capability:

• Manual Group Creation
  • Groups mapped into Heimdall must be manually created in Heimdall as well as the OIDC provider. For example, group "A" must first be created in the OIDC provider, and then manually created in Heimdall as well.
  • If a group is manually created in Heimdall which does not exist in the OIDC provider, then, upon the group creator's next login, the creator of the group will be removed from the group and ownership will be transferred to the default admin user (typically the admin associated with the ADMIN_EMAIL).
  • Once the group is created in both the OIDC provider and Heimdall, group membership will synced as users login.
• Manual Group Deletion
  • Heimdall currently has no mechanism to detect if a group was deleted on the OIDC provider. This means that groups deleted from the OIDC provider must be manually deleted from Heimdall as well.
• Group information is only synced per-user upon login
  • With this functionality enabled, Heimdall currently utilizes the "groups" client scope as part of the OIDC login process. This means that groups are only synced on a per-user basis, and only when a user logs on. This means that group membership will not be updated during an active session (the user would need to re-login in order to restore proper group membership).
• Multiple authentication methods
  • It is not recommended to use this with other authentication methods enabled at this time.