An Architecture for Personalization Services within Subject Gateways

Updated 05/04/02

Section 1: Introduction

Briefly, the functionality supported by this architecture is as follows:
Users register with the system so as to start building and using a personalized view of the Subject Gateway service. Registered users have a stored profile of preferences which is accessible to the subject gateway. Users create (and update) their own profile (or user preferences). When a registered user uses the service, their user preferences are retrieved by the system. The service is then presented to the user according to those preferences. These preferences may specify, for example, the look of the interface e.g colour settings, low-graphics versions etc. The registered user is recognised by the system in two ways. The user may set a 'remember me' option so that they do not need to authenticate if accessing from a specific IP address (this facility is supported by using cookies). The alternative method is to authenticate with the system via a username and password. Authentication details are also accessed by the system, in the form of authentication profiles. The process of authentication may also involve interaction with external entities. More details of this functionality are available in Section 2 and Section 3.

The IMesh Tookit Project acknowledges the indispensable contributions of Andy Powell and Pete Cliff of UKOLN in the design of this architecture. Several of the features are a direct result of their involvement. The collaboration took place within the context of discussions about applying the architecture within the Resource Discovery Network (RDN).

This document will be updated as the code is developed. The issues flagged will be resolved and documented.

Section 2: Diagram and functionality

Overview

The Web Interface Layer
The first layer is the layer at which the user interacts. This layer contains web interfaces and CGI scripts. Communication and processing takes place through HTTP and CGI. Communication with the user is through web pages displayed on a web browser. The user may enter data into web forms, and read messages displayed in the browser. Processing is carried out within cgi scripts. This layer is responsible for issuing SOAP service requests to the layer above, the SOAP service layer. Data returned from the SOAP layer will be encoded as XML. The Subject Gateway Services that are going to offer the personalized views fit into the Web Interface layer.

The SOAP Services Layer
The middle layer is the layer within which SOAP services are located. The SOAP services are requested by the Web Interface layer. Requests to the SOAP layer are made via the SOAP protocol, i.e transport happens over HTTP, and messages and data are encoded as XML. This layer sits in between the Web Interface layer and the database layer. It thus mediates access to the database layer, shielding the Web interface from details of database implementation and communication with databases. The main function of this layer is to store and retrieve data in the database. Information retrieved from the databases is packaged up within the SOAP services layer into a suitable SOAP response to be passed on down to the Web interface layer. An example of a service offered by the SOAP services layer is retrieval of user preferences from the databases.

The Database Layer
User information is located within this layer, held in databases. The supported protocol for access into this layer will be ODBC. Access to the data is via the services operating within the SOAP layer. The SOAP services are responsible for communication with the databases, and will be responsible for creating, updating, deleting and retrieving profiles from them. The SOAP services (at their backend) use ODBC for interaction with the databases.

Detailed Functionality - Soap Services

Division of functionality - AccessProfile and AccessAuth
To enable a separation of functioality between the authentication mechanisms and the profile storage and retrieval functions, the SOAP services are grouped into two interfaces. AccessProfile SOAP services handle interaction with the database tables which store the profile (preferences) information. AccessAuth SOAP services deal with the database tables that hold authentication-related information such as usernames and passwords.

Format used for describing service
The SOAP services are described as follows. A brief overview describes the scope of the SOAP interface and lists all the services within that interface. Each SOAP service within the interface is then described in detail.
The name of the service is given in the table header. The overall effect in a successful scenario is described. The inputs to the service are listed. The outputs in a succesful scenario are stated. The exceptions section describes the things that can go wrong. This section will be expanded to explain how these errors will be reported within the output of the SOAP services. As a first measure, errors will be reported via codes delivered as part of an array, together with a human-readable error message. It is envisaged that SOAP support for error-reporting, such as using custom fault-codes, will be considered at a later stage.

AccessProfile

