RBAC_PermissionNotes.adoc #1

= [DRAFT] Role-Based-Access-Control (RBAC) Permission Notes
Perforce Professional Services <[email protected]>
// Metadata
:revnumber: v2025.1
:revdate: 2025-10-29
:description: Thoughts on managing complex permissions with P4d using RBAC style groups.
// Settings
:doctype: book
:icons: font
:toc:
:toclevels: 5
:sectnumlevels: 4
:xrefstyle: full
:source-highlighter: highlight.js
// Attribute for ifdef usage
:unix_doc: true

[discrete]
=== Todo Items

* Add scripts to demonstrate reporting RBAC permissions ( likely using P4PHP and a webserver ).   This allows some experimentation with RBAC without changing P4d.

* Add triggers or new broker functions to handle RBAC permissions.   These could simply validate RBAC rules are followed.

// Horizontal Rule
// '''

== DRAFT NOTICE

WARNING: This document is in DRAFT status and should not be relied on yet.  It is a preview of a document to be completed in a future release.

== Preface

This document discusses some ideas on managing large complex Perforce permissions schemas using Role-Based-Access-Control ( RBAC ) methods.

Perforce has a simple model of permissions utilizing users, groups, nested groups, and permissions.   While this structure is very flexible, it sometimes may
get disorgnized when working with large complex permission schema's.   This document proposes some additinal formalization of the existing p4 groups into a RBAC model
consisting of `user groups` and `role groups`, along with rules for their useage.


[NOTE]
====
Motavation:  Many large Perforce sites often look for improved methods in managing Perforce permissions.  Some sites manage all user/groups/permissions in an external tool
and generate / import the entire protections table into P4d.   Some sites manage all groups externally in `MS Active Directory` groups synced to Perforce.  However, these
methods often lead to 

This document adds some additional formal structure to the existing P4d permission model simliar to _RBAC_ methods used with _Microsoft Active Directory_. 

====

The goal in these examples is to configure three LVM storage volumes separate from the OS volume on a server destined to become a Helix Core server.
At the start of this procedure, empty volumes with no data are formatted.


*Please Give Us Feedback*

Perforce welcomes feedback from our users.
Please send any suggestions for improving this document or the SDP to [email protected].

In particular user groups are often found with nearly identical permissions assigned but no
clear reason why

:sectnums:
== RBAC Intro

Role-based-access-control (RBAC)

====
RBAC, or Role-Based Access Control, is a security method that restricts system access based on a user's role within an organization, rather than on their individual identity. It works by assigning permissions and privileges to roles, which are then assigned to users, ensuring that individuals only have access to the data and applications needed for their specific job function
====




=== What is RBAC ?

RBAC is a formalized method of controlling permissions assigned to users in a more structured way.

Instead of assigning permissions to users or groups in an ad-hock mannner, we 
we assign Users to User Groups, User Groups to Role Groups,  and Role Groups to Permissions.

We specifically avoid assigning Permissions directly to user.  We also avoid any nesting of User Groups within other User Groups.

```
Assignment Hiearchy:
Users->UserGroups->RoleGroups->Permissions
```

==== Sample Schema

For this example we use a Game Developer company that uses internal staff and external contractors to fill many of the same roles.   The internal and external staff are kept separated, but may share many of the same roles.  The GameEngine code contains modification shared across several projects, so the folks editing the GameEngine are a subset of Developers.

This is a sample schema for **Project1** containing several _Roles_ and several _User Groups_ .


Project1: Roles

Note that each Role gets permissions assigned.

* Proj1_CodeDev_Role  - Development of the Game
* Proj1_GameEngineDev_Role - Modification of the Game Engine
* Proj1_Artist_Role - Art, 3d Models
* Proj1_AudioEngineer_Role - Audio tracks
* Proj1_BuildEng_Role - Build automation

Project1: User groups

Note that no permissions may be assigned, only roles.  External groups are explicitly separated from Internal.  Typical assigned roles are shown.

* Team1_Developers
** Proj1_CodeDev_Role
** Proj1_GameEngineDev_Role
* Partner1_Dev_External
** Proj1_CodeDev_Role
* Team1_Artists
** Proj1_Artist_Role
* APAC_Art_External
** Proj1_Artist_Role

==== Sample Report

Ultimately for this project, we could procedue an RBAC formatted representation of each project's permissions.


=== Problems RBAC Solves

Some of the issues commonly found with existing ad-hock permissions assignements are.

