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 ### and so that a library of targets
  21 is available, maintained using an instance of MKAdmin (often
  22 http://mkc-admin.indexdata.com/console/)
  23
  24
  25 2. Choosing targets from the library
  26 ------------------------------------
  27
  28 MKWS applications can choose what subset of the library's targets to
  29 use, by means of several alternative settings on individual widgets or
  30 in the mkws_config structure:
  31
  32 * targets -- contains a Pazpar2 targets string, typically of the form
  33   "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
  34   target IDs.
  35
  36   At present, these IDs can take one of two forms, depending on the
  37   configuration of the Service Proxy being used: they may be based on
  38   ZURLs, so a typical value would be something like:
  39         pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902
  40   Or they may be UDBs, so a typical value would be something like:
  41         pz:id=brown|artstor
  42
  43 * targetfilter -- contains a CQL query which is used to find relevant
  44   targets from the relvant library. For example,
  45         udb==Google_Images
  46   Or
  47         categories=news
  48
  49 * target -- contains a single UDB, that of the sole target to be
  50   used. For example
  51         Google_Images
  52   This is merely syntactic sugar for "targetfilter" with the query
  53         udb==NAME
  54
  55
  56 3. Authenticating onto the library
  57 ----------------------------------
  58
  59 Some MKWS applications will be content to use the default library with
  60 its selection of targets. Most, though, will want to define their own
  61 library providing a different range of available targets. An important
  62 case is that of applications that authenticate onto subscription
  63 resources by means of credentials stored in MKAdmin: precautions must
  64 be taken so that such library accounts do not allow unauthorised
  65 access.
  66
  67 Setting up such a library is a two, three or four-stage process.
  68
  69 Stage A: create the library
  70
  71 Use MKAdmin to create the library:
  72         - Make a new library on http://mkc-admin.indexdata.com/console/
  73         - Select relevant targets
  74         - Add authentication credentials to the targets as necessary
  75         - Create an end-user account
  76         - Depending on what authentication method it be used, set the
  77           end-user account's username and password, or IP-address
  78           range, or referring URL, or hostname.
  79
  80 Stage B: tell the application to use the library
  81
  82 In the HTML of the application, tell MKWS to authenticate on to the
  83 Service Proxy. When IP-based, referer-based or hostname-based
  84 authentication is used, this is very simple:
  85
  86         <script type="text/javascript">
  87           var mkws_config = { service_proxy_auth:
  88           "http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login" };
  89         </script>
  90
  91 And ensure that access to the MWKS application is from the correct
  92 IP-range, referer or hostname.
  93
  94 Stage C (optional): embed credentials for access to the library
  95
  96 When credential-based authentication is in use (username and
  97 password), it's necessary to pass these credentials into the Service
  98 Proxy when establishing the session. This can most simply be done just
  99 by setting the service_proxy_auth configuration item to a URL such as
 100         http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=MIKE&password=SWORDFISH
 101
 102 Stage D (optional): conceal credentials from HTML source
 103
 104 Using a Service-Proxy authentication URL such as the one above reveals
 105 the the credentials to public view -- to anyone who does View Source
 106 on the MKWS application. This may be acceptable for some libraries,
 107 but is intolerable for those which provide authenticated access to
 108 subscription resources.
 109
 110 In these circumstances, a more elaborate approach is necessary. The
 111 idea is to make a local URL that is used for authentication onto the
 112 Service Proxy, hiding the credentials, and to use local mechanisms to
 113 limit access to that local authentication URL. Here is one way to do
 114 it when Apache2 is the application's web-server, which we will call
 115 example.com:
 116
 117         - Add a rewriting authentication alias to the configuration:
 118                 RewriteEngine on
 119                 RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
 120         - Set thwe MKWS configuration item "service_proxy_auth" to:
 121                 http://example.com/spauth/
 122         - Protect access to the local path http://example.com/spauth/
 123                 (e.g. using a .htaccess file).
 124
 125 Once such a library has been set up, and access to it established,
 126 target selection within the set that it makes available can be done
 127 using the mechanisms above.
 128