Team Management

New as of 1.2

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

Usage

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.

How does it work

Dokku Pro's team system is made of the following objects:

Teams: Teams are groups of users that are granted permissions to perform commands against apps and services.
Admins: A special team of users that have full access to the entire Dokku system.
Owners: A team can have one or more owners. Owners can add and remove other owners from teams, as well as adminster team membership. Owners do not have access to commands, apps, or services a member would, but they can grant themselves membership in their own teams in order to do so.
Members: Team members have access to commands against apps and services granted by teams.
Commands: Almost all dokku commands can be added or removed from teams, and combining them with apps and services allows users to execute actions in the system.
Apps: Dokku apps can be added or removed from teams, and are used in combination with the commands assigned to teams in order to limit actions taken in the system.
Services: Dokku services can be added or removed from teams, and are used in combination with the commands assigned to teams in order to limit actions taken in the system. All official datastore plugins are supported as services by Dokku Pro.

To show how the system might work, here are a few hypothetical teams:

Team Name: "elevated-access"
- Owners: camila
- Members: jose, michael
- Commands: *
- Apps: *
- Services: *
Team Name: "restricted-users"
- Owners: camila
- Members: eli, danielle
- Commands: git-*, postgres:create, apps:list
- Apps: node-js-app
- Services:
Team Name: "fancy-users"
- Owners: camila
- Members: eli
- Commands: git-*, apps:*
- Apps: ruby-app
- Services:

With the above setup, the following holds true:

Both the jose and michael users can perform almost every action¹ in the system.
The users eli and danielle can perform git-* operations for the node-js-app app - necessary for deployments - as well as create postgres databases and list the node-js-app.
The eli user will additionally see the ruby-app in their output, and can also perform git actions as well as any action in the apps: command-space for the ruby-app. apps: commands that do not require app access - such as app creation via apps:create - will also be available to the eli user.
Finally, if the users jose, michael, and eli create apps - as allowed by their list of allowed commands - they become owners of those apps and can perform all app-specific commands against those apps.

Team permissions restrict commands to apps and services, ensuring that users do not escalate permissions to things they shouldn't by being added to groups that have access to non-overlapping resources with a different set of available commands.

Installing the teams plugin

Before usage, the teams plugin must be installed via the following commands:

# make the plugin available for dokku
dokku-pro teams:install

# enable the plugin in dokku
dokku plugin:enable teams

# enable integration with dokku
dokku teams:enable

Warning

As of Dokku Pro 1.2.x, there is a bug in creating cache directories used by the teams plugin. This can be worked around by running mkdir -p /var/lib/dokku/data/teams && chown dokku:dokku /var/lib/dokku/data/teams as the root user on your host.

While installing the plugin and enabling it in Dokku exposes cli commands for usage with Dokku, the teams:enable command must also be triggered in order to:

setup custom triggers that add/remove teams when apps or services are created
integrate with the authentication system in Dokku and official Dokku plugins
setup the initial dokku@admin team
create app-specific teams (without any initial users or owners) for each existing app

Note

The "doku@admin" team is a special team that grants access to all commands for all apps and services. When teams:enable is triggered for the first time, all existing users - as specified by the ssh-keys plugin - will be migrated into the dokku@admin team if the team does not exist. Users added via the initial web ui will also be added to the dokku@admin group. Permissions for the dokku@admin team cannot be changed.

Checking the currently logged in user

Note

Users will always be able to check who they are via the teams:whoami command.

The teams:whoami command can be used to get information about the current user. This will include the user's name as well as all teams they are currently associated with.

dokku teams:whoami

=====> root user information
       User app membership:
       User app ownership:
       User is global admin:          true
       User membership:               elevated-access
       User ownership:                elevated-access
       User service membership:
       User service ownership:
       Username:                      root

A single field can be shown using the corresponding flag:

# show only the username
dokku teams:whoami --username

# show only the user membership, space-delimited
dokku teams:whoami --user-membership

Finally, the output can be shown in json. Note that the membership and ownership values will be a single string, space-delimited, rather than an array.

dokku teams:whoami --format json

{"user-membership":"elevated-access", "user-ownership":"elevated-access","username":"root", ...}

Checking a specific user

Note

This command can only be performed if the specified user is the current user or by a global admin.

The teams:whois command can be used to get information about a given user. This will include the user's name as well as all teams they are currently associated with.

dokku teams:whois root

