User Management and Access Control

RBAC

Shipa offers a comprehensive Role-based access control system (RBAC) designed to provide users fine-grained access to resources within your organizations, no matter if using your own Shipa Installation or if you have an account on Shipa Cloud.

All potential permissions that a user can have can be visualized by executing the command

shipa permission list

+----------------------------------+--------------------------------------------+
| Name                             | Contexts                                   |
+----------------------------------+--------------------------------------------+
| *                                | organization                               |
| app                              | organization, app, team, framework         |
| app.admin                        | organization, app, team, framework         |
| app.admin.quota                  | organization, app, team, framework         |
| app.admin.routes                 | organization, app, team, framework         |
| app.admin.unlock                 | organization, app, team, framework         |
| app.autoscaling                  | organization                               |
| app.build                        | organization, app, team, framework         |
| ...more                          |                                            |
+----------------------------------+--------------------------------------------+

Administrators can define roles using the aforementioned permissions and assign them to users within different contexts to control the access each one of them has to specific resources

Such flexibility comes with a price, as composing the right set permissions for your teams and users might be a bit challenging at first; therefore, we decided to create an opinionated approach, using common concepts in the industry, to allow administrators to quickly onboard users based on the role they play within their own organization.

The aforementioned approach defines three "profiles" that can be assigned to onboarded users within your organization to scope the resources they have access to and the actions they can perform. Such roles are detailed below:

Admin

User enabled to manage the whole organization. Has access to all resources within an org and can perform all actions listed when running shipa permission list. This type of user can manage infrastructure, applications, and users.

RBAC Roles: Shipa-Admin

Access: Role scoped to the whole organization. The user can see any resource from any available team, which means that the user can manage any cluster, framework, app, volume, etc created by any user within the same organization

+------------------+--------------+----------------------+
| Role             | Context      | Permissions          |
+------------------+--------------+----------------------+
| Shipa-Admin      | organization | *                    |
+------------------+--------------+----------------------+

DevOps

User enabled to manage infrastructure, establish policies and oversee applications within a given team.

RBAC Roles: Shipa-DevOps, Shipa-Org-Shared

Access: Role scoped to a set of teams. Assigning this role requires specifying a team(s) to which a user should be appended. Once the assignment is completed, the user should be able to manage only the resources that users within the same team have created. Other resources belonging to other teams won’t be accessible for this user.

+------------------+--------------+----------------------+
| Role             | Context      | Permissions          |
+------------------+--------------+----------------------+
| Shipa-DevOps     | team         | app                  |
|                  |              | cluster              |
|                  |              | framework            |
|                  |              | node                 |
|                  |              | plan                 |
|                  |              | team                 |
|                  |              | volume               |
|                  |              | volume-plan          |
+------------------+--------------+----------------------+
| Shipa-Org-Shared | organization | role.read            |
+------------------+--------------+----------------------+

Developer

User enabled to manage applications within a given team

RBAC Roles: Shipa-Developer, Shipa-Org-Shared

Access: Role scoped to a set of teams. Assigning this role requires specifying a team(s) to which a user should be appended. Once the assignment is completed, the user should be able to manage applications only within the same team and read the resources listed above that other DevOps have created for them.

+------------------+--------------+----------------------+
| Role             | Context      | Permissions          |
+------------------+--------------+----------------------+
| Shipa-Developer  | team         | app                  |
|                  |              | cluster.read         |
|                  |              | framework.read       |
|                  |              | node.read            |
|                  |              | plan.read            |
|                  |              | volume-plan.read     |
|                  |              | volume.read          |
|                  |              | volume.update.bind   |
|                  |              | volume.update.unbind |
+------------------+--------------+----------------------+
| Shipa-Org-Shared | organization | role.read            |
+------------------+--------------+----------------------+

This structured approach can be visualized in the following illustration, and it encourages admins to split resource access across multiple teams.

926926

NOTE: A single DevOp or Developer can belong to multiple teams, so the flexibility of this approach still allows to provide higher-level access to those special users within your organization that are working in multiple teams

 

The roles described above are available in each installation/account out-of-the-box, and can be used right away by the Admin of the installation (is using a Self-hosted version), the Administrator of your organization (if using Shipa Cloud), or by any user assigned the pre-built profile of "Admin" through this opinionated RBAC.

  


 

1. RBAC support from the Dashboard

