Groups

Groups are organizational units that simplify role management. Instead of assigning roles to each user individually, you assign roles to a group and then add users to that group.

Concept

Group "Engineering"
├── Roles: Development, CommunicationManagement
├── Members (Users): alice, bob
├── Members (External Users): xt_parent_charlie
└── Child Groups:
    └── Group "Engineering Leads"
        ├── Roles: TenantManagement
        └── Members: alice

In this example:

• bob has roles: Development, CommunicationManagement
• alice has roles: Development, CommunicationManagement, TenantManagement (inherited from both groups)

Role Inheritance

Roles are resolved recursively through the group hierarchy:

1. A user's effective roles include all roles from groups they directly belong to
2. If a group contains child groups, the roles from those child groups are also included
3. Resolution supports up to 10 levels of nesting with cycle detection
4. The Identity Service resolves all effective roles at token issuance time

Default Group: TenantOwners

Every new tenant is automatically provisioned with a TenantOwners group that contains all 10 default roles. When an administrator provisions themselves in a new tenant (via admin provisioning), they are automatically added to this group.

Group Members

A group can contain three types of members:

Member Type	Description
Users	Local users in the same tenant
External Users	Cross-tenant user mappings (users from a parent tenant)
Child Groups	Nested groups for hierarchical role inheritance

Managing Groups via CLI

CRUD Operations

# List all groups
octo-cli -c GetGroups

# Get a specific group
octo-cli -c GetGroup -id "<group-rtid>"

# Create a group with optional roles
octo-cli -c CreateGroup -n "Engineering" -d "Engineering team" -rids "role1,role2"

# Update a group
octo-cli -c UpdateGroup -id "<group-rtid>" -n "New Name" -d "New description"

# Delete a group
octo-cli -c DeleteGroup -id "<group-rtid>"

Role Assignment

# Replace all roles assigned to a group
octo-cli -c UpdateGroupRoles -id "<group-rtid>" -rids "role1,role2,role3"

User Membership

# Add a user to a group
octo-cli -c AddUserToGroup -id "<group-rtid>" -uid "<user-id>"

# Remove a user from a group
octo-cli -c RemoveUserFromGroup -id "<group-rtid>" -uid "<user-id>"

Nested Groups

# Add a child group
octo-cli -c AddGroupToGroup -id "<parent-group-rtid>" -cgid "<child-group-rtid>"

# Remove a child group
octo-cli -c RemoveGroupFromGroup -id "<parent-group-rtid>" -cgid "<child-group-rtid>"

Circular References

The system prevents circular group references. If adding a child group would create a cycle, the operation is rejected.

Automatic Group Assignment

Users can be automatically assigned to groups on first login through two mechanisms:

1. Default group on identity provider — set the DefaultGroupRtId property on an identity provider. All new users registering through that provider are added to the specified group. See Identity Providers.

2. Email domain group rules — map email domain patterns to groups. Users whose email matches a pattern are automatically added to the corresponding group. See Email Domain Group Rules.