Project site | Get the code | Support | Forum

CentralSP README

"CentralSP" is a central service provider that manages web authentication on behalf of a number of relying sites. This document outlines how to use CentralSP as a developer/maintainer of a relying site. You do not need to install CentralSP to use it as a relying site, but you might like to copy one of the example "return scripts" to use on your site. However, you will require an operationing CentralSP server within your organisation.

The CentralSP server can supports multiple authentication mechanisms such as Shibboleth, OpenID and SSL certificates. CentralSP centralises this capability allowing for shared installation, management and maintenance of these authentication infrastructures.

As a relying site you can either choose to use one, many or all of the supported authentication mechanisms for your site. You will have the ability to do chained authentication that uses the CentralSP server, without the need to install CentralSP locally, without the need for additional software or administrative control, and using a simple protocol that can be implemented with almost any server side language (provided the relying site supports HTTP GET and text parsing). Example relying site code, called "return scripts" are found in IIS ASP, PHP, and JSP.

Should I use CentralSP?

You should use CentralSP if:

you are maintaining/creating a web site or web application and want to authenticate some of it with a CentralSP authentication mechanism; and
you don't have the resources to support distributed authentication infrastructure; and
your application allows you to write your own authentication mechanism using a simple script (ASP, PHP, CGI, JSP).

How to Setup Your Site for CentralSP

Contact your CentralSP server administrator to let them know you want to become a relying site.
Give them your site details: IP address or hostname, full URL of a return script (see below for how to build one), your contact details to display in case of error
Create a login link/form from your site. See example below.
Create a return script on your site. See example below.
Protect any of your pages requiring authentication with a session that the return script can create.

Creating a Login Link

This can be any link, button or script that forwards to the following URL: https://centralsp.server/pathto/auth.php

With the appended parameter "?Return=" and appended with the full URL of your return script URL.

Example:

<a href="https:///centralsp.server/centralsp/auth.php?Return=http://myhost.com/return.asp">
LOGIN WITH SHIB
</a>

There are some optional URL attributes which you can specify:

"&Type=shib1" forces Shibboleth authentication
"&Type=openid" forces OpenID authentication
"&Type=openid&OpenID=..." forces authentication with specified OpenID (this could be implemented as a form)
"&Type=ssl" forces SSL certificate authentication

Creating a Return Script

This script can be written in any language. It is the URL/location that CentralSP returns control to immediately after a user successfully authenticates with the AAF. A token string is passed back on this return URL as an appended "Token" parameter.

The Token must be used to make a backend connection to CentralSP to get the users attributes. (If a backend connection fails it is possible that a user is trying to bypass authentication, so do not authorise their access.) The backend connection should be a HTTP Get from the following URL

external link: https://treach.infodiv.unimelb.edu.au/CentralSPCheck2.php?Token= With the token string appended to this. The URL must also include an appended "&Secret=MyPassword" with a password assigned to for the CentralSP. The connection may be unencrypted "http://" if your script cannot perform HTTPS. The HTTP Get should return a text file of line separated attributes, "Key: Value" pairs. The pair will be "Secret: YourPassword" with another password assigned to you for the CentralSP response which you should check. All other attributes are AAF attributes of the user. (Please don't output the response password to the screen.)

See the "return_examples" directory for examples.

Protecting Your Pages

Once you have the users attributes in the return script you could establish a session to store these user attributes. The presence of such a session could indicate to further scripts that a user has logged in.

Project site | Get the code | Support | Forum