From ced3bcbcd56ef3e2967ba2fc47d83f28511e57b8 Mon Sep 17 00:00:00 2001 From: Gwendolynne Barr <31074572+gbarr01@users.noreply.github.com> Date: Sun, 19 Nov 2017 22:02:17 -0800 Subject: [PATCH] Update rbac docs (#298) --- _data/toc.yaml | 44 ++-- .../access-control/create-and-manage-teams.md | 130 ----------- .../access-control/create-and-manage-users.md | 65 ------ .../howto-deploy-wordpress-with-rbac.md | 90 ++++++++ deploy/access-control/index.md | 208 ++++++++---------- .../isolate-nodes-between-teams.md | 169 +++++++++++++- ...esources-create-collections-namespaces.md} | 148 ++++++++++++- ...ion-levels.md => usermgmt-create-roles.md} | 84 ++++++- .../usermgmt-create-subjects.md | 131 +++++++++++ ...sions.md => usermgmt-grant-permissions.md} | 9 +- ...d.md => usermgmt-recover-user-password.md} | 4 +- .../access-control/usermgmt-sync-with-ldap.md | 119 ++++++++++ 12 files changed, 855 insertions(+), 346 deletions(-) delete mode 100644 deploy/access-control/create-and-manage-teams.md delete mode 100644 deploy/access-control/create-and-manage-users.md create mode 100644 deploy/access-control/howto-deploy-wordpress-with-rbac.md rename deploy/access-control/{manage-access-with-collections.md => resources-create-collections-namespaces.md} (50%) rename deploy/access-control/{permission-levels.md => usermgmt-create-roles.md} (50%) create mode 100644 deploy/access-control/usermgmt-create-subjects.md rename deploy/access-control/{grant-permissions.md => usermgmt-grant-permissions.md} (90%) rename deploy/access-control/{recover-a-user-password.md => usermgmt-recover-user-password.md} (95%) create mode 100644 deploy/access-control/usermgmt-sync-with-ldap.md diff --git a/_data/toc.yaml b/_data/toc.yaml index 0174ebc5c6..91e246d526 100644 --- a/_data/toc.yaml +++ b/_data/toc.yaml @@ -310,42 +310,42 @@ guides: title: Use the ZFS storage driver - path: /storage/storagedriver/vfs-driver/ title: Use the VFS storage driver - -- sectiontitle: Configure user permissions +- sectiontitle: Authorize user access section: - path: /deploy/access-control/ title: Access control model overview - sectiontitle: User Management section: - - path: /deploy/access-control/create-and-manage-users - title: Create and manage users - - path: /deploy/access-control/create-and-manage-teams - title: Create and manage teams - - path: /deploy/access-control/permission-levels - title: Learn about user permissions - - path: /deploy/access-control/recover-a-user-password + - path: /deploy/access-control/usermgmt-create-subjects.md + title: Create and users and teams + - path: /deploy/access-control/usermgmt-sync-with-ldap.md + title: Synchronize teams with LDAP + - path: /deploy/access-control/usermgmt-create-roles.md + title: Create roles to authorize access + - path: /deploy/access-control/usermgmt-grant-permissions.md + title: Grant access to resources + - path: /deploy/access-control/usermgmt-recover-user-password title: Reset a user password - - path: /deploy/access-control/grant-permissions.md - title: Grant role-based permissions to users and teams - sectiontitle: Shared Resources section: - - path: /deploy/access-control/manage-access-with-collections - title: Manage access to collections - - path: /deploy/access-control/node-access-control + - path: /deploy/access-control/resources-create-collections-namespaces.md + title: Group resources as collections or namespaces + - path: /deploy/access-control/access-control-node.md title: Learn node access controls - path: /deploy/access-control/isolate-nodes-between-teams - title: Isolate swarm nodes to specific teams + title: Isolate Swarm nodes - path: /deploy/access-control/isolate-volumes-between-teams - title: Isolate volumes to specific teams - - path: /deploy/access-control/deploy-view-only-service - title: Deploy a service with view-only access - - sectiontitle: OrcaBank Tutorial + title: Isolate volumes + - sectiontitle: Tutorials section: + - path: /deploy/access-control/howto-deploy-wordpress-with-rbac.md + title: Wordpress and MySQL tutorial + - path: /deploy/access-control/deploy-view-only-service + title: Deploy service with view-only access - path: /deploy/access-control/access-control-design-ee-standard - title: Orcabank tutorial 1 + title: Orcabank tutorial with Docker EE Standard - path: /deploy/access-control/access-control-design-ee-advanced - title: Orcabank tutorial 2 - + title: Orcabank tutorial with Docker EE Advanced - sectiontitle: Deploy your app in production section: - path: /deploy/ diff --git a/deploy/access-control/create-and-manage-teams.md b/deploy/access-control/create-and-manage-teams.md deleted file mode 100644 index 14727dc046..0000000000 --- a/deploy/access-control/create-and-manage-teams.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -title: Create and manage teams -description: Learn how to administer team permissions in Docker Universal Control Plane. -keywords: authorize, authentication, users, teams, groups, sync, UCP, Docker -redirect_from: -- /ucp/ -ui_tabs: -- version: ucp-3.0 - orhigher: true -- version: ucp-2.2 - orlower: true ---- - -{% if include.ui %} - -You can extend the user's default permissions by granting them fine-grained -permissions over resources. You do this by adding the user to a team. - -To create a new team, go to the UCP web UI, and navigate to the -**Organizations** page. - -![](../images/create-and-manage-teams-1.png){: .with-border} - -If you want to put the team in a new organization, click -**Create Organization** and give the new organization a name, like -"engineering". Click **Create** to create it. - -In the list, click the organization where you want to create the new team. -Name the team, give it an optional description, and click **Create** to -create a new team. - -![](../images/create-and-manage-teams-2.png){: .with-border} - -## Add users to a team - -You can now add and remove users from the team. In the current organization's -teams list, click the new team, and in the details pane, click **Add Users**. -Choose the users that you want to add to the team, and when you're done, click -**Add Users**. - -![](../images/create-and-manage-teams-3.png){: .with-border} - -## Enable Sync Team Members - -To sync the team with your organization's LDAP directory, click **Yes**. - -If UCP is configured to sync users with your organization's LDAP directory -server, you have the option to enable syncing the new team's members when -creating a new team or when modifying settings of an existing team. -[Learn how to configure integration with an LDAP directory](../admin/configure/external-auth/index.md). -Enabling this option expands the form with additional fields for configuring -the sync of team members. - -![](../images/create-and-manage-teams-5.png){: .with-border} - -There are two methods for matching group members from an LDAP directory: - -**Match Group Members** - -This option specifies that team members should be synced directly with members -of a group in your organization's LDAP directory. The team's membership will by -synced to match the membership of the group. - -| Field | Description | -|:-----------------------|:------------------------------------------------------------------------------------------------------| -| Group DN | This specifies the distinguished name of the group from which to select users. | -| Group Member Attribute | The value of this group attribute corresponds to the distinguished names of the members of the group. | - -**Match Search Results** - -This option specifies that team members should be synced using a search query -against your organization's LDAP directory. The team's membership will be -synced to match the users in the search results. - -| Field | Description | -| :--------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | -| Search Base DN | The distinguished name of the node in the directory tree where the search should start looking for users. | -| Search Filter | The LDAP search filter used to find users. If you leave this field empty, all existing users in the search scope will be added as members of the team. | -| Search subtree instead of just one level | Whether to perform the LDAP search on a single level of the LDAP tree, or search through the full LDAP tree starting at the Base DN. | - -**Immediately Sync Team Members** - -Select this option to run an LDAP sync operation immediately after saving the -configuration for the team. It may take a moment before the members of the team -are fully synced. - -## Manage team permissions - -Create a grant to manage the team's permissions. -[Learn how to grant permissions to users based on roles](grant-permissions.md). -In this example, you'll create a collection for the "Data Center" team, -where they can deploy services and resources, and you'll create a grant that -gives the team permission to access the collection. - -![](../images/team-grant-diagram.svg){: .with-border} - -1. Navigate to the **Organizations & Teams** page. -2. Select **docker-datacenter**, and click **Create Team**. Name the team - "Data Center", and click **Create**. -3. Navigate to the **Collections** page. -4. Click **Create Collection**, name the collection "Data Center Resources", - and click **Create**. -5. Navigate to the **Grants** page, and click **Create Grant**. -6. Find **Swarm** in the collections list, and click **View Children**. -7. Find **Data Center Resources**, and click **Select Collection**. -8. In the left pane, click **Roles** and in the **Role** dropdown, select - **Restricted Control**. -9. In the left pane, click **Subjects** and select the **Organizations** - subject type. -10. In the **Organization** dropdown, select **docker-datacenter**, and in the - **Teams** dropdown, select **Data Center**. -11. Click **Create** to create the grant. - -![](../images/create-and-manage-teams-4.png){: .with-border} - -In this example, you gave members of the `Data Center` team -`Restricted Control` permissions to create and edit resources in -the `Data Center Resources` collection. - -## Where to go next - -- [UCP permission levels](permission-levels.md) -- [Isolate volumes between two different teams](isolate-volumes-between-teams.md) -- [Isolate swarm nodes between two different teams](isolate-nodes-between-teams.md) - -{% if include.version=="ucp-3.0" %} -{% elsif include.version=="ucp-2.2" %} - -{% endif %} -{% endif %} diff --git a/deploy/access-control/create-and-manage-users.md b/deploy/access-control/create-and-manage-users.md deleted file mode 100644 index fa1e9ad7ed..0000000000 --- a/deploy/access-control/create-and-manage-users.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: Create and manage users -description: Learn how to administer user permissions in Docker Universal Control Plane. -keywords: authorize, authentication, users, teams, UCP, Docker -redirect_from: -- /ucp/ -ui_tabs: -- version: ucp-3.0 - orhigher: true -- version: ucp-2.2 - orlower: true ---- - -{% if include.ui %} -Docker Universal Control Plane provides built-in authentication and also -integrates with LDAP directory services. - -> To enable LDAP and manage users and groups from your organization's directory, -> go to Admin > Admin Settings > Authentication and Authorization. -> [Learn how to integrate with an LDAP directory](../configure/external-auth/index.md). - -{% if include.version=="ucp-3.0" %} -To use UCP built-in authentication, you must manually create users. New users -are assigned a default permission level so that they can access the cluster. -You can optionally grant them UCP administrator permissions. - -To create a new user in the UCP web UI: -1. Navigate to the **Users** page. -2. Click **Create User**. -3. Input username, password, and full name. -4. Click **Create**. -5. [optional] Check "Is a Docker EE Admin". - -> Check `Is a Docker EE Admin` to grant a user permission to change the cluster -> configuration and manage grants, roles, and collections. - -![](../images/ucp_usermgmt_users_create01.png){: .with-border} - -![](../images/ucp_usermgmt_users_create02.png){: .with-border} - -{% elsif include.version=="ucp-2.2" %} -To use UCP built-in authentication, you must manually create users. New users -are assigned a default permission level so that they can access the swarm. -You can optionally grant them UCP administrator permissions. - -To create a new user in the UCP web UI: -1. Navigate to the **Users** page. -2. Click **Create User**. -3. Input username, password, and full name. -4. Click **Create**. -5. [optional] Check "Is a UCP admin?". - -![](../images/create-users-1.png){: .with-border} - -> Check `Is a UCP admin?` to grant a user permission to change the swarm -> configuration and manage grants, roles, and collections. - -![](../images/create-users-2.png){: .with-border} -{% endif %} - -## Where to go next - -* [Create and manage teams](create-and-manage-teams.md) -* [UCP permission levels](permission-levels.md) -{% endif %} diff --git a/deploy/access-control/howto-deploy-wordpress-with-rbac.md b/deploy/access-control/howto-deploy-wordpress-with-rbac.md new file mode 100644 index 0000000000..f98d8fef3d --- /dev/null +++ b/deploy/access-control/howto-deploy-wordpress-with-rbac.md @@ -0,0 +1,90 @@ +--- +title: Deploy simple Wordpress application with RBAC +description: Learn how to deploy a simple application and customize access to resources. +keywords: rbac, authorize, authentication, users, teams, UCP, Docker +redirect_from: +- /ucp/ +ui_tabs: +- version: ucp-3.0 + orhigher: true +- version: ucp-2.2 + orlower: true +--- + +{% if include.ui %} +{% if include.version=="ucp-3.0" %} +{% elsif include.version=="ucp-2.2" %} +{% endif %} + +This tutorial explains how to create a simple application with two services, +Worpress and MySQL, and use role-based access control (RBAC) to authorize access +across the organization. + +## Build the organization + +Acme company wants to start a blog to better communicate with its users. + +``` +Acme Datacenter +├── Dev +│   └── Alex Alutin +└── DBA +   └── Brad Bhatia +``` + +## Deploy Wordpress with MySQL + +``` +version: "3.1" + +services: + db: + image: mysql:5.7 + deploy: + replicas: 1 + labels: + com.docker.ucp.access.label: "/Shared/acme-blog/mysql-collection" + restart_policy: + condition: on-failure + max_attempts: 3 + volumes: + - db_data:/var/lib/mysql + networks: + - wordpress-net + environment: + MYSQL_ROOT_PASSWORD: wordpress + MYSQL_DATABASE: wordpress + MYSQL_USER: wordpress + MYSQL_PASSWORD: wordpress + wordpress: + depends_on: + - db + image: wordpress:latest + deploy: + replicas: 1 + labels: + com.docker.ucp.access.label: "/Shared/acme-blog/wordpress-collection" + restart_policy: + condition: on-failure + max_attempts: 3 + volumes: + - wordpress_data:/var/www/html + networks: + - wordpress-net + ports: + - "8000:80" + environment: + WORDPRESS_DB_HOST: db:3306 + WORDPRESS_DB_PASSWORD: wordpress + +volumes: + db_data: + wordpress_data: + +networks: + wordpress-net: + labels: + com.docker.ucp.access.label: "/Shared/acme-blog" +``` + +{% endif %} diff --git a/deploy/access-control/index.md b/deploy/access-control/index.md index 08b28e0eed..ef879668e5 100644 --- a/deploy/access-control/index.md +++ b/deploy/access-control/index.md @@ -23,29 +23,18 @@ next_steps: --- {% if include.ui %} - -With Docker Universal Control Plane (UCP), you can configure how users access -resources by assigning role-based permissions with grants. - {% if include.version=="ucp-3.0" %} -UCP administrators can control who views, edits, and uses Swarm and Kubernetes -resources. They can grant and manage permissions to enforce fine-grained access -control as needed. +With Docker Universal Control Plane (UCP), you can authorize how users view, +edit, and use cluster resources by granting role-based permissions. -## Grants +To authorize access to cluster resources across your organization, Docker +administrators should take the following high-level steps: -Grants define which users can access what resources. Grants are effectively -Access Control Lists (ACLs), which, when grouped together, can provide -comprehensive access policies for an entire organization. - -A grant is made up of a *subject*, *namespace*, and *role*. - -Administrators are users who create subjects, define namespaces by labelling -resources, define roles by selecting allowable operations, and apply grants to -users and teams. - -> Only an administrator can manage grants, subjects, roles, and resources. +- Add and configure subjects (users and teams) +- Define customer roles (or use defaults) by adding permissions resource types +- Group cluster resources into Swarm collections or Kubernetes namespaces +- Create grants by marrying subject + role + resource ## Subjects @@ -54,63 +43,80 @@ role that defines permitted operations against one or more resources. - **User**: A person authenticated by the authentication backend. Users can belong to one or more teams and one or more organizations. -- **Team**: A group of users that share permissions defined at the team level. - A team exists only as part of an organization, and all of its members - must be members of the organization. Team members share organization - permissions. A team can be in one organization only. +- **Team**: A group of users that share permissions defined at the team level. A + team can be in one organization only. - **Organization**: A group of teams that share a specific set of permissions, defined by the roles of the organization. -## Namespaces - -A namespace is ... +For more, see: +- [Create users and teams in UCP](./usermgmt-create-subjects.md) +- [Synchronize users and teams with LDAP](./usermgmt-sync-teams-with-ldap.md) ## Roles -Roles define what operations can be done by whom against which cluster -resources. A role is a set of permitted operations against a resource that is -assigned to a user or team with a grant. +Roles define what operations can be done by whom. A role is a set of permitted +operations (view, edit, use, etc.) against a *resource type* (such as an image, +container, volume, etc.) that is assigned to a user or team with a grant. For example, the built-in role, **Restricted Control**, includes permission to -view and schedule a node (in a granted namespace) but not update it. +view and schedule a node but not update it. A custom **DBA** role might include +permissions to create, attach, view, and remove volumes. -Most organizations use different roles to assign the right kind of access. A +Most organizations use different roles to fine-tune the approprate access. A given team or user may have different roles provided to them depending on what resource they are accessing. -You can build custom roles to meet your organizational needs or use the -following built-in roles: +For more, see: [Create roles that define user access to resources](./usermgmt-create-roles.md) -- **View Only** - Users can see all cluster resources but not edit or use them. -- **Restricted Control** - Users can view containers and run a shell inside a - container process (with `docker exec`) but not view or edit other resources. -- **Full Control** - Users can perform all operations against granted resources. -- **Scheduler** - Users can view and schedule nodes. +## Resources -[Learn more about roles and permissions](permission-levels.md). +Cluster resources are grouped into Swarm collections or Kubernetes namespaces. + +A collection is a directory that holds Swarm resources. You can define and build +collections in UCP by assinging resources to a collection. Or you can create the +path in UCP and use *labels* in your YAML file to assign application resources to +that path. + +> Swarm resources types that can be placed into a collection include: Containers, +> Networks, Nodes, Services, Secrets, and Volumes. + +A [namespace](https://kubernetes.io/docs/concepts/overview/working-with-objects/namespaces/) +holds Kubernetes resources. + +> Kubernetes resources types that can be placed into a namespace include: Pods, +> Deployments, NetworkPolcies, Nodes, Services, Secrets, and many more. + +For more, see: [Group resources into collections or namespaces](resources-create-collections-namespaces.md). + +## Grants + +A grant is made up of a *subject*, *resource group*, and *role*. + +Grants define which users can access what resources in what way. Grants are +effectively Access Control Lists (ACLs), and when grouped together, can +provide comprehensive access policies for an entire organization. + +Only an administrator can manage grants, subjects, roles, and resources. + +> Administrators are users who create subjects, group resources by moving them +> into directories or namespaces, define roles by selecting allowable operations, +> and apply grants to users and teams. + +For more, see: [Create grants and authorize access to users and teams](usermgmt-grant-permissions.md). {% elsif include.version=="ucp-2.2" %} -UCP administrators can control who views, edits, and uses resources such as -nodes, services, images, networks, and volumes. They can grant and manage -permissions to enforce fine-grained access control as needed. +With Docker Universal Control Plane (UCP), you can authorize how users view, +edit, and use cluster resources by granting role-based permissions. +To authorize access to cluster resources across your organization, Docker +administrators should take the following high-level steps: -## Grants -Grants define which users can access what resources. Grants are effectively -Access Control Lists (ACLs), which, when grouped together, can provide -comprehensive access policies for an entire organization. - -A grant is made up of a *subject*, *resource collection*, and *role*. - -Administrators are users who create subjects, define collections by labelling -resources, define roles by selecting allowable operations, and apply grants to -users and teams. - -> Only an administrator can manage grants, subjects, roles, and resources. - -![](../images/ucp-grant-model.svg) +- Add and configure subjects (users and teams) +- Define customer roles (or use defaults) by adding permissions resource types +- Group cluster resources into Swarm collections +- Create grants by marrying subject + role + resource ## Subjects @@ -119,84 +125,60 @@ role that defines permitted operations against one or more resources. - **User**: A person authenticated by the authentication backend. Users can belong to one or more teams and one or more organizations. -- **Team**: A group of users that share permissions defined at the team level. - A team exists only as part of an organization, and all of its members - must be members of the organization. Team members share organization - permissions. A team can be in one organization only. +- **Team**: A group of users that share permissions defined at the team level. A + team can be in one organization only. - **Organization**: A group of teams that share a specific set of permissions, defined by the roles of the organization. -## Collections - -A collection is a group of resources that you define with labels and access by -specifying a directory-like path. - -Swarm resources that can be placed into a collection include: - -- Application configs -- Containers -- Networks -- Nodes (Physical or virtual) -- Services -- Secrets -- Volumes +For more, see: +- [Create users and teams in UCP](./usermgmt-create-subjects.md) +- [Synchronize users and teams with LDAP](./usermgmt-sync-teams-with-ldap.md) ## Roles -Roles define what operations can be done by whom against which cluster -resources. A role is a set of permitted operations against a resource that is -assigned to a user or team with a grant. +Roles define what operations can be done by whom. A role is a set of permitted +operations (view, edit, use, etc.) against a *resource type* (such as an image, +container, volume, etc.) that is assigned to a user or team with a grant. -For example, the built-in role, **Restricted Control**, includes permission to view -and schedule a node (in a granted collection) but not update it. +For example, the built-in role, **Restricted Control**, includes permission to +view and schedule a node but not update it. A custom **DBA** role might include +permissions to create, attach, view, and remove volumes. -Most organizations use different roles to assign the right kind of access. A +Most organizations use different roles to fine-tune the approprate access. A given team or user may have different roles provided to them depending on what resource they are accessing. -You can build custom roles to meet your organizational needs or use the following -built-in roles: +For more, see [Create roles that define user access to resources](./usermgmt-create-roles.md) -- **View Only** - Users can see all cluster resources but not edit or use them. -- **Restricted Control** - Users can view containers and run a shell inside a - container process (with `docker exec`) but not view or edit other resources. -- **Full Control** - Users can perform all operations against granted resources. -- **Scheduler** - Users can view and schedule nodes. +## Resources -[Learn more about roles and permissions](permission-levels.md). +Cluster resources are grouped into collections. +A collection is a directory that holds Swarm resources. You can define and build +collections in UCP by assinging resources to a collection. Or you can create the +path in UCP and use *labels* in your YAML file to assign application resources to +that path. -## Collection architecture +> Swarm resources types that can be placed into a collection include: Containers, +> Networks, Nodes (physical or virtual), Services, Secrets, and Volumes. -Before grants can be implemented, collections must group resources in a way that -makes sense for an organization. +For more, see: [Group resources into collections](resources-create-collections-namespaces.md). -For example, consider an organization with two application teams, Mobile and -Payments, which share cluster hardware resources but segregate access to their -individual applications. +## Grants -``` -orcabank (organization) -├── ops (team) -├── security (team) -├── mobile-dev (team) -└── payments-dev (team) -``` +A grant is made up of a *subject*, *resource collection*, and *role*. -To define a potential access policy, the collection architecture should map to -the organizational structure. For a production UCP cluster, it might look like -this: +Grants define which users can access what resources in what way. Grants are +effectively Access Control Lists (ACLs), which when grouped together, can +provide comprehensive access policies for an entire organization. -``` -prod (collection) -├── mobile (sub-collection) -└── payments (sub-collection) -``` - -> A subject that has access to any level in a collection hierarchy has the -> same access to any collections below it. +Only an administrator can manage grants, subjects, roles, and resources. +> Administrators are users who create subjects, group resources by moving them +> into directories or namespaces, define roles by selecting allowable operations, +> and apply grants to users and teams. +For more, see: [Create grants and authorize access to users and teams](usermgmt-grant-permissions.md). ## Transition from UCP 2.1 access control @@ -210,7 +192,5 @@ prod (collection) [See a deeper tutorial on how to design access control architectures.](access-control-design-ee-standard.md) -[Learn to manage access to resources by using collections.](manage-access-with-collections.md). - {% endif %} {% endif %} diff --git a/deploy/access-control/isolate-nodes-between-teams.md b/deploy/access-control/isolate-nodes-between-teams.md index e0c2735638..14aa14766f 100644 --- a/deploy/access-control/isolate-nodes-between-teams.md +++ b/deploy/access-control/isolate-nodes-between-teams.md @@ -13,7 +13,174 @@ ui_tabs: {% if include.ui %} {% if include.version=="ucp-3.0" %} -This topic is under construction. +With Docker EE Advanced, you can enable physical isolation of resources +by organizing nodes into collections and granting `Scheduler` access for +different users. To control access to nodes, move them to dedicated collections +where you can grant access to specific users, teams, and organizations. + +In this example, a team gets access to a node collection and a resource +collection, and UCP access control ensures that the team members can't view +or use swarm resources that aren't in their collection. + +You need a Docker EE Advanced license and at least two worker nodes to +complete this example. + +1. Create an `Ops` team and assign a user to it. +2. Create a `/Prod` collection for the team's node. +3. Assign a worker node to the `/Prod` collection. +4. Grant the `Ops` teams access to its collection. + +![](../images/isolate-nodes-diagram.svg){: .with-border} + +## Create a team + +In the web UI, navigate to the **Organizations & Teams** page to create a team +named "Ops" in your organization. Add a user who isn't a UCP administrator to +the team. +[Learn to create and manage teams](create-and-manage-teams.md). + +## Create a node collection and a resource collection + +In this example, the Ops team uses an assigned group of nodes, which it +accesses through a collection. Also, the team has a separate collection +for its resources. + +Create two collections: one for the team's worker nodes and another for the +team's resources. + +1. Navigate to the **Collections** page to view all of the resource + collections in the swarm. +2. Click **Create collection** and name the new collection "Prod". +3. Click **Create** to create the collection. +4. Find **Prod** in the list, and click **View children**. +5. Click **Create collection**, and name the child collection + "Webserver". This creates a sub-collection for access control. + +You've created two new collections. The `/Prod` collection is for the worker +nodes, and the `/Prod/Webserver` sub-collection is for access control to +an application that you'll deploy on the corresponding worker nodes. + +## Move a worker node to a collection + +By default, worker nodes are located in the `/Shared` collection. +Worker nodes that are running DTR are assigned to the `/System` collection. +To control access to the team's nodes, move them to a dedicated collection. + +Move a worker node by changing the value of its access label key, +`com.docker.ucp.access.label`, to a different collection. + +1. Navigate to the **Nodes** page to view all of the nodes in the swarm. +2. Click a worker node, and in the details pane, find its **Collection**. + If it's in the `/System` collection, click another worker node, + because you can't move nodes that are in the `/System` collection. By + default, worker nodes are assigned to the `/Shared` collection. +3. When you've found an available node, in the details pane, click + **Configure**. +3. In the **Labels** section, find `com.docker.ucp.access.label` and change + its value from `/Shared` to `/Prod`. +4. Click **Save** to move the node to the `/Prod` collection. + +> Docker EE Advanced required +> +> If you don't have a Docker EE Advanced license, you'll get the following +> error message when you try to change the access label: +> **Nodes must be in either the shared or system collection without an advanced license.** +> [Get a Docker EE Advanced license](https://www.docker.com/pricing). + +![](../images/isolate-nodes-1.png){: .with-border} + +## Grant access for a team + +You'll need two grants to control access to nodes and container resources: + +- Grant the `Ops` team the `Restricted Control` role for the `/Prod/Webserver` + resources. +- Grant the `Ops` team the `Scheduler` role against the nodes in the `/Prod` + collection. + +Create two grants for team access to the two collections: + +1. Navigate to the **Grants** page and click **Create Grant**. +2. In the left pane, click **Collections**, and in the **Swarm** collection, + click **View Children**. +3. In the **Prod** collection, click **View Children**. +4. In the **Webserver** collection, click **Select Collection**. +5. In the left pane, click **Roles**, and select **Restricted Control** + in the dropdown. +6. Click **Subjects**, and under **Select subject type**, click **Organizations**. +7. Select your organization, and in the **Team** dropdown, select **Ops**. +8. Click **Create** to grant the Ops team access to the `/Prod/Webserver` + collection. + +The same steps apply for the nodes in the `/Prod` collection. + +1. Navigate to the **Grants** page and click **Create Grant**. +2. In the left pane, click **Collections**, and in the **Swarm** collection, + click **View Children**. +3. In the **Prod** collection, click **Select Collection**. +4. In the left pane, click **Roles**, and in the dropdown, select **Scheduler**. +5. In the left pane, click **Subjects**, and under **Select subject type**, click + **Organizations**. +6. Select your organization, and in the **Team** dropdown, select **Ops** . +7. Click **Create** to grant the Ops team `Scheduler` access to the nodes in the + `/Prod` collection. + +![](../images/isolate-nodes-2.png){: .with-border} + +## Deploy a service as a team member + +Your swarm is ready to show role-based access control in action. When a user +deploys a service, UCP assigns its resources to the user's default collection. +From the target collection of a resource, UCP walks up the ancestor collections +until it finds nodes that the user has `Scheduler` access to. In this example, +UCP assigns the user's service to the `/Prod/Webserver` collection and schedules +tasks on nodes in the `/Prod` collection. + +As a user on the Ops team, set your default collection to `/Prod/Webserver`. + +1. Log in as a user on the Ops team. +2. Navigate to the **Collections** page, and in the **Prod** collection, + click **View Children**. +3. In the **Webserver** collection, click the **More Options** icon and + select **Set to default**. + +Deploy a service automatically to worker nodes in the `/Prod` collection. +All resources are deployed under the user's default collection, +`/Prod/Webserver`, and the containers are scheduled only on the nodes under +`/Prod`. + +1. Navigate to the **Services** page, and click **Create Service**. +2. Name the service "NGINX", use the "nginx:latest" image, and click + **Create**. +3. When the **nginx** service status is green, click the service. In the + details view, click **Inspect Resource**, and in the dropdown, select + **Containers**. +4. Click the **NGINX** container, and in the details pane, confirm that its + **Collection** is **/Prod/Webserver**. + + ![](../../images/isolate-nodes-3.png){: .with-border} + +5. Click **Inspect Resource**, and in the dropdown, select **Nodes**. +6. Click the node, and in the details pane, confirm that its **Collection** + is **/Prod**. + + ![](../images/isolate-nodes-4.png){: .with-border} + +## Alternative: Use a grant instead of the default collection + +Another approach is to use a grant instead of changing the user's default +collection. An administrator can create a grant for a role that has the +`Service Create` permission against the `/Prod/Webserver` collection or a child +collection. In this case, the user sets the value of the service's access label, +`com.docker.ucp.access.label`, to the new collection or one of its children +that has a `Service Create` grant for the user. + +## Where to go next + +- [Node access control in Docker EE Advanced](access-control-node.md) +- [Isolate volumes between two different teams](isolate-volumes-between-teams.md) +- [Deploy a service with view-only access across an organization](deploy-view-only-service.md) + {% elsif include.version=="ucp-2.2" %} diff --git a/deploy/access-control/manage-access-with-collections.md b/deploy/access-control/resources-create-collections-namespaces.md similarity index 50% rename from deploy/access-control/manage-access-with-collections.md rename to deploy/access-control/resources-create-collections-namespaces.md index 929b616233..d3037ae03a 100644 --- a/deploy/access-control/manage-access-with-collections.md +++ b/deploy/access-control/resources-create-collections-namespaces.md @@ -1,7 +1,7 @@ --- -title: Manage access to resources by using collections -description: Use collections to enable access control for worker nodes and container resources. -keywords: ucp, grant, role, permission, authentication, resource collection +title: Group resources into collections or namespaces +description: Learn how to group resources into collections or namespaces to control access. +keywords: rbac, ucp, grant, role, permission, authentication, resource collection redirect_from: - /ucp/ ui_tabs: @@ -13,7 +13,147 @@ ui_tabs: {% if include.ui %} {% if include.version=="ucp-3.0" %} -This topic is under construction. + +Docker EE enables controlling access to container resources by using +*collections*. A collection is a group of swarm resources, like services, +containers, volumes, networks, and secrets. + +![](../images/collections-and-resources.svg){: .with-border} + +Access to collections goes through a directory structure that arranges a swarm's +resources. To assign permissions, administrators create grants against directory +branches. + +## Directory paths define access to collections + +Access to collections is based on a directory-like structure. For example, the +path to a user's default collection is `/Shared/Private/`. Every user +has a private collection that has the default permission specified by the UCP +administrator. + +Each collection has an access label that identifies its path. For example, the +private collection for user "hans" has a label that looks like this: + +``` +com.docker.ucp.access.label = /Shared/Private/hans +``` + +You can nest collections. If a user has a grant against a collection, the grant +applies to all of its child collections. + +For a child collection, or for a user who belongs to more than one team, the +system concatenates permissions from multiple roles into an "effective role" for +the user, which specifies the operations that are allowed against the target. + +## Built-in collections + +UCP provides a number of built-in collections. + +- `/` - The path to the `Swarm` collection. All resources in the + cluster are here. Resources that aren't in a collection are assigned + to the `/` directory. +- `/System` - The system collection, which contains UCP managers, DTR nodes, + and UCP/DTR system services. By default, only admins have access to the + system collection, but you can change this. +- `/Shared` - All worker nodes are here by default, for scheduling. + In a system with a standard-tier license, all worker nodes are under + the `/Shared` collection. With the EE Advanced license, administrators + can move worker nodes to other collections and apply role-based access. +- `/Shared/Private` - User private collections are stored here. +- `/Shared/Legacy` - After updating from UCP 2.1, all legacy access control + labels are stored here. + +![](../images/collections-diagram.svg){: .with-border} + +This diagram shows the `/System` and `/Shared` collections that are created +by UCP. User private collections are children of the `/Shared/private` +collection. Also, an admin user has created a `/prod` collection and its +`/webserver` child collection. + +## Default collections + +A user always has a default collection. The user can select the default +in UI preferences. When a user deploys a resource in the web UI, the +preselected option is the default collection, but this can be changed. + +Users can't deploy a resource without a collection. When deploying a +resource in CLI without an access label, UCP automatically places the +resource in the user's default collection. +[Learn how to add labels to cluster nodes](../admin/configure/add-labels-to-cluster-nodes/). + +When using Docker Compose, the system applies default collection labels +across all resources in the stack, unless the `com.docker.ucp.access.label` +has been set explicitly. + +> Default collections and collection labels +> +> Setting a default collection is most helpful for users who deploy stacks +> and don't want to edit the contents of their compose files. Also, setting +> a default collection is useful for users who work only on a well-defined +> slice of the system. On the other hand, setting the collection label for +> every resource works best for users who have versatile roles in the system, +> like administrators. + +## Collections and labels + +Resources are marked as being in a collection by using labels. +Some resource types don't have editable labels, so you can't move resources +like this across collections. You can't modify collections after +resource creation for containers, networks, and volumes, but you can +update labels for services, nodes, secrets, and configs. + +For editable resources, like services, secrets, nodes, and configs, +you can change the `com.docker.ucp.access.label` to move resources to +different collections. With the CLI, you can use this label to deploy +resources to a collection other than your default collection. Omitting this +label on the CLI deploys a resource on the user's default resource collection. + +The system uses the additional labels, `com.docker.ucp.collection.*`, to enable +efficient resource lookups. By default, nodes have the +`com.docker.ucp.collection.root`, `com.docker.ucp.collection.shared`, and +`com.docker.ucp.collection.swarm` labels set to `true`. UCP automatically +controls these labels, and you don't need to manage them. + +Collections get generic default names, but you can give them meaningful names, +like "Dev", "Test", and "Prod". + +A *stack* is a group of resources identified by a label. You can place the +stack's resources in multiple collections. Resources are placed in the user's +default collection unless you specify an explicit `com.docker.ucp.access.label` +within the stack/compose file. + +## Control access to nodes + +The Docker EE Advanced license enables access control on worker nodes. Admin +users can move worker nodes from the default `/Shared` collection into other +collections and create corresponding grants for scheduling tasks. + +In this example, an administrator has moved worker nodes to a `/prod` +collection: + +![](../images/containers-and-nodes-diagram.svg) + +When you deploy a resource with a collection, UCP sets a constraint implicitly +based on what nodes the collection, and any ancestor collections, can access. +The `Scheduler` role allows users to deploy resources on a node. +By default, all users have the `Scheduler` role against the `/Shared` +collection. + +When deploying a resource that isn't global, like local volumes, bridge +networks, containers, and services, the system identifies a set of +"schedulable nodes" for the user. The system identifies the target collection +of the resource, like `/Shared/Private/hans`, and it tries to find the parent +that's closest to the root that the user has the `Node Schedule` permission on. + +For example, when a user with a default configuration runs `docker container run nginx`, +the system interprets this to mean, "Create an NGINX container under the +user's default collection, which is at `/Shared/Private/hans`, and deploy it +on one of the nodes under `/Shared`. + +If you want to isolate nodes against other teams, place these nodes in +new collections, and assign the `Scheduler` role, which contains the +`Node Schedule` permission, to the team. +[Isolate swarm nodes to a specific team](isolate-nodes-between-teams.md). {% elsif include.version=="ucp-2.2" %} diff --git a/deploy/access-control/permission-levels.md b/deploy/access-control/usermgmt-create-roles.md similarity index 50% rename from deploy/access-control/permission-levels.md rename to deploy/access-control/usermgmt-create-roles.md index 8d7aa75b4e..bc9ca54d4d 100644 --- a/deploy/access-control/permission-levels.md +++ b/deploy/access-control/usermgmt-create-roles.md @@ -1,7 +1,7 @@ --- -description: Learn about permissions in Docker Universal Control Plane. -keywords: authorization, authentication, users, teams, UCP -title: Roles and permission levels +title: Create roles and set permission levels +description: Learn how to create roles and configure user authorization in Docker Universal Control Plane. +keywords: rbac, authorization, authentication, users, teams, UCP redirect_from: - /ucp/ ui_tabs: @@ -12,10 +12,86 @@ ui_tabs: --- {% if include.ui %} + {% if include.version=="ucp-3.0" %} -This topic is under construction. + +Docker Universal Control Plane has two types of users: administrators and +regular users. Administrators can make changes to the UCP swarm, while +regular users have permissions that range from no access to full control over +resources such as volumes, networks, images, and containers. + +Users are grouped into teams and organizations. + +![Diagram showing UCP permission levels](../images/role-diagram.svg) + +Administrators apply *grants* to users, teams, and organizations to give +permissions to swarm resources. + +## Administrator users + +In Docker UCP, only users with administrator privileges can make changes to +swarm settings. This includes: + +* Managing user permissions by creating grants. +* Managing swarm configurations, like adding and removing nodes. + +## Roles + +A role is a set of permitted API operations on a collection that you +can assign to a specific user, team, or organization by using a grant. + +UCP administrators view and manage roles by navigating to the **Roles** page. + +The system provides the following default roles: + +| Built-in role | Description | +|----------------------|-------------| +| `None` | The user has no access to swarm resources. This maps to the `No Access` role in UCP 2.1.x. | +| `View Only` | The user can view resources like services, volumes, and networks but can't create them. | +| `Restricted Control` | The user can view and edit volumes, networks, and images but can't run a service or container in a way that might affect the node where it's running. The user can't mount a node directory and can't `exec` into containers. Also, The user can't run containers in privileged mode or with additional kernel capabilities. | +| `Scheduler` | The user can view nodes and schedule workloads on them. Worker nodes and manager nodes are affected by `Scheduler` grants. Having `Scheduler` access doesn't allow the user to view workloads on these nodes. They need the appropriate resource permissions, like `Container View`. By default, all users get a grant with the `Scheduler` role against the `/Shared` collection. | +| `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. | + +![Diagram showing UCP permission levels](../images/permissions-ucp.svg) + +Administrators can create a custom role that has Docker API permissions +that specify the API actions that a subject may perform. + +The **Roles** page lists the available roles, including the default roles +and any custom roles that administrators have created. In the **Roles** +list, click a role to see the API operations that it uses. For example, the +`Scheduler` role has two of the node operations, `Schedule` and `View`. + +## Create a custom role + +Click **Create role** to create a custom role and define the API operations +that it uses. When you create a custom role, all of the APIs that you can use +are listed on the **Create Role** page. For example, you can create a custom +role that uses the node operations, `Schedule`, `Update`, and `View`, and you +might give it a name like "Node Operator". + +![](../images/custom-role.png){: .with-border} + +You can give a role a global name, like "Remove Images", which might enable +the **Remove** and **Force Remove** operations for images. You can apply a +role with the same name to different collections. + +Only an administrator can create and remove roles. Roles are always enabled. +Roles can't be edited, so to change a role's API operations, you must delete it +and create it again. + +You can't delete a custom role if it's used in a grant. You must first delete +the grants that use the role. + +## Where to go next + +* [Create and manage users](create-and-manage-users.md) +* [Create and manage teams](create-and-manage-teams.md) +* [Docker Reference Architecture: Securing Docker EE and Security Best Practices](https://success.docker.com/Architecture/Docker_Reference_Architecture%3A_Securing_Docker_EE_and_Security_Best_Practices) + {% elsif include.version=="ucp-2.2" %} + Docker Universal Control Plane has two types of users: administrators and regular users. Administrators can make changes to the UCP swarm, while regular users have permissions that range from no access to full control over diff --git a/deploy/access-control/usermgmt-create-subjects.md b/deploy/access-control/usermgmt-create-subjects.md new file mode 100644 index 0000000000..fe08c435dd --- /dev/null +++ b/deploy/access-control/usermgmt-create-subjects.md @@ -0,0 +1,131 @@ +--- +title: Create and manage users and teams +description: Learn how to add users and define teams in Docker Universal Control Plane. +keywords: rbac, authorize, authentication, users, teams, UCP, Docker +redirect_from: +- /ucp/ +ui_tabs: +- version: ucp-3.0 + orhigher: true +- version: ucp-2.2 + orlower: true +--- + +{% if include.ui %} + +Users, teams, and organizations are referred to as subjects in Docker Universal +Control Plane (UCP). + +Individual users can belong to one or more teams but each team can only be in +one ogranziation. At the fictional startup, Acme Company, some users are on +multiple teams; but all teams are necessarily unique. + +``` +Acme Organization +├── DevOps Team +│   ├── User Alex +│   └── User Brad +├── Infra Team +│ ├── User Alex +│  └── User Carl +└── Apps Team +    ├── User Doug +    └── User Evan +``` + +## Authentication + +All users are authenticated on the backend. UCP provides built-in authentication +and also integrates with LDAP directory services. + +> To enable LDAP and authenticate and synchronize UCP users and teams with your +> organization's LDAP directory, see: +> - [Synchronize users and teams with LDAP in the UI](./usermgmt-sync-teams-with-ldap.md) +> - [Synchronize users and teams with LDAP on the backend](../configure/external-auth/index.md). + +To use UCP built-in authentication, you must manually create users. + +New users are assigned a default permission level so that they can access the +cluster. You can optionally grant them UCP administrator permissions. + +You can extend the user's default permissions by granting them fine-grained +permissions over resources. You do this by adding the user to a team. + +## Build an organization architecture + +The general flow of designing an organization of teams in UCP is: + +1. Create an organization +2. Add users or configure UCP to sync with LDAP (in the UI or programmatically) +3. Create teams under the organization +4. Add users to teams manually or sync with LDAP + +### Create organizations + +To create an organzation in UCP: + +1. Click **Organization & Teams** under **User Management**. +2. Click **Create Organization**. +3. Input the organization name. +4. Click **Create**. + +### Create teams manually + +1. Click **Organization & Teams** under **User Management**. +2. Click through an organization name. +3. Click **Create Team**. +4. Input a team name (and description). +5. Click **Create**. +6. Add existing users to the team. If they don't exist, see below. + - Click the team name. + - Select **Actions** > **Add Users**. + - Check users to include. + - Click **Add Users**. + +> **Note**: To sync teams with groups in an LDAP server, see [Sync Teams with LDAP](./usermgmt-sync-teams-with-ldap). + + +{% if include.version=="ucp-3.0" %} + +### Create users manuallly + +To manally create users in UCP: + +1. Click **Users** under **User Management**. +2. Click **Create User**. +3. Input username, password, and full name. +4. Click **Create**. +5. [optional] Check "Is a Docker EE Admin". + +> A `Docker EE Admin` can grant users permission to change the cluster +> configuration and manage grants, roles, and collections. + +![](../images/ucp_usermgmt_users_create01.png){: .with-border} +![](../images/ucp_usermgmt_users_create02.png){: .with-border} + + +{% elsif include.version=="ucp-2.2" %} + +### Create users manuallly + +To manally create users in UCP: + +1. Navigate to the **Users** page. +2. Click **Create User**. +3. Input username, password, and full name. +4. Click **Create**. +5. [optional] Check "Is a UCP admin?". + +![](../images/create-users-1.png){: .with-border} + +> A `UCP Admin` can grant users permission to change the cluster configuration +> and manage grants, roles, and collections. + +![](../images/create-users-2.png){: .with-border} +{% endif %} + +## Where to go next + +- [Synchronize users and teams with LDAP](./usermgmt-sync-teams-with-ldap.md) +- [Create grants and authorize access to users and teams](usermgmt-grant-permissions.md). +{% endif %} diff --git a/deploy/access-control/grant-permissions.md b/deploy/access-control/usermgmt-grant-permissions.md similarity index 90% rename from deploy/access-control/grant-permissions.md rename to deploy/access-control/usermgmt-grant-permissions.md index 53ad4d13f9..4188b7c988 100644 --- a/deploy/access-control/grant-permissions.md +++ b/deploy/access-control/usermgmt-grant-permissions.md @@ -1,7 +1,7 @@ --- -title: Grant permissions to users based on roles -description: Grant access to swarm resources by using role-based access control. -keywords: ucp, grant, role, permission, authentication, authorization +title: Create grants to authorize access to resources +description: Learn how to grant users and teams access to cluster resources with role-based access control. +keywords: rbac, ucp, grant, role, permission, authentication, authorization redirect_from: - /ucp/ ui_tabs: @@ -12,10 +12,11 @@ ui_tabs: --- {% if include.ui %} +{% if include.version=="ucp-3.0" %} + UCP administrators can create *grants* to control how users and organizations access resources. -{% if include.version=="ucp-3.0" %} ## Kubernetes grants With Kubernetes orchestration, a grant is made up of a *subject*, a *role*, and a *namespace*. diff --git a/deploy/access-control/recover-a-user-password.md b/deploy/access-control/usermgmt-recover-user-password.md similarity index 95% rename from deploy/access-control/recover-a-user-password.md rename to deploy/access-control/usermgmt-recover-user-password.md index 186f400d51..76a2b7f158 100644 --- a/deploy/access-control/recover-a-user-password.md +++ b/deploy/access-control/usermgmt-recover-user-password.md @@ -1,6 +1,6 @@ --- title: Reset a user password -description: Learn how to recover your Docker Datacenter credentials +description: Learn how to recover your Docker Datacenter credentials. keywords: ucp, authentication redirect_from: - /ucp/ @@ -27,7 +27,7 @@ the **Users** page, and choose the user whose password you want to change. In the details pane, click **Configure** and select **Security** from the dropdown. -![](../images/recover-a-user-password-1.png){: .with-border} +![](../images/recover-user-password-1.png){: .with-border} Update the user's password and click **Save**. diff --git a/deploy/access-control/usermgmt-sync-with-ldap.md b/deploy/access-control/usermgmt-sync-with-ldap.md new file mode 100644 index 0000000000..65ed369602 --- /dev/null +++ b/deploy/access-control/usermgmt-sync-with-ldap.md @@ -0,0 +1,119 @@ +--- +title: Synchronize users and teams with LDAP +description: Learn how to enable LDAP and sync users and teams in Docker Universal Control Plane. +keywords: authorize, authentication, users, teams, UCP, Docker, LDAP +redirect_from: +- /ucp/ +ui_tabs: +- version: ucp-3.0 + orhigher: true +- version: ucp-2.2 + orlower: true +--- + +{% if include.ui %} +{% if include.version=="ucp-3.0" %} + +To enable LDAP in UCP and sync team members with your LDAP directory: + +1. Click **Admin Settings** under your username drop down. +2. Click **Authentication & Authorization**. +3. Scroll down and click `Yes` by **LDAP Enabled**. A list of LDAP settings displays. +4. Input values to match your LDAP server installation. +5. Test your configuration in UCP. +6. Manually create teams in UCP to mirror those in LDAP. +6. Click **Sync Now**. + +If UCP is configured to sync users with your organization's LDAP directory +server, you can enable syncing the new team's members when +creating a new team or when modifying settings of an existing team. + +[Learn how to sync with LDAP at the backend](../configure/external-auth/index.md). + +![](../images/create-and-manage-teams-5.png){: .with-border} + +There are two methods for matching group members from an LDAP directory: + +**Match Group Members** + +This option specifies that team members should be synced directly with members +of a group in your organization's LDAP directory. The team's membership will by +synced to match the membership of the group. + +| Field | Description | +|:-----------------------|:------------------------------------------------------------------------------------------------------| +| Group DN | The distinguished name of the group from which to select users. | +| Group Member Attribute | The value of this group attribute corresponds to the distinguished names of the members of the group. | + + +**Match Search Results** + +This option specifies that team members should be synced using a search query +against your organization's LDAP directory. The team's membership will be +synced to match the users in the search results. + +| Field | Description | +| :--------------------- | :---------------------------------------------------------------------------------------------------- | +| Search Base DN | Distinguished name of the node in the directory tree where the search should start looking for users. | +| Search Filter | Filter to find users. If null, existing users in the search scope are added as members of the team. | +| Search subtree | Defines search through the full LDAP tree, not just one level, starting at the Base DN. | + +**Immediately Sync Team Members** + +Select this option to run an LDAP sync operation immediately after saving the +configuration for the team. It may take a moment before the members of the team +are fully synced. + +{% elsif include.version=="ucp-2.2" %} + +To enable LDAP in UCP and sync team members with your LDAP directory: + +1. Click **Admin Settings** under your username drop down. +2. Click **Authentication & Authorization**. +3. Scroll down and click `Yes` by **LDAP Enabled**. A list of LDAP settings displays. +4. Input values to match your LDAP server installation. +5. Test your configuration in UCP. +6. Manually create teams in UCP to mirror those in LDAP. +6. Click **Sync Now**. + +If UCP is configured to sync users with your organization's LDAP directory +server, you can enable syncing the new team's members when +creating a new team or when modifying settings of an existing team. + +[Learn how to sync with LDAP at the backend](../configure/external-auth/index.md). + +![](../images/create-and-manage-teams-5.png){: .with-border} + +There are two methods for matching group members from an LDAP directory: + +**Match Group Members** + +This option specifies that team members should be synced directly with members +of a group in your organization's LDAP directory. The team's membership will by +synced to match the membership of the group. + +| Field | Description | +|:-----------------------|:------------------------------------------------------------------------------------------------------| +| Group DN | The distinguished name of the group from which to select users. | +| Group Member Attribute | The value of this group attribute corresponds to the distinguished names of the members of the group. | + +**Match Search Results** + +This option specifies that team members should be synced using a search query +against your organization's LDAP directory. The team's membership will be +synced to match the users in the search results. + +| Field | Description | +| :--------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------- | +| Search Base DN | The distinguished name of the node in the directory tree where the search should start looking for users. | +| Search Filter | The LDAP search filter used to find users. If you leave this field empty, all existing users in the search scope will be added as members of the team. | +| Search subtree instead of just one level | Whether to perform the LDAP search on a single level of the LDAP tree, or search through the full LDAP tree starting at the Base DN. | + +**Immediately Sync Team Members** + +Select this option to run an LDAP sync operation immediately after saving the +configuration for the team. It may take a moment before the members of the team +are fully synced. + +{% endif %} +{% endif %}