Skip to content

Commit aac4cd4

Browse files
yoonjs2yoonjs2
committed
Add documentation for explaining enable HTTP basic authentication served by NGINX
1 parent 3d9e5b3 commit aac4cd4

File tree

3 files changed

+116
-0
lines changed

3 files changed

+116
-0
lines changed

‎docs/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-https.png‎

202 KB
Loading

‎docs/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-request.png‎

155 KB
Loading

‎docs/security/authentication.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -23,6 +23,122 @@ Authentication is company-specific.
2323

2424
One option is to use [Basic Access Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication)
2525

26+
### HTTP Basic Authentication using NGINX
27+
28+
> **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.
29+
30+
So you can use NGINX server as proxy server to serve HTTP Basic Authentication as a separate process along with Zeppelin server.
31+
Here are instructions how to accomplish the setup NGINX as a front-end authentication server and connect Zeppelin at behind.
32+
33+
This instruction based on Ubuntu 14.04 LTS but may work with other OS with few configuration changes.
34+
35+
1. Install NGINX server on your server instance
36+
37+
You can install NGINX server with same machine where zeppelin installed or separate machine where it is dedicated to serve as proxy server.
38+
39+
```
40+
$ apt-get install nginx
41+
```
42+
43+
1. Setup init script in NGINX
44+
45+
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`.
46+
47+
```
48+
$ cd /etc/nginx/sites-available
49+
$ touch my-basic-auth
50+
```
51+
52+
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.
53+
54+
```
55+
upstream zeppelin {
56+
server [YOUR-ZEPPELIN-SERVER-IP]:8090;
57+
}
58+
59+
upstream zeppelin-wss {
60+
server [YOUR-ZEPPELIN-SERVER-IP]:8091;
61+
}
62+
63+
# Zeppelin Website
64+
server {
65+
listen 80;
66+
listen 443 ssl; # optional, to serve HTTPS connection
67+
server_name [YOUR-ZEPPELIN-SERVER-HOST]; # for example: zeppelin.mycompany.com
68+
69+
ssl_certificate /etc/nginx/conf.d/yimocall.chained.crt; # optional, to serve HTTPS connection
70+
ssl_certificate_key /etc/nginx/conf.d/yimocall.key; # optional, to serve HTTPS connection
71+
72+
if ($ssl_protocol = "") {
73+
rewrite ^ https://$host$request_uri? permanent; # optional, force to use HTTPS
74+
}
75+
76+
location / {
77+
proxy_set_header X-Real-IP $remote_addr;
78+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
79+
proxy_set_header Host $http_host;
80+
proxy_set_header X-NginX-Proxy true;
81+
proxy_pass http://zeppelin;
82+
proxy_redirect off;
83+
auth_basic "Restricted";
84+
auth_basic_user_file /etc/nginx/.htpasswd;
85+
}
86+
}
87+
88+
# Zeppelin Websocket
89+
server {
90+
listen 8091 ssl;
91+
server_name [YOUR-ZEPPELIN-SERVER-HOST]; # for example: zeppelin.mycompany.com
92+
93+
ssl_certificate /etc/nginx/conf.d/yimocall.chained.crt; # optional, to serve HTTPS connection
94+
ssl_certificate_key /etc/nginx/conf.d/yimocall.key; # optional, to serve HTTPS connection
95+
96+
location / {
97+
proxy_pass http://zeppelin-wss;
98+
proxy_http_version 1.1;
99+
proxy_set_header Upgrade websocket;
100+
proxy_set_header Connection upgrade;
101+
proxy_read_timeout 86400;
102+
}
103+
}
104+
```
105+
106+
Then make a symbolic link to this file from `/etc/nginx/sites-enabled/` to enable configuration above when NGINX reloads.
107+
108+
```
109+
$ ln -s /etc/nginx/sites-enabled/my-basic-auth /etc/nginx/sites-available/my-basic-auth
110+
```
111+
112+
1. Setup user credential into `.htpasswd` file and restart server
113+
114+
Now you need to setup `.htpasswd` file to serve list of authenticated user credentials for NGINX server.
115+
116+
```
117+
$ cd /etc/nginx
118+
$ htpasswd -c htpasswd [YOUR_ID]
119+
$ NEW passwd: [YOUR_PASSWORD]
120+
$ RE-type new passwd: [YOUR_PASSWORD_AGAIN]
121+
```
122+
Or you can use your own apache `.htpasswd` files in other location by setup property `auth_basic_user_file`
123+
124+
Restart NGINX server.
125+
126+
```
127+
$ service nginx restart
128+
```
129+
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.
130+
131+
<img src="/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-request.png" />
132+
<img src="/assets/themes/zeppelin/img/screenshots/authentication-basic-auth-nginx-https.png" />
133+
134+
1. More security consideration
135+
136+
* Using HTTPS connection with Basic Authentication is highly recommended since basic auth without encryption may expose your important credential information over the network.
137+
* Using [Shiro Security feature built-into Zeppelin](https://github.com/apache/incubator-zeppelin/pull/53) 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.
138+
* 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.
139+
140+
### Another option
141+
26142
Another option is to have an authentication server that can verify user credentials in an LDAP server.
27143
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
28144
is redirected to the authentication server. Once the user is verified, the authentication server redirects the browser to a specific

0 commit comments

Comments
 (0)