doc/library-configuration.markdown

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