This is an automated email from the ASF dual-hosted git repository.
chengpan pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/zeppelin.git
The following commit(s) were added to refs/heads/master by this push:
new 60aad4275a [ZEPPELIN-6223] Improve grammar and clarity in
SECURITY-README.md for Shiro authentication
60aad4275a is described below
commit 60aad4275adf8164b73f2da525ccae4c15620def
Author: Gyeongtae Park <[email protected]>
AuthorDate: Sun Jul 20 15:07:11 2025 +0900
[ZEPPELIN-6223] Improve grammar and clarity in SECURITY-README.md for Shiro
authentication
### What is this PR for?
This PR improves the grammar, clarity, and structure of SECURITY-README.md,
which explains how Shiro authentication works in Apache Zeppelin.
It fixes typos, updates awkward or outdated phrases, and improves the
consistency of terminology and punctuation. The documentation link has also
been updated to point to the stable 0.12.0 release.
These changes make the document easier to read and maintain, while
providing clearer guidance to users setting up security in Zeppelin.
### What type of PR is it?
Documentation
### Todos
* [x] - Fix typos and grammar issues
* [x] - Improve sentence clarity and consistency
* [x] - Update outdated documentation link
### What is the Jira issue?
* Jira: https://issues.apache.org/jira/browse/ZEPPELIN-6223
### How should this be tested?
* Strongly recommended: add automated unit tests for any new or changed
behavior
* Outline any manual steps to test the PR here.
### Screenshots (if appropriate)
N/A
### Questions:
* Does the license files need to update? No.
* Is there breaking changes for older versions? No.
* Does this needs documentation? No.
Closes #4959 from ParkGyeongTae/ZEPPELIN-6223.
Signed-off-by: Cheng Pan <[email protected]>
---
SECURITY-README.md | 46 +++++++++++++++++++++++++++++-----------------
1 file changed, 29 insertions(+), 17 deletions(-)
diff --git a/SECURITY-README.md b/SECURITY-README.md
index 4ef7440db1..7de758d215 100644
--- a/SECURITY-README.md
+++ b/SECURITY-README.md
@@ -13,23 +13,35 @@ limitations under the License.
-->
# Shiro Authentication
-To connect to Zeppelin, users will be asked to enter their credentials. Once
logged, a user has access to all notes including other users notes.
-This a a first step toward full security as implemented by this pull request
(https://github.com/apache/zeppelin/pull/53).
-Please check [Shiro authentication in Apache
Zeppelin](https://zeppelin.apache.org/docs/snapshot/security/shiroauthentication.html)
in our official website for more detailed information(e.g. How to setup the
security, How to configure user groups and permissions, and etc).
+To connect to Zeppelin, users will be asked to enter their credentials. Once
logged in, a user has access to all notes, including other users' notes.
+This marks the first step toward full security, as introduced in this [pull
request](https://github.com/apache/zeppelin/pull/53).
+
+Please check the [Shiro authentication documentation for Apache
Zeppelin](https://zeppelin.apache.org/docs/0.12.0/setup/security/shiro_authentication.html)
available on our official website for more detailed information (e.g., how to
set up security, how to configure user groups and permissions, etc.).
+
+# Implementation Notes
-# Implementation notes
## Vocabulary
-username, owner and principal are used interchangeably to designate the
currently authenticated user
-## What are we securing ?
-Zeppelin is basically a web application that spawn remote interpreters to run
commands and return HTML fragments to be displayed on the user browser.
-The scope of this PR is to require credentials to access Zeppelin. To achieve
this, we use Apache Shiro.
-## HTTP Endpoint security
-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
-
-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).
+
+The terms *username*, *owner*, and *principal* are used interchangeably to
refer to the currently authenticated user.
+
+## What Are We Securing?
+
+Zeppelin is essentially a web application that spawns remote interpreters to
run commands and return HTML fragments to be displayed in the user's browser.
+To protect user data and access, Zeppelin requires users to log in before
using the application. Authentication is handled using Apache Shiro.
+
+## HTTP Endpoint Security
+
+Apache Shiro acts as a servlet filter between the browser and the exposed
services.
+It handles authentication without requiring additional programming. (See
[Apache Shiro](https://shiro.apache.org) for more information.)
+
+## WebSocket Security
+
+Securing HTTP endpoints alone is not sufficient, since Zeppelin also
communicates with the browser via WebSockets. To secure this channel, we take
the following approach:
+
+1. On startup, the browser requests a ticket via HTTP.
+2. The Apache Shiro servlet filter authenticates the user.
+3. Once authenticated, a ticket is assigned to the user and returned to the
browser.
+
+Every WebSocket message must include both the username and the ticket.
+When receiving a WebSocket message, the server checks that the ticket matches
what was assigned to the username via the HTTP request (step 3 above).
