Repository: incubator-zeppelin Updated Branches: refs/heads/master 686921e60 -> e6447b256
[Zeppelin-661] Add a documentation for Shiro authentication ### What is this PR for? About a month ago, Shiro authentication for Zeppelin is merged by #586. Even though we already have [SECURITY-README.md](https://github.com/apache/incubator-zeppelin/blob/master/SECURITY-README.md), many people do not know about the existence of this file. So I wrote a docs based on `SECURITY-README.md` to the Zeppelin documentation website to guide step by step for Zeppelin users. ### What type of PR is it? Documentation ### Todos * [x] - Add shiro authentication docs * [x] - Add **zeppelin.anonymous.allowed** property in `zeppelin-site.md` * [x] - Indent **Websocket security** section in `SECURITY-README.md` ### Is there a relevant Jira issue? [ZEPPELIN-661](https://issues.apache.org/jira/browse/ZEPPELIN-661) ### How should this be tested? ### 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: Ryu Ah young <[email protected]> Closes #711 from AhyoungRyu/ZEPPELIN-661 and squashes the following commits: 482fc65 [Ryu Ah young] ZEPPELIN-661: ping travis 4fbc5e5 [Ryu Ah young] ZEPPELIN-661: Add the default status information of anon and authcBasic 795f177 [Ryu Ah young] ZEPPELIN-661: indent 'Websocket security' section in SECURITY-README.md f050f8d [Ryu Ah young] ZEPPELIN-661: Add 'zeppelin.anonymous.allowed' property in zeppelin-site.xml to install.md d841a8a [Ryu Ah young] ZEPPELIN-661: Add shiro authentication docs Project: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/commit/e6447b25 Tree: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/tree/e6447b25 Diff: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/diff/e6447b25 Branch: refs/heads/master Commit: e6447b256ab9bb81203bb3ff182b47cfc5de9dc9 Parents: 686921e Author: Ryu Ah young <[email protected]> Authored: Sat Feb 13 17:26:21 2016 +0900 Committer: Felix Cheung <[email protected]> Committed: Mon Feb 15 19:44:50 2016 -0800 ---------------------------------------------------------------------- SECURITY-README.md | 9 +-- docs/_includes/themes/zeppelin/_navigation.html | 3 + .../zeppelin/img/docs-img/zeppelin-login.png | Bin 0 -> 41310 bytes docs/install/install.md | 6 ++ docs/manual/shiroauthentication.md | 72 +++++++++++++++++++ 5 files changed, 84 insertions(+), 6 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/e6447b25/SECURITY-README.md ---------------------------------------------------------------------- diff --git a/SECURITY-README.md b/SECURITY-README.md index 2eb1fd6..a34b4a2 100644 --- a/SECURITY-README.md +++ b/SECURITY-README.md @@ -33,11 +33,8 @@ The scope of this PR is to require credentials to access Zeppelin. To achieve th Apache Shiro sits as a servlet filter between the browser and the exposed services and handles the required authentication without any programming required. (See Apache Shiro for more info). ## Websocket security Securing the HTTP endpoints is not enough, since Zeppelin also communicates with the browser through websockets. To secure this channel, we take the following approach: -1. The browser on startup requests a ticket through HTTP -2. The Apache Shiro Servlet filter handles the user auth -3. Once the user is authenticated, a ticket is assigned to this user and the ticket is returned to the browser + 1. The browser on startup requests a ticket through HTTP + 2. The Apache Shiro Servlet filter handles the user auth + 3. Once the user is authenticated, a ticket is assigned to this user and the ticket is returned to the browser All websockets communications require the username and ticket to be submitted by the browser. Upon receiving a websocket message, the server checks that the ticket received is the one assigned to the username through the HTTP request (step 3 above). - - - http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/e6447b25/docs/_includes/themes/zeppelin/_navigation.html ---------------------------------------------------------------------- diff --git a/docs/_includes/themes/zeppelin/_navigation.html b/docs/_includes/themes/zeppelin/_navigation.html index 22496b8..9eddbf9 100644 --- a/docs/_includes/themes/zeppelin/_navigation.html +++ b/docs/_includes/themes/zeppelin/_navigation.html @@ -88,6 +88,9 @@ <li><a href="{{BASE_PATH}}/development/writingzeppelininterpreter.html">Writing Zeppelin Interpreter</a></li> <li><a href="{{BASE_PATH}}/development/howtocontribute.html">How to contribute (code)</a></li> <li><a href="{{BASE_PATH}}/development/howtocontributewebsite.html">How to contribute (website)</a></li> + <li role="separator" class="divider"></li> + <!-- li><span><b>Shiro Security</b><span></li --> + <li><a href="{{BASE_PATH}}/manual/shiroauthentication.html">Shiro Authentication</a></li> </ul> </li> </ul> http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/e6447b25/docs/assets/themes/zeppelin/img/docs-img/zeppelin-login.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/docs-img/zeppelin-login.png b/docs/assets/themes/zeppelin/img/docs-img/zeppelin-login.png new file mode 100644 index 0000000..522630f Binary files /dev/null and b/docs/assets/themes/zeppelin/img/docs-img/zeppelin-login.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/e6447b25/docs/install/install.md ---------------------------------------------------------------------- diff --git a/docs/install/install.md b/docs/install/install.md index 8afc244..ae737b5 100644 --- a/docs/install/install.md +++ b/docs/install/install.md @@ -76,6 +76,12 @@ You can configure Zeppelin with both **environment variables** in `conf/zeppelin <td>*</td> <td>Enables a way to specify a ',' separated list of allowed origins for rest and websockets. <br /> i.e. http://localhost:8080 </td> </tr> + <tr> + <td>N/A</td> + <td>zeppelin.anonymous.allowed</td> + <td>true</td> + <td>Anonymous user is allowed by default.</td> + </tr> <tr> <td>ZEPPELIN_SERVER_CONTEXT_PATH</td> <td>zeppelin.server.context.path</td> http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/e6447b25/docs/manual/shiroauthentication.md ---------------------------------------------------------------------- diff --git a/docs/manual/shiroauthentication.md b/docs/manual/shiroauthentication.md new file mode 100644 index 0000000..c764885 --- /dev/null +++ b/docs/manual/shiroauthentication.md @@ -0,0 +1,72 @@ +--- +layout: page +title: "Shiro Security for Apache Zeppelin" +description: "" +group: manual +--- +<!-- +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + +http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +--> +{% include JB/setup %} + +# Shiro authentication for Apache Zeppelin +[Apache Shiro](http://shiro.apache.org/) is a powerful and easy-to-use Java security framework that performs authentication, authorization, cryptography, and session management. In this documentation, we will explain step by step how Shiro works for Zeppelin notebook authentication. + +When you connect to Apache Zeppelin, you will be asked to enter your credentials. Once you logged in, then you have access to all notes including other user's notes. + +## Security Setup +You can setup **Zeppelin notebook authentication** in some simple steps. + +####1. Secure the HTTP channel +To secure the HTTP channel, you have to change both **anon** and **authcBasic** settings in `conf/shiro.ini`. In here, **anon** means "the access is anonymous" and **authcBasic** means "basic auth security". + +The default status of them is + +``` +/** = anon +#/** = authcBasic +``` +Deactivate the line "/** = anon" and activate the line "/** = authcBasic" in `conf/shiro.ini` file. + +``` +#/** = anon +/** = authcBasic +``` + +For the further information about `shiro.ini` file format, please refer to [Shiro Configuration](http://shiro.apache.org/configuration.html#Configuration-INISections). + +####2. Secure the Websocket channel +Set to property **zeppelin.anonymous.allowed** to **false** in `conf/zeppelin-site.xml`. If you don't have this file yet, just copy `conf/zeppelin-site.xml.template` to `conf/zeppelin-site.xml`. + +####3. Start Zeppelin + +``` +bin/zeppelin-daemon.sh start (or restart) +``` + +Then you can browse Zeppelin at [http://localhost:8080](http://localhost:8080). + +####4. Login +Finally, you can login using one of the below **username/password** combinations. + +<center><img src="../assets/themes/zeppelin/img/docs-img/zeppelin-login.png" width="40%" height="40%"></center> + +``` +admin = password1 +user1 = password2 +user2 = password3 +``` + +Those combinations are defined in the `conf/shiro.ini` file. + +> **NOTE :** This documentation is originally from [SECURITY-README.md](https://github.com/apache/incubator-zeppelin/blob/master/SECURITY-README.md).
