doc/library-configuration.txt

   1 MKWS Target Selection
   2 =====================
   3
   4
   5 MKWS accesses targets using the Pazpar2 metasearching engine, almost
   6 always fronted by the Service Proxy to manage target selection. This
   7 document assumes the SP is used, and so that a library of targets is
   8 available, maintained using an instance of MKAdmin (often
   9 http://mkc-admin.indexdata.com/console/)
  10
  11
  12 1. Selecting targets within the library
  13 ---------------------------------------
  14
  15 MKWS applications can choose what subset of the library's targets to
  16 use, by means of several alternative settings on individual widgets or
  17 in the mkws_config structure:
  18
  19 * targets -- contains a Pazpar2 targets string, typically of the form
  20   "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
  21   target IDs.
  22
  23   At present, these IDs can take one of two forms, depending on the
  24   configuration of the Service Proxy being used: they may be based on
  25   ZURLs, so a typical value would be something like:
  26         pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902
  27   Or they may be UDBs, so a typical value would be something like:
  28         pz:id=brown|artstor
  29
  30 * targetfilter -- contains a CQL query which is used to find relevant
  31   targets from the relvant library. For example,
  32         udb==Google_Images
  33   Or
  34         categories=news
  35
  36 * target -- contains a single UDB, that of the sole target to be
  37   used. For example
  38         Google_Images
  39   This is merely syntactic sugar for "targetfilter" with the query
  40         udb==NAME
  41
  42
  43 2. Changing the library
  44 -----------------------
  45
  46 Some MKWS applications will be content to use the default library with
  47 its selection of targets. Most, though, will want to define their own
  48 library providing a different range of available targets. An important
  49 case is that of applications that authenticate onto subscription
  50 resources by means of credentials stored in MKAdmin: precautions must
  51 be taken so that such library accounts do not allow unauthorised
  52 access.
  53
  54 Setting up such a library is a two or three-stage process.
  55
  56 Stage A (on MKAdmin)
  57
  58 Create the library:
  59         - Make a new library on http://mkc-admin.indexdata.com/console/
  60         - Select relevant targets
  61         - Add authentication credentials to the targets as necessary
  62         - Create an end-user account
  63         - Set its username and password
  64
  65 Stage B (on the application's web-server):
  66
  67 ### simple SP URLs
  68
  69 Stage C (optional)
  70
  71 ### Fix description
  72
  73 Authentication onto the library can be achieved by a single HTTP GET
  74 to the relevant Service Proxy, passing in the credentials and thereby
  75 initiating an HTTP session. This can most simply be done just by
  76 setting the service_proxy_auth configuration item to a URL such as
  77         http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=MIKE&password=SWORDFISH
  78 which is usually done with JavaScript like:
  79
  80         <script type="text/javascript">
  81           var mkws_config = { service_proxy_auth:
  82           "http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=MIKE&password=SWORDFISH" };
  83         </script>
  84
  85 However, doing so reveals the the credentials to public view -- to
  86 anyone who does View Source on the MKWS application. This may be
  87 acceptable for some libraries, but is intolerable for those which
  88 provide authenticated access to subscription resources. For such
  89 circumstances, a more elaborate approach is necessary. The idea is to
  90 make a local URL that is used for authentication onto the Service
  91 Proxy, hiding the credentials, and to use local mechanisms to limit
  92 access to that local authentication URL. Here is one way to do it when
  93 Apache2 is the application's web-server, which we will call
  94 example.com:
  95
  96         - Add a rewriting authentication alias to the configuration:
  97                 RewriteEngine on
  98                 RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
  99         - Set thwe MKWS configuration item "service_proxy_auth" to:
 100                 http://example.com/spauth/
 101         - Protect access to http://example.com/spauth/ (e.g. using a .htaccess file).
 102
 103 Once such a library has been set up, and access to it established,
 104 target selection within the set that it makes available can be done
 105 using the mechanisms above.
 106