User Roles & Groups

To allow and restrict access to the features of your applications, every user must be assigned permissions based on their role (defines what they can do and not do on your app).

Managing the role of multiple system and app-level users individually is time-consuming and inefficient.

Key Benefits

User groups provide several key benefits for managing user access and permissions:

• Centralized Permission Management: Define and apply app permissions to all users in a group, eliminating the need to manage permissions individually
• Efficient Access Control: A single change to group access rights is automatically applied to all users mapped to the designated group
• Logical Organization: Group users based on common or shared traits such as department, function, or project
• Role-Based Access: Assign specific roles to users within groups, providing fine-grained control over what each user can do
• Scalability: Easily manage permissions for large numbers of users by organizing them into groups rather than configuring each user individually
• System Integration: Provision access to other systems by listening on webhooks (Events) that notify external systems when users are assigned to groups or roles change

For example,

• Your operations team may need to access shared documentation on your server.
• However, admin users may need different access permissions compared to the other non-admin users.
• For this, you can create a group named Operations-Admin that supports read, write, create, and delete permissions, and map users with the Admin role to it.
• Similarly, you can create a group named Operations Non-admin that supports read and write permissions, and map the users with the Developer or Operations Manager role to it.

Role-based Mapping of users to a Group ensures that unauthorized access is prevented at the system & app-levels.

cidaas supports user role-mapping and role-based group management as a part of our identity management services to enable login and user creation/updating restrictions.

Core Concepts

The group management system consists of four interconnected entities:

┌─────────────────────────────────────────────────────────────────┐
│                         GROUP MODEL                              │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────┐    defines      ┌─────────────┐                   │
│  │   Role   │◄───────────────►│  GroupType  │                   │
│  └──────────┘   allowed roles └─────────────┘                   │
│       │                             │                            │
│       │ assigned to                 │ tags                       │
│       ▼                             ▼                            │
│  ┌──────────────┐           ┌─────────────┐                     │
│  │ UserGroupMap │◄─────────►│  UserGroup  │                     │
│  │ (sub+roles)  │  relation │             │                     │
│  └──────────────┘           └─────────────┘                     │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Assigning Users to Groups and Roles

Users receive access permissions through their assignment to groups with specific roles. This assignment process is the foundation of the access control system in cidaas.

Important: Assignment of users to groups and roles can only be performed via administrative endpoints. These operations require appropriate administrative permissions and cannot be performed by regular users through self-service interfaces.

How Users Are Assigned to Groups

Users can be assigned to groups through several administrative methods:

1. During User Creation: When creating a user via the Create User By Admin API, groups and roles can be assigned as part of the user creation process
2. Bulk Assignment: Multiple users can be assigned to a group simultaneously using bulk assignment APIs
3. Individual Assignment: Single users can be assigned to one or multiple groups with specific roles using group map APIs
4. Automatic Assignment: Users can be automatically assigned to groups during registration or through configured control flows (requires administrative configuration)

Role Assignment Within Groups

When a user is assigned to a group, they must be assigned one or more roles that are allowed by the group's GroupType. The assignment process follows these principles:

• GroupType Constraints: Only roles defined in the group's GroupType allowedRoles list can be assigned to users in that group
• Role Mode Enforcement: The GroupType's roleMode determines whether roles are required, optional, or restricted:
  • roles_required: At least one role from allowedRoles must be assigned
  • allowed_roles: Only roles from allowedRoles can be assigned (optional)
  • any_roles: Any role in the system can be assigned
  • no_roles: No roles can be assigned
• Multiple Roles: A user can have multiple roles within a single group, allowing for flexible permission combinations
• Multiple Groups: A user can belong to multiple groups simultaneously, with potentially different roles in each group

The Assignment Process

The assignment of a user to a group with roles is managed through the UserGroupMap entity, which creates the relationship between:

• The user (identified by sub)
• The group (identified by groupId)
• The roles (list of role names)

Example Assignment Flow:

1. A GroupType is created with allowedRoles: ["GROUP_ADMIN", "MEMBER", "VIEWER"]
2. A UserGroup is created with that GroupType
3. A user is assigned to the group with roles ["MEMBER", "VIEWER"]
4. The system validates that both "MEMBER" and "VIEWER" are in the allowedRoles list
5. The UserGroupMap is created, establishing the user-group-role relationship

This group-role combination is the primary mechanism for managing user access and permissions in cidaas. All roles are user-specific within the context of their group memberships.

Administrative APIs for User Group and Role Assignment

The following administrative endpoints are available for assigning users to groups and roles:

Create User with Groups and Roles

API	Description	Link
Create User By Admin	Create a new user and assign groups and roles during user creation	View API

Assign Users to Groups

API	Description	Link
Assign Many Users From User Group	Bulk assign multiple users to a single user group with roles	View API
Stores User Group Maps Of User	Assign a user to multiple groups with roles, update existing assignments, or replace all group memberships	View API

Retrieve User Group Maps

