## Overview #### :tv: [Video about Customizable Roles and Permissions in GitLab](https://youtu.be/ogVgsYXaCfM) _note that our MVC has changed slightly from when this video was recorded. Good news is, customer value is delivered sooner than originally thought! Our MVC has been delivered, read about it on our blog: https://about.gitlab.com/blog/2023/03/08/expanding-guest-capabilities-in-gitlab-ultimate/_ #### :newspaper2: [Current Product Documentation](https://docs.gitlab.com/ee/user/permissions.html) ## Problem GitLab has 6 out of-the-box roles that cannot be modified: - Minimal Access - Guest - Reporter - Developer - Maintainer - Owner These roles are static and are defined by the GitLab project members permissions [matrix](https://docs.gitlab.com/ee/user/permissions.html#project-members-permissions). Since these roles are static, some customers find a particular role "too permissive" while another customer may wish they could expand permissions on to the same role. To make an adaptation on the phrase, "One size does not fit all"...in our case, "6 sizes do not fit all". Customers rely on adaptive roles and permission models to meet operational and compliance standards. Currently, GitLab's role system is considered too broad for many customers - especially those operating in regulated environments. ## UX Research Summary <details> <summary>UX Research Summary</summary> A [design pod](https://gitlab.com/groups/gitlab-org/-/epics/7420) was formed. This pod handled the research and outcome. ### Product Research Themes - I want to abide by the principle of least privilege to limit my risk. "Limited for the task, limited for the time" - Developer and Maintainer are most used - For Enterprises, there is a mapping that exists that between employee A and the role in GitLab that they should receive. Often this is assigned via an automatic process (part of SAML provisioning) - SMB more content with current 5 roles than enterprise and federal use cases - I am concerned that overprivileged users will come back to haunt us either in terms of someone doing something they shouldn't, or an audit - Users being able to delete things (even a label) without being able to get it back is scary and shouldn't be able to be easily done - When roles change, it is typically because someone needs more privileges, not less - Owner scares me - I don't want to be an owner, it has too many privileges - I don't want Owners to be able to create more Owners - I want to separate out the access my business users (Product, Project Managers, Auditors, Business Stakeholders) have vs the access my engineering team has - Contractor access has a different user lifecycle - spans a shorter period of time, is more controlled - Sometimes the developer role feels overly privileged (ability to delete container registry, for example) - If customers could create an infinite number of custom roles, most would need to create between 3-10 in order to achieve their goals. - Separation of duties - no one person should have access to "everything". Companies would like to map their job titles to a specific set of permissions in GitLab. -API support as part of initial implementation - Auditing as part of initial implementation, for security and compliance reasons </details> ## Product Research Summary <details> <summary>Product Research Summary</summary> | Persona | Use Case | Process | Pain Point | Requirement | | ----------- | ----------- | ----------- |----------- |----------- | | Admin | Onboard new users into the system | Manually input users, manually assign role based on tribal knowledge or HR system | N/A | No new requirement | | Admin | Create new custom role| Create role using new custom roles and permissions framework| Some permissions, when they're enabled or disabled, make it impossible to have a choice for a downstream permission | Account for blocking conflicting granular permission requirements: Ex, If I were to remove the permission to view project code, would that impact their ability to see MR changes, as that is showing the code? | | Admin | Onboard users into the system using Identity Provider | Use Identity Provider (SAML, LDAP) to store users and their attributes. Users automatically provisioned into GitLab. Use a pre-defined mapping to determine which role a users receive using group sync. | Because of the existing definition, I sometimes have to grant a more privileged role to users than I'd like to. | Allow roles to be customizable. Allow me to choose one of my custom roles from the SAML or LDAP group mapping dropdown for "Default Access Role". | | Admin | Onboard new users into the system via API | Custom integration between my system + GitLab, creates users using the GitLab User API | Can't customize existing roles/create new roles | Allow customization of roles to be done through the API (may not be part of MVC). Allow my integration to call the GitLab APIs in order to create these users | | Admin | Change user's current GitLab role to a new, existing role | When a user gets promoted or asks for more access, I need to change their role to give them more permissions | N/A | Allow GitLab users role to be changed via UI, Group Sync, and API (I believe this is existing functionality) | | Admin | Audit of a change in user's role in GitLab| Manually modify user permissions based on user phone call, access request, etc. mostly elevating permissions | Once permissions are elevated, they very rarely come back down. How can we stay on top of those with elevated permissions that may not need them? What elevated aspects haven't they used? | A way to audit which privileges a user has/hasn't used under their role. This will likely fall under ~"group::compliance". Further iteration: ability to subscribe to these updates | | Admin | Customize existing roles, Create new roles| No process in place today | The current pre-defined GitLab roles are too restrictive. I want to be able to customize them and choose exactly what each role means. | Allow for creation of custom roles (We can iterate here -- requirement at first can just be customizing the roles that exist, then later we can support creating entirely new custom roles) | | Admin | Delete role | If I can create custom roles, I want to also be able to delete them when they no longer suit my needs. | N/A | Allow for roles to be deleted. Offer reassignment to new role when users are assigned to a deleted role? | | Admin | Audit of a change in role definition or creation of a new role| Modify Existing Customizable Role, Create New Role | Doesn't exist today because this is not possible | A way to audit when a new role is created and when an existing role has its permissions modified. Further iteration: ability to subscribe to these updates. Further iteration: ability to subscribe to these updates | | Admin | Admin tasks | I want to restrict my own privileges, even at the Owner level | "Save me from myself". I don't want to have extremely elevated privileges. I want just enough to be able to do my job. I don't want a role that will let me do something that's disruptive to the business (delete an important project, etc) | Allow owner role to be customized | | Admin | View Inherited Permissions | Doesn't exist today |No clear way for admin to view inherited permissions when groups and projects are shared or part of inheritance | Clear way to see which projects a user has permissions to and what the permissions are within each project (this probably needs more definition, just want us to be aware)| | Admin & End User | View Permissions | Use existing permissions [matrix](https://docs.gitlab.com/ee/user/permissions.html#group-members-permissions)| As custom permissions are created, how do I know what I can and can't do? | Users and admins should have a way of clearly viewing which permissions they have and what they mean (need to consider how this would change, considering our current labels mapping to our static roles and the roles being defined in the matrix - how can this experience be made flexible along with the roles? | | GitLab Internal | Permissions should not be able to override licensing tiers/subscriptions | | | Ultimate accounts currently get unlimited free Guests. If they can elevate permissions on Guests to the point that they would never need any other roles, this would incentivize them to never buy more licenses. We need to consider other cases around this concept. | | End User | User Needs to be able to view their role definition | | | A user needs to understand what they can and can't do. If their role is custom, this is impossible for them to know. There needs to be a way for a user to view their role definition. | </details> ## Proposal Flexible access model that allows for fine-grained role control and permission customization. ### Iteration 1 - COMPLETE 1. "Guest" users in private projects are not able to view code today. This is the cause of a lot of customer pain, especially for Ultimate customers, who get free guest users. Create a new custom role based on "Guest" that has the ability to also see code: https://gitlab.com/gitlab-org/gitlab/-/issues/20277+ ### Iteration 2 IN PROGRESS 1. Allow admins/group owners to create custom roles via API. Audit this any time a role is modified, created, or deleted. Roles are additive only in nature (ex: I can start with Guest and add but I cannot subtract from Guest) - UNDER WAY, going one permission at a time. 2. :white_check_mark: Guardrails around licensing - not being able to elevate "Free" users above "Free" capabilities - [COMPLETE for SaaS](https://gitlab.com/gitlab-org/gitlab/-/issues/390269), [COMPLETE for Self-Managed](https://gitlab.com/gitlab-org/gitlab/-/issues/395794) 3. Auditing around custom roles - Likely in %"16.3" timeframe 4. Once a role is created and assigned to at least one user, the role cannot be modified. A new role would need to be created. 5. Consolidate like permissions ### Iteration 3 1. Custom role creation via UI 2. Admin can configure "max role" from list of custom roles, in addition to the static ones 3. Custom Roles obey group and project sharing ### Current Progress and Roadmap _last updated 11/14/23_ NOTE: We are starting with most in-demand customer permissions: https://gitlab.com/gitlab-org/gitlab/-/issues/391760+ - please increment the number next to the permission you'd like to see added next, or add a new row _Permission work in progress_ - https://gitlab.com/gitlab-org/gitlab/-/issues/393239+ / expected delivery %"16.7" - https://gitlab.com/gitlab-org/gitlab/-/issues/428043+ / expected delivery %"16.7" - https://gitlab.com/gitlab-org/gitlab/-/issues/417285+ / expected delivery %"16.7" - https://gitlab.com/gitlab-org/gitlab/-/issues/417201+ / expected delivery %"16.7" - https://gitlab.com/groups/gitlab-org/-/epics/11851+ / expected delivery %"16.8" _Recently Completed_ - https://gitlab.com/gitlab-org/gitlab/-/issues/425957+ - [Manage group members customizable permission](https://gitlab.com/gitlab-org/gitlab/-/issues/17364) - [Manage Project access tokens customizable permission](https://gitlab.com/gitlab-org/gitlab/-/issues/421778) - [Approve merge requests](https://gitlab.com/gitlab-org/gitlab/-/issues/412708) - [UI for Customizable Roles](https://gitlab.com/groups/gitlab-org/-/epics/9827) - [Read dependency list](https://gitlab.com/gitlab-org/gitlab/-/issues/415255) - [View Security Dashboard](https://gitlab.com/groups/gitlab-org/-/epics/10160) - [View vulnerability report](https://gitlab.com/groups/gitlab-org/-/epics/10160) - [Change vulnerability status](https://gitlab.com/gitlab-org/gitlab/-/issues/415252) - [Ultimate Guest User can View Code](https://gitlab.com/gitlab-org/gitlab/-/issues/20277+) - [Create custom role name and description in API](https://gitlab.com/gitlab-org/gitlab/-/issues/416751) _Permissions Up Next_ - https://gitlab.com/gitlab-org/gitlab/-/issues/421024+ - https://gitlab.com/gitlab-org/gitlab/-/issues/427954+ - https://gitlab.com/gitlab-org/gitlab/-/issues/428174+ - https://gitlab.com/gitlab-org/gitlab/-/issues/388934+ - https://gitlab.com/gitlab-org/gitlab/-/issues/393237+ - https://gitlab.com/gitlab-org/gitlab/-/issues/425959+ - https://gitlab.com/gitlab-org/gitlab/-/issues/428353+ _Futher Out, but still upcoming_ - [Add "Add Compliance Framework to a project" as a customizable permission](https://gitlab.com/gitlab-org/gitlab/-/issues/411502) - https://gitlab.com/gitlab-org/gitlab/-/issues/417755+ - https://gitlab.com/gitlab-org/gitlab/-/issues/421789+ - https://gitlab.com/gitlab-org/gitlab/-/issues/254668+ ### Future Work / Out of Scope 1. Permissions residing outside of current permissions matrix 2. User ability to view custom role definitions - this needs to be documented externally by the customer for now 3. Known limitation - customizable permissions will be additive only. To make a very customized role, you'd have to take `Guest` and add to it, there will be no ability to subtract. Functionally, it's the same, since rather than taking Role X and subtracting from it, you can take Role Y and add to it until you get to the (Role X minus). ## Approach - [x] Assemble a cross-stage design team [Design Pod](https://gitlab.com/gitlab-org/gitlab/-/issues/339285) to collaborate in the problem & solution space. [Configure, Manage, Monitor, Protect, Secure, Verify, Release] - [x] Product Manager Interviews with customers across small business, large enterprise, and government customers - [x] Requirements draft, mocks draft - [x] MVC proposal - [X] Technical spike to understand current constraints - https://gitlab.com/gitlab-org/gitlab/-/issues/352891 ## Tiering Strategy ~"GitLab Ultimate" only ## Related Epics and Issues https://gitlab.com/gitlab-org/gitlab-foss/-/issues/12736 https://gitlab.com/gitlab-org/gitlab/-/issues/339285