doc/library-configuration.txt

   1 MKWS Target Selection
   2 =====================
   3
   4
   5 MKWS accesses targets using the Pazpar2 metasearching engine. Although
   6 Pazpar2 can be used directly, using a statically configured set of
   7 targets, this usage is unusual. More often, Pazpar2 is fronted by the
   8 Service Proxy (SP), which manages authentication, sessions, target
   9 selection, etc.
  10
  11 This document assumes the SP is used, and explains how to go about
  12 making a set of targets (a "library") available, how to connect your
  13 MKWS application to that library, and how to choose which of the
  14 available targets to use.
  15
  16
  17 1. Maintaining the library
  18 --------------------------
  19
  20 The service proxy accesses sets of targets that are known as
  21 "libraries". In general, each customer will have their own library,
  22 though some standard libraries may be shared between many customers --
  23 for example, a library containing all open-access academic journals.
  24 A library can also contain other configuration information, including
  25 the set of categories by which targets are classified for the library.
  26
  27 Libraries are maintained using MKAdmin (MasterKey
  28 Admin). Specifically, those used by MKWS are generally maintained on
  29 the "MKC Admin" installation at
  30         http://mkx-admin.indexdata.com/console/
  31
  32 In general, Index Data will create a library for each customer, then
  33 give the customer a username/password pair that they can use to enter
  34 MKAdmin and administrate that library.
  35
  36 Once logged in, customers can select which targets to include (from
  37 the list of several thousand that MKAdmin knows about), and make
  38 customer-specific modifications -- e.g. overriding the titles of the
  39 targets.
  40
  41 Most importantly, customers' administrators can add authentication
  42 credentials that the Service Proxy will used on their behalf when
  43 accessing subscription resources -- username/password pairs or proxies
  44 to use for IP-based authentication. Note that IT IS THEN CRUICIAL TO
  45 SECURE THE LIBRARY FROM USE BY UNAUTHORISED CLIENTS, otherwise the
  46 customer's paid subscriptions will be exploited.
  47
  48 Access to libraries is managed by creating one or more "User Access"
  49 records in MKAdmin, under the tab of that name. Each of these records
  50 provides a combination of credentials and other data that allow an
  51 incoming MKWS client to be identified as having legitimate access to
  52 the library. The authentication process, described below, works by
  53 searching for a matching User Access record.
  54
  55
  56 2. Authenticating your MWKS application onto the library
  57 --------------------------------------------------------
  58
  59 Some MKWS applications will be content to use the default library with
  60 its selection of targets. Most, though, will want to define their own
  61 library providing a different range of available targets. An important
  62 case is that of applications that authenticate onto subscription
  63 resources by means of backe-end site credentials stored in MKAdmin:
  64 precautions must be taken so that such library accounts do not allow
  65 unauthorised access.
  66
  67 Setting up such a library is a process of several stages.
  68
  69 Stage A: create the User Access account
  70
  71 Log in to MKAdmin administrate your library:
  72         - Go to http://mkc-admin.indexdata.com/console/
  73         - Enter the adminstrative username/password
  74         - Go to the User Access tab
  75         - Create an end-user account
  76         - Depending on what authentication method it be used, set the
  77           User Access account's username and password, or IP-address
  78           range, or referring URL, or hostname.
  79
  80 If your MWKS application runs at a well-known, permanent address --
  81 http://yourname.com/app.html, say -- you can set the User Access
  82 record so that this originating URL is recognised by setting it into
  83 the "Referring URL" field.
  84
  85 If your application accesses the Service Proxy by a unique virtual
  86 hostname -- yourname.sp-mkws.indexdata.com, say -- you can tie the use
  87 of this hostname to your library by setting the User Access record's
  88 "Host Name" field to name of the host where the SP is accessed. NOTE
  89 THAT THIS IS NOT SECURE, AS OTHER APPLICATIONS CAN USE THIS VIRTUAL
  90 HOSTNAME TO GAIN ACCESS TO YOUR LIBRARY.
  91
  92 ### Authentication by IP address does not yet work correctly -- see
  93 bug MKWS-234 ("Improve SP configuration/proxying for better
  94 authentication").
  95
  96 Alternatively, your application can authenticate by username and
  97 password credentials. This is a useful approach in several situations,
  98 including when you need to specify the use of a different library from
  99 usual one. To arrange for this, set the username and password as a
 100 single string separated by a slash -- e.g. "mike/swordfish" -- into
 101 the User Access record's Authentication field.
 102
 103 You can create multiple User Access records: for example, one that
 104 uses Referring URL, and another that uses a username/password pair to
 105 be used when running an application from a different URL.
 106
 107 Stage B: tell the application to use the library
 108
 109 In the HTML of the application, tell MKWS to authenticate on to the
 110 Service Proxy. When IP-based, referer-based or hostname-based
 111 authentication is used, this is very simple:
 112
 113         <script type="text/javascript">
 114           var mkws_config = { service_proxy_auth:
 115           "//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig" };
 116         </script>
 117
 118 ### This should be the default setting
 119
 120 And ensure that access to the MWKS application is from the correct
 121 Referrer URL or IP-range.
 122
 123 Stage C1 (optional): access by a different virtual hostname
 124
 125 When hostname-based authentication is in use, it's necessary to access
 126 the Service Proxy as the correctly named virtual host. This can be
 127 done by setting the service_proxy_auth configuration item to a
 128 URL containing that hostname, such as
 129         //yourname.sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig
 130
 131 ### It should be possible to change just the hostname without needing
 132 to repeat the rest of the URL (protocol, path, query)
 133
 134 ### When changing the SP authentication URL, the Pazpar2 URL should in
 135 general change along with it.
 136
 137 Stage C2 (optional): embed credentials for access to the library
 138
 139 When credential-based authentication is in use (username and
 140 password), it's necessary to pass these credentials into the Service
 141 Proxy when establishing the session. This can most simply be done just
 142 by setting the service_proxy_auth configuration item to a URL such as
 143         //sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig&username=mike&password=swordfish
 144
 145 ### It should be possible to add the username and password to the
 146 configuration without needing to repeat the rest of the URL.
 147
 148 Stage D (optional): conceal credentials from HTML source
 149
 150 Using a credential-based Service-Proxy authentication URL such as the
 151 one above reveals the the credentials to public view -- to anyone who
 152 does View Source on the MKWS application. This may be acceptable for
 153 some libraries, but is intolerable for those which provide
 154 authenticated access to subscription resources.
 155
 156 In these circumstances, a more elaborate approach is necessary. The
 157 idea is to make a URL local to the customer that is used for
 158 authentication onto the Service Proxy, hiding the credentials in a
 159 local rewrite rule. Then local mechanisms can be used to limit access
 160 to that local authentication URL. Here is one way to do it when
 161 Apache2 is the application's web-server, which we will call
 162 yourname.com:
 163
 164         - Add a rewriting authentication alias to the configuration:
 165                 RewriteEngine on
 166                 RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
 167         - Set thwe MKWS configuration item "service_proxy_auth" to:
 168                 http://yourname.com/spauth/
 169         - Protect access to the local path http://yourname.com/spauth/
 170                 (e.g. using a .htaccess file).
 171
 172
 173 3. Choosing targets from the library
 174 ------------------------------------
 175
 176 MKWS applications can choose what subset of the library's targets to
 177 use, by means of several alternative settings on individual widgets or
 178 in the mkws_config structure:
 179
 180 * targets -- contains a Pazpar2 targets string, typically of the form
 181   "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
 182   target IDs.
 183
 184   At present, these IDs can take one of two forms, depending on the
 185   configuration of the Service Proxy being used: they may be based on
 186   ZURLs, so a typical value would be something like:
 187         pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902
 188   Or they may be UDBs, so a typical value would be something like:
 189         pz:id=brown|artstor
 190
 191 * targetfilter -- contains a CQL query which is used to find relevant
 192   targets from the relvant library. For example,
 193         udb==Google_Images
 194   Or
 195         categories=news
 196
 197 * target -- contains a single UDB, that of the sole target to be
 198   used. For example
 199         Google_Images
 200   This is merely syntactic sugar for "targetfilter" with the query
 201         udb==NAME
 202
 203