Service	createProfile
Effect	A new profile entry is created in the profile database with the given UserID and profile name, and any attribute values (if given).
Inputs	UserID and (optionally) Profile Name. If no profile name is given in the request for the service, the profile name `default' is assigned. A reference to a hash of attributes and values can be added to the input (optional). The order of the inputs must be userID, profile name, reference to attributes-values
Outputs	OK if successful
Exceptions	Problems connecting to the database The profile (UserID + profile name) already exists. The attributes being added do not match attributes that are in the database
Detail	First of all the SOAP service checks if that profile (combination of userID and profile name) already exists. If there is an entry with the profile name and userID in the database, an error results, and the error is reported. No new entries in the database are created. A hash of attribute-value pairs can be passed to the SOAP service. This is used when a gateway sets a default value for preferences when a new profile is created. The hash of the attribute-value pairs must be built up within the gateway service, and is passed to the SOAP service as a reference to a hash. The service then checks that all the attributes passed (if any) are valid attribute names for the database being used. If any of the attributes passed to the SOAP service are not found to be attributes used in the profiles table in the database, no new entry is created in the database, and the list of wrong attributes is reported as an error. If there are no errors, success is reported.
Used By	Register Web Interface, Update Profile Web Interface (? - for creating new profiles if multiple profile names allowed)

Service	getProfile
Effect	Retrieves and returns the profile preferences for that userID and profile name from the profile database.
Inputs	UserID and (optionally) Profile name. If no profile name is given in the request, the name 'default' is used.
Outputs	User Profile (preferences) from the profile database, as a reference to a hash of the attributes (as keys) and their values.
Exceptions	Problems connecting to the data base The profile (UserID + profile name) is not found in the database.
Detail	Searches the profile database for an entry with that user ID and profile name.. If the entry is not found, an error is reported. Returns the profile preferences as a reference to a hash if there are no errors.
Used By	Gateway Service, Update Profile Web Interface

Service	updateProfile
Effect	The profile in the profiles database with that UserID and profile name is updated. If no profile name has been provided in the request for the service, the name default is used.
Inputs	User Name, password, profile name, a reference to a hash of the fields to modify and their new values
Outputs	OK if successful [or profile preferences?]
Exceptions	Database unavailable Errors returned by databse e.g. UserID/Profile Name not found (?) [Issue: if verifyUser not OK, what happens ?]
Detail	First, requests verifyUser from AccessAuth (with User Name and password) AccessAuth returns the UserID if successful; If not successful, AccesAuth takes responsibility for re-trying and terminating. i.e. asks user to re-enter passwd etc If the request to AccessAuth is successful, the database is updated. Returns [OK or the profile preferences?]. [Follows a getProfile request]. [Cookies ?]
Used By	Update Profile Web Interface

Service	getAttributes
Inputs	None
Outputs	A reference to an array of the attribute names
Exceptions	Problems connecting to the database
Effect	Finds out the attributes in the User Profile
Detail	Retrieves the column names in the profiles tables in the profile database
Used By

Service	removeProfile
Inputs	UserID, profile name (optional). Profile name default is used if no profile name is given.
Outputs	OK if successful
Exceptions	Problems connecting to the databse The profile (ID and profile name) is not found.
Effect	Removes the profile with that userID and profile name.
Detail
Used By

AccessAuth

Service	createUser
Effect	Results in the creation of a new entry in the Auth database, with the given values and a unique ID. The entry is designated as pending.
Inputs	email address, User name, password (optional), athens flag (optional)
Outputs	UserID (if successful)
Exceptions	Email address already exists. UserName already exists. Problems connecting to the database.
Detail	Checks if the name already exists, returns an error if name exists. Checks if the email already exists, returns an error if email exists. Generates a unique UserID. Creates the new account in the database. Returns the unique userID.
Used By	Register Web Interface

Service	confirmUser
Effect	Status of entry with that userID in the Auth Database is changed from pending to confirmed
Inputs	userID
Outputs	OK, if successful
Exceptions	Problems connecting to the database Problems carrying out database instruction e.g. UserID not found
Detail
Used By	Register Web Interface

Service	verifyUser
Effect	The user is authenticated, either with the local database or with the athens service, and the User ID is returned.
Inputs	username and password
Outputs	UserID (if successful)
Exceptions	Auth Database Unavailable Athens service unavailable Password incorrect User name not vaild
Detail	Offers two methods, checkLocalUser to authenticate with a local database and checkAthensUser toi authenticate with the Athens service If checkPassword is successful, retrieves UserID from the local database for that user name or athens name, returns the userID
Used By	Register Web Interface (?), Gateway Service, updateProfile (an AccessProfile SOAP service). changePassword (an AccessAuth SOAP service)

Service	changePassword
Effect	The password for the user with that User name in the Auth database is changed. Only local passwords can be changed. This service is not available for those using Athens login and passwords.
Inputs	User name, old password, new password
Outputs	OK if successful
Exceptions	Data missing ?? If verifyUser not OK, what happens? Database unavailable. User name not found (?)
Detail	Checks that it is a local user name (and not Athens). Requests a verifyUser from AccessAuth If verifyUser returns UserID, proceeds to make the change Updates the database entry with the returned userID
Used By	Gateway service

[Issue: what party takes responsibility for checking that password entered twice is correct ? Could be caller and/or SOAP service]

Service	sendPassword
Effect	An email containing the username and password as found in the entry in the Auth database is sent to the user to the email address shown in the account. This method is not available to ATHENS users.
Inputs	email address
Outputs	OK if succesful and an email is sent to the user
Exceptions	Problems connecting to the Auth database Email address not vaild Email address not found User is an Athens user
Detail	This method is only available internally. The service first checks that the email submitted is a valid email address. The search assumes that the user is an ATHENS user. An email is sent to the email address with the username and password found in the databse.
Used By	AccessAuth services: verifyUser, following a number of failed attempts, createUser, if a new user trying to register already appears in the database under that email address. Gateway Service

[Issue deleteUser method, only for admin?]
[Issue: had put down a getUserNameFromID method but not sure why needed]
[Issue: had to check if a getEmailAddress for UserName is ever needed]

Service	removeAuthUser
Effect	The entry for a user is removed from the Auth database.
Inputs	UserID
Outputs	OK if successful
Exceptions	Problems connecting to the database UserID not found in database.
Detail
Used By

Detailed Functionality - Database Layer

Profile Database

The full list of preferences that the user may set is still to be determined, and is likely to include elements from published metadata schemas for describing people and/or learners and their preferences. It is intended that this list will be as flexible as possible to enable service providers to customise the service that they provide.

A set of preferences is called a profile. A user can group together a list of preferences as a profile; each set of preferences is given a profile name. A user is allowed to have more than one profile (i.e. sets of preferences), as long as each profile belonging to the same user has a different name. This enables the user to have different sets of preferences (profiles) according to context. For example a user may have a profile that is used when dialling up from home, which the user has called "From Home". In this profile the preference for graphics is set to "text-only" versions of web pages. The user may also set up a second profile, which is used from within the institution, called "From University". The preference for graphics is not set in this profile.

Within the database, each profile has a profile name, and a user ID (which is unique to a user). The combination of the name and userID makes each profile unique. Each profile also has a set of preferences which can be set.

Profiles table
Profile Name	User ID	Bookmarks	Graphics
History	MyUserID
English	MyUserID
History	YourUserID

The database will be accessible via ODBC. It will support the following queries and transactions:
Create a profile entry with this UserID and profile name [and these preferences].
Delete the profile entry with this UserID and profile name.
What is the list of profile names for this UserID ?
What are the attributes and values (set of preferences) for the profile entry with this UserID and profile name ?
Update the profile entry with this User ID and profile name [with these new values for preferences].

Permissions for some of these transactions on the database will be set [Need to determine which fields can be updated; how is the profile name updated ?]
[Delete all the profiles for a UserID ??]
[Permissions for some of these - admin-only ?]

Auth Database

Unique UserID

This ID is generated by the system, and is used to uniquely identify users.

User email address

Also used to identify users; however since a unique identifier is to be included in cookies, it is not the email address which is used in the cookie, but the UserID.

User Name

This field is used during authentication. A user who is only registered with the portal/subject gateway can create any username. The gateway can alternatively decide to use the email address as a username. (For example, this is the option that the RDN has opted for). However if a user is also registered with ATHENS, and will be using the ATHENS authentication mechanisms, then the User Name will be the ATHENS user name.

User Password

A user password is stored by the gateway so that it can carry out its own authentication. It is only required if a user is not making use of the ATHENS authentication (or any alternative authentication mechanism). If ATHENS is being used for authentication, this field is not required, as authentication is carried out at the ATHENS API.

Athens

This field flags whether a user is an ATHENS user or not. It can be true (user is using ATHENS for authentication) or false (user is using gateway authentication).

Confirmed

This field is used in the scenario where users will be asked to confirm their registration. When the user first registers, the confirmed field is set to false (i.e. this entry is pending confirmation). After the user has confirmed the details, the confirmed field is set to true.

Authentication table
UserID	email address	User Name	Athens	Password	Confirmed

Authentication information needs to be confirmed by the user and is designated 'pending' until the confirmation is received.

The authentication database is accessed using ODBC. It will support the following queries and transactions:
What is the UserID for this User Name ?
What is the email address for this User Name ? [Check if this is needed]
Does an entry with this email address exist ?
Does an entry with this User Name exist ?
[Issue - same User Names/Athens Names not allowed ?]
What are the password and UserName for this email address ?
What is the password for this UserName ?
Create a new account with this email address, userID, username, and password (optional), designated pending, and flagged as an ATHENS user (optional).
Change status of account with this UserID from pending to confirmed.
Change password for this userID
[Delete account with UserID /]
[Permissions for some of these - admin-only ?]

Note

Detailed Functionality - Web Interfaces

Register Web Interface

The main functions carried out at this interface are:

• New forms are generated for new users, where they can enter registration details;
• Filled-in forms are submitted by users. This registers them with the system. ( As a result of registration, a pending authentication account is created for the user - the registration process is started by the submission of the form at the web interface and is completed by the involvement of the SOAP services). The user is also emailed and asked to confirm registration;
• Users can confirm their registration;
• Any errors are reported back to the user through error messages displayed in the web browser.

For a new user to register:
An empty registration form is generated where the user can enter:
User Name or Athens Name
Password (entered twice)
Email address
All of these three fields are required.
[Issue: need to decide how the different name and password combinations are presented, i.e. user name plus new password, or athens name plus athens password... double checking not required for athens....]
Templates may be used so that the form that is generated is customised according to the gateway service that the user is registering from. The user may also register directly without paasing through a gateway service. In this case [what template is used ?]
If the user is referred to the register interface by a gateway service, then the register interface keeps a record of the referrant. (And information about which template to use can also be passed here).

The user may then complete the form and submit the data.

On submission of a form:
After the user completes the form and submits:-

1. a check is made to make sure all fields are present.
   [Issue: fields required depends on whether local or athens login is used]
2. the double-entry for the password is checked for errors
3. a createUser request is made to AccessAuth
4. errors returned are dealt with e.g. existing user name, existing email address. Example of how to deal with an error: if a user name or email address is already registered, a message is output saying that name/email already exists, and gives two options, start registration again (using dfferent names) or get the details of that account forwarded by email (user enters email address and the sendPassword method of accessAuth is requested).
5. if accessAuth createUser has been succesful, a UserID unique to that use will be returned.
6. user is mailed with the information entered at the interface, asking for confirmation, and giving a URL to use for confirming the registration. The URl will contain the userID and the referrer (if applicable)

User confirms registration (which includes the UserID):
The user returns to the register interface using a URL received in an email, which is sent when the user submits the registration form. The URL is supplied by the register interface and contains a unique userID for the user and a referrer (if applicable).

1. a request is made to createProfile in AccessProfile (inputs: userID, profilename)
2. a request is made to confirmUser in AccessAuth (inputs: UserID)
3. any errors are dealt with
4. a success message is displayed to the user
5. user is redirected to the gateway service if desired (only applicable if a referrer is available, ie.user had originally gone to registration via a gateway service.) . Otherwise user is offerred a list of links to gateway services where user may authenticate. (Or user may simply go away..)

Update Profile Web Interface

The main functions of this interface are to:

• Display the current preference settings in the user's profile;
• Allow the user to make changes to a displayed profile and submit the changes (subject to authentication).
• Any errors are reported back to the user through error messages displayed in the web browser.
• User can be referred back to the original gateway service.

User decides to update (or view) the profile
When the user presses the view/update preferences button at the gateway service, the user is redirected to the update web interface/cgi script. The UserID and profile name are sent. [Issue. Profile Name 'default' assumed if missing] [Issue2: send userID as part of CGI or read directly from cookie ?]
Then:

1. referrer is recorded
2. a getProfile AccessProfile request is made (inputs UserID, profile name).
3. any errors are dealt with
4. the profile is displayed to the user

1. if verifyUser is successful, userID is returned; An updateProfile AccessProfile request is made (inputs: userID) profile name, [Issue: changes only or whole profile has to be sent??].
2. the user must first be authenticated before the submission is accepted; the user is prompted to enter username and password; [a verifyUser AccessAuth is requested (inputs: username and password) in the background by getProfile. Interaction with the user to do the athentication is dealt with by the other units and not by the Update Profile Web interface]
   [Issue: dealing with errors - should this be done by accessAuth? When does this interface eventually deal with the errors?]
3. Any other errors are dealt with.
4. Success message is displayed to the user.
5. The user's cookie is changed to resetProfile=yes.

User returns to gateway service
After changes have been made and the success message shown, user can choose to return to the gateway service.
If the user chooses to return to the gateway service, the user is redirected to the referrer.
[Issue: need to cope with scenario where user reaches update profile interface without a userID e.g. without a cookie, i.e. not re-directed from subject gateway. Already discussed with P.Cliff - could ask user to authenticate]

Subject Gateway Services

To enable the user to personalize, the subject gateway will have to offer links to

• register
• log on (i.e. authenticate)
• view profiles
• update profile
• change password
• request the password to be sent by email

*Note: Search and browse facilities as a minimum. The gateway may of course have other features such as news feeds, which may also be included in the customization options.

Details

First of all the gateway interface checks if the user has a cookie that it recognizes.

User arrives with no cookie (This may happen because the user has only just registered or if user is a regular user but does not use the remember me option, or else the user does not use personalization). If the user decides to log on:

• Gateway takes input of user name and password, and asks for a verifyUser from AccessAuth interface.
  [Issue: need to decide which bit takes responsibility for checking if username is athens or local...)
• If verifyUser is succesful, a cookie with limited expiry (for a session) is set for the user. If the user clicks the remember me option when logging on, then the expiry for the cookie is ????
• In the cookie, profileReset=no
• User profile is retrived from the database by requesting a getProfile from AccessProfile.
• Profile is stored in local cache.

User arrives with a recognized cookie. (This happens when the remember me option is being used or a user arrives with a valid session cookie (may also be the case if user has viewed or updated profile). On recognizing the cookie:

• userID is retrieved from the cookie
• The profileReset value in the cookie is checked.
• if profileReset=no - the profile in local cache with that userID is retrieved and used
• if profileReset=yes, user profile with the userID is retrieved from the Profile database by requesting a getProfile from AccessProfile. The retrieved preferences are then stored in a local cache (optional).
• preferences are used to customize service (according to local usage)

• User clicks change password link.
• User enters UserName, current password and new password (entered twice)
• user data is passed on to the changePassword service of the AccessAuth SOAP interface.
  [Issue: what party takes responisibility for checking that password entered twice is correct ? Could be caller or within SOAP service]
• if succesful, success message is output to user.

User wants to be sent email with password.

• User presses send me my password link
• Interface is presented to user to enter email address.
• User enters email adress in interface.
• sendPassword service is requested from acccessAuth SOAP interface.
• user gets appropriate message

• User presses view profile link
• User is redirected to update web interface (including referrer info).

• User presses update profile link.
• User is redirected to update Web interface (including referrer info)

Section 3 (which is in development) contains diagrams of interactions.