Repository: incubator-zeppelin Updated Branches: refs/heads/master 2befbb455 -> 79b2aa43a
Add documentation about setup HTTP basic auth via NGINX ### What is this PR for? Provide a guide to setup basic authentication using NGINX with detailed instruction for users who wants to use NGINX as a separate authentication server. Shiro Security is preferred way to provide a basic authentication for future releases, but we may need to provide a way to workaround when user need other options. ### What type of PR is it? Documentation ### Questions: * Does the licenses files need update? No * Is there breaking changes for older versions? No * Does this needs documentation? No Author: Jesang Yoon <[email protected]> Closes #775 from yoonjs2/add-nginx-auth-documentation and squashes the following commits: 54b8970 [Jesang Yoon] Fix reference url about Shiro security to https://github.com/apache/incubator-zeppelin/blob/master/SECURITY-README.md in document fe0f616 [Jesang Yoon] Merge branch 'master' of https://github.com/apache/incubator-zeppelin into add-nginx-auth-documentation 10f339d [Jesang Yoon] Fix server port naming 4b2223a [Jesang Yoon] Make path to cert and key for HTTPS Ambigious aac4cd4 [Jesang Yoon] Add documentation for explaining enable HTTP basic authentication served by NGINX 3d9e5b3 [Jesang Yoon] Merge remote-tracking branch 'upstream/master' eba0315 [Jesang Yoon] Merge remote-tracking branch 'upstream/master' db8b4da [Jesang Yoon] Merge remote-tracking branch 'upstream/master' 781954b [Jesang Yoon] Interpreter documentation merge with commit #578 af55811 [Jesang Yoon] Merge remote-tracking branch 'origin/master' 079480f [Jesang Yoon] Merge remote-tracking branch 'origin/master' 5f0a6e0 [Jesang Yoon] Merge remote-tracking branch 'origin/master' 4d1503a [Jesang Yoon] Merge remote-tracking branch 'origin/master' 5b091e4 [Jesang Yoon] Fix wrong HTML tags, indention and space between paragraph and tables. Remove unnecessary spaces. 5665dcf [Jesang Yoon] Fix wrong HTML tags, indention and space between paragraph and tables. Remove unnecessary spaces. Project: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/commit/79b2aa43 Tree: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/tree/79b2aa43 Diff: http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/diff/79b2aa43 Branch: refs/heads/master Commit: 79b2aa43af1ac8fb754fd5afaab7cf8f55122376 Parents: 2befbb4 Author: Jesang Yoon <[email protected]> Authored: Tue Mar 15 10:57:08 2016 +0900 Committer: Lee moon soo <[email protected]> Committed: Fri Mar 18 09:33:03 2016 -0700 ---------------------------------------------------------------------- .../authentication-basic-auth-nginx-https.png | Bin 0 -> 206365 bytes .../authentication-basic-auth-nginx-request.png | Bin 0 -> 159005 bytes docs/security/authentication.md | 116 +++++++++++++++++++ 3 files changed, 116 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/79b2aa43/docs/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-https.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-https.png b/docs/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-https.png new file mode 100644 index 0000000..46767ed Binary files /dev/null and b/docs/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-https.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/79b2aa43/docs/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-request.png ---------------------------------------------------------------------- diff --git a/docs/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-request.png b/docs/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-request.png new file mode 100644 index 0000000..6c24073 Binary files /dev/null and b/docs/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-request.png differ http://git-wip-us.apache.org/repos/asf/incubator-zeppelin/blob/79b2aa43/docs/security/authentication.md ---------------------------------------------------------------------- diff --git a/docs/security/authentication.md b/docs/security/authentication.md index 081d419..4806b2f 100644 --- a/docs/security/authentication.md +++ b/docs/security/authentication.md @@ -23,6 +23,122 @@ Authentication is company-specific. One option is to use [Basic Access Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) +### HTTP Basic Authentication using NGINX + +> **Quote from Wikipedia:** NGINX is a web server. It can act as a reverse proxy server for HTTP, HTTPS, SMTP, POP3, and IMAP protocols, as well as a load balancer and an HTTP cache. + +So you can use NGINX server as proxy server to serve HTTP Basic Authentication as a separate process along with Zeppelin server. +Here are instructions how to accomplish the setup NGINX as a front-end authentication server and connect Zeppelin at behind. + +This instruction based on Ubuntu 14.04 LTS but may work with other OS with few configuration changes. + +1. Install NGINX server on your server instance + + You can install NGINX server with same machine where zeppelin installed or separate machine where it is dedicated to serve as proxy server. + + ``` + $ apt-get install nginx + ``` + +1. Setup init script in NGINX + + In most cases, NGINX configuration located under `/etc/nginx/sites-available`. Create your own configuration or add your existing configuration at `/etc/nginx/sites-available`. + + ``` + $ cd /etc/nginx/sites-available + $ touch my-basic-auth + ``` + + Now add this script into `my-basic-auth` file. You can comment out `optional` lines If you want serve Zeppelin under regular HTTP 80 Port. + + ``` + upstream zeppelin { + server [YOUR-ZEPPELIN-SERVER-IP]:8090; + } + + upstream zeppelin-wss { + server [YOUR-ZEPPELIN-SERVER-IP]:8091; + } + + # Zeppelin Website + server { + listen [YOUR-ZEPPELIN-WEB-SERVER-PORT]; + listen 443 ssl; # optional, to serve HTTPS connection + server_name [YOUR-ZEPPELIN-SERVER-HOST]; # for example: zeppelin.mycompany.com + + ssl_certificate [PATH-TO-YOUR-CERT-FILE]; # optional, to serve HTTPS connection + ssl_certificate_key [PATH-TO-YOUR-CERT-KEY-FILE]; # optional, to serve HTTPS connection + + if ($ssl_protocol = "") { + rewrite ^ https://$host$request_uri? permanent; # optional, force to use HTTPS + } + + location / { + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header Host $http_host; + proxy_set_header X-NginX-Proxy true; + proxy_pass http://zeppelin; + proxy_redirect off; + auth_basic "Restricted"; + auth_basic_user_file /etc/nginx/.htpasswd; + } + } + + # Zeppelin Websocket + server { + listen [YOUR-ZEPPELIN-WEBSOCKET-PORT] ssl; # add ssl is optional, to serve HTTPS connection + server_name [YOUR-ZEPPELIN-SERVER-HOST]; # for example: zeppelin.mycompany.com + + ssl_certificate [PATH-TO-YOUR-CERT-FILE]; # optional, to serve HTTPS connection + ssl_certificate_key [PATH-TO-YOUR-CERT-KEY-FILE]; # optional, to serve HTTPS connection + + location / { + proxy_pass http://zeppelin-wss; + proxy_http_version 1.1; + proxy_set_header Upgrade websocket; + proxy_set_header Connection upgrade; + proxy_read_timeout 86400; + } + } + ``` + + Then make a symbolic link to this file from `/etc/nginx/sites-enabled/` to enable configuration above when NGINX reloads. + + ``` + $ ln -s /etc/nginx/sites-enabled/my-basic-auth /etc/nginx/sites-available/my-basic-auth + ``` + +1. Setup user credential into `.htpasswd` file and restart server + + Now you need to setup `.htpasswd` file to serve list of authenticated user credentials for NGINX server. + + ``` + $ cd /etc/nginx + $ htpasswd -c htpasswd [YOUR_ID] + $ NEW passwd: [YOUR_PASSWORD] + $ RE-type new passwd: [YOUR_PASSWORD_AGAIN] + ``` + Or you can use your own apache `.htpasswd` files in other location by setup property `auth_basic_user_file` + + Restart NGINX server. + + ``` + $ service nginx restart + ``` + Then check HTTP Basic Authentication works in browser. If you can see regular basic auth popup and then able to login with credential you entered into `.htpasswd` you are good to go. + + <img src="/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-request.png" /> + <img src="/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-https.png" /> + +1. More security consideration + +* Using HTTPS connection with Basic Authentication is highly recommended since basic auth without encryption may expose your important credential information over the network. +* Using [Shiro Security feature built-into Zeppelin](https://github.com/apache/incubator-zeppelin/blob/master/SECURITY-README.md) is recommended if you prefer all-in-one solution for authentication but NGINX may provides ad-hoc solution for re-use authentication served by your system's NGINX server or in case of you need to separate authentication from zeppelin server. +* It is recommended to isolate direct connection to Zeppelin server from public internet or external services to secure your zeppelin instance from unexpected attack or problems caused by public zone. + +### Another option + Another option is to have an authentication server that can verify user credentials in an LDAP server. If an incoming request to the Zeppelin server does not have a cookie with user information encrypted with the authentication server public key, the user is redirected to the authentication server. Once the user is verified, the authentication server redirects the browser to a specific
