diff --git a/images/authentication-authorization-1.svg b/images/authentication-authorization-1.svg
new file mode 100644
index 0000000000..72b3492d96
--- /dev/null
+++ b/images/authentication-authorization-1.svg
@@ -0,0 +1,90 @@
+
+
\ No newline at end of file
diff --git a/images/create-and-manage-orgs-1.png b/images/create-and-manage-orgs-1.png
new file mode 100644
index 0000000000..1b242c0148
Binary files /dev/null and b/images/create-and-manage-orgs-1.png differ
diff --git a/images/create-and-manage-orgs-2.png b/images/create-and-manage-orgs-2.png
new file mode 100644
index 0000000000..6f010ea345
Binary files /dev/null and b/images/create-and-manage-orgs-2.png differ
diff --git a/images/create-and-manage-orgs-3.png b/images/create-and-manage-orgs-3.png
new file mode 100644
index 0000000000..a0793bd592
Binary files /dev/null and b/images/create-and-manage-orgs-3.png 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..3c0c7ac437
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..48f69a9c88
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..07bcd825e5
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..823defa208
Binary files /dev/null and b/images/create-and-manage-teams-4.png differ
diff --git a/images/create-and-manage-teams-5.png b/images/create-and-manage-teams-5.png
new file mode 100644
index 0000000000..d70972364f
Binary files /dev/null and b/images/create-and-manage-teams-5.png differ
diff --git a/images/create-manage-users-1.png b/images/create-manage-users-1.png
new file mode 100644
index 0000000000..cbf30037c9
Binary files /dev/null and b/images/create-manage-users-1.png differ
diff --git a/images/create-manage-users-2.png b/images/create-manage-users-2.png
new file mode 100644
index 0000000000..91360649ab
Binary files /dev/null and b/images/create-manage-users-2.png differ
diff --git a/user-management/create-and-manage-orgs.md b/user-management/create-and-manage-orgs.md
new file mode 100644
index 0000000000..07c143ef0e
--- /dev/null
+++ b/user-management/create-and-manage-orgs.md
@@ -0,0 +1,54 @@
+
+
+# Create and manage organizations
+
+When a user creates a repository, only that user has permissions to make changes
+to the repository.
+
+For team workflows, where multiple users have permissions to manage a set of
+common repositories, create an organization. By default, DTR has one organization
+called 'docker-datacenter', that is shared between DTR and UCP.
+
+To create a new organization, navigate to the **DTR web UI**, and go to the
+**Organizations** page.
+
+
+
+Click the **New organization** button, and choose a meaningful name for the
+organization.
+
+
+
+Repositories owned by this organization will contain the organization name, so
+to pull an image from that repository, you'll use:
+
+```bash
+$ docker pull //:
+```
+
+Click **Save** to create the organization, and then **click the organization**
+to define which users are allowed to manage this
+organization. These users will be able to edit the organization settings, edit
+all repositories owned by the organization, and define the user permissions for
+this organization.
+
+For this, click the **Add user** button, **select the users** that you want to
+grant permissions to manage the organization, and click
+**Save**. Then change their permissions from 'Member' to **Admin**.
+
+
+
+## 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..2fd97342c8
--- /dev/null
+++ b/user-management/create-and-manage-teams.md
@@ -0,0 +1,62 @@
+
+
+# Create and manage teams
+
+You can extend the user's default permissions by granting them fine-grain
+permissions over image repositories. You do this by adding the user to a team.
+A team defines the permissions a set of users have for a set of repositories.
+
+To create a new team, go to the **DTR web UI**, and navigate to the
+**Organizations** page.
+Then **click the organization** where you want to create the team. In this
+example, we'll create the 'billing' team team under the 'whale' organization.
+
+
+
+Click '**+**' to create a new team, and give it a name.
+
+
+
+## Add users to a team
+
+Once you have created a team, **click the team** name, to manage its settings.
+The first thing we need to do is add users to the team. Click the **Add user**
+button and add users to the team.
+
+
+
+## Manage team permissions
+
+The next step is to define the permissions this team has for a set of
+repositories. Navigate to the **Repositories** tab, and click the
+**Add repository** button.
+
+
+
+Choose the repositories this team has access to, and what permission levels the
+team members have.
+
+
+
+There are three permission levels available:
+
+| Permission level | Description |
+|:-----------------|:-----------------------------------------------------------------|
+| Read only | View repository and pull images. |
+| Read & Write | View repository, pull and push images. |
+| Admin | Manage repository and change its settings, pull and push images. |
+
+## Where to go next
+
+* [Create and manage users](create-and-manage-users.md)
+* [Create and manage organizations](create-and-manage-orgs.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..d06bfb323d
--- /dev/null
+++ b/user-management/create-and-manage-users.md
@@ -0,0 +1,36 @@
+
+
+# Create and manage users
+
+When using the Docker Datacenter built-in authentication, you can create users
+to grant them fine-grained permissions.
+Users are shared across Docker Datacenter. When you create a new user in
+Docker Universal Control Plane, that user becomes available in DTR and vice
+versa.
+
+To create a new user, go to the **DTR web UI**, and navigate to the **Users**
+page.
+
+
+
+Click the **New user** button, and fill-in the user information.
+
+
+
+Check the **Trusted Registry admin** option, if you want to grant permissions
+for the user to change Docker Datacenter configurations.
+
+## Where to go next
+
+* [Create and manage organizations](create-and-manage-orgs.md)
+* [Create and manage teams](create-and-manage-teams.md)
diff --git a/user-management/index.md b/user-management/index.md
index c1efdf7bdb..9a4944fd85 100644
--- a/user-management/index.md
+++ b/user-management/index.md
@@ -1,114 +1,65 @@
-# DTR permission levels
+# Authentication and authorization
-Administrators assign permissions to control users level of access to the
-Trusted Registry. To access repositories, these users are grouped into teams and
-organizations. Users can use the Trusted Registry UI to view their teams,
-organizations, and the repositories they belong to.
+With DTR you get to control which users have access to your image repositories.
-This document describes:
+By default, anonymous users can only pull images from public repositories.
+They can't create new repositories or push to existing ones.
+You can then grant permissions to enforce fine-grained access control to image
+repositories. For that:
-* How account management is organized, and
-* Provides examples of using the UI to organize and view users, teams, organizations, and repositories.
+* Start by creating a user.
->**Note**: You can manage accounts and repositories from a Trusted Registry API. Refer to the API documentation located under the user drop down menu in the Trusted Registry UI to learn about it.
+ Users are shared across Docker Datacenter. When you create a new user in
+ Docker Universal Control Plane, that user becomes available in DTR and vice
+ versa. Registered users can create and manage their own repositories.
-## Account types
+ You can also integrate with an LDAP service to manage users from a single
+ place.
-Docker defines two types of accounts: users and organizations.
+* Extend the permissions by adding the user to a team.
-* **User** accounts correspond to individuals able to authenticate to the Trusted Registry.
-* **Organization** accounts consists of subsets of users grouped into teams. Organizations can correspond to separate divisions, business units, or product teams within in your corporation.
-
-Both user and organization accounts are uniquely identified by an account name.
-These names also serve to organize repositories in the Trusted Registry into
-namespaces corresponding to each account using the format
-`/`.
-
-### User accounts
-
-Users may be members of multiple teams and multiple organizations. As such, they may have differing permissions that are particular to that team. For example, team A can have admin permissions to manage teams while Team B can have only read permissions.
-
-* Users, through their own namespace, can manage and share their own repositories.
-* Users can be granted permission to repositories through team membership in an organization.
-* Users can be an "owner" member of an organization. This grants them permission to manage all teams and repositories in that organization.
-
-The following table depicts user permissions and roles:
-
-| Permissions/Roles | sys admin | org admin | org member | team member | user |
-|:----------------------------------------|:---------:|:---------:|:----------:|:-----------:|:----:|
-| orgs: create, edit, delete | x | | | | |
-| orgs: view public repos, teams, members | x | x | x | | |
-| orgs: view public repos only | x | x | x | x | x |
-| teams: create, edit, delete | x | x | | | |
-| teams: view public repos, members | x | x | x | x | |
-| teams: set repo permissions | x | x | | | |
-
-### Organization accounts
-
-Organizations are defined by its own namespace of repositories. They can consist
-of one or more teams with each team having its own set of permissions. It can
-also be managed by anyone in an initial "owners" team, which is created by
-default.
-
-* **Organization owners** have the highest level of permissions within the
-organization. They can manage all teams and repositories and create, modify,
-or delete teams.
-
-* **Organization members** must be a member of one or more teams within the
-organization.
-
-All organization members can see teams and their members. However, they are not
-visible to users outside that organization.
+ To extend a user's permission and manage their permissions over repositories,
+ you add the user to a team.
+ A team defines the permissions users have for a set of repositories.
-### Teams in an organization
+## Organizations and teams
-Teams are a convenient grouping of users. Organization owners can create a team and control team membership using the following authentication methods:
+When a user creates a repository, only that user can make changes to the
+repository settings, and push new images to it.
-* Importing a managed list of users.
-* Setting up LDAP integration and configuring team membership sync with an LDAP group.
+Organizations take permission management one step further, since they allow
+multiple users to own and manage a common set of repositories. This
+is useful when implementing team workflows. With organizations you can
+delegate the management of a set of repositories and user permissions to the
+organization administrators.
-Organization owners, other than the system administrator, are the only people
-who can create, modify, or delete those teams that belong to that organization.
+An organization owns a set of repositories, and defines a set of teams. With
+teams you can define fine-grain permissions that a team of
+user has for a set of repositories.
-The following table depicts teams permissions to their repositories:
+
-| Repository access | read | read-write | admin |
-|:-----------------------|:----:|:----------:|:-----:|
-| view/ browse | x | x | x |
-| pull | x | x | x |
-| push | | x | x |
-| edit/delete tags | | x | x |
-| edit the description | | | x |
-| make public or private | | | x |
-| manage user access | | | x |
+In this example, the 'Whale' organization has three repositories and two teams:
-**Team permissions are additive**. This means that the highest level of permissions is always granted and can’t be reduced. For example, a user belongs to two teams. Team A grants its members "read-write" access to a repository and Team B grants "read-only" access to the same repository. That user will have "read-write" access to the repository because it is the higher permission level of the two.
+* Members of the blog team can only see and pull images from the whale/java
+repository,
+* Members of the billing team can manage the whale/golang repository, and push
+and pull images from the whale/java repository.
-### Repository behavior
+## Where to go next
-Repositories are identified by a namespace value. A namespace has the format `account-name/repository-name`. The `account-name` can be either a user or organization account. Upon creation, you can determine whether the repository has either public or private visibility.
-
-Public repositories are visible to all accounts. But it can only be written to by accounts granted explicit write access. However private repositories can’t be discovered by any account type unless it has explicit read access to it.
-
-You must first create a repository before pushing an image to it. Otherwise you will see the following error message:
-
-```
-% docker push my.dtr.host/user1/myimage
-The push refers to a repository [my.dtr.host/user1/myimage] (len: 1) 1d073211c498: Image push failed
-unauthorized: access to the requested resource is not authorized
-```
+* [Create and manage users](create-and-manage-users.md)
diff --git a/user-management/permission-levels.md b/user-management/permission-levels.md
new file mode 100644
index 0000000000..36881a6981
--- /dev/null
+++ b/user-management/permission-levels.md
@@ -0,0 +1,62 @@
+
+
+# Permission levels
+
+Docker Trusted Registry allows you to define fine-grain permissions over image
+repositories.
+
+## Administrator users
+
+Users are shared across Docker Datacenter. When you create a new user in Docker
+Universal Control Plane, that user becomes available in DTR and vice versa.
+When you create an administrator user in DTR, that user is a Docker Datacenter
+administrator, with permissions to:
+
+* Manage users across Docker Datacenter,
+* Manage DTR repositories and settings,
+* Manage the whole UCP cluster.
+
+## Team permission levels
+
+Teams allow you to define the permissions a set of user has for a set of
+repositories. Three permission levels are available:
+
+| Repository operation | read | read-write | admin |
+|:----------------------|:----:|:----------:|:-----:|
+| View/ browse | x | x | x |
+| Pull | x | x | x |
+| Push | | x | x |
+| Delete tags | | x | x |
+| Edit description | | | x |
+| Set public or private | | | x |
+| Manage user access | | | x |
+| Delete repository | | | |
+
+Team permissions are additive. When a user is a member of multiple teams, they
+have the highest permission level defined by those teams.
+
+## Overall permissions
+
+Here's an overview of the permission levels available in DTR:
+
+* Anonymous users: Can search and pull public repositories.
+* Users: Can search and pull public repos, and create and manage their own
+repositories.
+* Team member: Everything a user can do, plus the permissions granted by the teams the user is member of.
+* Team admin: Everything a team member can do, and can also add members to the team.
+* Organization admin: Everything a team admin can do, can create new teams, and add members to the organization.
+* DDC admin: Can manage anything across UCP and DTR.
+
+## Where to go next
+
+* [Authentication and authorization](index.md)