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