. Discrete permissions are assiged directly to a user, leading to a collection of permissions without any documentation of what each permission or group of permissions are for. Only the Subject Matter Experts ( SME's ) understand the permissions,  not the IT folks assigning new users to a group.

. User groups are sometimes nested to pick up permissions of the parent group, however this relationship is not often well displayed or understood and often leads to over assigning permissions.   In general we avoid the pernicious nesting of user groups within user groups.

. Requests to add permissions are often ( give new user X the same permissions as Y ) without any clear understanding of what those permissions are. 

[NOTE]
Microsoft guidance on Nesting of groups in Active Directory:
https://www.techtarget.com/searchwindowsserver/tip/Active-Directory-nesting-groups-strategy-and-implementation
This "ADGLP" strategy allows 2 levles of nesting, but since we don't have a global context and are dealing with a single project inside a Perforce instance our RBAC limits nesting to just _User Groups_ as subgroups of _Role Groups_ and no further nesting.


=== Scanerios where RBAC may be beneficial

Adopting Perforce *RBAC* procedures as described here may be beneficial if.

. Folks requesting permissions for new users don't typically know the exact list of permissions required.  Often requests are made to _provide permissions same as user X_.
*RBAC* gives names ( e.g Roles ) to groups of permissions making it easier for folks to understand 
. Perforce permissions are often assigned by IT folks who are not Perforce experts.  This follows closely how Active Directory Roles are assigned for multiple corporate Roles, without IT knowing the detailed permissiongs granted by the Roles.   Perforce experts are involved with creating or changing permissions in the Roles,  but assigning them.
. There are user groups in Perforce with very similar assignments of permissions , but no clear understanding of why the differences exist.


[discrete]
=== Todo Items

. Show a sample RBAC report output.   See <<Sampe Schema>>.

. Need a demo script that reports a basic RBAC Schema report.   This could be simple command-line canned report,  or a php App.


== Implementation


=== Current status

Currently there is no built-in suppportin P4d for _RBAC_ roles, however these procedure use existing p4d functionality by simply reporting _RBAC_ permissions.  Permission changes in an _RBAC_ enabled project that don't meed the rules, are flagged or ignored. Some of these ideas could be supported futher with triggers or broker scripts, especially if further interest is expressed.

.Design note
[NOTE]
The implementation discussed here uses procedures or scripts only to report the Perforce Permissions in an enhanced RBAC Schema. The _RBAC_ schema has slightly stricter rules, but uses existing p4d commands.
The design goal is that these procedures do not intercept normal P4d permission operations.     That is, initally these procedures are designed to be fail-safe by simply reporting permission in an _RBAC_ manner, and simply reporting any _RBAC_ schema violations.   Later, enforcement of _RBAC_ schema could be added, but could easily disabled if no longer needed.


=== Supporting Role Groups

To support the concept of Role groups we split the namespace of User groups into the following:

User Groups::
  * _User groups_ contain only users and can't be nested inside other user group.
  * _User groups_ are never assigned permissions directly
  * _User groups_ may be assigned as a subgroup of a _Role Group_ to pick up permissions

Role Groups::
  * _Role Groups_ never contain users
  * _Role Groups_ are assigned permissions
  * _Role groups_ have subgroups containing _User Groups_


So in effect we are enforcing some new procedures.

  . Permissions are never directly assigned to a user or group.    We enforce *ALWAYS* creating a *Role* for any single permission or group of permissions.   This Role should have an clear name that describes it's function.   This is an _extra_ layey of inderection being imposed.

  . Other than a single level nesting of _User Groups_ as subgroups of _Role Groups_ there is no other nesting allowed.    _User Groups_ may not be nested inside other _User Groups_ as that is pernicious.

  
By following these rules,  the permission schema is simplified so that most folks only ever need to understand the limited set of _Roles_ for the project.  Only the Project SME's need to understand the permissions assigned to a _Role_ and rarely change them.


=== Reporting

The simplest reporting can be accomplished by command-line p4 scripts to report some of the following:

* List Role groups
** List Role group and associated User ( sub-groups ), and effective permissions assigned.
* List User Groups
** List User Groups and associated Roles ( and optionally a list of users assigned )
* List users in the project ( belonging to at least one User Group in the project ) and their assigned Roles

[appendix]
== DRAFT NOTICE

WARNING: This document is in DRAFT status and should not be relied on yet.  It is a preview of a document to be completed in a future release.