doc/library-configuration.txt

   1 MKWS Target Selection
   2 =====================
   3
   4
   5 1. Selecting targets within the library
   6 ---------------------------------------
   7
   8 MKWS applications can choose what subset of the available targets to
   9 use, by means of several alternative settings on individual widgets or
  10 in the mkws_config structure:
  11
  12 * targets -- contains a Pazpar2 targets string, typically of the form
  13   "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
  14   target IDs. At present, these IDs are based on ZURLs, so a typical
  15   value would be something like:
  16         pz:id~josiah.brown.edu:210/innopac|connect.indexdata.com:9000/mit_opencourseware'
  17
  18 * targetfilter -- contains a CQL query which is used to find relevant
  19   targets from the relvant library. For example,
  20         udb==Google_Images
  21
  22 * target -- contains a single UDB, that of the sole target to be
  23   used. For example
  24         Google_Images
  25
  26
  27 2. Changing the library
  28 -----------------------
  29
  30 Some MKWS applications will want to define their own library providing
  31 a different range of available targets. This is particularly important
  32 in the case of applications that authenticate onto subscription
  33 resources by means of credentials stored in MKAdmin, in that such
  34 library accounts need to prohibit unauthorised access.
  35
  36 Setting up such a library is a two-stage process.
  37
  38 Stage A (on MKAdmin)
  39
  40 Create the library:
  41         - Make a new library on http://mkc-admin.indexdata.com/console/
  42         - Select relevant targets
  43         - Add authentication credentials as necessary
  44         - Create an end-user account
  45         - Set its username and password
  46
  47 Stage B (on the application's web-server):
  48
  49 Authentication onto the library can be achieved by a single HTTP GET
  50 to the relevant Service Proxy, passing in the credentials and thereby
  51 initiating an HTTP session. This can most simply be done just by
  52 setting service_proxy_auth to a URL such as
  53         http://mkws.indexdata.com/service-proxy/?command=auth&action=login&username=MIKE&password=SWORDFISH
  54
  55 However, doing so reveals the the credentials to public view -- to
  56 anyone who does View Source on the MKWS application. This may be
  57 acceptable for some libraries, but is intolerable for those which
  58 provide authenticated access to subscription resources. For such
  59 circumstances, a more elaborate approach is necessary. The idea is to
  60 make a local URL that is used for authentication onto the Service
  61 Proxy, hiding the credentials, and to use local mechanisms to limit
  62 access to that local authentication URL. Here is one way to do it when
  63 Apache2 is the application's web-server:
  64
  65         - Add a rewriting authentication alias to the configuration:
  66                 RewriteEngine on
  67                 RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=login&username=U&password=PW [P]
  68         - Extend the MKWS configuration to set service_proxy_auth:
  69                 http://application.com/spauth/
  70         - Protect access to /apauth/ (e.g. using a .htaccess file).
  71
  72 Once such a library has been set up, and access to it established,
  73 target selection within the set that it makes available can be done
  74 using the mechanisms above.
  75