DOC-11383 clarify collection_access for channel assignment (#853)

* DOC-11383 clarify collection_access for channel assignment

* Clarify channel definition

---------

Co-authored-by: Simon Dew <Simon.Dew@couchbase.com>

Author: torcolvin

modules/ROOT/pages/_partials/concepts/channels.adoc

@@ -95,7 +95,7 @@ Version 3.x::
 image::channel-access-grant-3.0.png["Access Control Points 3.x",400]
 
 <1> Using the Admin REST API: +
-You can provide the `admin_channels` property using the *Admin REST API* endpoint ({rest-api-admin-user-put--xref}).
+You can provide the `admin_channels` property within the `collection_access` property using the *Admin REST API* endpoint ({rest-api-admin-user-put--xref}).
 
 <2> Programmatically using Access Grant Document: +
 The {sync-function--xref} provides a flexible and secure method for controlling document access and routing.

modules/ROOT/pages/_partials/concepts/roles.adoc

@@ -11,15 +11,15 @@ They enable the grouping together of {users--xref} with similar characteristics,
 // end::summary[]
 // tag::body[]
 
-A Role and a user assigned to a Role is granted access to a channel, a part of collections. 
-The user can then access all documents assigned to that channel. 
+A Role and a user assigned to a role is granted to access to a channel, which is associated with a specific collection.
+The user can then access all documents assigned to that channel.
 When granting user access to admin channels statically, the user must specify the collection and corresponding channel.
 
 As an entity, roles comprise a name and a list of channels.
 
-Any user associated with a role inherits the right to access any of the channels in the role’s list. This provides a convenient way to associate multiple channels with multiple users.
+Any user associated with a role inherits the right to access any of the channels in the role's list. This provides a convenient way to associate multiple channels with multiple users.
 
-TIP: Roles have a separate namespace from users, so it’s possible to have a user and a role with the same name.
+TIP: Roles have a separate namespace from users, so it's possible to have a user and a role with the same name.
 
 
 // end::body[]

modules/ROOT/pages/_partials/howto/how-to-control-document-access.adoc

@@ -22,7 +22,7 @@ This dual-purpose is reflected in the way you use channels:
 You grant roles and-or users access to channels using:
 
 * Admin REST API +
- Using admin_channels property using the admin REST API endpoint -- see {rest-api-admin-user-put--xref}
+ Using `admin_channels` property inside the `collection_access` property using the admin REST API endpoint -- see {rest-api-admin-user-put--xref}
 * Dynamically via Sync Function  +
  Programmatically within the sync function using the exposed helper function access() — see {sync-function-api--xref}
 * Configuration File (pre 3.0) +
@@ -47,11 +47,11 @@ Specify the roles to be assigned in the `admin_channels` array.
 ----
 $ curl -vX PUT "http://localhost:4985/mydatabase/_user/{user}" -H //<.>
 "accept: application/json" -H "Content-Type: application/json" -d
-'{ "admin_channels": ["Channel1","Channel3]}' // <.>
+'{"collection_access": {"scopename": { "collectionname": {"admin_channels": ["Channel1","Channel3"]}}}}' // <.>
 ----
 
 <.> {user} is the user name to be updated, e.g. "Edge1User"
-<.> Here we add _Channel1_ and _Channel3_ to the user
+<.> Here we add _Channel1_ and _Channel3_ to the user inside scope scopename and collection collectionname.
 
 --
 
@@ -134,21 +134,46 @@ Use the *Admin REST API* for production systems.
     "mydatabase": {
       "users": {
         "GUEST": {"disabled": true},
-        "Edge1User": {"password": "pass", "admin_roles": ["Edge1"],
-              "admin_channels": ["Channel1","Channel3","RandomChannel"]} // <.>
+        "Edge1User": {
+          "password": "pass",
+          "admin_roles": ["Edge1"],
+          "collection_access": {
+            "scopename": {
+              "collectionname": {
+                "admin_channels": ["Channel1","Channel3","RandomChannel"] // <.>
+              }
+            }
+          }
+        }
       },
       "roles": {
-        "Edge1": {"admin_channels": ["channel1", "channel3"]},
-        "Edge2": {"admin_channels": ["Channel2","Channel3","SkyChannel"]} // <.>
+        "Edge1": {
+          "collection_access": {
+	    "scopename": {
+	      "collectionname": {
+		"admin_channels": ["channel1","channel3"]
+	      }
+	    }
+	  }
+	},
+	"Edge2": {
+          "collection_access": {
+	    "scopename": {
+	      "collectionname": {
+                "admin_channels": ["channel2","channel3","SkyChannel"]} // <.>
+	      }
+	    }
+	  }
+	},
       }
     }
   }
 }
 ----
 
