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