Everything related to Transparent-Client-Authentication module

Ticket-Links

• https://sugardextrose.org/issues/4248
• https://sugardextrose.org/issues/4301

h2. Objectives (from bird-view level)

• Make it as easy and as seamless to use school-server services, for XO-clients and Android-clients, irrespective.
• The solution must be scalable.

h2. Objectives (with one level more zoom-in)

1. Any service currently running on the school-server (or that may run in the future), which requires a per-user account, is intended to behave as follows ::

• • If the user accesses any domain/sub-domain of any service-requiring-per-user-account, WITHOUT having registered with the school-server, he must be shown a message - asking him to register with the school-server first.
  • If the user accesses any domain/sub-domain of any service-requiring-per-user-account, AFTER having registered with the school-server, he must be logged in transparently, without requiring him to enter any username/password whatsoever.
  • Note that, only services that require per-user-accounts would be required to conform to the above (as any service requiring admin-access-only must be strictly password-protected).

1. We must strive to achieve the above objective, without making any changes in any of the services' code. In other words, the solution must be a sandwitch/plugin solution, which can be easily plugged/unplugged. When the solution is plugged in, we achieve the above objective; when the solution is unplugged, the service(s) behave in their usual, normal manner.
2. Just for the sake of repeating, the login must be transparent; i.e. the user is not expected to remember any username/passwords (and it holds true for any service other than Moodle).

h2. Algorithm for authentication

At the most basic level, we use the same mechanism as used by Moodle - a HTTP cookie. This cookie is generated at the client, when the client registers with the school-server. Thereafter, this cookie is used to uniquely identify the client, whenever the client logs onto the school-server. For code-level details, please refer to the link :: https://gist.github.com/migonzalvar/279de1bbf414df1fad8c *(Thanks a ton to Miguel Gonzalez Alavarez for the research and documentation)*.

h2. Assumptions

• If the user is a XO-user, he accesses the services only through his XO (and not through someone-else's XO, ever).
• If the user is an Android-user, he accesses the services only through his Android-machine (and not through someone-else's Android-machine, ever).

h2. (Proposed) Generic Solution, catering to both XO-Clients and Android-Clients

• Workflow
  • The client visits any URL on the School-Server.
  • If the URL is for a service being "served" by our solution (and which requires a per-user-account), then the school-server redirects to an internal URL (a "PHP + JSP" script), which checks whether the user credentials are present. There are two following options ::
    • *[Credentials are present]* The user is taken to the URL automatically (without needing to login, ever).
    • *[Credentials are not present]* An HTML page is shown, asking the user to register first (see below for "How to do one time registration").
• How to do one time registration
  • XO-clients register via the "Register" option in the Favorites view (as it happens now). The *XO-machine Serial-Number* serves as the unique-identifier.
  • Android-clients register via a client-side utility. The *Android-machine MAC-Address* serves as the unique-identifier. The clients will need to install a simple client-side utility, which would register them to the school-server (in much the same way as it happens on the XO-s).

h2. Implementation notes/details

• The feasibility of sandwitching this authentication-layer between the time when the user enters *any* URL, and the time when that URL is served, has been confirmed (by achieving the objectives for Moodle, which is currently the only service in DXS, that requires a per-user-login-account). For adding any new service-that-requires-per-user-account that needs to conform to the objectives, following two things would need to be done ::
  • Add a redirection entry in file "/etc/httpd/conf.d/transparent-mods-auth.conf".
  • Add the logic to transparently login into the service, in the file "/var/www/login/web/login.php". The basic objective of the logic would be to create and map the user-cookie data, to the user's login/account for that particular service.

• Registration Details *(Thanks to Anish Mangal, for providing the motivation to document this down)* ::
  • Client launches the "Register" option from its side, sending the unique-identifier for the client-machine along.
  • At the server, following things happen ::
    • The client is registered, using the unique-identifier sent from the client as the "client-identifier". Also, a cookie is sent back to the client. From now on, this cookie will serve as the base, via which the user will not need to enter any login-details ever.
    • For each service being "served" by our solution, there will a small per-service glue/custom-code.
      • For Moodle, there is no need of any extra glue/custom-code (as Moodle directly uses the cookie-data to authenticate internally).
      • Let's take "Pathagar" as another example (which in all likelihood is the next service which will benefit from this sandwitch-plugin solution). In this case, during the (only one-time) registration-process, a user-corresponding-to-the-client-registering will be created in the Pathagar DB, and a one-to-one mapping created between the client-unique-identifier (available via the cookie) and the just created user. Thereafter, whenever the client tries to navigate to Pathagar, the client will firstly be identified via the cookie (with the client-unique-identifier as the cookie-value). Thereafter, because the user is wanting to access Pathagar, the client-unique-identifier will be mapped to the Pathagar-user, and the client will thus be logged-in "transparently".

h2. FAQ

• I could auto-login into Moodle, using the URL, "http://schoolserver/moodle", but when I navigate to "http://schoolserver/moodle/admin", I am denied access, as I do not have sufficient previleges. How can I be granted admin-previleges (just to get a hang of how it looks)?
  • *(solution courtesy Anna Schoolfield)*
    • A client is generally not expected to have admin-previleges. Only the first XO to ever register with the school-server, is granted admin-previleges, and thus is the only one who can do admin-related tasks. Anyhow, the "first admin" *may* grant others the admin-previleges.
    • If the "first admin" does grant you the admin-previleges, then do the following ::
      • Exit "Browse".
      • Start "Browse".
      • Navigate to "http://schoolserver/moodle/admin".. you must now have the admin-previleges. But remember the evergreen saying .. "with great power, comes great responsibility".