Repository: zeppelin Updated Branches: refs/heads/master 7420f2df7 -> 20fd2a9c8
[ZEPPELIN-2036] add documentation on separating workspaces (public/private) ### What is this PR for? This is to add more description in documentation about notebook workspaces. Also some details from user mailing list [here](https://lists.apache.org/thread.html/d94276521942c90cca1325514ea93b737a517679dd0f6f7eb287492a%3Cusers.zeppelin.apache.org%3E) ### What type of PR is it? Improvement | Documentation ### Todos * [x] - add desc ### What is the Jira issue? [ZEPPELIN-2036](https://issues.apache.org/jira/browse/ZEPPELIN-2036) ### How should this be tested? green CI/ if description clear ### Screenshots (if appropriate) ### Questions: * Does the licenses files need update? no * Is there breaking changes for older versions? no * Does this needs documentation? no Author: Khalid Huseynov <[email protected]> Closes #1965 from khalidhuseynov/docs/private-workspace and squashes the following commits: fae6410 [Khalid Huseynov] fix formating: add lines c85ee6e [Khalid Huseynov] rewording cec8bbd [Khalid Huseynov] add public vs. private 8703770 [Khalid Huseynov] add description on separating workspaces Project: http://git-wip-us.apache.org/repos/asf/zeppelin/repo Commit: http://git-wip-us.apache.org/repos/asf/zeppelin/commit/20fd2a9c Tree: http://git-wip-us.apache.org/repos/asf/zeppelin/tree/20fd2a9c Diff: http://git-wip-us.apache.org/repos/asf/zeppelin/diff/20fd2a9c Branch: refs/heads/master Commit: 20fd2a9c8c3ac521a9b0026d9973e458af4e9e2c Parents: 7420f2d Author: Khalid Huseynov <[email protected]> Authored: Wed Feb 1 17:54:05 2017 +0900 Committer: ahyoungryu <[email protected]> Committed: Fri Feb 3 21:14:23 2017 +0900 ---------------------------------------------------------------------- docs/security/notebook_authorization.md | 29 ++++++++++++++++++++++------ 1 file changed, 23 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/zeppelin/blob/20fd2a9c/docs/security/notebook_authorization.md ---------------------------------------------------------------------- diff --git a/docs/security/notebook_authorization.md b/docs/security/notebook_authorization.md index dee3138..a227854 100644 --- a/docs/security/notebook_authorization.md +++ b/docs/security/notebook_authorization.md @@ -24,14 +24,14 @@ limitations under the License. <div id="toc"></div> ## Overview -We assume that there is an **Shiro Authentication** component that associates a user string and a set of group strings with every NotebookSocket. +We assume that there is an **Shiro Authentication** component that associates a user string and a set of group strings with every NotebookSocket. If you don't set the authentication components yet, please check [Shiro authentication for Apache Zeppelin](./shiroauthentication.html) first. ## Authorization Setting -You can set Zeppelin notebook permissions in each notebooks. Of course only **notebook owners** can change this configuration. +You can set Zeppelin notebook permissions in each notebooks. Of course only **notebook owners** can change this configuration. Just click **Lock icon** and open the permission setting page in your notebook. -As you can see, each Zeppelin notebooks has 3 entities : +As you can see, each Zeppelin notebooks has 3 entities : * Owners ( users or groups ) * Readers ( users or groups ) @@ -42,18 +42,35 @@ As you can see, each Zeppelin notebooks has 3 entities : Fill out the each forms with comma seperated **users** and **groups** configured in `conf/shiro.ini` file. If the form is empty (*), it means that any users can perform that operation. -If someone who doesn't have **read** permission is trying to access the notebook or someone who doesn't have **write** permission is trying to edit the notebook, Zeppelin will ask to login or block the user. +If someone who doesn't have **read** permission is trying to access the notebook or someone who doesn't have **write** permission is trying to edit the notebook, Zeppelin will ask to login or block the user. <center><img src="../assets/themes/zeppelin/img/docs-img/insufficient_privileges.png"></center> -By default when you create a new note, the owner is the user who create it. And the readers/writers is empty which means it is shared publicly. But if you don't want it to be shared by default. You can set `zeppelin.notebook.public` to be false in `zeppelin-site.xml`. +## Separate notebook workspaces (public vs. private) +By default, the authorization rights allow other users to see the newly created note, meaning the workspace is `public`. This behavior is controllable and can be set through either `ZEPPELIN_NOTEBOOK_PUBLIC` variable in `conf/zeppelin-env.sh`, or through `zeppelin.notebook.public` property in `conf/zeppelin-site.xml`. Thus, in order to make newly created note appear only in your `private` workspace by default, you can set either `ZEPPELIN_NOTEBOOK_PUBLIC` to `false` in your `conf/zeppelin-env.sh` as follows: + +``` +export ZEPPELIN_NOTEBOOK_PUBLIC="false" +``` + +or set `zeppelin.notebook.public` property to `false` in `conf/zeppelin-site.xml` as follows: + +``` +<property> + <name>zeppelin.notebook.public</name> + <value>false</value> + <description>Make notebook public by default when created, private otherwise</description> +</property> +``` + +Behind the scenes, when you create a new note only the `owners` field is filled with current user, leaving `readers` and `writers` fields empty. All the notes with at least one empty authorization field are considered to be in `public` workspace. Thus when setting `zeppelin.notebook.public` (or corresponding `ZEPPELIN_NOTEBOOK_PUBLIC`) to false, newly created notes have `readers` and `writers` fields filled with current user, making note appear as in `private` workspace. ## How it works In this section, we will explain the detail about how the notebook authorization works in backend side. ### NotebookServer The [NotebookServer](https://github.com/apache/zeppelin/blob/master/zeppelin-server/src/main/java/org/apache/zeppelin/socket/NotebookServer.java) classifies every notebook operations into three categories: **Read**, **Write**, **Manage**. -Before executing a notebook operation, it checks if the user and the groups associated with the `NotebookSocket` have permissions. +Before executing a notebook operation, it checks if the user and the groups associated with the `NotebookSocket` have permissions. For example, before executing a **Read** operation, it checks if the user and the groups have at least one entity that belongs to the **Reader** entities. ### Notebook REST API call
