diff --git a/SECURITY-README.md b/SECURITY-README.md
index 4ef7440db12..7de758d215f 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).