=====> root user information
       User app membership:
       User app ownership:
       User is global admin:          true
       User membership:               elevated-access
       User ownership:                elevated-access
       User service membership:
       User service ownership:
       Username:                      root

Users that do not exist will not error, but their permissions will also be empty.

A single field can be shown using the corresponding flag:

# show only the username
dokku teams:whois root --username

# show only the user membership, space-delimited
dokku teams:whois root --user-membership

Finally, the output can be shown in json. Note that the membership and ownership values will be a single string, space-delimited, rather than an array.

dokku teams:whois root --format json

{"user-membership":"elevated-access", "user-ownership":"elevated-access","username":"root", ...}

Listing teams

Teams can be listed using the teams:list command. This will only include teams the currently logged in user is has access to. For non-owners, this will include only those teams they are part of.

dokku teams:list

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

Logged in admins will see all teams that are available on the server, whether or not they are part of the team.

Creating teams

Note: There are a few special team types:

dokku@admin: Global admin users

dokku@app--${APP}: Managed automatically on a per-app basis.

dokku@service--${SERVICE_TYPE}-${SERVICE}: Managed automatically on a per-service basis.

Custom team names must therefore not include the prefix dokku@.

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

dokku teams:create elevated-access

Creating elevated-access

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

Destroying teams

A team can be destroyed by either an admin or a team owner via the teams:destroy command.

dokku teams: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

Attempting to destroy a team that does not exist or where the current user does not have access to that team will result in an error.

Team Management

Adding owners to a team

Admins and team owners can administrate permissions and membership for a given team. To add new owners, use the teams:owners-add command.

dokku teams:owners-add elevated-access other-user

Removing owners from a team

Admins and team owners can remove owners via the teams:owners-remove command.

dokku teams:owners-remove elevated-access other-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 teams:member-add command will allow that user to access anything allowed to that team.

dokku teams:member-add elevated-access jose

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 teams:user-remove command will remove access to anything not covered by other team permissions

dokku teams:member-remove elevated-access jose

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.

Admin Only commands

For security reasons, the following commands may only be performed by an admin. Changes to this list is subject to updates as Dokku and Dokku Pro change over time.

domains:add-global
domains:clear-global
domains:remove-global
domains:set-global
events
events:list
events:off
events:on
git:allow-host
git:auth
logs:vector-start
logs:vector-stop
network:create
network:destroy
network:exists
network:info
network:list
network:rebuildall
shell
trace:on

Additionally, any command invocation with the --global flag will only be executable by an admin.

Allowing access to specific commands

Note

Only admins can add commands to a team.

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

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

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.

# the `*` character must be single-quoted
dokku teams:commands-add elevated-users '*'

dokku teams: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 teams:commands-remove command.

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

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

dokku teams: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

Note

Only admins can add apps to a team.

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

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

Non-existent apps can be specified for the teams:app-add command. This allows the ability to pre-configure permissions for teams prior to the initial setup of an app. As a result, app permissions are not removed from teams when an app is deleted. Permissions do, however, persist through clones and renames.

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.

# the `*` character must be single-quoted
dokku teams:app-add elevated-access '*'

Removing access to specific apps

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

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

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

# the `*` character must be single-quoted
dokku teams: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

Note

Only admins can add services to a team.

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

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

Non-existent services can be specified for the teams:service-add command. This allows the ability to pre-configure permissions for teams prior to the initial setup of a service. As a result, service permissions are not removed from teams when a service is deleted.

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.

# the `*` character must be single-quoted
dokku teams: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.

# the `*` character must be single-quoted
dokku teams:service-add elevated-access '*'

Removing access to a service

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

dokku teams: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.

# the `*` character must be single-quoted
dokku teams:service-remove elevated-access postgres '*'

# the `*` character must be single-quoted
dokku teams:service-remove elevated-access '*'

Displaying reports for a team

Global admins can get a report about a specific team using the teams:team-report command:

dokku teams:team-report dokku@admin

=====> dokku@admin team information
       Team apps:
       Team commands:
       Team is internal:              true
       Team is internal app team:     false
       Team is internal service team: false
       Team members:
       Team name:                     dokku@admin
       Team owners:                   admin1 default
       Team services:

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

dokku teams:team-report dokku@admin --team-members

Integrating custom plugins

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)

As denoted in the Admin Only commands section, some commands require global administrative access in order to be performed by users. ↩