= How To Login to the LTK from a Portal =

This document explains how to make a link from a web portal that, when clicked, will log a portal user into their own LTK account bypassing the login screen. 

These instructions are general and do not include step by step instructions for any particular brand of portal software. In order to complete this process you will need to have experience managing your own portal software.

== If You Are Upgrading From ePEARL Version 2.0 ==

In ePEARL version 2.0, portal users logged in by passing login information to 'epearl/login_portal.php'. In version 3.0, that file has been moved to 'ltk/login/portal.php'. When you first upgrade to version 3.0 your portal login link will break. You can fix the link in two ways: 

1. Update the link so that it uses the new path (ltk/login/portal.php)
2. Follow the instructions in 'ReadMe-How to support old bookmarks' to provide support for links (like this one) that were made for ePEARL v2.0.

Note also that the 'portal_config.php' file has changed somewhat since version 2.0. You should re-enter your settings into this new file. Do not overwrite the new file with your old one.

== Instructions ==

Connecting to the LTK from a portal involves adding a user-clickable link to the user's portal environment. The link will point to the file 'ltk/login/portal.php' which is inside your ltk installation. When doing this, information about which user is trying to log in must be passed. In most cases the link will look like this:

http://myserver.com/ltk/login/portal.php?username=[ltk_username]

In the above link, [ltk_username] is the user's LTK username (the one that they would use to log in to through the LTK login screen).

== Portal Login Configurations ==

The file 'ltk/portal_config.php' contains various options that control how 'ltk/login/portal.php' works. This readme outlines the recommended and most secure settings only. For more detailed configuration options, see the file portal_config.php itself.

1. $use_host_checking = true;

This option is set to 'true' by default and should be left as such. Host checking will prevent users from passing fake login information through the address bar and from placing auto-login links on unauthorized websites.

2. $allowed_hosts = array(
	"portal.myserver.com",
	"portal.myotherserver.com"
); 

This option sets a list of hosts that may use auto-login links. When $use_host_checking is true, auto-login will only work from when the user clicks a link on one of these sites. 

3. $reject_admin_user = true;

This option prevents access to the admin user account through auto-login links. It is true by default and should be left as true.

4. $reject_subadmin_users = true;

This option prevents access to subadmin accounts through auto-login links. It is true by default and should be left as true.

5. $require_username = true;

This option requires that the user's LTK username be passed to ltk/login/portal.php. When this option is used by itself the user's password is not required. For example: 

http://myserver.com/ltk/login/portal.php?username=jsmith

The above link will bypass the login screen and enter the account of user "jsmith". 

It may seem that this method is insecure and that it would be better to pass the user's password as well, this is not the case however. When $use_host_checking is true, users are prevented from gaining access to other accounts by changing the username in the address bar. Therefore, the username-only method is secure. Furthermore, if the password were passed along with the username, then there would be a greater chance that someone other than the current user might see it, and use it to gain access to that user's account through the LTK login screen.

== Note for GPI Database users ==

If you are importing user accounts from your GPI database then, by default, student usernames will equal their fiche numbers, and teacher usernames will equal [school#]_[interv#]. These defaults can be changed from the administrator environment by going to "Import from DB", editing a database profile, changing the options and then reimporting data from that profile.

== Troubleshooting ==

If you have any questions, email 'epearlhelp@education.concordia.ca'.