To simplify this process even further, the dashboard shipped with Shipa exposes a friendly UI that allows Admins to use this opinionated RBAC approach.

 

1.1. Users onboarding and Role assignment

Let’s take the following guided tutorial to emulate the scenario illustrated above.

1.1.1. Create an account on Shipa Cloud and sign in at apps.shipa.cloud

12241224

 
1.1.2. Go to the User management section and make sure you have admin privileges.

12251225

Note: You email address should be marked as Admin, and when hovering over the Role column, you should either see the reserved role "AllowAllOrg" (on Shipa Cloud) or "AllowAll" on a self-hosted installation. By default, only admins can manage users.

 
1.1.3. Click the button Invite users and enter 2 email addresses to add your new users. In our case [email protected] and [email protected].

510510

Note: Users get created without initial roles

 
1.1.4. Go to the Teams tab and create a new team to scope your users. Call it dev.

451451

 
1.1.5. Go to the Plans page and create a custom plan for your new team. This will define the resources that later on the apps within your team can consume. Make sure to select the team dev

551551

 
1.1.6. Go back to the User management page, locate the user you want to assign as Developer and click the button Roles. Select the role Developer and the team we just created dev

352352

Note: The dashboard displays a summary of the actions the developer can execute based on the default permissions

 
1.1.7. Your user is already a Developer. Hover over the Role dropdown, and see the roles assigned to it, You should see Shipa-Developer and Shipa-Org-Shared

348348

 
1.1.8. Repeat the process with your second user but assign the role DevOps (choosing the same dev team)

351351

 
1.1.9. That’s it! Your users have been rightfully configured to manage scope resources within the team dev and won’t have visibility over resources other users create out of the given team.

 
1.1.10. Sign in as the [email protected] user (DevOps) and proceed to create a framework and connect a cluster.

📘

Note

New users need to complete a sign-up process following the instructions sent to their email upon invitation.

752752 924924 921921

 
1.1.11. Sign in as the developer [email protected] and proceed to create and deploy your first app, using the framework your DevOps previously created

401401 920920

📘

Easy cooperation

As you can see, both users dev1 and ops1 are "connected" between each other, their resources are being scoped to the same team, so dev1 can use the framework and cluster that ops1 created.

 
1.1.12. Let’s take the tutorial further, let’s create one more user [email protected], and assign the role of DevOps, but let’s assign it to a new team prod

354354

 
1.1.13. Sign in as the new ops2 user, and visit the Frameworks page. As you will see, you don’t have access to the dev-frameworks ops1 created, as you don’t share the same team. As an Admin though, you can see anything the three users create

 

1.2. How to see my own roles?

If you are unclear on what roles and permissions have been assigned to you as a user, visit your profile page and go through the section called Roles. To do so:

 
1.2.1 Sign in into your dashboard and locate your profile page on the top right corner

179179

 
1.2.2. Click on the profile icon to open your details. All your information will be displayed there:

545545

 
1.2.3. Check the permissions of a given Role by hovering over the Details button

603603

 

1.3. Extending pre-built roles

All pre-built roles that support this opinionated approach, can be extended by adding more permissions to them when needed. To do so, you can either use our CLI or the dashboard (recommended), and it is as simple as following the steps shown below:

 
1.3.1. Sign in as an Admin user and visit the section User Management. Click the Roles tab

918918

 
1.3.2. Edit the user role of your preference. As an example let’s click the Developer role

12081208

 
1.3.3. Locate the plus icon next to the role Shipa-Developer and click on it

452452

📘

Wildcard permissions

Permissions already covered by wildcards will be disabled as they enable actions that the user can already do. For example, if the role has the permission app assigned, all child permissions are included .i.e.: app.create, app.delete, app.build, etc

 
1.3.4. Locate and select the permissions of your preference and click the button Add. In this case, we will filter the webhook permissions, and we will select the following ones:

452452

 
1.3.5. The permissions selected are added to your role.

12081208

📘

Inmutable permissions

Notice that any extra permission added to the role appends a "remove" icon next to it, indicating that the permission can be removed from the role at any point in time. However, the rest of the permissions (originally added to the role) do not contain the same icon, hinting to the user that they cannot be removed. This constraint guarantees that our opinionated approach keeps its integrity no matter the mutations the users perform to the role

 
1.3.6. To remove one permission, simply click the minus button and confirm the operation

513513

 
1.3.7. That’s it, your role has been updated and now your developers can create and read webhooks. Use the same approach to add any permission of your preference to any of our available roles Shipa-Developer or Shipa-DevOps

  

