Fine‑Grained Control in Portainer: How to Use Role‑Based Access Control (RBAC) in a Self‑Hosted Deployment

Problem

When a Docker host is shared among multiple developers or teams, the default Portainer user model gives everyone the same access level. This can lead to accidental stack deletions, unwanted image pulls, or exposure of sensitive endpoint information. The question is: how can we give each team only the permissions they need without giving them full administrator rights?

RBAC in Portainer – A Quick Overview

Role‑Based Access Control (RBAC) is a security model that maps roles to specific permissions and assigns those roles to users or teams. In Portainer, the built‑in roles are Administrator, Standard User, and Read‑Only. Beyond these, you can create custom roles that grant or deny access to individual resources such as endpoints, stacks, templates, or settings.

Key concepts:

• Endpoint – a Docker host or Swarm cluster exposed to Portainer.
• Stack – a group of services defined in a Compose file.
• Team – a logical grouping of users that can share roles.
• Permission – an action that can be allowed or denied (e.g., View stacks, Create stacks).

RBAC is available in Portainer CE from version 2.0 onward and is fully featured in the Business Edition, which adds audit‑log integration.

Step‑by‑Step: Create a Custom Role and Assign It to a Team

1. Deploy a self‑hosted Portainer instance

   Run the following command on the host that will run Portainer. Replace portainer_data with a persistent volume name if desired.

   docker run -d \
     -p 9000:9000 \
     -v /var/run/docker.sock:/var/run/docker.sock \
     -v portainer_data:/data \
     portainer/portainer-ce:latest
   

   Access the UI at http://localhost:9000. Create the first admin user during the wizard.

2. Create a test team

   Navigate to Teams → Add team. Name it devs. Add a test user (e.g., [contact removed]) to the team.

3. Define a custom role

   Go to Roles → Add role. Name it ViewOnlyStacks. In the permission matrix, enable only View stacks on the desired endpoint (e.g., endpoint‑1) and leave all other actions disabled.

   Permission	Endpoint‑1
   View stacks	✅
   Create stacks	❌
   Delete stacks	❌
   Manage endpoints	❌

   Click Save role.

4. Assign the role to the team

   Back on the Roles page, click the ViewOnlyStacks role, then Assign to team. Select devs and confirm.

5. Verify the permissions

   Log out and log back in as [contact removed]. The UI should show the Stacks tab, but the Create button will be hidden or disabled. Attempting to access the Stacks → Add stack page directly should result in a 403 Forbidden message.

   For Business Edition users, open the Audit log and confirm that the permission check events match the attempted actions.

Trade‑offs and Limitations

While RBAC gives fine‑grained control, it introduces a few practical concerns:

• Union of Roles – If a user belongs to multiple teams, the effective permissions are the union of all assigned roles. A single permissive role can override a restrictive one, so careful role design is essential.
• Cache Invalidation – Permission changes take effect only after the user logs out and back in. Cached JWT tokens may temporarily allow or deny actions until the token expires.
• Complexity – Custom roles require manual testing. Mis‑configured permissions can lock out administrators or expose sensitive resources.
• Endpoint Scope – Permissions can be scoped to specific endpoints. If you need a role that spans all endpoints, you must explicitly grant permissions for each one.

Practical Checklist for Production

1. Define a minimal set of roles that reflect real job functions.
2. Test each role in a staging environment before applying to production.
3. Document role assignments and the rationale behind them.
4. Use the Business Edition audit logs to monitor permission usage.
5. Encourage users to log out after role changes to avoid token caching issues.

Takeaway

Portainer’s RBAC lets you move beyond the “all‑or‑nothing” model and give teams only the capabilities they need. By creating custom roles, assigning them to teams, and verifying the permissions, you can harden your Docker environment without sacrificing flexibility. Remember that the union of roles and token caching can introduce surprises, so rigorous testing and documentation are key to a secure setup.