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 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.
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/`
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.
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
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 crucial to
45 secure the library from use by unauthorised clients**, otherwise the
46 customer's paid subscriptions will be exploited.
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.
56 2. Authenticating your MWKS application onto the library
57 --------------------------------------------------------
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
67 Setting up such a library is a process of several stages.
69 ### Stage A: create the User Access account
71 Log in to MKAdmin administrate your library:
73 * Go to `http://mkc-admin.indexdata.com/console/`
74 * Enter the adminstrative username/password
75 * Go to the User Access tab
76 * Create an end-user account
77 * Depending on what authentication method it be used, set the
78 User Access account's username and password, or IP-address range, or
79 referring URL, or hostname.
81 If your MWKS application runs at a well-known, permanent address --
82 `http://yourname.com/app.html`, say -- you can set the User Access
83 record so that this originating URL is recognised by setting it into
84 the "Referring URL" field.
86 If your application accesses the Service Proxy by a unique virtual
87 hostname -- yourname.sp-mkws.indexdata.com, say -- you can tie the use
88 of this hostname to your library by setting the User Access record's
89 "Host Name" field to name of the host where the SP is accessed. **Note
90 that this is not secure, as other applications can use this virtual
91 hostname to gain access to your library.**
93 > TODO Authentication by IP address does not yet work correctly -- see
94 > bug MKWS-234 ("Improve SP configuration/proxying for better
97 Alternatively, your application can authenticate by username and
98 password credentials. This is a useful approach in several situations,
99 including when you need to specify the use of a different library from
100 usual one. To arrange for this, set the username and password as a
101 single string separated by a slash -- e.g. "mike/swordfish" -- into
102 the User Access record's Authentication field.
104 You can create multiple User Access records: for example, one that
105 uses Referring URL, and another that uses a username/password pair to
106 be used when running an application from a different URL.
108 ### Stage B: tell the application to use the library
110 In the HTML of the application, tell MKWS to authenticate on to the
111 Service Proxy. When IP-based, referer-based or hostname-based
112 authentication is used, this is very simple:
114 <script type="text/javascript">
115 var mkws_config = { service_proxy_auth:
116 "//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig" };
119 > TODO This should be the default setting
121 And ensure that access to the MWKS application is from the correct
122 Referrer URL or IP-range.
124 ### Stage C1 (optional): access by a different virtual hostname
126 When hostname-based authentication is in use, it's necessary to access
127 the Service Proxy as the correctly named virtual host. This can be
128 done by setting the service_proxy_auth configuration item to a
129 URL containing that hostname, such as
130 `//yourname.sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig`
132 > TODO It should be possible to change just the hostname without
133 > needing to repeat the rest of the URL (protocol, path, query)
135 > TODO When changing the SP authentication URL, the Pazpar2 URL should
136 > in general change along with it.
138 ### Stage C2 (optional): embed credentials for access to the library
140 When credential-based authentication is in use (username and
141 password), it's necessary to pass these credentials into the Service
142 Proxy when establishing the session. This can most simply be done just
143 by setting the service_proxy_auth configuration item to a URL such as
144 `//sp-mkws.indexdata.com/service-proxy/?command=auth&action=perconfig&username=mike&password=swordfish`
146 > TODO It should be possible to add the username and password to the
147 > configuration without needing to repeat the rest of the URL.
149 ### Stage D (optional): conceal credentials from HTML source
151 Using a credential-based Service-Proxy authentication URL such as the
152 one above reveals the the credentials to public view -- to anyone who
153 does View Source on the MKWS application. This may be acceptable for
154 some libraries, but is intolerable for those which provide
155 authenticated access to subscription resources.
157 In these circumstances, a more elaborate approach is necessary. The
158 idea is to make a URL local to the customer that is used for
159 authentication onto the Service Proxy, hiding the credentials in a
160 local rewrite rule. Then local mechanisms can be used to limit access
161 to that local authentication URL. Here is one way to do it when
162 Apache2 is the application's web-server, which we will call
165 - Add a rewriting authentication alias to the configuration:
167 RewriteRule /spauth/ http://mkws.indexdata.com/service-proxy/?command=auth&action=check,login&username=U&password=PW [P]
168 - Set thwe MKWS configuration item "service_proxy_auth" to:
169 http://yourname.com/spauth/
170 - Protect access to the local path http://yourname.com/spauth/
171 (e.g. using a .htaccess file).
174 3. Choosing targets from the library
175 ------------------------------------
177 MKWS applications can choose what subset of the library's targets to
178 use, by means of several alternative settings on individual widgets or
179 in the mkws_config structure:
181 * targets -- contains a Pazpar2 targets string, typically of the form
182 "pz:id=" or "pz:id~" followed by a pipe-separated list of low-level
185 At present, these IDs can take one of two forms, depending on the
186 configuration of the Service Proxy being used: they may be based on
187 ZURLs, so a typical value would be something like:
188 pz:id=josiah.brown.edu:210/innopac|lui.indexdata.com:8080/solr4/select?fq=database:4902
189 Or they may be UDBs, so a typical value would be something like:
192 * targetfilter -- contains a CQL query which is used to find relevant
193 targets from the relvant library. For example,
198 * target -- contains a single UDB, that of the sole target to be
201 This is merely syntactic sugar for "targetfilter" with the query