Skip to content

[ZEPPELIN-6223] Improve grammar and clarity in SECURITY-README.md for Shiro authentication #4959

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
46 changes: 29 additions & 17 deletions SECURITY-README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
The scope of this pull request is to require user credentials to access Zeppelin. To achieve this, we use Apache Shiro.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the words of this line are strange, this is user-facing docs, not a PR description

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@pan3793
Thanks for the feedback! I've updated the sentence to better fit a user-facing documentation tone. Let me know if you have any further suggestions.


## 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).
Loading