You may use this system to develop alternative login methods - alternative to those built into TOPICA ("login as employee" and "login as patient").

A typical scenario is to implement login methods based on some central authentication system, typically with better security than the built in methods. Such more secure login methods may use certificates, PKI ("Public Key Infrastructure"), SAML, etc. PKI systems tend to be country specific. Because the TOPICA framework is internationalized (and thus not targeted one specific country / culture), such secure login methods are not built into the framework. This is why this "custom login module" system exists.

No matter how a "custom login module" is developed, it must end up using the TOPICA API to login to the application either as an employee or as a patient (citizen). In other word: a standard TOPICA login session must be created. Almost every functionality in TOPICA needs a valid session, and the only way to create such a session is to call one of the TOPICA API functions to login. That is, there are only 2 types of session: either logged in as employee or logged in as patient / citizen - irrespective of the login method / authentication system (built-in or custom).

The standard login methods to login as employee or patient have the requirement, that the employee or patient must exist in the database. A custom login module may create the employee or patient respectively, provided that enough information is available. For example: A custom login module to login as patient/citizen may use an interface to lookup a national id from a central database of citizens, and if successful, create the patient in the TOPICA database.

The standard TOPICA login form (LoginForm.aspx) scans the folder Login below the configuration folder. Each .aspx file (webform) found in this folder is treated as a "custom login module".

Each "custom login module" generates its own tab in the tabset in TOPICA's standard login form, and the .aspx (webform) is displayed in an iframe on that tab.

For each "custom login module", TOPICA checks if there exists an .xml file with the same base name as the aspx (i.e. replacing the extension .aspx with .xml). If such an .xml file is found, the contents of this file is used to specify various parameters (size, style, caption, ...) of the iframe, where the custom login module is displayed.

Example:

<?xml version="1.0" encoding="utf-8" ?>
    <LoginPageInfo>
    <TabText>Login 1 tab text</TabText>
    <TabValue>Login1</TabValue>
    <AccessKey>1</AccessKey>
    <Visible>true</Visible>
    <Enabled>true</Enabled>
    <FrameBorder>no</FrameBorder>
    <Scrolling>auto</Scrolling>
    <Width></Width>
    <Height></Height>
    <Style>width:90%; height:400px;</Style>
</LoginPageInfo>

The function of the individual elements should be deductible from the element name.

Note that there are two ways to specify width and height: either using the Width and Height tags, or using the Style tag (CSS syntax). Normally you should use only one of methods, not both. The Style is the preferred (modern) way - but the Width and Height tags may be necessary in older browsers. If you use both ways, specify same values for width and height.

The panel containing the tabset has a width, that is specified by the .config-file parameter LoginForm.PanelLogin.Width. The default value is 500px. This is suitable for the built-in set of login methods. If one or more of the custom login modules do not "fit" in this space, you can change the width of the panel (and thus the tabset) by overriding this .config-file parameter, e.g. in Application.config. Unfortunately, the system cannot automatically determine the width of the widest enabled login module, and set the tabset width accordingly.

The ONLY constraint on how to build a custom login form is, that it MUST end up creating a session by using the TOPICA API to login either as employee or as patient.

TODO: sample code

Normally, a TOPICA application is started using a URL, that points to the built-in login form LoginForm.aspx. This built in form displays the login methods enabled in the actual configuration in a tab set.

When you have developed a custom login form (and this login method should be the ONLY login method in the application), you may set the link to start up the application to point to your custom login form directly.

That is: if there should be only one custom login form for an application (all users login the same way), you do not need to use the described system of plugging custom modules into the tabset in the standard login form. You could have the users hit the custom login form directly.

Of course this implies, that your custom login form will not run in an iframe, - it will "take over" the entire browser window.

In cases where the user is known and has already been authenticated (e.g. when integrating with a context manager), a login form is not needed at all.

A session must still be created by using the TOPICA API to login - either as employee or as patient (a "silent" login).