We assume you have set up your system with the Shibboleth SP as described in the documentation.
The Shibboleth SP is tightly integrated with the Apache webserver and provides the user information to the
apache process with the
mod_shib module as UTF-8 encoded environment variables.
Accessing the data via the Apache environment
The following text assumes your application is running within Apache, i.e. as a python wsgi application or ruby passenger or tomcat with ajp.
An alternative is the case of a seperate application server behind an Apache proxy, described below.
Let's assume you application has a login form at the url
/login (Note that you need a dedicated login page, a dropdown menu will not so!), say along the lines of this highly simplistic python code:
- By default, the page renders a login form that will than make a post to the same url.
- If the page is called via post request, you validate the user input from the login form.
- If the authentication is successful, or the page is called by a GET from an authenticated user request, you send the user to the startpage.
- Otherwise you display the login form again, containing the error message from the validation.
validate_login_form function will do something like
Thus it returns true if the user and password combination is known, otherwise it informs the user about the error.
Now to add a hook for Shibboleth to the mix, lets add an else branch to the
request.method switch to process Shibboleth information.
process_shib_data function does something like
Thus the function checks whether there is a Shibboleth session by checking for the existence of a session id.
If successful, It takes the user currently logged through shibboleth and tries logging him in. If the user does not yet exist locally, he will be created.
This of course assume you have a username field that can by any string (in particular including
@ symbols) and you won't run into trouble with multiple users having the same mail address.
You can also do more than just create plain users, such as e.g. mapping groups based on the
isMemberOf attribute etc.
How it works
If there is Shibboleth data in the Apache session available, you use it to (optionally create and) log in the user, otherwise you simply default back to standard behaviour.
Enabling Shibboleth in Apache
Now to switch between Shibboleth and standard login, you simply protect the login page by Shibboleth.
In case you can't or won't run your application within Apache's enviroment, you can also put Apache as a reverse proxy in front of your application server (or say a docker container for that matter).
Beware the Security implications
On the Apache end, you will need to enable
and than process the request headers instead of environment variables at the end.
While Apache will happily forward the UTF-8 encoded strings to the backend, as per RFC 2616 HTTP request headers are expected to be
ISO-8859-1 encoded and some application servers such as Tomcat will interpret them as such!