Securing a Shared Docker Host with Portainer RBAC: A Practical Guide

Why RBAC Matters

In a multi‑user Docker environment, the default Docker daemon grants every authenticated user full control over containers, networks, and images. A single accidental command can stop a critical service, delete an image, or expose sensitive data. Portainer’s Role‑Based Access Control (RBAC) lets you slice that power into granular, auditable permissions. By assigning users to teams and scoping those teams to specific endpoints or global actions, you can keep developers productive while protecting production workloads.

Setting Up RBAC in Portainer

RBAC is available in Portainer Community Edition (CE) 2.0 and later. Before you start, verify your version:

curl -s http:///api/version | jq .Version

On the UI, the Teams and Roles tabs appear under Settings. The process involves four steps:

1. Enable authentication – Portainer can integrate with LDAP, OAuth, or its own user database. For this guide we’ll use the built‑in user store.
2. Create users – Add individual accounts for each person who will use Portainer.
3. Form teams – Group users that share the same responsibilities (e.g., "Developers", "Ops").
4. Assign role scopes – Link each team to a role (Admin, Read, etc.) and specify the endpoints or global scope they apply to.

Defining Role Scopes

Roles are pre‑defined in Portainer: Admin, Read, Endpoint Admin, etc. When you create a role assignment, you choose the scope:

Scope Type	What it Controls
Global	All endpoints and global actions (e.g., user management)
Endpoint	All resources on a specific Docker endpoint
Environment	All endpoints grouped under a single environment (e.g., "Production")

Worked Example: Two Developers, Two Endpoints

Scenario: You have two Docker endpoints – dev-host for staging and prod-host for production. Two developers, Alice and Bob, need read access on dev-host but only admin rights on prod-host for a limited set of containers.

1. Create Users

Via UI:

• Navigate to Users → Add User.
• Enter alice, set a password, and repeat for bob.

Or via API (replace ADMIN_TOKEN with a token that has admin rights):

curl -X POST http:///api/users -H "Authorization: Bearer ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"username":"alice","password":"Password123!"}'

2. Create a Team

Team: Developers. In the UI, go to Settings → Teams → Add Team. Or via API:

curl -X POST http:///api/teams -H "Authorization: Bearer ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"name":"Developers"}'

3. Add Users to the Team

UI: Settings → Teams → Developers → Add members. API:

curl -X POST http:///api/teams/1/members -H "Authorization: Bearer ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"userId":1}'

Replace 1 with the actual team ID and userId with the user IDs for Alice and Bob.

4. Assign Role Scopes

We want the team to have Read on dev-host (endpoint ID 2) and Admin on prod-host (endpoint ID 3). In the UI, go to Settings → Roles, click Add Role, and create two assignments:

• Role: Read, Scope: Endpoint 2, Teams: Developers
• Role: Admin, Scope: Endpoint 3, Teams: Developers

API example for the first assignment:

curl -X POST http:///api/role/scope -H "Authorization: Bearer ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"role":"Read","endpointId":2,"teamIds":[1]}'

Repeat for the second assignment with role":"Admin" and endpointId":3.

Verification

Log in as Alice. You should see only dev-host in the endpoint list and be unable to start or stop containers. Attempting to do so will yield a 403 Forbidden error. Bob, with the same role scopes, will have admin rights on prod-host and read rights on dev-host. To confirm programmatically, use a non‑admin token:

curl -s -H "Authorization: Bearer NON_ADMIN_TOKEN" http:///api/endpoints

The JSON response should list only the endpoints Alice or Bob are permitted to see.

Trade‑offs & Limitations

RBAC adds a layer of security but also complexity:

• Administrative Overhead – Every new user or endpoint requires explicit role assignment. Mistakes can lock out legitimate users or, conversely, expose sensitive endpoints.
• Scoping Granularity – Portainer’s scopes are endpoint‑based; you cannot limit a user to a single container or network without custom scripting.
• Version Dependency – RBAC is CE 2.0+. Older installations lack the feature, forcing you to upgrade or use external tools.
• Auditability – While you can view role assignments, detailed audit logs of who performed what action are limited in CE; consider the Enterprise edition for full auditing.

Next Steps

1. Document your RBAC policy: list users, teams, roles, and endpoint IDs. Keep this in version control.

2. Test with a non‑privileged account before rolling out to production. Verify that denied actions return proper errors.

3. Automate role creation via API scripts or IaC tools (Terraform provider for Portainer) to reduce manual errors.

4. If you need finer granularity, explore Portainer Enterprise or integrate with an external identity provider that supports attribute‑based access control (ABAC).

By following this pattern, you can keep your Docker hosts safe without sacrificing developer agility.