diff --git a/modules/ROOT/pages/_partials/concepts/channels.adoc b/modules/ROOT/pages/_partials/concepts/channels.adoc index 1cea67e62..d45f90bdc 100644 --- a/modules/ROOT/pages/_partials/concepts/channels.adoc +++ b/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. diff --git a/modules/ROOT/pages/_partials/concepts/roles.adoc b/modules/ROOT/pages/_partials/concepts/roles.adoc index 72ed34b6c..927244c47 100644 --- a/modules/ROOT/pages/_partials/concepts/roles.adoc +++ b/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[] diff --git a/modules/ROOT/pages/_partials/howto/how-to-control-document-access.adoc b/modules/ROOT/pages/_partials/howto/how-to-control-document-access.adoc index b37c8a079..95e5b90c5 100644 --- a/modules/ROOT/pages/_partials/howto/how-to-control-document-access.adoc +++ b/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] -- diff --git a/modules/ROOT/pages/_partials/howto/how-to-create-roles.adoc b/modules/ROOT/pages/_partials/howto/how-to-create-roles.adoc index e44135ef1..f6db98fe3 100644 --- a/modules/ROOT/pages/_partials/howto/how-to-create-roles.adoc +++ b/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 \ No newline at end of file +// END how-to -- HOW-TO CREATE A ROLE diff --git a/modules/ROOT/pages/_partials/howto/how-to-verify-access.adoc b/modules/ROOT/pages/_partials/howto/how-to-verify-access.adoc index b2faa33ae..037526133 100644 --- a/modules/ROOT/pages/_partials/howto/how-to-verify-access.adoc +++ b/modules/ROOT/pages/_partials/howto/how-to-verify-access.adoc @@ -40,8 +40,9 @@ curl http://localhost:4985/db/_user/pupshaw The <> 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 <> 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 \ No newline at end of file +// END how-to -- HOW-TO VERIFY ACCESS diff --git a/modules/ROOT/pages/authentication-users.adoc b/modules/ROOT/pages/authentication-users.adoc index 51c0d0d41..083f5dbc8 100644 --- a/modules/ROOT/pages/authentication-users.adoc +++ b/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"]}}}}' ---- diff --git a/modules/ROOT/pages/get-started-verify-install.adoc b/modules/ROOT/pages/get-started-verify-install.adoc index aed67e34c..6b2973ca2 100644 --- a/modules/ROOT/pages/get-started-verify-install.adoc +++ b/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`