A document scoping out how team management might work in Dokku. This would likely replace the need for the community-managed dokku-acl plugin.

team-management.md

Team Access Control

New as of ???

team:admin-add <team> [<user> ...]                     # add a team admin
team:admin-remove <team> [<user> ...]                  # remove a team admin
team:app-add <team> [<app> ...]                        # add an app to a team
team:app-remove <team> [<app> ...]                     # remove an app from a team
team:command-add <team> [<command> ...]                # allow a team to access access specific command(s)
team:command-remove <team> [<command> ...]             # remove team access to specific command(s)
team:create <team>                                     # create a team
team:destroy <team>                                    # destroy a team
team:leave <team>                                      # removes the current user from a team
team:list                                              # list all teams
team:access-report <team>                              # display a report about a team
team:service-add <team> [<service-type> <service>]     # add a service to a team
team:service-remove <team> [<service-type> <service>]  # remove a service from a team
team:user-add <team> [<user> ...]                      # add a user to a team
team:user-remove <team> [<user> ...]                   # remove a user from a team
team:whoami                                            # outputs current user

Plugin Changes

A plugin that wishes to implement the team system can trigger any of the following plugin triggers:

• plugn trigger user-auth SSH_USER SSH_NAME COMMAND: Exits with an error message if the user does not have access to the command. This is used for commands that do not interact with a specific app or service.
• plugn trigger user-auth-app SSH_USER SSH_NAME APP: Exits with an opaque error message if the user does not have access to the app.
• plugn trigger user-auth-service SSH_USER SSH_NAME SERVICE_TYPE SERVICE_NAME: Exits with an opaque error message if the user does not have access to the service.

Each plugin will need to implement these triggers before any logic is executed. Plugins should avoid calling the dokku binary directly, as there is no guarantee that a command will be available to a user, and thus commands that mutate state may partially fail.

The following triggers are already implemented in Dokku core:

• user-auth: Implemented within the dokku binary itself.
• user-auth-app: Implemented by any plugin that calls common.DokkuApps() (golang) or dokku_apps (shell)

Usage

Note: The "admin" team is a special team that grants access to all commands for all apps and services. On upgrade, all existing users will be migrated into the admin team if the team does not exist. Users added via the initial web ui will also be added to the admin group. Permissions for the admin team cannot be changed.

The team plugin can be used to control user access to specific commands on apps and services. While the core Dokku project has native support for the team plugin, not all community plugins do, and those will need to be updated in order to take advantage of the team system. Please read the plugin development documentation for more information.

The team plugin can also be disabled safely if it is not desired.

Listing teams

Teams can be listed using the team:list command. This will only include teams the currently logged in user has access to.

dokku team:list

=====> Teams
admin
elevated-access
restricted-users

Creating teams

Note: There is a special team created for each app called dokku@${APP}. Team names must therefore not include the prefix dokku@.

A team can be created by user in the admin group via the team:create command.

dokku team:create elevated-access

Creating elevated-access

The user that created the team will be set as the team's admin.

Destroying teams

A team can be created by user in the admin group via the team:destroy command.

dokku team:destroy elevated-access

 !     WARNING: Potentially Destructive Action
 !     This command will destroy the team elevated-access.
 !     To proceed, type "elevated-access"

> elevated-access
Destroying elevated-access

Team Management

Adding admins to a team

Team admins can administrate permissions and membership for a given team. To add new admins, use the team:admins-add command.

dokku team:admins-add elevated-access other-user

Multiple users can be added at one time:

dokku team:admins-add elevated-access other-user yet-another-user

Removing admins from a team

To add remove admins, use the team:admins-remove command.

dokku team:admins-remove elevated-access other-user

Multiple users can be removed at one time:

dokku team:admins-remove elevated-access other-user yet-another-user

Teams must have at least one admin. Attempting to remove all admins will result in an error.

Adding a user to a team

Adding a user to a team via the team:user-add command will allow that user to access anything allowed to that team.

dokku team:user-add elevated-access ben

Multiple users can be added to a team at once.

dokku team:user-add elevated-access ben chelsea

Users can be a part of multiple teams, allowing overlapping permissions to enhance the access a particular user has.

Removing a user from a team

Removing a user from a team via the team:user-remove command will remove access to anything not covered by other team permissions

dokku team:user-remove elevated-access ben

Multiple users can be removed from a team at once.

