%META:TOPICINFO{author="TWikiContributor" date="1398126889" format="1.1" version="$Rev$"}%
---+!! Knowd Login Plugin
<!--
   Contributions to this plugin are appreciated. Please update the plugin page at
   http://twiki.org/cgi-bin/view/Plugins/KnowdLoginPlugin or provide feedback at
   http://twiki.org/cgi-bin/view/Plugins/KnowdLoginPluginDev.
   If you are a TWiki contributor please update the plugin in the SVN repository.
-->
<sticky><div style="float:right; background-color:#EBEEF0; margin:0 0 20px 20px; padding: 0 10px 0 10px;">
%TOC{title="Page contents"}%
</div>
<div style="float:right; margin:0 0 20px 20px; width: 400px;">
<a href="%PUBURLPATH%/%WEB%/%TOPIC%/login-screen-1.png"><img src="%PUBURLPATH%/%WEB%/%TOPIC%/login-screen-400.png" alt="login-screen-400.png" width="400" height="243" /></a>
</div></sticky>
%SHORTDESCRIPTION%

---++ Overview

Conventionally, users access a TWiki site with username and password. [[https://id.wave.com/][Wave Knowd]] is an endpoint identity cloud service that provides a link between a unique device identity and Internet services. The Knowd cloud service manages the identity and trust score of user devices. With Knowd, users can log in to a site without specifying a password if the device used has a high enough trust score.

This plugin provides a login manager where TWiki users can register their devices (computers, smartphones, etc), then log in to the TWiki site without a password, provided their device has a high enough trust score. The threshold of the trust score can be set by a TWiki administrator.

---++ Login Procedure

This assumes your TWiki administrator installed and configured this plugin. Follow this procedure to log in to the TWiki site automatically, without specifying a password:

   * One time setup for each device (computer, smartphone, etc) you use:
      * Go to [[%SCRIPTURL{login}%][login screen]] and watch the Knowd info on the upper right. It should show something like this:
        %BR% =Identity: 2a717742-f579-42f7-bcb5-44104bc65e8f=
        %BR% =Score: 331=
      * Log in with username and password.
      * Visit the [[KnowdDeviceManager][Knowd Device Manager]], and register the device - give it a memorable name, such as =Work PC=.
      * Log out.

   * Automatic login:
      * Go to login screen.
      * If the trust score is high enough you will be logged in automatically and redirected to TWiki.
      * Else, you will see the score with the =(not high enough)= message. Log in with your username and password.

Simply put, the automated Knowd log in works as follows:

<img src="%PUBURLPATH%/%WEB%/%TOPIC%/knowd-login-diagram.png" alt="knowd-login-diagram.png" width="661" height="131" />

   1. TWiki sends the login screen to the browser.
   1. With an Ajax call in the login screen, the browser sends a "Get ID" request to the Knowd server.
   1. The Knowd server sends back the ID and a score of the device (browser).
   1. Request automatic log in on TWiki server.
   1. Automatic log in: In case the device is registered and has a high enough score, the automated log in is performed for the user associated with the device, followed by a redirect to the TWiki view script.

This is a simplified diagram. The actual flow is more complex and is documented in the developer section below.

---++ Device Management

The *[[KnowdDeviceManager][Knowd Device Manager]]* lets you manager your devices (computer, smartphone, etc). Members of the %USERSWEB%.TWikiAdminGroup can manage devices of other users.

__Screenshot:__ %BR%
<img src="%PUBURLPATH%/%WEB%/%TOPIC%/device-manager.png" alt="device-manager.png" width="1045" height="233" style="margin-left:20px;" />

__Functionality:__

   * Select user (only available to TWiki administrators).
   * See list of devices. For each device you can:
      * See ID, name, trust score, date of registration, and last access
      * Register a device by giving it a name, such as "Work PC", "MacBook Pro", "iPhone", "Home computer". Unregistered devices are highlighted with a yellow background.
      * Change the name of a registered device.
      * Remove (deregister) a device.

When an action is taken, a the result is shown in a green note. A red note is shown in case of an error.

---++ Developer Documentation

You can skip this unless you want to learn how automated login works.
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

The login sequence is a bit convoluted due to security considerations.

__Knowd login sequence diagram:__

<img src="%PUBURLPATH%/%WEB%/%TOPIC%/knowd-login-sequence.png" alt="knowd-login-sequence.png" width="706" height="410" />

   1. TWiki sends login screen to the browser.
   1. The login screen does an Ajax call to the Knowd ID server requesting a claim ticket.
   1. The Knowd ID server returns a one time use claim ticket.
   1. The login screen sends an Ajax request to the TWiki server, passing along the claim ticket.
   1. The TWiki server sends a device ID request to the Knowd ID server, passing along the claim ticket.
   1. The Knowd ID server returns the ID and score of the device, e.g. browser.
   1. The TWiki server returns the Ajax call from the browser, returning the device ID and score. In case the score is above a set threshold and the device is registered, it also returns a magic number.
   1. In case the magic is received, the login screen sends a redirect to the TWiki server, requesting the login screen, passing along the magic number.
   1. The TWiki server handling the login screen checks for the magic number parameter. In case the magic number exists and is correct, TWiki logs in the user associated with the device, and redirects to the view script.

The =login= method in the =TWiki::LoginManager::KnowdLogin= module generates the login screen with the Javascript code that does the Ajax calls.

The =TWiki::Plugins::KnowdLoginPlugin::Core= module handles the KNOWD TWiki variable to manages the device IDs. It also handles the magic number.

The KNOWD TWiki variable supports these parameters:

__1. <tt>action="checkid" id="..."</tt>__

Request the device ID from the Knowd ID server. The id parameter is the claim ticket. This calls the Knowd ID server at =https://id.wave.com/upi/willcall/claim?ticket=<nop>...=. A response JSON data might look like:
%BR%
={"message":"", "result":"OK", "info":"{\"id\":\"a27d00fc-d4f4-4ac1-9a20-dd748d0c2954\", \"score\":244, \"needsSetup\":false, \"setupURL\":null}"}=

__2. <tt>action="getdevices" user="..."</tt>__

Returns the list of device IDs associated with a user. Specify the !WikiName of the user. This also sets SpreadSheetPlugin hashes that can be retrieved as follows:

   * =$GETHASH(knowd-login, id)= - login name associated with device ID
   * =$GETHASH(knowd-wikiname, id)= - !WikiName associated with device ID
   * =$GETHASH(knowd-name, id)= - device name
   * =$GETHASH(knowd-score, id)= - device score
   * =$GETHASH(knowd-atime, id)= - last login date (epoch time format)
   * =$GETHASH(knowd-rtime, id)= - date of registration (epoch time format)

This is used to populate the device table at KnowdDeviceManager.

__3. <tt>action="registerdevice" id="..." name="..." user="..."</tt>__

Register a device by ID. The name and user is required. Only the device owner or an administrator can register a device.

__4. <tt>action="deregisterdevice" id="..." user="..."</tt>__

De-register a device by ID. The user is required. Only the device owner or an administrator can de-register a device.

The plugin stores device data in the plugin's working directory at =twiki/working/work_areas/KnowdLoginPlugin=. Each device is represented by a file named =id-&lt;device-id&gt;.txt=, such as =id-3b9d59a5-4452-48fe-8197-b36bc6127f2c.txt=. Sample content:

<verbatim>
atime: 1394694634
login: JimmyNeutron
magic: 
name: iPhone
rtime: 1394694634
score: 244
wikiname: JimmyNeutron
</verbatim>

%ENDTWISTY%

---++ Plugin Installation &amp; Configuration

You do not need to install anything on the browser to use this plugin. These instructions are for the administrator who installs the plugin on the TWiki server.
%TWISTY{
 mode="div"
 showlink="Show details %ICONURL{toggleopen}% "
 hidelink="Hide details %ICONURL{toggleclose}% "
}%

   * For an __automated installation__, run the [[%SCRIPTURL{configure}%][configure]] script and follow "Find More Extensions" in the in the __Extensions__ section.
      * See the [[http://twiki.org/cgi-bin/view/Plugins/BuildContribInstallationSupplement][installation supplement]] on TWiki.org for more information.

   * Or, follow these __manual installation__ steps:
      * Download the ZIP file from the Plugins home (see below).
      * Unzip ==%TOPIC%.zip== in your twiki installation directory. Content:
        | *File:* | *Description:* |
        | ==bin/knowd== | Utility script to verify device ID |
        | ==data/TWiki/KnowdDeviceManager.txt== | Knowd device manger topic |
        | ==data/TWiki/KnowdLoginPlugin.txt== | Plugin topic |
        | ==lib/TWiki/LoginManager/KnowdLogin.pm== | Login manager Perl module |
        | ==lib/TWiki/Plugins/KnowdLoginPlugin.pm== | Plugin Perl module |
        | ==lib/TWiki/Plugins/KnowdLoginPlugin/Config.spec== | Configure spec file |
        | ==lib/TWiki/Plugins/KnowdLoginPlugin/Core.pm== | Plugin Core module |
      * Set the ownership of the extracted directories and files to the webserver user.
      * Install the dependencies indicated below.

   * Plugin __configuration__:
      * Run the [[%SCRIPTURL{configure}%][configure]] script and enable the plugin in the __Plugins__ section.
      * Enable the Know login manager in the __Security setup__ section:
        %BR% For ={LoginManager}= select =TWiki::LoginManager::KnowdLogin=.
      * Configure additional plugin settings in the __Extensions__ section. Settings:
        %BR% =$TWiki::cfg{Plugins}{KnowdLoginPlugin}{ScoreThreshold}= # Trust score threshold to allow user to login without a password. Default: 400
        %BR% =$TWiki::cfg{Plugins}{KnowdLoginPlugin}{ClaimIdUrl}= # URL to claim an ID and trust score based on the claim ticket.
      * __Note:__ The plugin works on older TWiki releases, however, the GUI of the KnowdDeviceManager depends on TWiki-6.0. If you have an older TWiki release do this:
         * Upgrade to the latest SpreadSheetPlugin and SetGetPlugin
         * Remove the PARENTBC variable in the heading
         * Replace the USERREPORT variables with the direct link to the user's profile page.

   * __Testing__:
      * Go to login screen and watch the Knowd info on the upper right. It should show something like this:
        %BR% =Identity: 2a717742-f579-42f7-bcb5-44104bc65e8f=
        %BR% =Score: 231 (not high enough)=
      * Log in, visit KnowdDeviceManager, and register the device (your computer) - give it a memorable name, such as =Work PC=.
      * Log out, then go to login screen again. If the trust score is high enough you will be logged in automatically and redirected to TWiki. Otherwise, you will see the score with a =(not high enough)= message.

%ENDTWISTY%

---++ Plugin Info

   * One line description, is shown in the %SYSTEMWEB%.TextFormattingRules topic:
      * Set SHORTDESCRIPTION = Knowd - login without password on devices that have a high enough trust score

%TABLE{ tablewidth="100%" columnwidths="170," }%
|  Plugin Author: | TWiki:Main.PeterThoeny |
|  Copyright: | &copy; 2014 Wave Systems Corp. %BR% &copy; 2014 TWiki:Main.PeterThoeny %BR% &copy; 2014 TWiki:TWiki.TWikiContributor |
|  License: | GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]]) |
|  Sponsor: | [[http://www.wave.com/][Wave Systems Corp.]] |
|  Plugin Version: | 2014-04-21 |
%TWISTY{
 mode="div"
 showlink="Show Change History %ICONURL{toggleopen}%"
 hidelink="Hide Change History %ICONURL{toggleclose}%"
}%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  2014-04-21: | TWikibug:Item7452: Support device setup URL in login screen and device manager; test for vulnerabilities |
|  2014-04-10: | TWikibug:Item7452: Add developer documentation; add Knowd login sequence diagram |
|  2014-04-09: | TWikibug:Item7452: Doc enhancements; add Knowd login diagram |
|  2014-03-13: | TWikibug:Item7452: Initial version |
%ENDTWISTY%
%TABLE{ tablewidth="100%" columnwidths="170," }%
|  TWiki Dependency: | $TWiki::Plugins::VERSION 1.2 |
|  CPAN Dependencies: | CPAN:Crypt-SSLeay |
|  Other Dependencies: | none |
|  Perl Version: | 5.005 |
|  [[TWiki:Plugins.Benchmark][Plugin Benchmark]]: | %SYSTEMWEB%.GoodStyle nn%, %SYSTEMWEB%.FormattedSearch nn%, %TOPIC% nn% |
|  Plugin Home: | http://TWiki.org/cgi-bin/view/Plugins/KnowdLoginPlugin |
|  Feedback: | http://TWiki.org/cgi-bin/view/Plugins/KnowdLoginPluginDev |
|  Appraisal: | http://TWiki.org/cgi-bin/view/Plugins/KnowdLoginPluginAppraisal |

__Related Topics:__ KnowdDeviceManager, %SYSTEMWEB%.TWikiPlugins, %SYSTEMWEB%.AdminDocumentationCategory, %SYSTEMWEB%.TWikiPreferences

%META:FILEATTACHMENT{name="device-manager.png" attachment="device-manager.png" attr="h" comment="" date="1398124549" path="device-manager.png" size="60938" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="login-screen-1.png" attachment="login-screen-1.png" attr="h" comment="" date="1398126499" path="login-screen-1.png" size="56494" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="login-screen.png" attachment="login-screen.png" attr="h" comment="" date="1394693042" path="login-screen.png" size="28758" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="login-screen-400.png" attachment="login-screen-400.png" attr="h" comment="" date="1398126760" path="login-screen-400.png" size="34435" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="knowd-login-diagram.png" attachment="knowd-login-diagram.png" attr="h" comment="" date="1397110466" path="knowd-login-diagram.png" size="50328" user="TWikiContributor" version="1"}%
%META:FILEATTACHMENT{name="knowd-login-sequence.png" attachment="knowd-login-sequence.png" attr="h" comment="" date="1397113946" path="knowd-login-sequence.png" size="43080" user="TWikiContributor" version="1"}%
