SSPH is a Shiboleth Service Provider Helper.

Shibboleth is hard for a service provider to use directly.  There is a
huge amount of detail, and you can't get it right without a very good
understanding of SAML.  But, whoever set up your IDP can give you
an Apache server that uses Shibboleth to authenticate access to a
directory on that server.

SSPH is a simple CGI program that offers an easy way for non-Apache
web servers (e.g. Tornado) to get Shibboleth authentication through
an Apache server that has SSPH installed.

SSPH is currently scoped to provide user authentication only.  It
is assumed that your application will understand authorization and
access control.

SSPH does not implement anonymous users, but your application
can by simply not directing the anonymous users through SSPH.

--
Overview:

Your SP offers a LOGIN button that links to a specific URL on the
SSPH server.  That URL includes the name of your SP.

SSPH authenticates your user.  The authentication information (i.e. who
the user is) is inserted into a database table as the tuple
( IDP, EPPN ).  

IDP is the Identity Provider; it identifies who confirmed the user's
identity.  When multiple organizations join in a "federation", there
is a different IDP for each one.

EPPN is the name of the user who is logged in.  The EPPN is unique
within a single IDP, but it would appear that a hostile IDP could
return an arbitrary EPPN.  Therefore, the tuple of IDP and EPPN
must be used together for user identification.

SSPH is configured with the name of your SP, a URL to redirect
back to your web application, and miscellaneous other configuration
parameters.

Once the user logs in, they are redirected back to your URL with
the parameter "?evid=XXX" where XXX is a crypto-strong authentication
event identifier.  Your application uses a back channel to ask SSPH
who logged in and received that evid.  Now you know who they are.

There are two options for your SP:

- You can configure SSPH to insert the authentication directly into
  your database.  You confirm the authentication by looking up the
  evid in your database table (Database Confirmation)

- Your SP can ask a CGI on the SSPH server to confirm the evid for
  you. (CGI Confirmation)

--
Setting up your SP as a client of SSPH

Make your LOGIN button go to
	https://ssph.stsci.edu/secure/ssph_auth.cgi?sp=NAME

	The test configuration is
	https://etcbrady.stsci.edu/secure/ssph_auth.cgi?sp=NAME

	NAME is the name of your SP as configured in SSPH

Configure SSPH to recognize your SP:
	https://etcbrady.stsci.edu/secure/ssph_admin.cgi

	sp 		NAME that you used in the URL above
	url		URL on your web server where the user will
			return to after authentication
	dbtype		type of database you are using -- use
			"ssph" if SSPH if you will use CGI Confirmation.
	dbcreds		JSON of database credentials
			{ } if using CGI Confirmation
	contact		real names of people who manage your SP
	email		email addresses of contacts for your SP
	secret		shared secret between your SP and SSPH
			for use with CGI Confirmation
	hash		hash type to use with CGI Confirmation

If the user succeeds in logging in, they will come to your application
at
	RETURN_URL?evid=XXX


--
Confirming the authentication, Database Confirmation

When the user comes back to RETURN_URL, look in the table ssph_auth_events
for the evid.  This table contains IDP, EPPN, and ATTRIBS that were
returned by the Shibboleth system.

Update the column "CONSUMED" to the value 'Y' so that a second attempt to
use the same evid will be rejected.

The application demo/demo.py shows actual code to do this in python.

--
Confirming the authentication, CGI Confirmation

ssph_client.cgi contains a function for authenticating in CGI mode.
Documentation is feeble at the moment, but demo/demo.py has an example
of its use.

--

Installing SSPH (for Pandeia Server usage)

SSPH is a set of small python programs.

The specific dependencies are:
etc_utils package from pandokia
dateutil

for Microsoft SQL Server support:

	install freetds RPMs
	pip install pymssql

for MySQL support:

	install mysql client library RPMs
	install MySQLdb from docs at
		http://mysql-python.sourceforge.net/MySQLdb.html

for Postgres support:
	install postgres client library RPMs
	pip install psycopg2
		docs at http://initd.org/psycopg/docs/

for SQLite3 support:
    only python standard libraries needed

(as of 2020-03-11 we will be using the full Pandeia TP package, which contains
all the necessary code for mysql support)

n.b. SSPH requires one database driver for itself.  If you will use
Database Confirmation, you also need a driver for each type of
database that the SP wants you to contact.
(the Pandeia server uses CGI authentication)

For high availability, you should use a high availability incoming proxy
that can distribute across two or more instances of SSPH.  All instances
should be configured to use the same high availability database.

Install the server package:

The server code lives in a git repository in /internal/data1/other/pylibs/

Put a password file (pswd) in /internal/data1/other/config/

Install a TP into /internal/data1/other/<tp dir>

Make a logging directory for internal non-apache logs: 
/internal/data1/other/logs

Copy the cgi directory's files to the webroot (currently named
/internal/data1/sites/ssph1.etc.stsci.edu/, for both 
plssph4/ssph1.etc.stsci.edu AND plssph3/ssph2.etc.stsci.edu).

Note that the CGI files must run the exact python installation (pointing 
to the <environment>/bin/python executable), and manually add the path to 
the server code to the system PYTHONPATH. Make sure those paths are correct.

Make sure all of the above files are readable by the apache user.