API	Description	Link
Get User Group Map	Get the group-role relationship for a specific user in a specific group	View API
Get User Groups Maps For User	Get all group memberships and roles for a specific user	View API

Roles

A Role defines access rights and responsibilities of a user.

Property	Description
role	Unique name/id of the role
roleOwner	ADMIN (cidaas managed) or CLIENT (customer managed)
description	Optional description to help organize roles

Role Properties

	Description	Example
Purpose	A role defines the access rights & responsibilities of a user.	A function like manager in a company.
Creation	Roles are defined and managed as a list of tags each with a certain meaning. A role can be assigned to a grouptype. The assignment to cidaas default user groups (CIDAAS_USERS, CUSTOMER_USERS, ENTERPRISE_USERS) is allowed immediately.	-
Evaluation	The evaluation of a role in a business or system context can be considered as a function hasRole(A,B,C):boolean	A user has to have one or more roles assigned to use an App or to execute a service.
Application	A role can be used only in context of a group.	A user has to belong to a group and in this particular group the user has one role. The default for users on cidaas is that they belong to CIDAAS_USERS with the role USER.

Constraints of the Role Entity

Change Role Entity

1. Attribute role (id) can only be allowed with any constraints if it was just created (be careful when applying this constraint, since role creation could have been done using the cidaas APIs. Hence, it could be applied immediately on other objects).

• If changed on the administrative UI:
  • The system shall show if the role is already assigned to User, App role/restriction and GroupType.
  • The system shall show a warning.
• If changed via API:
  • The system shall provide an additional status saying that role change might lead to ambiguous results.

2. The change of role description can be done at any time without impact.

Delete Role Entity

1. The deletion of a role does not support role entity change.

Group Types

A GroupType categorizes user groups and controls which roles can be assigned.

Property	Description
groupType	Unique identifier used to tag UserGroups
roleMode	Controls role assignment behavior
allowedRoles	List of roles assignable to users in this group type

GroupType Properties

	Description	Example
Purpose	A GroupType is used to categorize UserGroups. A GroupType defines allowed Roles which users shall have to have if they join the UserGroup.	cidaas introduces the cidaas_customer_grouptype to manage a user group for each cidaas customer.
Creation	It's a conceptual activity to create the right types of groups with the right roles. A GroupType must have assigned allowed roles. These roles should be created beforehand.
Evaluation	When assigning users to UserGroups, only those roles can be applied that are specified in the group type. In addition, user groups can already be handled individually with the marking of the group type.	Suppose customer_group_type predefines [TECHNICALADMIN, BUSINESSADMIN, TICKET_REPORTER, CONTACT_PERSON], the user can only join the respective UserGroup when assigned to at least one of the predefined Roles.
Application	Every UserGroup should be tagged with only one GroupType.

Role Modes

Mode	Description
any_roles	Any role in the system can be assigned
roles_required	At least one of the allowedRoles must be assigned
allowed_roles	Only allowedRoles can be assigned (optional)
no_roles	No roles can be assigned

Example GroupType:

{
  "groupType": "CUSTOMER_GROUP_TYPE",
  "description": "Group type for customer management",
  "objectOwner": "client",
  "roleMode": "allowed_roles",
  "allowedRoles": [
    "GROUP_ADMIN",
    "MEMBER_INVITER",
    "MEMBER_ADDER"
  ]
}

Constraints of GroupType entity:

• Change GroupType Entity
  1. The constraints of the changing attributes is described with the attributes.

Changing of GroupType name might affect the stability of customer systems since they may rely on stable GroupType names.

• Delete GroupType Entity
  1. The deletion of a GroupType used in UserGroups should be avoided.
  2. The deletion of a GroupType which is unused is supported on cidaas.

User Groups

A UserGroup is a logical container for users.

Property	Description
groupId	Unique identifier
groupName	Human-readable name
groupType	Reference to GroupType
parentId	Parent group (use "root" for top-level)
make_first_user_admin	Auto-assign GROUP_ADMIN to first member
memberProfileVisibility	public or full - controls profile access for members
noneMemberProfileVisibility	public or none - controls profile access for non-members

UserGroup Properties

To leverage groups and make them easier to understand, the following definitions illustrate the parent-child relationships between user groups and the assignment of users to user groups.

1. A user can be assigned to multiple groups.
2. The relationships of user groups are defined by the following conditions:
   • A parent user group does not inherit any properties or behavior to its child user group.
   • Thus, the parent user group does not inherit users to its child groups or the group type of the parent group.
   • The relationship of the groups provides an ordering framework that allows navigation between user groups.
3. The user group concept helps map the requirements for modern user administration.

	Description	Example
