AutoMate/docs/keycloak_naming_convention.md

Revised Plan: Role Naming with Realm/Domain Prefix

1. Naming Conventions

Realm Roles

Realm roles define permissions for users. The naming convention will follow:

<realm>_<scope>_<service>

Component	Example	Description
Realm/Domain	management	The realm where the role is defined.
Scope	service_admin	Specifies the level or type of access.
Service	nextcloud	The specific service or application.

Examples:

• management_service_admin_nextcloud
• analytikdata_service_admin_paperless
• riechsteiner_user_kimai

Groups

Groups are collections of users and do not define permissions themselves. They are used to organize users logically. Examples:

• nextcloud_admins
• finance_team
• analytikdata_employees

---

2. Role and Group Usage

Roles

• Define specific permissions for services.
• Assigned to individual users or groups.

Groups

• Act as containers for users.
• Inherit realm roles to apply permissions to all members.

---

3. Role and Group Setup Example

Management Realm

• Roles:
  • management_service_admin_nextcloud
  • management_service_admin_paperless
  • management_user_kimai
• Groups:
  • nextcloud_admins → Assigned management_service_admin_nextcloud
  • paperless_admins → Assigned management_service_admin_paperless

AnalytikData Realm

• Roles:
  • analytikdata_service_admin_nextcloud
  • analytikdata_user_nextcloud
• Groups:
  • admins → Assigned analytikdata_service_admin_nextcloud
  • employees → Assigned analytikdata_user_nextcloud

---

4. Updated Naming in Practice

Updated Keycloak Roles

Realm	Role Name	Purpose
management	management_service_admin_nextcloud	Admin rights for Nextcloud in management realm.
management	management_service_admin_paperless	Admin rights for Paperless in management realm.
analytikdata	analytikdata_service_admin_nextcloud	Admin rights for Nextcloud for AnalytikData GmbH.
analytikdata	analytikdata_user_nextcloud	General user access to Nextcloud.
riechsteiner	riechsteiner_service_admin_kimai	Admin rights for Kimai for Riechsteiner.

Updated Groups

Realm	Group Name	Purpose
management	nextcloud_admins	Admin group for Nextcloud.
management	paperless_admins	Admin group for Paperless.
analytikdata	employees	General employees.
riechsteiner	admins	Admins for all services.

---

5. Implementation Steps

Step 1: Set Up Roles in Keycloak

1. Go to Realm Settings > Roles for each realm.
2. Add roles based on the new naming convention (e.g., management_service_admin_nextcloud).
3. Map these roles to clients (e.g., Nextcloud, Paperless).

Step 2: Create Groups

1. Go to Groups in each realm.
2. Add groups (e.g., nextcloud_admins, employees).
3. Assign relevant roles to the groups.

Step 3: Assign Users to Groups

1. Go to Users > Groups.
2. Add users to groups to inherit permissions.

---

6. Example User Workflow

User: Jane Doe (AnalytikData)

• Realm: analytikdata
• Group: employees
• Roles (via group): analytikdata_user_nextcloud, analytikdata_user_paperless
• Access:
  • Can log in to Nextcloud and Paperless as a regular user.

User: John Smith (Management)

• Realm: management
• Group: nextcloud_admins
• Roles (via group): management_service_admin_nextcloud
• Access:
  • Admin access to Nextcloud in the management realm.

---

7. Git Commit Message

Restructure Keycloak roles and groups with realm prefixes

- Implemented a consistent naming convention for roles:
  <realm>_<scope>_<service> (e.g., management_service_admin_nextcloud).
- Added roles for each service in management and company realms.
- Created logical groups for user organization (e.g., nextcloud_admins, employees).
- Mapped roles to groups to simplify user permission assignments.
- Improved clarity and scalability for multi-realm setups.