Editing Add a parallel authentication routine (section)

==Goal==
Let us assume we want to allow our users to log in using their standard eprints username and password, but we want to verify the authenticity of the user via an external agency when they register.
We will use an external agency that defines a Persistent User ID (a "PUID"), which is unique and unchanging for each user.

We will then allow the user to actually log in using this PUID, and as a final treat, we will allow the user to change the PUID accociated with their account from one provider to another.

This therefor breaks down into three main tasks:
# Authentication during registration
# Using Authentication as an alternative to normal logging in
# Changing the Authentication PUID for an EPrints account

===Explanation in more detail===
We want to associate the EPrints user account with an identifying PUID, which allows us to identify the user by EPrints userID or PUID.
We will also want to display the organisation (university/department/research-group) that the user is associated with.

We will use a cookie to define which authentication point we want (we might as well make in generic enough to cope with multiple systems)

For security, we will never pass the PUID via URI parameter (POST '''''or''''' GET) as that provides a means of spoofing a user-id

This document will assume that you are creating a new archive rather than modifying a live site.
If you want to modify an existing system, you'll need to update the database tables by hand as well as modifying the user object as shown here.

Much of the new code we will be creating will be in a file in <code>archives/''ARCHIVEID''/cfg/cfg.d/</code>. Call it something sensible and meaningful. In this example, I'll call it <code>MyCode.pl</code>

===The flow===

EPrints authentication Handler is called:

* Do we have a current eprints session cookie? (looks in ticket table)
** N - Bounce the user off to get authenticated.
*** user authenticates.
**** Set an eprints session cookie
**** Store an identifier on the "new" auth table
*** bounce user back to their original page
** Y - Can we get user from EPrints ticket table?
*** Y - Get user details, and log them in
*** N - Can we get details from the auth table?
**** N - Bounce user over to manual login pages
**** Y - Can we get a user based on identifier in auth table
***** N - Bounce user over to manual login pages
***** Y - Create record in ticket table
****** bounce user to their original page