Skip to content

Commit f9ed92c

Browse files
skorandaskoranda
committed
Add documentation for deploying with mod_wsgi
Add documentation for how to deploy the SATOSA proxy using Apache HTTP Server and mod_wsgi.
1 parent 1723565 commit f9ed92c

File tree

2 files changed

+217
-1
lines changed

2 files changed

+217
-1
lines changed

‎doc/README.md

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -573,7 +573,17 @@ satosa-saml-metadata <path to proxy_conf.yaml> <path to key for signing> <path t
573573

574574
Detailed usage instructions can be viewed by running `satosa-saml-metadata --help`.
575575

576-
# <a name="run" style="color:#000000">Start proxy application</a>
576+
# Running the proxy application
577+
578+
The SATOSA proxy is a Python WSGI application and so may be run using any WSGI compliant web server.
579+
580+
## Using Gunicorn
581+
582+
Gunicorn 'Green Unicorn' is a Python WSGI HTTP Server for UNIX and is the server used most often
583+
to run the proxy. In a production deployment the Gunicorn server is often proxied by a
584+
full featured general purpose web server (in a reverse proxy architecture) such as Nginx or
585+
Apache HTTP Server to help buffer slow clients and enable more sophisticated error page rendering.
586+
577587
Start the proxy server with the following command:
578588
```bash
579589
gunicorn -b<socket address> satosa.wsgi:app --keyfile=<https key> --certfile=<https cert>
@@ -589,3 +599,9 @@ located somewhere else, use the environment variable `SATOSA_CONFIG` to specify
589599
```bash
590600
set SATOSA_CONFIG=/home/user/proxy_conf.yaml
591601
```
602+
603+
## Using Apache HTTP Server and mod\_wsgi
604+
605+
See the [auxiliary documentation for running using mod\_wsgi](mod_wsgi.md).
606+
607+

‎doc/mod_wsgi.md

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# Running SATOSA Using Apache HTTP Server and mod\_wsgi
2+
3+
This document describes how to deploy and run the SATOSA proxy using
4+
Apache HTTP Server and mod\_wsgi. To be concrete this document details
5+
deploying SATOSA on the latest CentOS 7.x release.
6+
7+
## Dependencies
8+
9+
```
10+
yum install epel-release
11+
yum install httpd mod_ssl httpd-devel python34 python34-devel
12+
yum install xmlsec1-openssl gcc curl
13+
```
14+
15+
Install the latest production release of pip and use it to install the latest
16+
production release of mod\_wsgi:
17+
18+
```
19+
curl https://bootstrap.pypa.io/get-pip.py | python3
20+
pip install mod_wsgi
21+
```
22+
23+
Create a `satosa` user to run the WSGI daemon:
24+
25+
```
26+
useradd --home-dir /etc/satosa --no-create-home --system --user-group satosa
27+
```
28+
29+
## Installation
30+
31+
Use pip to install SATOSA:
32+
33+
```
34+
pip install SATOSA
35+
```
36+
37+
To instead install the latest from the master branch on the GitHub repository:
38+
39+
```
40+
yum install git
41+
pip install --upgrade git+https://github.com/IdentityPython/SATOSA.git#egg=SATOSA
42+
```
43+
44+
To upgrade and use the latest release of pySAML2:
45+
46+
```
47+
pip install --upgrade pysaml2
48+
```
49+
50+
## Installation of SATOSA Microservices
51+
52+
```
53+
curl -L -o satosa_microservices.tar.gz \
54+
https://github.com/IdentityPython/satosa_microservices/archive/master.tar.gz \
55+
&& mkdir -p /opt/satosa_microservices \
56+
&& tar -zxf satosa_microservices.tar.gz -C /opt/satosa_microservices --strip-components=1 \
57+
&& rm -f satosa_microservices.tar.gz
58+
```
59+
60+
If you need the LDAP Attribute Store microservice you must also install
61+
ldap3 using pip:
62+
63+
```
64+
pip install ldap3
65+
```
66+
67+
## Apache Configuration
68+
69+
Use the `mod_wsgi-express module-config` command to determine the correct
70+
module path and Python home to add to the Apache configuration. For
71+
example:
72+
73+
```
74+
$ mod_wsgi-express module-config
75+
LoadModule wsgi_module "/usr/lib64/python3.4/site-packages/mod_wsgi/server/mod_wsgi-py34.cpython-34m.so"
76+
WSGIPythonHome "/usr"
77+
```
78+
79+
Edit the Apache config and in the global section (not within a virtual
80+
host) add the `LoadModule` and `WSGIPythonHome` lines as output from the
81+
above command.
82+
83+
Edit the Apache config and in your virtual host configuration add
84+
85+
```
86+
WSGIDaemonProcess satosa processes=2 threads=15 \
87+
display-name=%{GROUP} home=/etc/satosa user=satosa group=satosa \
88+
restart-interval=86400 graceful-timeout=3600 \
89+
python-path=/opt/satosa_microservices/src/satosa/micro_services:/etc/satosa
90+
91+
WSGIApplicationGroup satosa
92+
WSGIProcessGroup satosa
93+
94+
WSGIScriptAlias / /usr/lib/python3.4/site-packages/satosa/wsgi.py
95+
WSGICallableObject app
96+
WSGIImportScript /usr/lib/python3.4/site-packages/satosa/wsgi.py \
97+
process-group=satosa application-group=satosa
98+
```
99+
100+
## SATOSA Configuration
101+
102+
Create the directory `/etc/satosa` and in it the SATOSA `proxy_conf.yaml`
103+
configuration file. For example
104+
105+
```
106+
$ mkdir /etc/satosa
107+
$ cat << EOF > /etc/satosa/proxy_conf.yaml
108+
109+
BASE: https://some.host.org
110+
111+
STATE_ENCRYPTION_KEY: fazmC8yELv38f9PF0kbS
112+
113+
USER_ID_HASH_SALT: i7tmt34rzb2QRDgN1Ggy
114+
115+
INTERNAL_ATTRIBUTES: "/etc/satosa/internal_attributes.yaml"
116+
117+
COOKIE_STATE_NAME: "SATOSA_STATE"
118+
119+
BACKEND_MODULES:
120+
- "/etc/satosa/plugins/saml2_backend.yaml"
121+
122+
FRONTEND_MODULES:
123+
- "/etc/satosa/plugins/ping_frontend.yaml"
124+
- "/etc/satosa/plugins/saml2_frontend.yaml"
125+
126+
MICRO_SERVICES:
127+
- "/etc/satosa/plugins/primary_identifier.yaml"
128+
- "/etc/satosa/plugins/ldap_attribute_store.yaml"
129+
130+
CONSENT:
131+
enable: No
132+
133+
ACCOUNT_LINKING:
134+
enable: No
135+
136+
LOGGING:
137+
version: 1
138+
formatters:
139+
simple:
140+
format: "[%(asctime)s] [%(levelname)s] [%(name)s]: %(message)s"
141+
handlers:
142+
console:
143+
class: logging.StreamHandler
144+
formatter: simple
145+
stream: ext://sys.stderr
146+
loggers:
147+
satosa:
148+
level: INFO
149+
handlers:
150+
- console
151+
propagate: no
152+
root:
153+
level: INFO
154+
handlers:
155+
- console
156+
```
157+
158+
Complete the SATOSA configuration as detailed in your `proxy_conf.yaml`
159+
file. See the [SATOSA configuration reference](./README.md) for details.
160+
161+
After SATOSA is configured restart the Apache server:
162+
163+
164+
```
165+
systemctl restart httpd
166+
```
167+
168+
## Logging
169+
170+
SATOSA log output is sent to the Apache server logs as configured in the
171+
Apache configuration.
172+
173+
174+
## Overriding Errors
175+
176+
The body of the HTML sent by SATOSA when it encounters an error condition
177+
is not user friendly. To configure Apache to catch errors returned by
178+
SATOSA and override the HTML displayed add to the global Apache config
179+
180+
```
181+
WSGIErrorOverride On
182+
```
183+
184+
Then in the virtual host add before the WSGIScriptAlias for example
185+
186+
```
187+
ErrorDocument 404 /error.html
188+
ErrorDocument 500 /error.html
189+
190+
Alias /error.html /var/www/html/error.html
191+
```
192+
193+
194+
195+
196+
197+
198+
199+
200+

0 commit comments

Comments
 (0)