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. Authenticating onto 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, three or four-stage process.
  55
  56 Stage A: create the library
  57
  58 Use MKAdmin to 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         - Depending on what authentication method it be used, set the
  64           end-user account's username and password, or IP-address
  65           range, or referring URL, or hostname.
  66
  67 Stage B: tell the application to use the library
  68
  69 In the HTML of the application, tell MKWS to authenticate on to the
  70 Service Proxy. When IP-based, referer-based or hostname-based
  71 authentication is used, this is very simple:
  72
  73         <script type="text/javascript">
  74           var mkws_config = { service_proxy_auth:
  75           "http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login" };
  76         </script>
  77
  78 And ensure that access to the MWKS application is from the correct
  79 IP-range, referer or hostname.
  80
  81 Stage C (optional): embed credentials for access to the library
  82
  83 When credential-based authentication is in use (username and
  84 password), it's necessary to pass these credentials into the Service
  85 Proxy when establishing the session. This can most simply be done just
  86 by setting the service_proxy_auth configuration item to a URL such as
  87         http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=MIKE&password=SWORDFISH
  88
  89 Stage D (optional): conceal credentials from HTML source
  90
  91 Using a Service-Proxy authentication URL such as the one above reveals
  92 the the credentials to public view -- to anyone who does View Source
  93 on the MKWS application. This may be acceptable for some libraries,
  94 but is intolerable for those which provide authenticated access to
  95 subscription resources.
  96
  97 In these circumstances, a more elaborate approach is necessary. The
  98 idea is to make a local URL that is used for authentication onto the
  99 Service Proxy, hiding the credentials, and to use local mechanisms to
 100 limit access to that local authentication URL. Here is one way to do
 101 it when Apache2 is the application's web-server, which we will call
 102 example.com:
 103
 104         - Add a rewriting authentication alias to the configuration:
 105                 RewriteEngine on
 106                 RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
 107         - Set thwe MKWS configuration item "service_proxy_auth" to:
 108                 http://example.com/spauth/
 109         - Protect access to the local path http://example.com/spauth/
 110                 (e.g. using a .htaccess file).
 111
 112 Once such a library has been set up, and access to it established,
 113 target selection within the set that it makes available can be done
 114 using the mechanisms above.
 115