Purpose	The UserGroup is a container to group users based on specific requirements. Each UserGroup is hierarchically assigned to a parent group while the highest group is ROOT, which is effectively not a user group. In addition to this, a UserGroup may have sub-groups. A GroupType tags the UserGroup to define which Roles can be assigned to the users	Please see the examples illustrated above.
Creation	UserGroups can be created centrally by the administrators or delegated to applications using cidaas APIs.	For example, a UserGroup for a cidaas customer is created automatically when a customer signs up for a cidaas plan. The respective contact person of an organization handling the customers becomes the GROUP_ADMIN which allows them to invite other users to their company's customer group.
Evaluation	When assigning users to UserGroups, only those roles will be applied that are specified in the group type. In addition, user groups can be handled individually with the marking of the group type.	Suppose the customer_group_type predefines [TECHNICALADMIN, BUSINESSADMIN, TICKET_REPORTER, CONTACT_PERSON] the user can only join that respective UserGroup if they get assigned to at least one of the predefined Roles.
Application	A UserGroup is a common approach on cidaas to define specific user access rights.	-

Example UserGroup:

{
  "groupId": "DATA_ANALYSTS_TEAM",
  "groupName": "Data Analysts Team",
  "groupType": "DEPARTMENT_GROUP_TYPE",
  "parentId": "ENGINEERING",
  "groupOwner": "client",
  "make_first_user_admin": true,
  "memberProfileVisibility": "full",
  "noneMemberProfileVisibility": "none"
}

Constraints of the UserGroup entity

• Change UserGroup Entity
  1. The constraints of changing attributes are described with the attributes.
• Delete UserGroup Entity
  1. Users still assigned to the deleted UserGroup will get unassigned automatically.
  2. UserGroups still used on apps to restrict access should not be deleted. The UserGroup must be removed beforehand.
  3. A UserGroup which has child UserGroup(s) cannot be deleted directly. Sub-groups must be assigned a different parent group or the virtual group "root."

User Group Map

The UserGroupMap represents the relationship between a user and a group.

Property	Description
sub	User's unique identifier
groupId	Reference to the user group
roles	List of roles the user has in this group

Example UserGroupMap:

{
  "sub": "2cca1f8b-1d68-4d63-9819-065983323456",
  "groupId": "DATA_ANALYSTS_TEAM",
  "roles": ["GROUP_ADMIN", "MEMBER_INVITER", "MEMBER_ADDER"]
}

The assignment of a user to a group is managed in the UserGroupMap entity. Each entry reflects the link of one user to a specific user group.

Role and Group Mapping Overview

The admin user needs to follow these steps to set up role and group mapping for apps:

1. Create Roles: Define roles under Role Master that represent the different permission levels needed
2. Create GroupType: Create a GroupType and map the allowed role(s) to it. The GroupType defines which roles can be assigned to users in groups of this type
3. Create UserGroup: Create a UserGroup with the GroupType and assign a group name and group ID
4. Assign GroupType to Application: Assign the GroupType to the application to enable group-based access control
5. Configure Access Restrictions: Define Group & Roles restrictions for Login and user creation and updation by specifying which groups and roles are required for access

Group Role Restriction in Apps (Clients)

You can restrict user access to specific apps by applying group role restrictions under App Settings on the cidaas Admin interface.

Learn more: Groups Role Restrictions - Detailed guide on using group role restrictions for access control

Group Role Restriction in Services

cidaas interceptors can be used to restrict access to web services. If a cidaas user decides to use those interceptors in its web services group and role restrictions can be defined in annotations to block API usage for users who don't meet the requirements of the specified groups and roles.

Learn more: Groups Role Restrictions - Detailed guide on using group role restrictions for access control

Groups and Ownerships

GroupOwner

Each group has a groupOwner that manages it. The following distinctions are made on cidaas:

GroupOwner	Description
ADMIN	GroupOwner of the default user groups on cidaas.
CLIENT	GroupOwner of the user groups that customers create.

Default User Groups

Group name	Description
CIDAAS_ADMINS	All the admin users of an organization become members of this group.
CIDAAS_USERS	All the regular users of an organization become members of this group or its sub-groups.

Best Practices

1. Use Group Hierarchy Wisely

ROOT
├── DEPARTMENTS
│   ├── ENGINEERING
│   │   ├── DEVELOPERS
│   │   └── DATA_ANALYSTS
│   └── MARKETING
└── EXTERNAL
    └── CONTRACTORS

2. Apply Principle of Least Privilege

Only assign the roles necessary for the task. When using delegated group administration, assign only the required roles.

3. Plan Group Types Before Creating Groups

Create GroupTypes with appropriate role modes and allowed roles before creating UserGroups. This ensures consistency and prevents role assignment errors.

4. Audit and Monitor

• All group membership changes are logged
• Review group membership changes regularly

Technical Integration

The following APIs are available for managing roles, group types, user groups, and user group mappings:

API	Description	Link
Get Role Setup	Get the Role Setup properties	View API
Store Role Setup	Create or update role setup to structure users and control access rights	View API
Find Group Types	Get the properties of a GroupType	View API
Get Group Type	Get the properties of a UserGroup	View API
Store User Group	Create a new user group	View API
Get User Group Map	Get the UserGroupMap properties	View API

Need Support?

Please contact us directly on our support page. Thank you!