You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@zeppelin.apache.org by fe...@apache.org on 2016/02/16 04:44:57 UTC
incubator-zeppelin git commit: [Zeppelin-661] Add a documentation for
Shiro authentication
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 <fb...@hanmail.net>
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 <fb...@hanmail.net>
Authored: Sat Feb 13 17:26:21 2016 +0900
Committer: Felix Cheung <fe...@apache.org>
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).