1.4. Considerations when extending pre-built roles

 

  • Not all permissions available in shipa permissions list are compatible with a given role as they depend on supporting the used context. Since Shipa-Developer and Shipa-DevOps are created in the context of a team, only the permissions listed with the team string next to it will be valid for them. This filter is automatically done by the dashboard when mutating existing roles, but if an admin is using the CLI it should keep it in mind
shipa permission list
+----------------------------------+--------------------------------------------+
| Name                             | Contexts                                   |
+----------------------------------+--------------------------------------------+
| cluster                          | organization, team, framework, cluster     |
| cluster.create                   | organization, team, framework, cluster     |
| cluster.delete                   | organization, team, framework, cluster     |
| cloud-credentials                | organization, user                         |
| framework                        | organization, framework, team              |
| framework.create                 | organization, framework, team              | 
+----------------------------------+--------------------------------------------+

📘

Context contraint

In the example above, you can see how the cluster.create permissions exist within the context of team but cloud-credentials are only supported in the context of organization and user. That is the constraint you should keep in mind when looking to extend your roles.

 

  • Both profiles, DevOps and Developer, have a shared RBAC role assigned to them called Shipa-Org-Shared. We created it to enable both types of users to read their own roles when checking their profile information. Such a role uses the context of organization, so adding permissions to it might provide access to undesired resources. We recommend updating it only if the administrator understands clearly how our RBAC model works.

  


 

2. RBAC support from the CLI

Using the pre-built roles available on Shipa is also supported when consuming the CLI. Assuming we have a similar scenario to the one described in Diagram 1, let’s see how we can assign a Developer role to one of our existing users

 

2.1. Users onboarding and Role assignment

 
2.1.1. Sign in as an Admin and list your existing roles

shipa role list

You should see the pre-built roles available there:

+------------------+--------------+----------------------+
| Role             | Context      | Permissions          |
+------------------+--------------+----------------------+
| AllowAllOrg      | organization | *                    |
+------------------+--------------+----------------------+
| Shipa-DevOps     | team         | app                  |
|                  |              | cluster              |
|                  |              | framework            |
|                  |              | node                 |
|                  |              | plan                 |
|                  |              | team                 |
|                  |              | volume               |
|                  |              | volume-plan          |
+------------------+--------------+----------------------+
| Shipa-Developer  | team         | app                  |
|                  |              | cluster.read         |
|                  |              | framework.read       |
|                  |              | node.read            |
|                  |              | plan.read            |
|                  |              | volume-plan.read     |
|                  |              | volume.read          |
|                  |              | volume.update.bind   |
|                  |              | volume.update.unbind |
+------------------+--------------+----------------------+
| Shipa-Admin      | organization | *                    |
+------------------+--------------+----------------------+
| Shipa-Org-Shared | organization | role.read            |
+------------------+--------------+----------------------+

2.1.2. Get your organization ID as you will need it for assigning one of the rules. Run the command:

shipa user info

2.1.3. You should see a role AllowAllOrg with an ID next to the organization context, keep that ID present as it constitute your organization ID

Email: [email protected]
Roles:
    AllowAllOrg(organization <<orgId>>)

2.1.4. Assuming that all previous components have been already created (users, teams, plans, etc) as described before, and assuming that [email protected] does not have current roles assigned, run the following command:

shipa role assign Shipa-Developer [email protected] dev
shipa role assign Shipa-Org-Shared <<orgID>>

Note: If your user contains previous roles assigned, for example, a different team, or the wrong role Shipa-DevOps you will need to dissociate the role first to avoid having wrong permissions:

shipa role dissociate Shipa-DevOps dev
shipa role dissociate Shipa-Developer <<wrongTeam>>

 

2.2. Extending pre-built roles

Extending existing roles is also available through the dashboard as long as the permissions you are trying to remove are not any of the default permissions available for the reserve Roles.

 
To add permissions to existing roles, run the following command proving all the permissions of your preference:

shipa role permission add Shipa-Developer webhook.create webhook.delete webhook.read

📘

Note

Remember that as mentioned in Section 1, not all permissions are compatible with a given context. Make sure the permissions added to the command support the context that the Role internally refers to.

To remove permissions from existing roles, run the following command providing the permissions you want to remove:

shipa role permission remove Shipa-Developer webhook.create

Did this page help you?