diff --git a/access-ucp/cli-based-access.md b/access-ucp/cli-based-access.md index f0651d5ec1..9f41be717d 100644 --- a/access-ucp/cli-based-access.md +++ b/access-ucp/cli-based-access.md @@ -19,7 +19,7 @@ For this reason, when running docker commands on a UCP node, you need to authenticate your request using client certificates. When trying to run docker commands without a valid certificate, you get an authentication error: -```bash +```markdown $ docker ps An error occurred trying to connect: Get https://ucp:443/v1.22/containers/json: x509: certificate signed by unknown authority (possibly because of "crypto/rsa: verification error" when trying to verify candidate authority certificate "UCP Client Root CA") @@ -64,7 +64,7 @@ certificates as part of the request to the Docker Engine. You can now use the `docker info` command to see if the certificates are being sent to the Docker Engine. -```bash +```markdown $ docker info Containers: 11 diff --git a/images/account_details.png b/images/account_details.png deleted file mode 100644 index 775384f538..0000000000 Binary files a/images/account_details.png and /dev/null differ diff --git a/images/add_permission.png b/images/add_permission.png deleted file mode 100644 index 07cb6920c6..0000000000 Binary files a/images/add_permission.png and /dev/null differ diff --git a/images/create-and-manage-teams-1.png b/images/create-and-manage-teams-1.png new file mode 100644 index 0000000000..2f0e49f9ad Binary files /dev/null and b/images/create-and-manage-teams-1.png differ diff --git a/images/create-and-manage-teams-2.png b/images/create-and-manage-teams-2.png new file mode 100644 index 0000000000..6038e42ac4 Binary files /dev/null and b/images/create-and-manage-teams-2.png differ diff --git a/images/create-and-manage-teams-3.png b/images/create-and-manage-teams-3.png new file mode 100644 index 0000000000..9dd0749d47 Binary files /dev/null and b/images/create-and-manage-teams-3.png differ diff --git a/images/create-and-manage-teams-4.png b/images/create-and-manage-teams-4.png new file mode 100644 index 0000000000..3072aa964d Binary files /dev/null and b/images/create-and-manage-teams-4.png differ diff --git a/images/create-users-1.png b/images/create-users-1.png new file mode 100644 index 0000000000..72a69f43eb Binary files /dev/null and b/images/create-users-1.png differ diff --git a/images/create-users-2.png b/images/create-users-2.png new file mode 100644 index 0000000000..047b481144 Binary files /dev/null and b/images/create-users-2.png differ diff --git a/images/create_user.png b/images/create_user.png deleted file mode 100644 index 82aa50a5fb..0000000000 Binary files a/images/create_user.png and /dev/null differ diff --git a/images/ldap_access.png b/images/ldap_access.png deleted file mode 100644 index f8956badc7..0000000000 Binary files a/images/ldap_access.png and /dev/null differ diff --git a/images/match_list.png b/images/match_list.png deleted file mode 100644 index 32b50bb168..0000000000 Binary files a/images/match_list.png and /dev/null differ diff --git a/images/save_team.png b/images/save_team.png deleted file mode 100644 index 567368d348..0000000000 Binary files a/images/save_team.png and /dev/null differ diff --git a/images/secure-your-infrastructure-1.svg b/images/secure-your-infrastructure-1.svg new file mode 100644 index 0000000000..bb5f6a845a --- /dev/null +++ b/images/secure-your-infrastructure-1.svg @@ -0,0 +1,94 @@ + + + + secure-your-infrastructure-1 + Created with Sketch. + + + + + + + + + + + + + + + + + + com.docker.ucp.access.label = billing + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + com.docker.ucp.access.label = crm + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/images/secure-your-infrastructure-2.svg b/images/secure-your-infrastructure-2.svg new file mode 100644 index 0000000000..bbba79e98d --- /dev/null +++ b/images/secure-your-infrastructure-2.svg @@ -0,0 +1,147 @@ + + + + secure-your-infrastructure-2 + Created with Sketch. + + + + + + + + + + + + + + + + + + + + + + ops team + + + + + billing team + + + + + + crm team + + + + + + + + + + com.docker.ucp.access.label = billing + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + com.docker.ucp.access.label = crm + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/index.md b/index.md index 425fa1efa2..805ddd29c8 100644 --- a/index.md +++ b/index.md @@ -25,6 +25,6 @@ The UCP documentation includes the following topics: * [Configuration](configuration/multi-host-networking.md) * [Monitor and troubleshoot](monitor/monitor-ucp.md) * [High availability](high-availability/set-up-high-availability.md) -* [User management](user-management/manage-users.md) +* [User management](user-management/authentication-and-authorization.md) * [Applications](applications/deploy-app-ui.md) * [Release notes](release_notes.md) diff --git a/user-management/authentication-and-authorization.md b/user-management/authentication-and-authorization.md new file mode 100644 index 0000000000..a755cc84cc --- /dev/null +++ b/user-management/authentication-and-authorization.md @@ -0,0 +1,69 @@ + + +# Authentication and authorization + +With Docker Universal Control Plane you get to control who can create and edit +resources like images, networks, volumes, and containers in your cluster. + +By default no one can make changes to your cluster. You can then grant and +manage permissions to enforce fine-grained access control. For that: + +* Start by creating a user and assigning them with a default permission. + + Default permissions specify the permission a user has to create and edit + resources. You can choose from four permission levels that range from + no access to full control over the resources. + + When a user only has a default permission assigned, only them and admin + users can see the containers they deploy in the cluster. + +* Extend the user permissions by adding users to a team. + + You can extend the user's default permissions by granting them fine-grain + permissions over containers. You do this by adding the user to a team. + A team defines the permissions users have for containers that have the label + `com.docker.ucp.access.label` applied to them. + +## Users and teams + +When users create a container with no label, that container is only visible to +them and administrator users. +For a team of users to be able to see and edit the same container, that +container needs to have the `com.docker.ucp.access.label` label applied. + +![](../images/secure-your-infrastructure-1.svg) + +In the example above, we have two sets of containers. One set has all containers +labeled with `com.docker.ucp.access.label=crm`, the other has all containers +labeled with `com.docker.ucp.access.label=billing`. + +You can now create different teams, and tune the permission level each +team has for those containers. + +![](../images/secure-your-infrastructure-2.svg) + +As an example you can create three different teams: + +* The team that's developing the CRM app has access to create and edit +containers with the label `com.docker.ucp.access.label=crm`. +* The team that's developing the Billing app, has access to create and edit +containers with the label `com.docker.ucp.access.label=billing`. +* And of course, the operations team has access to create and edit containers +with any of the two labels. + +## Where to go next + +* [Create and manage users](create-and-manage-users.md) +* [Create and manage teams](create-and-manage-teams.md) diff --git a/user-management/create-and-manage-teams.md b/user-management/create-and-manage-teams.md new file mode 100644 index 0000000000..aaca4135d3 --- /dev/null +++ b/user-management/create-and-manage-teams.md @@ -0,0 +1,73 @@ + + +# Create and manage teams + +You can extend the user's default permissions by granting them fine-grain +permissions over containers. You do this by adding the user to a team. +A team defines the permissions users have for containers that have the label +`com.docker.ucp.access.label` applied to them. + +To create a new team, go to the **UCP web UI**, and navigate to the +**Users & Teams** page. + +![](../images/create-and-manage-teams-1.png) + +Click the **Create** button to create a new team. + +![](../images/create-and-manage-teams-2.png) + +Give a name to the team, and choose if the team is managed by UCP, or +discovered from an LDAP service: + +* Managed: You'll manage the team and manually define the users that are part +of the team. +* Discovered: When integrating with an LDAP service, you can map a team to +an LDAP group. When a user is added to the LDAP group, it is automatically added +to the UCP team. + +## Add users to a team + +If you've created a managed team, you can now add and remove users from the +team. +Navigate to the **Members** tab, and click the **Add User to Team** button. +Then choose the list of users that you want to add to the team. + +![](../images/create-and-manage-teams-3.png) + +If you've created a discovered team, users are automatically added and removed +from the team the next time UCP synchronizes with the LDAP server. + +## Manage team permissions + +To manage the permissions of the team, click the **Permissions** tab. +Here you can specify a list of labels and the permission level users will have +for containers with those labels. + +![](../images/create-and-manage-teams-4.png) + +In the example above, members of the 'Operations' team have permissions to +create and edit containers that have the labels +`com.docker.ucp.access.label=crm` or `com.docker.ucp.access.label=billing`. + +There are four permission levels available: + +| Team permission level | Description | +|:----------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------| +| `No Access` | The user can't view containers with this label. | +| `View Only` | The user can view but can't create containers with this label. | +| `Restricted Control` | The user can view and create containers with this label. The user can't run `docker exec`, or containers that require privileged access to the host. | +| `Full Control` | The user can view and create containers with this label, without any restriction. | + +## Where to go next + +* [UCP permission levels](permission-levels.md) diff --git a/user-management/create-and-manage-users.md b/user-management/create-and-manage-users.md new file mode 100644 index 0000000000..29c646f06f --- /dev/null +++ b/user-management/create-and-manage-users.md @@ -0,0 +1,48 @@ + + +# Create and manage users + +When using the UCP built-in authentication, you need to create users and +assign them with a default permission level so that they can access the +cluster. + +To create a new user, go to the **UCP web UI**, and navigate to the +**Users & Teams** page. + +![](../images/create-users-1.png) + +Click the **Create User** button, and fill-in the user information. + +![](../images/create-users-2.png) + +Check the 'Is a UCP admin' option, if you want to grant permissions for the +user to change cluster configurations. Also, assign the user with a default +permission level. + +Default permissions specify the permission a user has to create and edit +resources in the cluster. There are four permission levels: + +| Default permission level | Description | +|:-------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `No Access` | The user can't view any resource, like volumes, networks, images, or containers. | +| `View Only` | The user can view volumes, networks and images, but can't create any containers. | +| `Restricted Control` | The user can view and edit volumes, networks, and images. They can create containers, but can't see other users containers, run `docker exec`, or run containers that require privileged access to the host. | +| `Full Control` | The user can view and edit volumes, networks, and images, They can create containers without any restriction, but can't see other users containers. | + +[Learn more about the UCP permission levels](permission-levels.md). Finally, +click the **Create User** button, to create the user. + +## Where to go next + +* [Create and manage teams](create-and-manage-teams.md) +* [UCP permission levels](permission-levels.md) diff --git a/user-management/index.md b/user-management/index.md index 2575520dab..6eb4862f2c 100644 --- a/user-management/index.md +++ b/user-management/index.md @@ -14,4 +14,7 @@ weight=70 This section includes the following topics: -* [Manage users](manage-users.md) +* [Authentication and authorization](authentication-and-authorization.md) +* [Create and manage users](create-and-manage-users.md) +* [Create and manage teams](create-and-manage-teams.md) +* [Permission levels](permission-levels.md) diff --git a/user-management/manage-users.md b/user-management/manage-users.md deleted file mode 100644 index 751f91ff5c..0000000000 --- a/user-management/manage-users.md +++ /dev/null @@ -1,195 +0,0 @@ - - -# Manage and authorize UCP users - -This page explains how to manage users and authorize users within the UCP. -Managing users requires that you understand how to create users and combine them -into teams. Authorizing users requires that you understand how to apply roles -and create permissions within UCP. On this page, you learn to do both. You also -learn about the features and systems of UCP that support user management and -authorization. - -## Understand user authorization - -Users in UCP have two levels of authorization. They may have authorization to -manage UCP and they have authorization to access the Docker objects and -resources that UCP manages. You can authorize user to UCP manage UCP by enabling -the **IS A UCP ADMIN** in a user's **Account Details**. - -![Account Details](../images/account_details.png) - -Users that are UCP administrators have authorization to fully access all Docker -objects in your production system. This authorization is the granted both -whether access is through the GUI or the command line. - -Users within UCP have *permissions* assigned to them by default. This authorizes -what a user can do to Docker resource such as volumes, networks, images, and -containers. UCP allows you define default permissions for a user when you create -that user. In this release of UCP, more granular access to just one object, the -container object, is possible through the use of teams. - -The possible permissions are: - -| Type | Description | -|:-------------------|:----------------------------------------------------------------------------------------------------------| -| No Access | Cannot access any resources. | -| View Only | Can view resources. This role grants the ability to view a container but not restart, kill, or remove it. | -| Restricted Control | Can edit resources. This role grants the ability to create, restart, kill, and remove containers. | -| Full Control | Can do anything possible to resources. This role grants full rights to all actions on containers. | - -For containers only, you can extend the default access permissions with more -granular, role-based permissions. Docker Engine allows container creators to -apply arbitrary, descriptive strings called *labels* to a container. If you -define labels for use by container creators, you can leverage these -labels with UCP teams to configure role-based access to containers. - -The general process for configuring role-based access to containers is: - -* Identify one or more labels to apply to containers. -* Create one or more teams. -* Define a permission by combining a pre-identified label with a role value. -* Add users to the team. -* Ensure container creators use the pre-defined labels. - -Once you configure it, users have this access through UCP and through their -interactions on the command line via the client bundle. - ->**Note**: Users can by-pass all UCP authorization controls by logging into a UCP node via -standard SSH and addressing the Swarm cluster directly. For this reason, You -must be sure to secure network access to a cluster's nodes. - -## Understand restricted control - -Containers run as services on your network. Without proper knowledge, users can -launch a container with an insecure configuration. To reduce the risk of this -happening, the **Restricted Control** limits the options users can use when -launching containers. - -A user with **Restricted Control** can create, restart, kill, or remove a -container. These users are can not `docker exec` into a container. Additionally, -**Restricted Control** prevents users from running a container with these -options: - -| Prevented Option | Description | -|:---------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--privileged` | A “privileged” container is given access to all devices. | -| `--cap-add` | The ability to expand the kernel-level capabilities a user or process has in a container. | -| host mounted volumes | Mount a volume from the host where the container is running. | -| `--ipc` | The ability to set a container's IPC (POSIX/SysV IPC) namespace mode. This provides separation of named shared memory segments, semaphores and message queues. mode | -| `--pid` | PID namespace provides separation of processes. The PID Namespace removes the view of the system processes, and allows process ids to be reused including pid 1. | - -Users that attempt to create containers with these options receive an error message. - -## Creating users on UCP - -UCP offers two ways to create user accounts. You can manually create accounts -one-at-a-time or you can import users as a group into a team via UCP's LDAP -integration. To create an individual user, do the following: - -1. Click **Users & Teams** from the UCP dashboard. - -2. Click **Create User**. - - ![Create users](../images/create_user.png) - -3. Complete the fields for the user. - - The **DEFAULT PERMISSIONS** define the default access role a user has to all - the Docker objects and resources in the system. You can refine and extend access - on containers by adding a user to a **Team** later. - -4. Click **Save** to create the user. - -## Creating a team - -UCP offers two ways to create teams. You can manually create teams one-at-a-time -or you can populate a team by importing multiple users via an LDAP or Active -Directory connection. The teams you populate one-at-a-time are **Managed** teams -meaning they contain only users managed by UCP. - -Teams you create via an LDAP or Active Directory connection are known as -**Discovered** teams. To use LDAP or Active Directory, you must have already -configured the AUTH settings in UCP. When you create a **Discovered** team, the -system imports the members and applies the default authorization set in UCP's -**AUTH** settings. The value appears in the **DEFAULT PERMISSIONS FOR NEW -DISCOVERED ACCOUNTS** field. - -![LDAP config](../images/ldap_access.png) - -To create **Discovered** team with LDAP or Active Directory, do the following: - -1. Login into UCP as a user with UCP ADMIN authorization. - -2. Click **Users & Teams** from the UCP dashboard. - -3. Click **Create a Team**. - - The system displays the **Create Team** page. At this point, you decide what - **TYPE** of team you want to create. You can't change or convert the team - **TYPE** later. - -4. Choose **Discovered** from the **TYPE** dropdown. - - The system displays options for the **Discovered** team. Completing this - dialog requires that you have a basic understanding of LDAP or access to - someone who does. - -5. Enter a **Name** for the team. - -5. Enter an **LDAP DN** value. - - This value is a distinguished name (DN) identify the group you want to - import. A distinguished name describes a position in an LDAP - directory information tree (DIT). - -6. Enter a **LDAP MEMBER ATTRIBUTE** value. - - This identifies the attribute you should use to retrieve the values. - - ![Create users](../images/save_team.png) - -7. Save the team. - - After a moment, the system creates a team with the users matching - your team specification. - - ![Match users](../images/match_list.png) - -## Add permissions to a team - -You can use a team to simply organize **Managed** users or to import/organize -**Discovered** users. Optionally, you can also add permissions to a the team. -Permissions are a combination of labels and roles you can apply to a team. -Permissions authorize users to act on containers with the matching labels -according to roles you define. - ->**Note**: For correct application, you must ensure the labels exist on -containers deployed ins UCP. - -To add **Permissions** to a team, do the following: - -1. Select the team. - -2. Choose **PERMISSIONS**. - -3. Click **Add Label**. - - ![Add permission](../images/add_permission.png) - -4. Click **Save**. - -## Related information - -To learn how to apply labels, see the how to [Apply custom -metadata](/engine/userguide/labels-custom-metadata.md) -Engine documentation. diff --git a/user-management/permission-levels.md b/user-management/permission-levels.md new file mode 100644 index 0000000000..dabf2f5ec0 --- /dev/null +++ b/user-management/permission-levels.md @@ -0,0 +1,64 @@ + + +# Permission levels + +Docker Universal Control Plane has two types of users: administrators and +regular users. Administrators can make changes to the UCP cluster, while +regular users have permissions that range from no access to full control over +volumes, networks, images, and containers. + +## Administrator users + +In Docker UCP, only users with administrator privileges can make changes to +cluster settings. This includes: + +* Managing user and team permissions, +* Managing cluster configurations like adding and removing nodes to the cluster. + +## Default permission levels + +Regular users can't change cluster settings, and they are assigned with a +default permission level. + +The default permission level specify the permission a user has to access or +edit resources. You can choose from four permission levels that range from no +access to full control over the resources. + +| Default permission level | Description | +|:-------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `No Access` | The user can't view any resource, like volumes, networks, images, or containers. | +| `View Only` | The user can view volumes, networks and images, but can't create any containers. | +| `Restricted Control` | The user can view and edit volumes, networks, and images. They can create containers, but can't see other users containers, run `docker exec`, or run containers that require privileged access to the host. | +| `Full Control` | The user can view and edit volumes, networks, and images, They can create containers without any restriction, but can't see other users containers. | + +When a user only has a default permission assigned, only them and admin +users can see the containers they deploy in the cluster. + +## Team permission levels + +Teams allow you to define fine-grain permissions to containers that have the +label `com.docker.ucp.access.label` applied to them. + +There are four permission levels: + +| Team permission level | Description | +|:----------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------| +| `No Access` | The user can't view containers with this label. | +| `View Only` | The user can view but can't create containers with this label. | +| `Restricted Control` | The user can view and create containers with this label. The user can't run `docker exec`, or containers that require privileged access to the host. | +| `Full Control` | The user can view and create containers with this label, without any restriction. | + +## Where to go next + +* [Create and manage users](create-and-manage-users.md) +* [Create and manage teams](create-and-manage-teams.md)