README.md 18.5 KB
Newer Older
Marco Malavolti's avatar
Marco Malavolti committed
1
# EduGAIN Connectivity Check Service - ECCS
Marco Malavolti's avatar
Marco Malavolti committed
2

Marco Malavolti's avatar
Marco Malavolti committed
3
4
5
6
7
8
9
10
1. [Introduction](#introduction)
2. [Check Performed on the IdPs](#check-performed-on-the-idps)
3. [Limitations](#limitations)
4. [Disable Checks](#disable-checks)
5. [On-line interface](#on-line-interface)
6. [Requirements Hardware](#requirements-hardware)
7. [Requirements Software](#requirements-software)
8. [HOWTO Install and Configure](#howto-install-and-configure)
Marco Malavolti's avatar
Marco Malavolti committed
11
   * [Python 3](#python-3)
Marco Malavolti's avatar
Marco Malavolti committed
12
13
     + [CentOS 7 requirements](#centos-7-requirements)
     + [Debian requirements](#debian-requirements)
Marco Malavolti's avatar
Marco Malavolti committed
14
15
16
17
18
19
20
21
22
23
24
25
     + [Install](#install)
   * [Install the Chromedriver](#install-the-chromedriver)
   * [Install Google Chrome needed by Selenium](#install-google-chrome-needed-by-selenium)
   * [ECCS Script](#eccs-script)
     + [Install](#install-1)
     + [Configure](#configure)
     + [Execute](#execute)    
9. [ECCS API Server (UWSGI)](#eccs-api-server-uwsgi)
   * [Install](#install-1)
   * [Configure](#configure-1)
   * [Utility](#utility)
10. [ECCS API JSON](#eccs-api-json)
26
27
28
29
11. [User Interface](#user-interface)
    * [User interface parameters](#user-interface-parameters)
12. [Utility for web interface](#utility-for-web-interface)
13. [Utility for developers](#utility-for-developers)
Marco Malavolti's avatar
Marco Malavolti committed
30
    * [ECCS API Development Server](#eccs-api-development-server)
31
14. [Authors](#authors)
Marco Malavolti's avatar
Marco Malavolti committed
32

33
## Introduction
Marco Malavolti's avatar
Marco Malavolti committed
34

35
The purpose of the eduGAIN Connectivity Check is to identify eduGAIN Identity Providers (IdP) that are not properly configured. In particular it checks if an IdP properly loads and consumes SAML2 metadata which contains the eduGAIN Service Providers (SP). The check results are published on the public eduGAIN Connectivity Check web page ([https://technical.edugain.org/eccs](https://technical.edugain.org/eccs)). The main purpose is to increase the service overall quality and user experience of the eduGAIN interfederation service by making Federation and Identity Provider operators aware of configuration problems.
Marco Malavolti's avatar
Marco Malavolti committed
36
37
38
39
40

The check is performed by sending a SAML authentication request to each eduGAIN IdP and then follow the various HTTP redirects. The expected result is a login form that allows users to authenticate (typically with username/password) or an error message of some form. For those Identity Providers that output an error message, it can be assumed that they don't consume eduGAIN metadata properly or that they suffer from another configuration problem. There are some cases where the check will generate false positives, therefore IdPs can be excluded from checks as is described below.

The Identity Providers are checked once per day. Therefore, the login requests should not have any significant effect on the log entries/statistics of an Identity Provider. Also, no actual login is performed because the check cannot authenticate users due to missing username and password for the IdPs. Only Identity Providers are checked but not the Service Providers.

41
## Check Performed on the IdPs
Marco Malavolti's avatar
Marco Malavolti committed
42

43
The check follows the steps:
Marco Malavolti's avatar
Marco Malavolti committed
44
45
46

1. It retrieves the eduGAIN IdPs from eduGAIN Operator Team database via a JSON interface

Marco Malavolti's avatar
Marco Malavolti committed
47
2. For each IdP, that hasn't been disabled manually by the eduGAIN Operations Team or dynamically by `robots.txt` (explained below) and that has a valid SSL certificate on its HTTP-Redirect Location, it performs an IdP-initiated SSO with SAML Authentication Request for two SP belonging two different NREN, members of eduGAIN interfederation, and for one fake SP. It expects to find the HTML form with username and password fields on the "good" SPs and an error or other on the "bad" SP. If an IdP uses frames on its Login page, the check follows only the first one on each redirected pages. If an IdP uses HTTP Basic Authentication, the check searches '401 Unauthorized' string into the web page content presented and establish the correct behaviour of the IdP. Therefore, no complete login will happen at the Identity Provider because the check stops at the login page or at SSL Certificate validation.
48
The SAML authentication request is not signed. Therefore, an authentication request for any eduGAIN SP could be created because the SP's private key is not needed.
Marco Malavolti's avatar
Marco Malavolti committed
49
The SPs HTTP-Post Assertion Consumer Service URLs used by the check are retrieved by `sps-metadata.xml` into the "input" directory. The 'validation' method used to validate the "sps-metadata.xml" is a deployer decision, but a solution is provided on the `README-SPS-METADATA.md` file.
Marco Malavolti's avatar
Marco Malavolti committed
50

51
52
53
54
55
3. If the check fails for an IdP the first time, it will be checked again at the end of the execution for a second time before exit.

4. It keeps the results of the last 7 days, but it can be increased by the deployers.

## Limitations
Marco Malavolti's avatar
Marco Malavolti committed
56
57
58
59
60

There are some situations where the check cannot work reliably. In those cases it is possible to disable the check for a particular IdP. The so far known cases where the check might generate a false negative are:

* IdP does not support HTTP or HTTPS with at least SSLv3 or TLS1 or newer (these IdPs are insecure anyway)
* IdP is part of a Hub & Spoke federation (some of them manually have to first approve eduGAIN SPs)
61
* IdP does not use web-based login form (e.g. Account Chooser Authentication or X.509 login)
Marco Malavolti's avatar
Marco Malavolti committed
62

63
## Disable Checks
Marco Malavolti's avatar
Marco Malavolti committed
64

65
In cases where an IdP cannot be reliably checked, it is necessary to create or enrich the `robots.txt` file on the IdP's web root dir with:
66
67
68
69
70

```bash
User-agent: ECCS
Disallow: /
```
Marco Malavolti's avatar
Marco Malavolti committed
71

72
If an IdP is not able to create its own `robots.txt`, it can be disabled by an eduGAIN Operation Team member by setting the dictionary `IDPS_DISABLED_DICT` into `eccs_properties.py` with a line in the form:
Marco Malavolti's avatar
Marco Malavolti committed
73

Marco Malavolti's avatar
Marco Malavolti committed
74
`<idp-entity-id>':'<eccs-check-disabling-reason>`
Marco Malavolti's avatar
Marco Malavolti committed
75
76


77
## On-line interface
Marco Malavolti's avatar
Marco Malavolti committed
78
79
80
81

The tool uses following status for IdPs:

* ERROR (red):
Marco Malavolti's avatar
Marco Malavolti committed
82
  * The IdP's response contains an HTTP Error or the web page returned does not look like a login page.
83
    * **Unable-To-Check**: considers those IdPs that do not load a standard username/password login page and do not return messages like "*No return endpoint available for relying party*" or "*No metadata found for relying party"*.
Marco Malavolti's avatar
Marco Malavolti committed
84
85
    * **Timeout**: considers those IdPs that do not load a standard username/password login page within 60 seconds.
    * **Connection-Error**: considers those IdPs that are not reachable due to a connection problem. View the "Page Source" value to discover which problem the IdP has. 
Marco Malavolti's avatar
Marco Malavolti committed
86
    * **IdP-Error**: considers those IdPs that the web page returned does not contain a Login Form and reports an unspecified error such as "*An error occured*". This has been seen on Micrsoft ADFS based IdPs
Marco Malavolti's avatar
Marco Malavolti committed
87
  * The IdP most likely does not consume the eduGAIN metadata correctly.
Marco Malavolti's avatar
Marco Malavolti committed
88
    A typical case that falls into this category is when an IdP returns a message "*No return endpoint available for relying party*" or "*No metadata found for relying party*":
Marco Malavolti's avatar
Marco Malavolti committed
89
90
91
    * **No-eduGAIN-Metadata**
  * The IdP has a problem with its SSL certificate:
    * **SSL-Error**
Marco Malavolti's avatar
Marco Malavolti committed
92
93
* OK (green):
  * The IdP most likely correctly consumes eduGAIN metadata and returns a valid login page. This is no guarantee that login on this IdP works for all eduGAIN services but if the check is passed for an IdP, this is probable.
Marco Malavolti's avatar
Marco Malavolti committed
94
* DISABLED (white)
Marco Malavolti's avatar
Marco Malavolti committed
95
  * The IdP is excluded because it cannot be checked reliably. The "*Page Source*" column, when an entity is disabled, shows the reason of the disabling.
Marco Malavolti's avatar
Marco Malavolti committed
96

97
## Requirements Hardware
98

Marco Malavolti's avatar
Marco Malavolti committed
99
* OS: Debian 9, CentOS 7.8 (tested)
100
101
* HDD: 10 GB
* RAM: 4 GB
102
* CPU: >= 2 vCPU (suggested)
Marco Malavolti's avatar
Marco Malavolti committed
103
* ARCH: 64 Bit
104

105
## Requirements Software
106
107

* Apache Server + WSGI
108
* Python 3 (tested with v3.9.1, v3.10.4)
Marco Malavolti's avatar
Marco Malavolti committed
109
* Selenium + Google Chrome Web Brower (tested with v91.0.4472.164, v100.0.4896.127)
110
* Chromedriver (tested with v91.0.4472.101, v100.0.4896.60)
Marco Malavolti's avatar
Marco Malavolti committed
111
* Git
112
* PHP
113

114
## HOWTO Install and Configure
115

116
### Download ECCS Repository
117

Marco Malavolti's avatar
Marco Malavolti committed
118
* `cd $HOME ; git clone https://gitlab.geant.org/edugain/eccs.git`
119

120
### Install Python 3
Marco Malavolti's avatar
Marco Malavolti committed
121

122
#### CentOS 7 requirements
Marco Malavolti's avatar
Marco Malavolti committed
123
124
125
126

1. Update the system packages:
   * `sudo yum -y update`

127
128
2. Install the YUM utils:
   * `sudo yum install yum-utils`
Marco Malavolti's avatar
Marco Malavolti committed
129
130

3. Install needed packages to build python:
131
   * `sudo yum-builddep python3`
Marco Malavolti's avatar
Marco Malavolti committed
132

133
134
135
136
137
138
139
   If you want to use Python 3.10, you need OpenSSL >= 1.1.1:
   * `sudo yum install openssl11 openssl11-devel`
   * `sudo mkdir /usr/local/openssl11`
   * `sudo cd /usr/local/openssl11`
   * `sudo ln -s /usr/lib64/openssl11 lib`
   * `sudo ln -s /usr/include/openssl11 include`

Marco Malavolti's avatar
Marco Malavolti committed
140
141
142
4. Install Git:
   * `sudo yum -y install git`

143
#### Debian requirements
144
145
146
147

1. Update the system packages:
   * `sudo apt update ; sudo apt upgrade -y`

148
2. Install needed packages to build python3:
149
   * `sudo apt-get build-dep python3 libffi-dev libssl-dev zlib-dev`
150

Marco Malavolti's avatar
Marco Malavolti committed
151
152
153
3. Install Git:
   * `sudo apt install git`

154
#### Install
155

Marco Malavolti's avatar
Marco Malavolti committed
156
1. Download the last version of Python 3 from https://www.python.org/downloads/source/ into your home:
157
   * `wget https://www.python.org/ftp/python/3.10.4/Python-3.10.4.tgz -O $HOME/eccs/Python-3.10.4.tgz`
158

Marco Malavolti's avatar
Marco Malavolti committed
159
2. Extract Python source package:
Marco Malavolti's avatar
Marco Malavolti committed
160
   * `cd $HOME/eccs/`
161
   * `tar xzf Python-3.10.4.tgz`
162

Marco Malavolti's avatar
Marco Malavolti committed
163
3. Build Python from the source package:
164
165
166
167
168
169
170
171
172
   * Debian:
     * `cd $HOME/eccs/Python-3.10.4`
     * `./configure --prefix=$HOME/eccs/python`
     * `make`

   * Centos 7:
     * `cd $HOME/eccs/Python-3.10.4`
     * `./configure --prefix=$HOME/eccs/python --with-openssl=/usr/local/openssl11`
     * `make`
173

Marco Malavolti's avatar
Marco Malavolti committed
174
4. Install Python 3 under `$HOME/eccs/python`:
175
   * `make install`
Marco Malavolti's avatar
Marco Malavolti committed
176
   * `$HOME/eccs/python/bin/python3 --version`
177
   * `$HOME/eccs/python/bin/python3 -c "import ssl; print (ssl.OPENSSL_VERSION)"`
178
 
179
   This will install python3 under your $HOME/eccs/python directory.
180
181
   
5. Remove useless things:
182
   * `rm -Rf $HOME/eccs/Python-3.10.4 $HOME/eccs/Python-3.10.4.tgz`
183

184
### Install Google Chrome needed by Selenium
185

Marco Malavolti's avatar
Marco Malavolti committed
186
* Debian (64 bit):
Marco Malavolti's avatar
Marco Malavolti committed
187
  * `cd $HOME/eccs`
Marco Malavolti's avatar
Marco Malavolti committed
188
189
  * `sudo wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb`
  * `sudo apt install ./google-chrome-stable_current_amd64.deb`
Marco Malavolti's avatar
Marco Malavolti committed
190

Marco Malavolti's avatar
Marco Malavolti committed
191
* CentOS (64 bit):
Marco Malavolti's avatar
Marco Malavolti committed
192
  * `cd $HOME/eccs`
Marco Malavolti's avatar
Marco Malavolti committed
193
194
  * `sudo wget https://dl.google.com/linux/direct/google-chrome-stable_current_x86_64.rpm`
  * `sudo yum install ./google-chrome-stable_current_x86_64.rpm`
195

196
### Install the Chromedriver
197

Marco Malavolti's avatar
Marco Malavolti committed
198
199
1. Find out which version of Chromium you are using:
   * Debian 9 (stretch):
200
     * `google-chrome -version` => Google Chrome 100.0.4896.127
Marco Malavolti's avatar
Marco Malavolti committed
201
   * CentOS 7.8:
202
     * `google-chrome -version` => Google Chrome 100.0.4896.127
Marco Malavolti's avatar
Marco Malavolti committed
203

204
2. Take the Chrome version number, remove the last part, and append the result to URL "`https://chromedriver.storage.googleapis.com/LATEST_RELEASE_`". For example, with Chrome version 100.0.4896.127, you'd get a URL "`https://chromedriver.storage.googleapis.com/LATEST_RELEASE_100.0.4896`".
Marco Malavolti's avatar
Marco Malavolti committed
205

206
3. Use the URL created in the last step to discover the version of ChromeDriver to use. For example, the above URL will get your a file containing "100.0.4896.60".
Marco Malavolti's avatar
Marco Malavolti committed
207

208
4. Use the version number retrieved from the previous step to construct the URL to download ChromeDriver. With version `100.0.4896.60`, the URL would be "https://chromedriver.storage.googleapis.com/index.html?path=100.0.4896.60/"
209

Marco Malavolti's avatar
Marco Malavolti committed
210
5. Download the Chromedriver and extract it with:
Marco Malavolti's avatar
Marco Malavolti committed
211
   * `cd $HOME/eccs`
212
   * `wget https://chromedriver.storage.googleapis.com/100.0.4896.60/chromedriver_linux64.zip`
Marco Malavolti's avatar
Marco Malavolti committed
213
   * `unzip chromedriver_linux64.zip`
Marco Malavolti's avatar
Marco Malavolti committed
214
   * `rm chromedriver_linux64.zip google-chrome-stable_current_amd64.deb`
Marco Malavolti's avatar
Marco Malavolti committed
215
216
217

**Note:**
After the initial download, it is recommended that you occasionally go through the above process again to see if there are any bug fix releases.
218

219
### ECCS Script
Marco Malavolti's avatar
Marco Malavolti committed
220

221
#### Install and Configure the Virtual Environment
Marco Malavolti's avatar
Marco Malavolti committed
222

Marco Malavolti's avatar
Marco Malavolti committed
223
224
225
226
227
228
* `cd $HOME/eccs`
* `./python/bin/python3 -m pip install virtualenv`
* `$HOME/eccs/python/bin/virtualenv --python=$HOME/eccs/python/bin/python3 eccs-venv`
* `$HOME/eccs/eccs-venv/bin/python3 -m pip install --upgrade pip`
* `source eccs-venv/bin/activate`   (`deactivate` to exit Virtualenv)
  * `python3 -m pip install -r requirements.txt`
229

230
#### Configure ECCS
231

Marco Malavolti's avatar
Marco Malavolti committed
232
1. Configure ECCS properties:
233
234
   * `cp $HOME/eccs/eccs_properties.py.template $HOME/eccs/eccs_properties.py`
   * `vim $HOME/eccs/eccs_properties.py` (and change it upon your needs)
235

236
2. Change `PATH` by adding the virtualenv Python `bin` dir:
237
238
   * CentOS:
     * `vim $HOME/.bash_profile`
Marco Malavolti's avatar
Marco Malavolti committed
239
240
241
     * Add the following lines at the tail:
       
       ```bash
Marco Malavolti's avatar
Marco Malavolti committed
242
       # set PATH for ECCS
243
       if [ -d "$HOME/eccs" ]; then
Marco Malavolti's avatar
Marco Malavolti committed
244
          PATH="$HOME/eccs/eccs-venv/bin:$PATH"
Marco Malavolti's avatar
Marco Malavolti committed
245
246
247
       fi
       ```

Marco Malavolti's avatar
Marco Malavolti committed
248
249
     * `source $HOME/.bash_profile`

250
   * Debian:
Marco Malavolti's avatar
Marco Malavolti committed
251
     * `vim $HOME/.bash_profile`
Marco Malavolti's avatar
Marco Malavolti committed
252
253
254
     * Add the following lines at the tail:
       
       ```bash
Marco Malavolti's avatar
Marco Malavolti committed
255
       # set PATH for ECCS
256
       if [ -d "$HOME/eccs" ]; then
Marco Malavolti's avatar
Marco Malavolti committed
257
          PATH="$HOME/eccs/eccs-venv/bin:$PATH"
Marco Malavolti's avatar
Marco Malavolti committed
258
259
260
       fi
       ```

Marco Malavolti's avatar
Marco Malavolti committed
261
262
     * `source $HOME/.bash_profile`

Marco Malavolti's avatar
Marco Malavolti committed
263
3. Configure the cron job that runs the ECCS script:
264
   * `crontab -e`
265

266
     ```bash
Marco Malavolti's avatar
Marco Malavolti committed
267
268
     SHELL=/bin/bash

Marco Malavolti's avatar
Marco Malavolti committed
269
     0 4 * * * /bin/bash $HOME/eccs/cleanAndRunEccs.sh > $HOME/eccs/logs/eccs-cron.log 2>&1
270
     ```
Marco Malavolti's avatar
Marco Malavolti committed
271

Marco Malavolti's avatar
Marco Malavolti committed
272
273
274
275
276
277
     The script takes about 2 hours to check 4666 IDPs, so its execution is suggested in the early morning,before the users start using the tool. 
     The `eccs-cron.log` file will contains:
        * The execution time of the entire ECCS script
        * Each failed IdP checked again and its result
        * The result of the entire ECCS script executed

278
### Execute
279

Marco Malavolti's avatar
Marco Malavolti committed
280
281
282
283
284
285
286
  * `cd $HOME/eccs`
  * `./cleanAndRunEccs.py` (to run a full and clean check)
  * `./runEccs.py` (to run a full check on the existing inputs)
  * `./runEccs.py --idp <IDP-ENTITYID>` (to run check on a single IdP)
  * `./runEccs.py --test` (to run a full check without effects)
  * `./runEccs.py --idp <IDP-ENTITYID> --test` (to run check on a single IdP without effects)
  * `./runEccs.py --idp <IDP-ENTITYID> --replace` (to run check on a single IdP and replace, or add, a result)
287

Marco Malavolti's avatar
Marco Malavolti committed
288
  If something prevent the good execution of the ECCS's check, the `logs/failed-cmd.sh` file will be not empty at the end of the execution.
Marco Malavolti's avatar
Marco Malavolti committed
289

Marco Malavolti's avatar
Marco Malavolti committed
290
  The "--test" parameter will not change the result of ECCS, but will write the output on the `logs/stdout_idp_YYYY-MM-DD.log`,`logs/stderr_idp_YYYY-MM-DD.log` and `logs/failed-cmd-idp.sh` files if the argument "--test" will be used.
Marco Malavolti's avatar
Marco Malavolti committed
291

292
## ECCS API Server (uWSGI)
Marco Malavolti's avatar
Marco Malavolti committed
293

294
### Install
Marco Malavolti's avatar
Marco Malavolti committed
295

296
297
298
299
300
1. Install requirements:
   * Debian:
     * `sudo apt-get install libpcre3 libpcre3-dev libapache2-mod-proxy-uwsgi build-essentials python3-dev unzip`
   * CentOS:
     * `sudo yum install mod_proxy_uwsgi unzip`
Marco Malavolti's avatar
Marco Malavolti committed
301
     * Configure SElinux to enable ECCS:
Marco Malavolti's avatar
Marco Malavolti committed
302
       * `sudo semanage fcontext -a -t httpd_sys_content_t $HOME/eccs/eccs.conf`
Marco Malavolti's avatar
Marco Malavolti committed
303
       * `sudo restorecon -v $HOME/eccs/eccs.conf`
Marco Malavolti's avatar
Marco Malavolti committed
304
       * `sudo semanage fcontext -a -t httpd_sys_content_t $HOME/eccs/html(/.*)?`
Marco Malavolti's avatar
Marco Malavolti committed
305
       * `sudo restorecon -R -v "$HOME/eccs/html/"`
306
307
       * `sudo setsebool -P httpd_can_network_connect 1`
 
308
### Configure
Marco Malavolti's avatar
Marco Malavolti committed
309

Marco Malavolti's avatar
Marco Malavolti committed
310
311
312
313
314
315
316
1. Add the systemd service to enable ECCS API:
   * `cd $HOME/eccs`
   * `cp eccs.ini.template eccs.ini`
   * `cp eccs.service.template eccs.service`
   * `vim eccs.ini` (and change "`uid`", "`gid`" and "`base`" values opportunely)
   * `vim eccs.service` (and change "`User`","`Group`","`WorkingDirectory`","`RuntimeDirectory`","`ExecStart`" values opportunely)
   * `sudo cp $HOME/eccs/eccs.service /etc/systemd/system/eccs.service`
317
   * `sudo systemctl daemon-reload`
Marco Malavolti's avatar
Marco Malavolti committed
318
319
   * `sudo systemctl enable eccs.service`
   * `sudo systemctl start eccs.service`
320

Marco Malavolti's avatar
Marco Malavolti committed
321
2. Configure Apache for ECCS web side:
322
   * Debian:
Marco Malavolti's avatar
Marco Malavolti committed
323
     * `sudo cp $HOME/eccs/eccs-debian.conf /etc/apache2/conf-available/eccs.conf`
324
     * `sudo vim /etc/apache2/conf-available/eccs.conf` (and change the file opportunely)
Marco Malavolti's avatar
Marco Malavolti committed
325
     * `sudo a2enconf eccs.conf`
326
     * `sudo a2enmod proxy_uwsgi`
327
328
329
     * `sudo chgrp www-data $HOME ; sudo chmod g+rx $HOME` (Apache needs permission to access the $HOME dir)
     * `sudo systemctl restart apache2.service`
   * CentOS:
Marco Malavolti's avatar
Marco Malavolti committed
330
     * `sudo cp $HOME/eccs/eccs-centos.conf /etc/httpd/conf.d/eccs.conf`
331
332
     * `sudo chgrp apache $HOME ; sudo apache g+rx $HOME` (Apache needs permission to access the $HOME dir)
     * `sudo systemctl restart httpd.service`
333

Marco Malavolti's avatar
Marco Malavolti committed
334
3. Restart API WSGI server each day before the ECCS script:
335
336
   * `crontab -e`

Marco Malavolti's avatar
Marco Malavolti committed
337
338
     ```bash
     SHELL=/bin/bash
339

Marco Malavolti's avatar
Marco Malavolti committed
340
341
     0 3 * * * /usr/bin/touch $HOME/eccs/eccs.ini
     ```
342

Marco Malavolti's avatar
Marco Malavolti committed
343
     This cron job must be executed prior to the ECCS script because it updates the date to the current day.
Marco Malavolti's avatar
Marco Malavolti committed
344

345
### Utility
346
347
348

To perform a restart after an API change use the following command:

Marco Malavolti's avatar
Marco Malavolti committed
349
* `touch $HOME/eccs/eccs.ini`
350

351
## ECCS API JSON
352

353
* `/api/eccsresults` (Return the results of the last check ready for ECCS web interface)
Marco Malavolti's avatar
Marco Malavolti committed
354
* `/api/eccsresults?<parameter1>=<value1>&<parameter2>=<value2>`:
355
  * `date=2020-02-20` (select date)
Marco Malavolti's avatar
Marco Malavolti committed
356
  * `idp=https://idp.example.org/idp/shibboleth` (select a specific idp)
Marco Malavolti's avatar
Marco Malavolti committed
357
  * `status=` (select specific ECCS status)
358
359
360
    * 'OK'
    * 'ERROR'
    * 'DISABLED'
Marco Malavolti's avatar
Marco Malavolti committed
361
362
363
364
  * `check_result=`
    * `OK`
    * `Timeout`
    * `Connection-Error`
Marco Malavolti's avatar
Marco Malavolti committed
365
    * `IdP-Error`
Marco Malavolti's avatar
Marco Malavolti committed
366
367
    * `No-eduGAIN-Metadata`
    * `SSL-Error`
368
    * `Unable-To-Check`
Marco Malavolti's avatar
Marco Malavolti committed
369
    * `DISABLED`
370
  * `reg_auth=https://reg.auth.example.org` (select a specific Registration Authority)
371
  * `format=simple` (retrieve results in a simple format)
372
373
* `/api/fedstats`
* `/api/fedstats?reg_auth=https://reg.auth.example.org`:
374

Marco Malavolti's avatar
Marco Malavolti committed
375
## User interface
376

Marco Malavolti's avatar
Marco Malavolti committed
377
The eduGAIN Connectivity Check Service web page is available at https://technical.edugain.org/eccs
Marco Malavolti's avatar
Marco Malavolti committed
378

379
### User interface parameters
Marco Malavolti's avatar
Marco Malavolti committed
380
381
382
383
384
385
386
387
388
389
390

| Parameter name | Example                                      |
| -------------- | -------------------------------------------- |
| `date`         | `date=2020-02-20`                            |
| `reg_auth`     | `reg_auth=https://reg.auth.example.org`      |
| `idp`          | `idp=https://idp.example.org/idp/shibboleth` |
| `status`       | `status=ERROR`                               |
| `check_result` | `check_result=Timeout`                       |

**Example:**

Marco Malavolti's avatar
Marco Malavolti committed
391
`https://technical.edugain.org/eccs?reg_auth=http://www.idem.garr.it/&check_result=SSL-Error`
Marco Malavolti's avatar
Marco Malavolti committed
392

393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
## Utility for web interface

The available dates are provided by the first and the last file created into the `output/` directory,
remember to change its path into `web/eccs.php` file.

### Clean old results

To clean the ECCS results from files older than last 7 days use (modify it on your needs):

* `crontab -e`

  ```bash
  SHELL=/bin/bash

  0 10 * * * /bin/bash $HOME/eccs/clean7daysOldFiles.sh > $HOME/eccs/logs/clean7daysOldFiles.log 2>&1  
  ```

Marco Malavolti's avatar
Marco Malavolti committed
410
411
412
413
  This cron job is useful to reduce the considered days selectable on the ECCS Web GUI.

  It is suggested to configure it after the execution of ECCS script to get the hoped result

414
## Utility for developers
415

416
### ECCS API Development Server
417

Marco Malavolti's avatar
Marco Malavolti committed
418
* `cd $HOME/eccs ; ./api.py`
419

420
### Search files created on the current date
Marco Malavolti's avatar
Marco Malavolti committed
421
422
423
424

* `cd $HOME/eccs`
* `find . -name *$(date +%Y-%m-%d)*`

425
### Delete files created on the current date
Marco Malavolti's avatar
Marco Malavolti committed
426
427
428
429

* `cd $HOME/eccs`
* `rm -rf html/$(date +%Y-%m-%d) output/eccs_$(date +%Y-%m-%d).log logs/*_$(date +%Y-%m-%d).log`

430
## Authors
Marco Malavolti's avatar
Marco Malavolti committed
431

432
### Original Author
Marco Malavolti's avatar
Marco Malavolti committed
433
434

 * Marco Malavolti (marco.malavolti@garr.it)