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