dokku team:user-remove elevated-access ben chelsea

Leaving a team

If the currently logged in user longer wishes to be a part of a team, they can leave using the team:leave command.

dokku team:leave elevated-access

Note that this will not remove the current user as an admin of said team, only as a member.

Command Management

Commands must be whitelisted before a team can run the command. Attempting to execute a command that is not whitelisted will result in an error.

Allowing access to specific commands

Command access can be granted to teams by utilizing the team:commands-add command.

dokku team:commands-add restricted-users postgres:create

Multiple commands can be added at once:

dokku team:commands-add restricted-users postgres:create postgres:destroy

Commands can also be globbed via the * operator. If specified, the entry is taken as a POSIX regex for command matching. This can be used to whitelist all commands or even a subset for a given plugin.

dokku team:commands-add elevated-users '*'

dokku team:commands-add restricted-users 'git*'

If a team does not have commands added, then members of the team will not be allowed to perform any commands on an app or service, regardless of other permissions.

Removing access to specific commands

If a command was previously added to a team, it can be removed via the team:commands-remove command.

dokku team:commands-remove restricted-users postgres:create

Multiple commands can be removed at once:

dokku team:commands-remove restricted-users postgres:create postgres:destroy

Commands are taken as a literal string when matching against any commands currently associated with a team.

dokku team:commands-remove restricted-users 'git*'

App Access

By default, teams do not have access to specific apps. Any command that acts upon an app will not be executable, and will throw an opaque error - meaning, it will not indicate if the app exists or not - if the app has not been added to a specific team.

Allowing access to specific apps

Apps can be added to specific teams via the team:app-add command.

dokku team:app-add elevated-access node-js-app

Multiple apps can be added to a team at once.

dokku team:app-add elevated-access node-js-app io-js-app

Finally, the special * operator can be used to add access to all apps. This is not treated as a regex, and will override any other apps currently attached to a team.

dokku team:app-add elevated-access '*'

Removing access to specific apps

Apps can be removed from specific teams via the team:app-remove command.

dokku team:app-remove elevated-access node-js-app

Multiple apps can be removed to a team at once.

dokku team:app-remove elevated-access node-js-app io-js-app

Finally, the special * operator can also be removed from a given team.

dokku team:app-remove elevated-access '*'

Service Access

Service plugins can also take advantage of the team system. Services do not need to be whitelisted in Dokku core, and simply need to use the appropriate service "namespace" for access control. See the plugin development documentation for more details.

If the service plugin supports the team system and a user does not have access to the service, an opaque error message - meaning, it will not indiciate if the service exists or not - will be returned.

Allowing access to a service

A service can be added to a team via the team:service-add command. This takes a "service-type" and the name of a service.

dokku team:service-add elevated-access postgres test-db

All services within a service-type can be allowed access via the * operator. This is not treated as a regex, and thus cannot be combined with other characters. Note that adding the * operator to a team will override any other services of that service type currently attached to a team.

dokku team:service-add elevated-access postgres '*'

Finally, all services for all service types can be whitelisted by specifying only a * operator for the service-type argument. This is not treated as a regex, and thus cannot be combined with other characters. Note that adding the * operator to a team will override any other service settings associated with a team.

dokku team:service-add elevated-access '*'

Removing access to a service

A service can be added to a team via the team:service-remove command. This takes a "service-type" and the name of a service.

dokku team:service-remove elevated-access postgres test-db

The * operator can also be removed from a team in the same way it was added to the team.

dokku team:service-remove elevated-access postgres '*'

dokku team:service-remove elevated-access '*'

Displaying reports for an app

You can get a report about teams using the team:report command:

dokku team:access-report

=====> admin team access report
       admins:              admin
       members:             admin,dokku
       commands:            *
       apps:                *
       services:            *
=====> elevated-access team access report
       admins:              admin
       members:             ben,chelsea
       commands:            *
       apps:                *
       services:            *
=====> restricted-users team access report
       admins:              admin
       members:             john,rob
       commands:            git*,postgres:create,postgres:link,postgres:destroy
       apps:                node-js-app
       services:

You can run the command for a specific app also.

dokku apps:access-report team elevated-access

=====> elevated-access team access report
       admins:              admin
       members:             ben,chelsea
       commands:            *
       apps:                *
       services:            *

You can pass flags which will output only the value of the specific information you want. For example:

dokku apps:access-report elevated-access --members