This package provides the Sakai Authentication Service.

Authentication is the process of finding out who the end user is and assuring that it is truly this user. Sakai has to deal with at least three forms of Authentication (as well as others):

- user enters a name and password, which Sakai has responsibility for maintaining and checking.

- user enters a name and password, which Sakai sends out to an external authority for checking.

- user does something to convince the web application container (Apache, Tomcat) who they are, and a user name is made available from the container to Sakai, which Sakai translates into a user id, if possible, to be the authenticated user.

The user name which the end users enters to authenticate, or which the container presents as the current user, may not be their Id in the permanent globally unique id sense. Sakai needs to have a map between the names presented and the user id for this user, even with external authority or container trusted situations. This is modeled for Sakai in the {@link org.sakaiproject.service.common.authentication.Authentication Authentication} entity.

Sakai has the idea of request - response transactions, which map well to the web application nature of Sakai today. Each transaction is associated with a particular usage session, and with a particular end user. Sakai also runs background threads for maintenance which are not associated with any particular user, but need to have certain permissions.

Users of authentication fall into three camps. The majority of users are the tools and services which need to know who is the "current" user - i.e. the user associated with this particular request - response transaction. They want a User object. If the current user is not authenticated, the User object they get is that of the anonymous user.

Then there are the very few cases of users of Authentication which maintain user id to external id, user id to user name and password records which are relied upon to make Authentication work.

Finally, there are the very few cases of the users of Authentication which cause the current usage session to be associated with an authenticated User, or which remove the authenticated User status from this usage session. This is mostly in the Sakai framework, which checks to see if the section of the system you are entering needs authentication, and diverts the request-response transaction to the authentication tool, which goes through the motions of authentication attempts and user name and password harvesting from the end user. There is also a "Logout" tool, and the automatic inactivity logout mechanism which ask Authentication to remove the authenticated User from the current usage session.

The first set of users need a User object, so a method like this would be just fine:

{@link org.sakaiproject.service.common.authentication.AuthenticationManager#getAuthenticatedUser getAuthenticatedUser}

Which would return the anonymous user as appropriate.

The second set of users need basic CRUDS (create, read, update, delete, security) maintenance interface, like this:

{@link org.sakaiproject.service.common.authentication.AuthenticationManager#createAuthentication createAuthentication}
{@link org.sakaiproject.service.common.authentication.AuthenticationManager#getAuthentication getAuthentication}
{@link org.sakaiproject.service.common.authentication.AuthenticationManager#getAuthenticationByUid getAuthenticationByUid}
{@link org.sakaiproject.service.common.authentication.AuthenticationManager#allowCreateAuthentication allowCreateAuthentication}

Since Authentication is a {@link org.sakaiproject.service.common.shared.Resource Resource}, it has built in methods to check for update and delete permission, and to cause an update or a delete to happen. The Authentication entity has these properties:

Id agentId - The Id of the User (Agent) for this record
String userName - the external user identity, or the string the user can enter when providing a password
String pw - the user's internally maintained password, encoded, if any

The final set of users of Authentication would make use of the maintenance methods, as well as these:

{@link org.sakaiproject.service.common.authentication.AuthenticationManager#authenticate authenticate}
(first try - deals with cases where no more user information is needed, such as container auth, cookie, certificate in request, etc)

{@link org.sakaiproject.service.common.authentication.AuthenticationManager#authenticate authenticate(String username, String password)}
(if authenticate() fails, we need some user info.)

{@link org.sakaiproject.service.common.authentication.AuthenticationManager#clearAuthentication clearAuthentication}

Authentication details would be handled by the implementation of the service. For example, we could have a simple one that maintains Authentication entities and simply checks them. authenticate() would, if not already authenticated, always fail, while the authenticate(user, pw) would work if an Authentication could be found matching this user name, and the password when encoded matches the record.

Another service could, in authenticate(), check the container, and if a REMOTE_USER were present, use this as a user name and find an authentication record. If found, that user would be authenticated. If the REMOTE_USER is set, but no authentication record is found, it could create a new one, create a new User object, and authenticate that user (we don't know much about that user other than their container provided external user name). If no REMOTE_USER were found, then authenticate() would fail and authenticate(user, pw) would act as above.

A further twist in another implementation would fail authenticate() as above, but when authenticate(user, pw) were called, some external authority (Kerberos, UMIAC, LDAP) would be referenced, and if it indicated successful authentication, the User from the authentication record would be associated with the current usage session as authenticated. This could also work with automatic User creation as in the second scenario.

The third scenario could make use of a standard API for authentication plugin - of which Kerberos, UMIAC, LDAP, etc could be implemented.