-<.> Here we have added the channel _RandomChannel_ to the user _Edge1User_ {configuration-schema-database--pfx--db}-users-this_user-admin_channels[databases.$db.users.$user.admin_channel]
+<.> Here we have added the channels _channel1_ and `_channel3_ to the user _Edge1User_ {configuration-schema-database--pfx--db}-users-this_user-admin_channels[databases.$db.users.$user.collection_access.$scopename.$collectionname.admin_channels]
 
-<.> Here we have added the channel _SkyChannel_ to the role _Edge2_ {configuration-schema-database--pfx--db}-roles-this_role-admin_channels[databases.$db.users.$user.admin_channel]
+<.> Here we have added the channels _channel2_, _channel3_ and _SkyChannel_ to the role _Edge2_ {configuration-schema-database--pfx--db}-roles-this_role-admin_channels[databases.$db.users.$user.$collection_access.$scopename.$collectionname.$admin_channels]
 
 --
 

modules/ROOT/pages/_partials/howto/how-to-create-roles.adoc

@@ -47,9 +47,9 @@ Create a new role using the {rest-api-admin-role-post--xref} endpoint.
 ----
 $ curl -vX POST "http://localhost:4985/mydatabase/_roles/" -H
 "accept: application/json" -H "Content-Type: application/json" -d
-'{"name": "Edge1", "admin_channels": ["channel1", "channel3"]]}' // <.>
+'{"name": "Edge1", "collection_acces": {"scopename": {"collectionname": {"admin_channels": ["channel1", "channel3"]]}}}}' // <.>
 ----
-<.> Here we add the Edge1 role.
+<.> Here we add the Edge1 role which grants channel access to channel1 and channel3 in scope scopename and collection collectionname.
 
 --
 
@@ -69,7 +69,15 @@ It is recommended to use the *REST API* for production systems.
   "databases": {
     "mydatabase": {
       "roles": { // <.>
-        "Edge1": {"admin_channels": ["channel1", "channel3"]}, // <.>
+        "Edge1": {
+          "collection_access": {
+            "scopename": {
+              "collectionname": {
+                "admin_channels": ["channel1", "channel3"] // <.>
+              }
+            }
+          }
+	},
         "Edge2": {"admin_channels": ["channel2", "channel3"]},
         "GUEST": {"disabled": true}
       }
@@ -84,4 +92,4 @@ It is recommended to use the *REST API* for production systems.
 =====
 ====
 
-// END how-to -- HOW-TO CREATE A ROLE
+// END how-to -- HOW-TO CREATE A ROLE

modules/ROOT/pages/_partials/howto/how-to-verify-access.adoc

@@ -40,8 +40,9 @@ curl http://localhost:4985/db/_user/pupshaw
 
 The <<ex-output,output>> shows that the user `pupshaw` has access to the following channels:
 
-<.> `all` through its own `admin_channels` setting
-<.> `hoopy` through the `froods` role's `admin_channels` setting
+<.> `all` through its own `admin_channels` setting for the default collection.
+<.> `collectionAChannel` through its own `admin_channels` setting for the collection `collectionA`.
+<.> `hoopy` through the `froods` role's `admin_channels` setting in the default collection.
 
 [#ex-output]
 [source,json]
@@ -50,6 +51,18 @@ The <<ex-output,output>> shows that the user `pupshaw` has access to the followi
     "admin_channels": [
         "all" // <.>
     ],
+    "collection_access": {
+        "scopeA": {
+	    "collectionA": {
+		"admin_channels": [
+		    "collectionAChannel" // <.>
+		],
+		"all_channels": [
+		    "collectionAChannel"
+		]
+	    }
+	}
+    },
     "admin_roles": [
         "froods"
     ],
@@ -77,12 +90,25 @@ curl http://localhost:4985/db/_role/frood
 
 The output shows that the role `froods` has access to the following channels:
 
-<.> `hoopy` through its role's `admin_channels` setting
+<.> `hoopy` through its role's `admin_channels` setting for the default collection.
+<.> `collectionA` through its role's `admin_channels` setting for the collection `collectionA`.
 
 [source,json]
 ----
 {
     "name": "froods",
+    "collection_access": {
+        "scopeA": {
+	    "collectionA": {
+		"admin_channels": [
+		    "collectionAChannel" // <.>
+		],
+		"all_channels": [
+		    "collectionAChannel"
+		]
+	    }
+	}
+    },
     "admin_channels": [
         "hoopy" // <.>
     ],
@@ -128,4 +154,4 @@ That assignment to `hoopy` is what makes it available to our `froods` role and t
 
 ====
 
-// END how-to -- HOW-TO VERIFY ACCESS
+// END how-to -- HOW-TO VERIFY ACCESS

modules/ROOT/pages/authentication-users.adoc

@@ -55,7 +55,7 @@ The following sample command enables the GUEST account and allows it access to a
 [source,bash]
 ----
 $ curl -X PUT localhost:4985/$DB/_user/GUEST --data \
-   '{"disabled":false, "admin_channels":["public"]}'
+   '{"disabled":false, "collection_access": {"scopename": {"collectionname": {"admin_channels":["public"]}}}}'
 ----
 
 

modules/ROOT/pages/get-started-verify-install.adoc

@@ -202,7 +202,13 @@ curl  --location --request PUT 'http://127.0.0.1:4985/traveldb/_role/stdrole' \/
       --header 'Content-Type: application/json' \
       --data-raw '{
           "name": "stdrole",
-          "admin_channels": ["newrolechannel"] // <.>
+          "collection_access": {
+             "scopename": {
+                "collection_name" {
+                    admin_channels": ["newrolechannel"] // <.>
+                 }
+             }
+           }
       }'
 ----
 
@@ -231,7 +237,13 @@ curl  --location -g --request POST 'http://localhost:4985/traveldb/_user/' \// <
           "name": "sgwuser1", // <.>
           "password": "passwordstring",
           "admin_roles": ["stdrole"], // <.>
-          "admin_channels": ["public"] // <.>
+          "collection_access": {
+             "scopename": {
+                "collection_name" {
+                    admin_channels": ["public"] // <.>
+                 }
+             }
+           }
       }'
 ----
 <.> Here we identify the name of the {sgw} database -- `traveldb` and the required object, `_user`