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 want to define their own library providing
  47 a different range of available targets. This is particularly important
  48 in the case of applications that authenticate onto subscription
  49 resources by means of credentials stored in MKAdmin, in that such
  50 library accounts need to prohibit unauthorised access.
  51
  52 Setting up such a library is a two-stage process.
  53
  54 Stage A (on MKAdmin)
  55
  56 Create the library:
  57         - Make a new library on http://mkc-admin.indexdata.com/console/
  58         - Select relevant targets
  59         - Add authentication credentials as necessary
  60         - Create an end-user account
  61         - Set its username and password
  62
  63 Stage B (on the application's web-server):
  64
  65 Authentication onto the library can be achieved by a single HTTP GET
  66 to the relevant Service Proxy, passing in the credentials and thereby
  67 initiating an HTTP session. This can most simply be done just by
  68 setting service_proxy_auth to a URL such as
  69         http://mkws.indexdata.com/service-proxy/?command=auth&action=login&username=MIKE&password=SWORDFISH
  70
  71 However, doing so reveals the the credentials to public view -- to
  72 anyone who does View Source on the MKWS application. This may be
  73 acceptable for some libraries, but is intolerable for those which
  74 provide authenticated access to subscription resources. For such
  75 circumstances, a more elaborate approach is necessary. The idea is to
  76 make a local URL that is used for authentication onto the Service
  77 Proxy, hiding the credentials, and to use local mechanisms to limit
  78 access to that local authentication URL. Here is one way to do it when
  79 Apache2 is the application's web-server:
  80
  81         - Add a rewriting authentication alias to the configuration:
  82                 RewriteEngine on
  83                 RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=login&username=U&password=PW [P]
  84         - Extend the MKWS configuration to set service_proxy_auth:
  85                 http://application.com/spauth/
  86         - Protect access to /apauth/ (e.g. using a .htaccess file).
  87
  88 Once such a library has been set up, and access to it established,
  89 target selection within the set that it makes available can be done
  90 using the mechanisms above.
  91