doc/library-configuration.txt

   1 MKWS Target Selection
   2 =====================
   3
   4
   5 MKWS accesses targets using the Pazpar2 metasearching engine. Although
   6 Pazpar2 can be used directly, using a statically configured set of
   7 targets, this usage is unusual. More often, Pazpar2 is fronted by the
   8 Service Proxy (SP), which manages authentication, sessions, target
   9 selection, etc.
  10
  11 This document assumes the SP is used, and explains how to go about
  12 making a set of targets (a "library") available, how to connect your
  13 MKWS application to that library, and how to choose which of the
  14 available targets to use.
  15
  16
  17 1. Maintaining the library
  18 --------------------------
  19
  20 The service proxy accesses sets of targets that are known as
  21 "libraries". In general, each customer will have their own library,
  22 though some standard libraries may be shared between many customers --
  23 for example, a library containing all open-access academic journals.
  24 A library can also contain other configuration information, including
  25 the set of categories by which targets are classified for the library.
  26
  27 Libraries are maintained using MKAdmin (MasterKey
  28 Admin). Specifically, those used by MKWS are generally maintained on
  29 the "MKC Admin" installation at
  30         http://mkx-admin.indexdata.com/console/
  31
  32 In general, Index Data will create a library for each customer, then
  33 give the customer a username/password pair that they can use to enter
  34 MKAdmin and administrate that library.
  35
  36 Once logged in, customers can select which targets to include (from
  37 the list of several thousand that MKAdmin knows about), and make
  38 customer-specific modifications -- e.g. overriding the titles of the
  39 targets.
  40
  41 Most importantly, customers' administrators can add authentication
  42 credentials that the Service Proxy will used on their behalf when
  43 accessing subscription resources. Note that IT IS THEN CRUICIAL TO
  44 SECURE THE LIBRARY FROM USE BY UNAUTHORISED CLIENTS, otherwise the
  45 customer's paid subscriptions will be exploited.
  46
  47 Access to libraries is managed by creating one or more "User Access"
  48 records in MKAdmin, under the tab of that name. Each of these records
  49 provides a combination of credentials and other data that allow an
  50 incoming MKWS client to be identified as having legitimate access to
  51 the library. The authentication process, described below, works by
  52 searching for a matching User Access record.
  53
  54
  55 2. Authenticating onto the library
  56 ----------------------------------
  57
  58 Some MKWS applications will be content to use the default library with
  59 its selection of targets. Most, though, will want to define their own
  60 library providing a different range of available targets. An important
  61 case is that of applications that authenticate onto subscription
  62 resources by means of credentials stored in MKAdmin: precautions must
  63 be taken so that such library accounts do not allow unauthorised
  64 access.
  65
  66 Setting up such a library is a two, three or four-stage process.
  67
  68 Stage A: create the library
  69
  70 Use MKAdmin to create the library:
  71         - Make a new library on http://mkc-admin.indexdata.com/console/
  72         - Select relevant targets
  73         - Add authentication credentials to the targets as necessary
  74         - Create an end-user account
  75         - Depending on what authentication method it be used, set the
  76           end-user account's username and password, or IP-address
  77           range, or referring URL, or hostname.
  78
  79 Stage B: tell the application to use the library
  80
  81 In the HTML of the application, tell MKWS to authenticate on to the
  82 Service Proxy. When IP-based, referer-based or hostname-based
  83 authentication is used, this is very simple:
  84
  85         <script type="text/javascript">
  86           var mkws_config = { service_proxy_auth:
  87           "http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login" };
  88         </script>
  89
  90 And ensure that access to the MWKS application is from the correct
  91 IP-range, referer or hostname.
  92
  93 Stage C (optional): embed credentials for access to the library
  94
  95 When credential-based authentication is in use (username and
  96 password), it's necessary to pass these credentials into the Service
  97 Proxy when establishing the session. This can most simply be done just
  98 by setting the service_proxy_auth configuration item to a URL such as
  99         http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=MIKE&password=SWORDFISH
 100
 101 Stage D (optional): conceal credentials from HTML source
 102
 103 Using a Service-Proxy authentication URL such as the one above reveals
 104 the the credentials to public view -- to anyone who does View Source
 105 on the MKWS application. This may be acceptable for some libraries,
 106 but is intolerable for those which provide authenticated access to
 107 subscription resources.
 108
 109 In these circumstances, a more elaborate approach is necessary. The
 110 idea is to make a local URL that is used for authentication onto the
 111 Service Proxy, hiding the credentials, and to use local mechanisms to
 112 limit access to that local authentication URL. Here is one way to do
 113 it when Apache2 is the application's web-server, which we will call
 114 example.com:
 115
 116         - Add a rewriting authentication alias to the configuration:
 117                 RewriteEngine on
 118                 RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
 119         - Set thwe MKWS configuration item "service_proxy_auth" to:
 120                 http://example.com/spauth/
 121         - Protect access to the local path http://example.com/spauth/
 122                 (e.g. using a .htaccess file).
 123
 124 Once such a library has been set up, and access to it established,
 125 target selection within the set that it makes available can be done
 126 using the mechanisms above.
 127
 128
 129 3. Choosing targets from the library
 130 ------------------------------------
 131
 132 MKWS applications can choose what subset of the library's targets to
 133 use, by means of several alternative settings on individual widgets or
 134 in the mkws_config structure:
 135
 136 * targets -- contains a Pazpar2 targets string, typically of the form
 137   "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
 138   target IDs.
 139
 140   At present, these IDs can take one of two forms, depending on the
 141   configuration of the Service Proxy being used: they may be based on
 142   ZURLs, so a typical value would be something like:
 143         pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902
 144   Or they may be UDBs, so a typical value would be something like:
 145         pz:id=brown|artstor
 146
 147 * targetfilter -- contains a CQL query which is used to find relevant
 148   targets from the relvant library. For example,
 149         udb==Google_Images
 150   Or
 151         categories=news
 152
 153 * target -- contains a single UDB, that of the sole target to be
 154   used. For example
 155         Google_Images
 156   This is merely syntactic sugar for "targetfilter" with the query
 157         udb==NAME
 158
 159