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.

Active Directory Group Synchronization

When using a Microsoft Active Directory identity provider, AD group memberships are automatically synchronized with OctoMesh groups on every login. This enables role inheritance directly from your AD group structure.

How It Works

1. During LDAP authentication, the Identity Service reads the memberOf attribute from the AD user entry
2. Each AD group's Common Name (CN) is extracted (e.g., CN=FdaUsers,CN=Users,DC=example,DC=com becomes FdaUsers)
3. The extracted group names are matched against existing OctoMesh groups by name (case-insensitive)
4. If a matching OctoMesh group exists, the user is added as a member (if not already)
5. The user then inherits all roles assigned to that OctoMesh group, which appear in their access token

Setup

To enable AD group-to-role mapping:

1. Create an OctoMesh group with the exact same name as the AD group (e.g., FdaUsers)
2. Assign roles to that OctoMesh group (e.g., Development, AssetRepositoryReadOnly)
3. Ensure the AD user is a member of the AD group (memberOf attribute)

# Example: Create a group matching AD group "FdaUsers" and assign a role
octo-cli -c CreateGroup -n "FdaUsers" -d "Mapped from Active Directory" -rids "<role-rtid>"

Behavior

Scenario	Result
AD group name matches an OctoMesh group	User is added as member, inherits group roles
AD group name has no matching OctoMesh group	Group is skipped (logged as warning)
User is already a member of the OctoMesh group	No change (idempotent)
User is removed from AD group	Membership in OctoMesh is not automatically removed
Group sync fails	Login proceeds normally; failure is logged as error

Sync Direction

Group synchronization is one-way (AD to OctoMesh) and additive only. If a user is removed from an AD group, they are not automatically removed from the corresponding OctoMesh group. To remove a user from an OctoMesh group, use the Groups API or CLI.

OpenLDAP

AD group synchronization is only available for Microsoft Active Directory providers. OpenLDAP providers do not extract group memberships from the directory.